crp.activation¶
Auto-generated reference for the crp.activation subpackage.
activation¶
crp.activation ¶
CRP progressive activation & Zero-CKF mode (CRP-SPEC-017).
Graceful degradation for an empty or sparse Contextual Knowledge Fabric: operating-mode detection (Zero/Partial/Full-CKF) with sticky transitions, per-call coverage adaptation, the time-based onboarding overlay + feature cascade, Zero-CKF Safety Policy auto-adjustment, and the DPE stage plan.
Public API
ActivationMode / detect_mode / ModeState - mode detection + stickiness assess_coverage / apply_tier_cap - per-call coverage TenantState / build_activation_headers - onboarding + activation headers adjust_for_zero_ckf / AdjustedPolicy - Zero-CKF policy adjustment stage_plan_for / StagePlan - DPE stage selection
ActivationMode ¶
Bases: str, Enum
The three CRP operating modes (CRP-SPEC-017 §2).
Attributes:
| Name | Type | Description |
|---|---|---|
ZERO_CKF | No active facts; CRP operates without a Contextual Knowledge Fabric. | |
PARTIAL_CKF | Some facts exist but thresholds for Full-CKF are not met. | |
FULL_CKF | Large, well-clustered knowledge fabric available for retrieval. |
CoverageResult dataclass ¶
Per-call coverage outcome in Partial-CKF mode (CRP-SPEC-017 §7).
Attributes:
| Name | Type | Description |
|---|---|---|
coverage | float | Ratio of retrieved facts to expected facts needed. |
effective_mode | ActivationMode | Mode implied by the coverage level. |
tier_cap | str | None | Quality-tier cap to apply, or None if no cap. |
reason | str | None | Human-readable reason for a cache miss, or None. |
headers property ¶
CRP headers describing coverage and any tier cap.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary containing |
dict[str, str] | applicable, |
ModeState dataclass ¶
Sticky mode tracker (CRP-SPEC-017 §3.3).
Holds the currently effective mode plus the timestamp at which a candidate transition was first observed, so brief reindexing does not flap the mode.
Attributes:
| Name | Type | Description |
|---|---|---|
mode | ActivationMode | Effective operating mode. |
candidate | ActivationMode | None | Candidate mode currently being observed, or None if stable. |
candidate_since | float | None | Unix timestamp when the current candidate was first observed, or None. |
update(fact_count, community_count, now) ¶
Re-evaluate the mode given current CKF state and wall-clock now.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fact_count | int | Current number of CKF facts. | required |
community_count | int | Current number of CKF communities. | required |
now | float | Current Unix timestamp. | required |
Returns:
| Type | Description |
|---|---|
ModeTransition | A |
ModeTransition | sticky transition actually fires. |
ModeTransition dataclass ¶
Result of a :meth:ModeState.update call.
Attributes:
| Name | Type | Description |
|---|---|---|
previous | ActivationMode | Mode before the update. |
current | ActivationMode | Mode after the update. |
transitioned | bool | True if the sticky timer fired and the mode changed. |
headers property ¶
CRP headers describing the mode and any transition.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary containing |
dict[str, str] | occurred, |
TenantState dataclass ¶
Inputs used to compute onboarding + activation headers.
AdjustedPolicy dataclass ¶
A Zero-CKF-adjusted policy plus the list of adjustments made.
headers property ¶
Return the headers.
PolicyAdjustment dataclass ¶
A single auto-adjusted directive (CRP-SPEC-017 §6.2).
to_header_value() ¶
Serialize this adjustment to a CRP-Safety-Policy-Adjustment header value.
StageMode ¶
Bases: str, Enum
How a DPE stage executes under the current activation mode.
StagePlan dataclass ¶
apply_tier_cap(tier, cap) ¶
Clamp tier so it is no better than cap (None = no cap).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tier | str | Proposed quality tier. | required |
cap | str | None | Maximum allowed tier, or None to allow any tier. | required |
Returns:
| Type | Description |
|---|---|
str | The original tier if it is no better than cap, otherwise cap. |
str | Unknown tiers fall back to the original tier. |
assess_coverage(matching_facts, expected_facts_needed) ¶
Compute per-call coverage and the resulting tier cap (CRP-SPEC-017 §7.1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
matching_facts | int | Facts retrieved at relevance ≥ 0.60 for this query. | required |
expected_facts_needed | int | Estimated facts required to answer the query. | required |
Returns:
| Type | Description |
|---|---|
CoverageResult | A |
CoverageResult | and any quality-tier cap. |
detect_mode(fact_count, community_count=0) ¶
Classify the operating mode from CKF state (CRP-SPEC-017 §2).
Full-CKF requires both 1000+ facts AND 3+ detected communities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fact_count | int | Number of facts currently in the CKF. | required |
community_count | int | Number of detected CKF communities. | 0 |
Returns:
| Type | Description |
|---|---|
ActivationMode | The matching |
activation_status(mode, fact_count) ¶
The CRP-Activation-Status value for the mode (CRP-SPEC-017 §2).
active_features(state) ¶
Compute the active feature-group list (CRP-SPEC-017 §5.2).
build_activation_headers(state, mode) ¶
Build the full CRP-Activation-* / CRP-Onboarding-* header set.
Combines mode status, the feature cascade, the mode-appropriate hint, and the time-based onboarding overlay (only while within the 14-day window).
next_action(state) ¶
Determine the most useful onboarding next-action (CRP-SPEC-017 §4.3).
onboarding_hint(mode) ¶
The mode-appropriate CRP-Onboarding-Hint value (CRP-SPEC-017 §2).
adjust_for_zero_ckf(policy) ¶
Return a Zero-CKF-adjusted copy of policy (CRP-SPEC-017 §6.1).
Adjustments
default-src context→ addparametric(relax source trust)block-ungrounded→ downgrade to warn (cleared + flagged)require-grounding→ skipped (no facts to ground against)
halt-on, block-pii, require-entailment (vs. query), upgrade-on-risk, oversight and report-uri are preserved.
stage_plan_for(mode) ¶
Return the DPE stage plan appropriate for mode.
zero_ckf_stage_plan() ¶
The Zero-CKF stage plan (CRP-SPEC-017 §2.1).
Stages 1, 2, 5, 6, 7, 8, 9, 11, 12, 13 run normally; Stage 3 (fidelity) is limited to common-knowledge fabrication detection; Stage 4 (entailment) runs against the query rather than the empty envelope; Stage 10 (omission) is skipped. Grounding mode is forced to parametric-only.
activation.mode¶
crp.activation.mode ¶
Operating-mode detection + per-call coverage (CRP-SPEC-017 §2, §3, §7).
Determines whether a tenant is in Zero-CKF, Partial-CKF, or Full-CKF mode from the active fact count and community count, applies sticky transition rules to prevent flapping, and computes the per-call coverage adjustment used in Partial-CKF mode.
Relevant specifications
- CRP-SPEC-017: Zero-CKF Mode
ActivationMode ¶
Bases: str, Enum
The three CRP operating modes (CRP-SPEC-017 §2).
Attributes:
| Name | Type | Description |
|---|---|---|
ZERO_CKF | No active facts; CRP operates without a Contextual Knowledge Fabric. | |
PARTIAL_CKF | Some facts exist but thresholds for Full-CKF are not met. | |
FULL_CKF | Large, well-clustered knowledge fabric available for retrieval. |
ModeState dataclass ¶
Sticky mode tracker (CRP-SPEC-017 §3.3).
Holds the currently effective mode plus the timestamp at which a candidate transition was first observed, so brief reindexing does not flap the mode.
Attributes:
| Name | Type | Description |
|---|---|---|
mode | ActivationMode | Effective operating mode. |
candidate | ActivationMode | None | Candidate mode currently being observed, or None if stable. |
candidate_since | float | None | Unix timestamp when the current candidate was first observed, or None. |
update(fact_count, community_count, now) ¶
Re-evaluate the mode given current CKF state and wall-clock now.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fact_count | int | Current number of CKF facts. | required |
community_count | int | Current number of CKF communities. | required |
now | float | Current Unix timestamp. | required |
Returns:
| Type | Description |
|---|---|
ModeTransition | A |
ModeTransition | sticky transition actually fires. |
ModeTransition dataclass ¶
Result of a :meth:ModeState.update call.
Attributes:
| Name | Type | Description |
|---|---|---|
previous | ActivationMode | Mode before the update. |
current | ActivationMode | Mode after the update. |
transitioned | bool | True if the sticky timer fired and the mode changed. |
headers property ¶
CRP headers describing the mode and any transition.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary containing |
dict[str, str] | occurred, |
CoverageResult dataclass ¶
Per-call coverage outcome in Partial-CKF mode (CRP-SPEC-017 §7).
Attributes:
| Name | Type | Description |
|---|---|---|
coverage | float | Ratio of retrieved facts to expected facts needed. |
effective_mode | ActivationMode | Mode implied by the coverage level. |
tier_cap | str | None | Quality-tier cap to apply, or None if no cap. |
reason | str | None | Human-readable reason for a cache miss, or None. |
headers property ¶
CRP headers describing coverage and any tier cap.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary containing |
dict[str, str] | applicable, |
PartialModeCaps dataclass ¶
Partial-CKF mode default caps (CRP-SPEC-017 §2.2).
Attributes:
| Name | Type | Description |
|---|---|---|
max_tier | str | Maximum quality tier allowed while in Partial-CKF mode. |
feature_milestones | dict[int, str] | Optional mapping of fact-count milestones to unlocked feature identifiers. |
detect_mode(fact_count, community_count=0) ¶
Classify the operating mode from CKF state (CRP-SPEC-017 §2).
Full-CKF requires both 1000+ facts AND 3+ detected communities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fact_count | int | Number of facts currently in the CKF. | required |
community_count | int | Number of detected CKF communities. | 0 |
Returns:
| Type | Description |
|---|---|
ActivationMode | The matching |
assess_coverage(matching_facts, expected_facts_needed) ¶
Compute per-call coverage and the resulting tier cap (CRP-SPEC-017 §7.1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
matching_facts | int | Facts retrieved at relevance ≥ 0.60 for this query. | required |
expected_facts_needed | int | Estimated facts required to answer the query. | required |
Returns:
| Type | Description |
|---|---|
CoverageResult | A |
CoverageResult | and any quality-tier cap. |
apply_tier_cap(tier, cap) ¶
Clamp tier so it is no better than cap (None = no cap).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tier | str | Proposed quality tier. | required |
cap | str | None | Maximum allowed tier, or None to allow any tier. | required |
Returns:
| Type | Description |
|---|---|
str | The original tier if it is no better than cap, otherwise cap. |
str | Unknown tiers fall back to the original tier. |
activation.onboarding¶
crp.activation.onboarding ¶
Onboarding overlay + feature-activation cascade (CRP-SPEC-017 §4, §5).
Two independent UX layers on top of mode detection:
- Onboarding overlay - a time-based (14-day) overlay that emits
CRP-Onboarding-*headers and a constantly-updated "next action" signal. - Feature cascade - the set of feature groups that become active as the tenant's CKF fact count crosses milestones, emitted via
CRP-Activation-FeaturesandCRP-Activation-Status.
TenantState dataclass ¶
Inputs used to compute onboarding + activation headers.
OnboardingHeaders dataclass ¶
Computed onboarding + activation header bundle.
next_action(state) ¶
Determine the most useful onboarding next-action (CRP-SPEC-017 §4.3).
active_features(state) ¶
Compute the active feature-group list (CRP-SPEC-017 §5.2).
onboarding_hint(mode) ¶
The mode-appropriate CRP-Onboarding-Hint value (CRP-SPEC-017 §2).
activation_status(mode, fact_count) ¶
The CRP-Activation-Status value for the mode (CRP-SPEC-017 §2).
build_activation_headers(state, mode) ¶
Build the full CRP-Activation-* / CRP-Onboarding-* header set.
Combines mode status, the feature cascade, the mode-appropriate hint, and the time-based onboarding overlay (only while within the 14-day window).
activation.policy_adjust¶
crp.activation.policy_adjust ¶
Zero-CKF Safety Policy adjustments (CRP-SPEC-017 §6).
In Zero-CKF mode there are no facts to ground against, so certain Safety Policy directives cannot be enforced as written. Rather than block every response, the gateway auto-adjusts the offending directives and emits CRP-Safety-Policy-Adjustment so the developer (and CRP-Scan / Comply) can see what will be enforced once the CKF is populated.
Safety directives that still work without facts - halt-on, block-pii, upgrade-on-risk, oversight, report-uri - are left untouched.
PolicyAdjustment dataclass ¶
A single auto-adjusted directive (CRP-SPEC-017 §6.2).
to_header_value() ¶
Serialize this adjustment to a CRP-Safety-Policy-Adjustment header value.
AdjustedPolicy dataclass ¶
A Zero-CKF-adjusted policy plus the list of adjustments made.
headers property ¶
Return the headers.
adjust_for_zero_ckf(policy) ¶
Return a Zero-CKF-adjusted copy of policy (CRP-SPEC-017 §6.1).
Adjustments
default-src context→ addparametric(relax source trust)block-ungrounded→ downgrade to warn (cleared + flagged)require-grounding→ skipped (no facts to ground against)
halt-on, block-pii, require-entailment (vs. query), upgrade-on-risk, oversight and report-uri are preserved.
activation.stages¶
crp.activation.stages ¶
DPE stage selection for Zero-CKF mode (CRP-SPEC-017 §2.1, §5.1).
In Zero-CKF mode there is no envelope to ground against, so some DPE stages run in limited mode or are skipped entirely. :func:zero_ckf_stage_plan returns the stage execution plan so the pipeline can skip work that cannot produce a meaningful result.
StageMode ¶
Bases: str, Enum
How a DPE stage executes under the current activation mode.
StagePlan dataclass ¶
full_stage_plan(mode=ActivationMode.FULL_CKF) ¶
All 13 stages run fully (Partial/Full-CKF default).
zero_ckf_stage_plan() ¶
The Zero-CKF stage plan (CRP-SPEC-017 §2.1).
Stages 1, 2, 5, 6, 7, 8, 9, 11, 12, 13 run normally; Stage 3 (fidelity) is limited to common-knowledge fabrication detection; Stage 4 (entailment) runs against the query rather than the empty envelope; Stage 10 (omission) is skipped. Grounding mode is forced to parametric-only.
stage_plan_for(mode) ¶
Return the DPE stage plan appropriate for mode.