Skip to content

crp.stl

Auto-generated reference for the crp.stl subpackage.

stl

crp.stl

STLOperation

Bases: str, Enum

The ten canonical cognitive operations (SPEC-031 §3.1; CRP v5 taxonomy).

Reconciled in CRP v5 so the STL classifier, the capability-descriptor schema (CRP-SPEC-050), and the operation-type headers (CRP-SPEC-049 §4.8) all share ONE taxonomy. TRANSFORM and PLAN were added for agentic tool use; the legacy schema value EVALUATE maps to VERIFY (see operation_from_token).

DepthLevel

Bases: str, Enum

Five depth levels (SPEC-031 §4.2).

OperationFrame dataclass

The minimal focused assignment that positions the model (SPEC-031 §5.1).

Attributes:

Name Type Description
operation_type STLOperation

Which of the 8 cognitive operations.
assignment str

The ONE thing to do, imperatively stated.
frame_content str

ONLY the context THIS operation needs.
goal_compass GoalCompass

Anchored positioning for coherence.
success_test str

How the STL will judge the output.
output_contract str

Expected form of the output.
depth DepthLevel

D1–D5, how far to take this operation.

estimated_tokens property

Rough word-count estimate of the frame size.

to_prompt()

Render the complete frame as a prompt for the LLM.

GoalCompass dataclass

The minimal anchor that prevents incoherence across operations (SPEC-031 §6.2).

Attributes:

Name Type Description
ultimate_goal str

One sentence - what the user ultimately wants.
this_operation_serves str

One sentence - how THIS operation contributes.
fit_constraint str

One sentence - what makes this output fit the whole.

to_prompt_text()

Render as compact prompt text.

token_estimate()

Rough token count for the compass.

InvalidTransition

Bases: RuntimeError

Raised when an illegal state transition is attempted.

OperationEvent dataclass

A single transition - both audit record and live visibility event.

to_dict()

Render the event for streaming / audit.

OperationState

Bases: str, Enum

States of the agentic operation lifecycle (CRP-SPEC-050 §5.1).

OperationStateMachine dataclass

Tracks the lifecycle of an agentic task across its operation plan.

current_operation property

The operation currently being executed, or None.

is_complete property

Whether the plan has finished.

is_halted property

Whether the machine halted (preventive safety or failure).

completion property

Fraction of the plan integrated so far (0.0–1.0).

remaining property

Names of operations not yet started.

can_transition(to_state)

Return whether a transition to to_state is legal from the current state.

position(*, detail='')

Advance to the next operation and mark it positioned.

select_tool(capability_id)

Mark that the model emitted a valid tool selection.

execute_tool(capability_id)

Mark that the selected capability executed.

verify(*, detail='')

Mark the operation output verified (DPE / safety check).

integrate(*, detail='')

Mark the operation result integrated into the CSO.

complete(*, detail='')

Mark the whole plan complete.

halt(reason)

Halt the machine (preventive safety or unrecoverable failure).

note(detail, *, operation=None)

Record an informational event (e.g. a continuation window) WITHOUT a state transition. Visible in the event stream/audit; does not affect the FSM state or the completion count.

to_headers()

Emit the CRP-SPEC-049/050 operation headers for the current state.

event_stream()

Return the full event log (for the visibility UI / audit).

STLResult dataclass

The result of an STL execution cycle.

PositionedResult dataclass

The result of a positioned-tool-loop run.

event_stream property

The Operation State Machine event log (visibility / audit).

CapabilitySlot dataclass

One capability offered in a Tool Positioning Frame.

ParsedToolCall dataclass

A tool selection parsed from the model's output.

is_tool_call property

Whether the model chose a tool (vs answering directly).

ToolPositioningFrame dataclass

The 1–3 capabilities offered to the model for one operation (CRP-SPEC-050 §4.3).

capability_ids property

Ids of the offered capabilities.

to_prompt()

Render the operation frame + the offered tools as a compact instruction.

output_schema()

JSON schema constraining the model output to a tool selection (for constrained decoding).

classify_operations(user_request)

Classify a user request into a sequence of cognitive operations (SPEC-031 §3.3).

Returns a list of operations in suggested execution order.

operation_from_token(token)

Map an operation-type token (any casing) to a canonical operation.

Accepts the canonical names used by the capability-descriptor schema (CRP-SPEC-050) and the CRP-Agent-Operation-Type header (CRP-SPEC-049), plus legacy aliases (e.g. EVALUATE → VERIFY). Returns None for unknown tokens so callers can skip/warn rather than crash.

operation_to_token(op)

Render an operation as its canonical uppercase token (schema/header form).

negotiate_depth(request, operations, current_depth=None, renegotiation_count=0)

Propose initial depth and return metadata (SPEC-031 §4.3).

Returns:

Type Description
tuple[DepthLevel, dict[str, Any]]

(proposed_depth, metadata_dict)

renegotiate_depth(current_depth, reason, renegotiation_count=0)

Revise depth mid-execution (SPEC-031 §4.4).

Reasons

"unresolved-complexity" → deepen "high-confidence-fast" → shallow

build_operation_frame(operation, user_request, context_facts=None, depth=DepthLevel.D3, goal_compass=None)

Build a minimal Operation Frame for the given operation (SPEC-031 §5.2).

Parameters:

Name Type Description Default
operation STLOperation

The cognitive operation to position on.

 required
user_request str

The original user request.

 required
context_facts list[str] | None

Retrieved facts relevant to THIS operation only.

 None
depth DepthLevel

Depth level D1–D5.

 D3
goal_compass GoalCompass | None

Pre-built compass, or None to build default.

 None

build_goal_compass(operation, user_request, prior_operations=None)

Construct a goal-compass for the current operation (SPEC-031 §6).

Parameters:

Name Type Description Default
operation str

The STL operation name, e.g. "ANALYSE".

 required
user_request str

The original user request.

 required
prior_operations list[str] | None

List of already-completed operations.

 None

stl_execute(user_request, session, context_facts=None)

Execute the full STL positioning cycle (SPEC-031 §7.1).

Parameters:

Name Type Description Default
user_request str

The user's natural-language request.

 required
session Any

CRP session object (for CSO integration, etc.).

 required
context_facts list[str] | None

Optional pre-retrieved facts from CKF.

 None

Returns:

Type Description
STLResult

STLResult with assembled text, operation log, and efficiency metrics.

guard_prompt_budget(prompt, *, context_window, requested_max_tokens, count_tokens_fn=None, safety_margin=256, min_output_tokens=128)

Ensure prompt + the response never overflow the model's real context window.

This is the protocol-level context-overflow guard (input, tool-call frames, accumulated multi-turn/CSO state, and output are all covered because every call site - direct generation, tool positioning, continuation windows - funnels through the model_call this wraps). Returns (safe_prompt, safe_max_tokens):

  • safe_max_tokens is capped so prompt_tokens + safe_max_tokens + margin fits inside context_window (never less than min_output_tokens).
  • If the prompt itself is still too large to leave room for the minimum output, the earliest lines are trimmed (oldest carried-forward state/context) while the tail - the actual task/operation frame - is preserved intact.

provider_model_call(provider, *, temperature=0.2, max_tokens=1024)

Adapt a CRP LLMProvider into a positioned-loop model_call.

The structured-output schema is advisory here - the prompt instructs the model to emit JSON and parse_tool_call robustly extracts it; provider-native constrained decoding can be layered on later (CRP-SPEC-049 §4.4).

Every call is passed through :func:guard_prompt_budget using the provider's own context_window_size()/count_tokens() (mandatory on the LLMProvider ABC), so input, tool-call frames, continuation windows, and multi-turn state can never overflow the model's real context window - the guard adapts to whatever window the connected LLM (local or frontier) actually reports.

run_positioned(user_request, model_call, *, fabric=None, executor=None, profile=CapabilityProfile.FRONTIER, policy=None, context_facts=None, max_operations=12, oversight_required=None, governor=None, clarify_handler=None, hmac_key=None, prior_cso=None, max_continuation_windows=1)

Run the positioned-tool-loop for a request (CRP-SPEC-049/050).

Parameters:

Name Type Description Default
user_request str

The natural-language request.

 required
model_call ModelCall

(prompt, schema|None) -> text. The only LLM dependency.

 required
fabric ToolCapabilityFabric | None

Optional Tool Capability Fabric; if absent, operations are direct-generation.

 None
executor CapabilityExecutor | None

Optional capability executor; if absent, tool ops run in selection-only mode.

 None
profile CapabilityProfile

Capability profile bounding frame size (small-local 1–2 tools, etc.).

 FRONTIER
policy PolicyContext | None

Optional policy pre-filter / preventive-safety context.

 None
context_facts list[str] | None

Optional pre-retrieved facts for the first operations.

 None
max_operations int

Hard cap on operations (loop guard).

 12
hmac_key bytes | None

If provided, seals the CSO with an HMAC chain link.

 None
prior_cso CognitiveStateObject | None

Optional prior-turn CSO to relay forward (multi-turn workflows).

 None

build_tool_positioning_frame(operation_frame, selection, *, profile=CapabilityProfile.FRONTIER, depth=None, structured_output_mode='json-schema')

Compose a Tool Positioning Frame from an operation frame and a TCF selection.

parse_tool_call(raw_output, frame)

Parse the model's tool-selection output against a positioning frame.

Returns a :class:ParsedToolCall. If the model answered directly (no tool), capability_id is None and answer carries the text. Returns None only when the output is unparseable AND there is no single obvious capability to default to.

stl.classifier

crp.stl.classifier

STL Operation Classifier - 8-operation taxonomy (SPEC-031 §3).

Fast semantic check: verb-anchored + keyword heuristics, sub-millisecond. No model call required for classification.

STLOperation

Bases: str, Enum

The ten canonical cognitive operations (SPEC-031 §3.1; CRP v5 taxonomy).

Reconciled in CRP v5 so the STL classifier, the capability-descriptor schema (CRP-SPEC-050), and the operation-type headers (CRP-SPEC-049 §4.8) all share ONE taxonomy. TRANSFORM and PLAN were added for agentic tool use; the legacy schema value EVALUATE maps to VERIFY (see operation_from_token).

classify_operations(user_request)

Classify a user request into a sequence of cognitive operations (SPEC-031 §3.3).

Returns a list of operations in suggested execution order.

operation_from_token(token)

Map an operation-type token (any casing) to a canonical operation.

Accepts the canonical names used by the capability-descriptor schema (CRP-SPEC-050) and the CRP-Agent-Operation-Type header (CRP-SPEC-049), plus legacy aliases (e.g. EVALUATE → VERIFY). Returns None for unknown tokens so callers can skip/warn rather than crash.

operation_to_token(op)

Render an operation as its canonical uppercase token (schema/header form).

stl.depth_model

crp.stl.depth_model

STL Depth Model - D1–D5 depth negotiation (SPEC-031 §4).

Depth is negotiated: proposed, executed, and revised mid-flight if needed.

DepthLevel

Bases: str, Enum

Five depth levels (SPEC-031 §4.2).

negotiate_depth(request, operations, current_depth=None, renegotiation_count=0)

Propose initial depth and return metadata (SPEC-031 §4.3).

Returns:

Type Description
tuple[DepthLevel, dict[str, Any]]

(proposed_depth, metadata_dict)

renegotiate_depth(current_depth, reason, renegotiation_count=0)

Revise depth mid-execution (SPEC-031 §4.4).

Reasons

"unresolved-complexity" → deepen "high-confidence-fast" → shallow

stl.frame_builder

crp.stl.frame_builder

Operation Frame Builder - minimal frame assembly per cognitive operation (SPEC-031 §5).

The frame is built UP from what the operation requires, not trimmed DOWN from everything available. This is the structural token-efficiency primitive.

OperationFrame dataclass

The minimal focused assignment that positions the model (SPEC-031 §5.1).

Attributes:

Name Type Description
operation_type STLOperation

Which of the 8 cognitive operations.
assignment str

The ONE thing to do, imperatively stated.
frame_content str

ONLY the context THIS operation needs.
goal_compass GoalCompass

Anchored positioning for coherence.
success_test str

How the STL will judge the output.
output_contract str

Expected form of the output.
depth DepthLevel

D1–D5, how far to take this operation.

estimated_tokens property

Rough word-count estimate of the frame size.

to_prompt()

Render the complete frame as a prompt for the LLM.

build_operation_frame(operation, user_request, context_facts=None, depth=DepthLevel.D3, goal_compass=None)

Build a minimal Operation Frame for the given operation (SPEC-031 §5.2).

Parameters:

Name Type Description Default
operation STLOperation

The cognitive operation to position on.

 required
user_request str

The original user request.

 required
context_facts list[str] | None

Retrieved facts relevant to THIS operation only.

 None
depth DepthLevel

Depth level D1–D5.

 D3
goal_compass GoalCompass | None

Pre-built compass, or None to build default.

 None

stl.goal_compass

crp.stl.goal_compass

Goal Compass - anchored positioning for global coherence (SPEC-031 §6).

Three sentences (~60–100 tokens) that keep locally-focused operations globally coherent without re-injecting full context.

GoalCompass dataclass

The minimal anchor that prevents incoherence across operations (SPEC-031 §6.2).

Attributes:

Name Type Description
ultimate_goal str

One sentence - what the user ultimately wants.
this_operation_serves str

One sentence - how THIS operation contributes.
fit_constraint str

One sentence - what makes this output fit the whole.

to_prompt_text()

Render as compact prompt text.

token_estimate()

Rough token count for the compass.

build_goal_compass(operation, user_request, prior_operations=None)

Construct a goal-compass for the current operation (SPEC-031 §6).

Parameters:

Name Type Description Default
operation str

The STL operation name, e.g. "ANALYSE".

 required
user_request str

The original user request.

 required
prior_operations list[str] | None

List of already-completed operations.

 None

stl.operation_state

crp.stl.operation_state

Operation State Machine - the agent always knows where it is (CRP-SPEC-050 §5).

An agentic task is an explicit lifecycle, tracked by the protocol rather than inferred by the model:

INTENT_CLASSIFIED → OPERATION_POSITIONED → TOOL_SELECTED → TOOL_EXECUTED
                  → OPERATION_VERIFIED → INTEGRATED → (next) … → COMPLETE
                  (any state → HALTED on preventive safety)

Every transition emits an :class:OperationEvent, which is both the audit record and the live visibility stream the UI consumes ("not a blind machine"). The machine carries the operation plan and the current position, so a 300-operation run is always introspectable: which operation, which state, how much of the checklist remains.

OperationState

Bases: str, Enum

States of the agentic operation lifecycle (CRP-SPEC-050 §5.1).

InvalidTransition

Bases: RuntimeError

Raised when an illegal state transition is attempted.

OperationEvent dataclass

A single transition - both audit record and live visibility event.

to_dict()

Render the event for streaming / audit.

OperationStateMachine dataclass

Tracks the lifecycle of an agentic task across its operation plan.

current_operation property

The operation currently being executed, or None.

is_complete property

Whether the plan has finished.

is_halted property

Whether the machine halted (preventive safety or failure).

completion property

Fraction of the plan integrated so far (0.0–1.0).

remaining property

Names of operations not yet started.

can_transition(to_state)

Return whether a transition to to_state is legal from the current state.

position(*, detail='')

Advance to the next operation and mark it positioned.

select_tool(capability_id)

Mark that the model emitted a valid tool selection.

execute_tool(capability_id)

Mark that the selected capability executed.

verify(*, detail='')

Mark the operation output verified (DPE / safety check).

integrate(*, detail='')

Mark the operation result integrated into the CSO.

complete(*, detail='')

Mark the whole plan complete.

halt(reason)

Halt the machine (preventive safety or unrecoverable failure).

note(detail, *, operation=None)

Record an informational event (e.g. a continuation window) WITHOUT a state transition. Visible in the event stream/audit; does not affect the FSM state or the completion count.

to_headers()

Emit the CRP-SPEC-049/050 operation headers for the current state.

event_stream()

Return the full event log (for the visibility UI / audit).

stl.orchestrator

crp.stl.orchestrator

STL Orchestrator - the full positioning execution cycle (SPEC-031 §7).

  1. RECEIVE user request
  2. CLASSIFY → sequence of operations
  3. PROPOSE depth
  4. DECOMPOSE into operation plan
  5. FOR each operation: BUILD frame → POSITION model → VERIFY → INTEGRATE
  6. ASSEMBLE final response

STLResult dataclass

The result of an STL execution cycle.

stl_execute(user_request, session, context_facts=None)

Execute the full STL positioning cycle (SPEC-031 §7.1).

Parameters:

Name Type Description Default
user_request str

The user's natural-language request.

 required
session Any

CRP session object (for CSO integration, etc.).

 required
context_facts list[str] | None

Optional pre-retrieved facts from CKF.

 None

Returns:

Type Description
STLResult

STLResult with assembled text, operation log, and efficiency metrics.

stl.positioned

crp.stl.positioned

Positioned execution loop - the live positioned-tool-loop (CRP-SPEC-049/050).

run_positioned is the real STL spine that replaces the v4 simulation: it classifies a request into operations, and for each operation it positions the model on a focused frame with the 1–3 tools the TCF selected, runs the structured tool call, stores the observation in the CSO, advances the Operation State Machine, and integrates - then assembles a coherent final response. The window never accumulates tool history, so the working set is bounded across hundreds of tool calls (positioning, not injection).

The only external dependency is model_call: a callable (prompt, schema) -> text. Real providers wrap their generate_chat; tests pass a deterministic stub.

PositionedResult dataclass

The result of a positioned-tool-loop run.

event_stream property

The Operation State Machine event log (visibility / audit).

guard_prompt_budget(prompt, *, context_window, requested_max_tokens, count_tokens_fn=None, safety_margin=256, min_output_tokens=128)

Ensure prompt + the response never overflow the model's real context window.

This is the protocol-level context-overflow guard (input, tool-call frames, accumulated multi-turn/CSO state, and output are all covered because every call site - direct generation, tool positioning, continuation windows - funnels through the model_call this wraps). Returns (safe_prompt, safe_max_tokens):

  • safe_max_tokens is capped so prompt_tokens + safe_max_tokens + margin fits inside context_window (never less than min_output_tokens).
  • If the prompt itself is still too large to leave room for the minimum output, the earliest lines are trimmed (oldest carried-forward state/context) while the tail - the actual task/operation frame - is preserved intact.

provider_model_call(provider, *, temperature=0.2, max_tokens=1024)

Adapt a CRP LLMProvider into a positioned-loop model_call.

The structured-output schema is advisory here - the prompt instructs the model to emit JSON and parse_tool_call robustly extracts it; provider-native constrained decoding can be layered on later (CRP-SPEC-049 §4.4).

Every call is passed through :func:guard_prompt_budget using the provider's own context_window_size()/count_tokens() (mandatory on the LLMProvider ABC), so input, tool-call frames, continuation windows, and multi-turn state can never overflow the model's real context window - the guard adapts to whatever window the connected LLM (local or frontier) actually reports.

run_positioned(user_request, model_call, *, fabric=None, executor=None, profile=CapabilityProfile.FRONTIER, policy=None, context_facts=None, max_operations=12, oversight_required=None, governor=None, clarify_handler=None, hmac_key=None, prior_cso=None, max_continuation_windows=1)

Run the positioned-tool-loop for a request (CRP-SPEC-049/050).

Parameters:

Name Type Description Default
user_request str

The natural-language request.

 required
model_call ModelCall

(prompt, schema|None) -> text. The only LLM dependency.

 required
fabric ToolCapabilityFabric | None

Optional Tool Capability Fabric; if absent, operations are direct-generation.

 None
executor CapabilityExecutor | None

Optional capability executor; if absent, tool ops run in selection-only mode.

 None
profile CapabilityProfile

Capability profile bounding frame size (small-local 1–2 tools, etc.).

 FRONTIER
policy PolicyContext | None

Optional policy pre-filter / preventive-safety context.

 None
context_facts list[str] | None

Optional pre-retrieved facts for the first operations.

 None
max_operations int

Hard cap on operations (loop guard).

 12
hmac_key bytes | None

If provided, seals the CSO with an HMAC chain link.

 None
prior_cso CognitiveStateObject | None

Optional prior-turn CSO to relay forward (multi-turn workflows).

 None

stl.tool_positioner

crp.stl.tool_positioner

Tool Positioner - Operation Frame → Tool Positioning Frame (CRP-SPEC-050 §4.3).

The TCF decides which 1–3 capabilities serve the current operation; the Tool Positioner turns that decision into the minimal prompt fragment the model actually sees, and parses the model's structured tool-selection output. The model never sees the full catalogue - only the capabilities the protocol positioned it on.

CapabilitySlot dataclass

One capability offered in a Tool Positioning Frame.

ToolPositioningFrame dataclass

The 1–3 capabilities offered to the model for one operation (CRP-SPEC-050 §4.3).

capability_ids property

Ids of the offered capabilities.

to_prompt()

Render the operation frame + the offered tools as a compact instruction.

output_schema()

JSON schema constraining the model output to a tool selection (for constrained decoding).

ParsedToolCall dataclass

A tool selection parsed from the model's output.

is_tool_call property

Whether the model chose a tool (vs answering directly).

build_tool_positioning_frame(operation_frame, selection, *, profile=CapabilityProfile.FRONTIER, depth=None, structured_output_mode='json-schema')

Compose a Tool Positioning Frame from an operation frame and a TCF selection.

parse_tool_call(raw_output, frame)

Parse the model's tool-selection output against a positioning frame.

Returns a :class:ParsedToolCall. If the model answered directly (no tool), capability_id is None and answer carries the text. Returns None only when the output is unparseable AND there is no single obvious capability to default to.