crp.tools¶
Auto-generated reference for the crp.tools subpackage.
tools¶
crp.tools ¶
Tool Capability Fabric (TCF) - protocol-level tool selection (CRP-SPEC-050).
Positioning, not injection: the protocol selects the minimal 1–3 (up to 5–7 on frontier) capabilities relevant to the current STL operation, so the model is never flooded with the full tool catalogue.
Public API
CapabilityDescriptor, CostProfile, CapabilityKind, SafetyClass - the declaration ToolCapabilityFabric, CapabilityProfile, PolicyContext - the registry/selection CapabilitySelection, ScoredCapability, max_capabilities - selection results CapabilityExecutor, ToolObservation, ToolExecutionResult - execution ExecutionStatus, ToolResultExtractor, validate_arguments - execution helpers
CapabilityProfile ¶
Bases: str, Enum
Model execution profile - bounds how many tools a frame may contain (CRP-SPEC-049 §3.1).
CapabilitySelection dataclass ¶
PolicyContext dataclass ¶
The active policy pre-filter for capability selection (CRP-SPEC-050 §3.4).
Empty fields mean "no constraint". A capability with no data_residency or allowed_policy_domains is not restricted by those checks.
evaluate(cap) ¶
Return (allowed, reason); reason is the rejection cause when blocked.
ScoredCapability dataclass ¶
A capability with its selection score and the reason it was chosen.
ToolCapabilityFabric ¶
Registry + retrieval for capability descriptors (CRP-SPEC-050 §3).
register(descriptor) ¶
Register (or replace) a capability. Raises ValueError if invalid.
register_dict(data) ¶
Register a capability from its JSON form; returns the parsed descriptor.
unregister(capability_id) ¶
Remove a capability from the fabric.
get(capability_id) ¶
Return a registered capability by id, or None.
all() ¶
Return all registered capabilities.
retrieve(operation) ¶
Return capabilities whose operation_types include the operation (§4.1.2).
select(operation, query_text='', *, query_embedding=None, profile=CapabilityProfile.FRONTIER, policy=None, available_facts=None, k=None) ¶
Select the minimal positioned capability set for an operation (CRP-SPEC-050 §4.1).
CapabilityDescriptor dataclass ¶
A single capability registered in the Tool Capability Fabric (CRP-SPEC-050 §3.1).
operation_types is stored as canonical :class:STLOperation members; the JSON form uses uppercase tokens (RETRIEVE …) normalised on load.
description property ¶
Human-readable description from metadata, if present.
serves_operation(op) ¶
Return whether this capability serves the given cognitive operation.
required_inputs() ¶
Return the required argument names declared in input_schema.
from_dict(data) classmethod ¶
Build a descriptor from its JSON form, normalising operation tokens.
Unknown operation tokens are dropped with a warning rather than raising, so a single bad tag does not break registration of an otherwise valid tool.
to_dict() ¶
Render the descriptor as its canonical JSON form.
validate() ¶
Return a list of validation errors (empty list ⇒ valid).
Mirrors the required fields of schemas/capability-descriptor.json so callers can validate without a JSON-Schema dependency in the core.
CapabilityKind ¶
Bases: str, Enum
Runtime kind of a capability (CRP-SPEC-050 §3.2).
CostProfile dataclass ¶
SafetyClass ¶
Bases: str, Enum
Safety classification used for policy pre-filtering (CRP-SPEC-050 §3.4).
CapabilityExecutor ¶
Holds capability implementations and executes them into typed observations.
register_impl(capability_id, fn, extractor=None) ¶
Register the implementation (and optional result extractor) for a capability.
has_impl(capability_id) ¶
Return whether an implementation is registered for the capability.
execute(descriptor, args, operation, *, window_id='') ¶
Validate, execute, extract, and produce a :class:ToolObservation.
ExecutionStatus ¶
Bases: str, Enum
Outcome of a capability execution.
ToolExecutionResult dataclass ¶
The full result of attempting to execute a capability.
ok property ¶
True when execution succeeded and produced an observation.
ToolObservation dataclass ¶
A typed, provenanced fact produced by executing a capability (CRP-SPEC-050 §6.3).
Designed to convert losslessly into a CSO EstablishedFact (provenance=TOOL) in the Operation State Machine integration step.
to_dict() ¶
Render the observation as its CRP-SPEC-050 §6.3 JSON form.
descriptor_from_callable(fn, operation_types=None) ¶
Build a capability descriptor from a callable's signature and docstring.
fabric_from_callables(callables, operation_types=None) ¶
Build a Tool Capability Fabric + executor from plain callables.
The executor invokes each callable with keyword arguments parsed from the model's tool call (fn(**args)).
max_capabilities(profile) ¶
Return the maximum number of capabilities a frame may offer for a profile.
validate_arguments(descriptor, args) ¶
Validate call arguments against the capability input_schema (lightweight subset).
Checks required keys are present and that declared property types match. Full JSON-Schema validation is intentionally out of the zero-dependency core.
tools.adapters¶
crp.tools.adapters ¶
Adapters - build TCF capabilities from plain Python callables (CRP v5).
Lets the SDK's @client.tool functions (and any callables) participate in the positioned-tool-loop without hand-writing capability descriptors. Each callable becomes a :class:CapabilityDescriptor (input schema inferred from its signature) and a registered executor implementation.
descriptor_from_callable(fn, operation_types=None) ¶
Build a capability descriptor from a callable's signature and docstring.
fabric_from_callables(callables, operation_types=None) ¶
Build a Tool Capability Fabric + executor from plain callables.
The executor invokes each callable with keyword arguments parsed from the model's tool call (fn(**args)).
tools.capability_fabric¶
crp.tools.capability_fabric ¶
Tool Capability Fabric (TCF) - protocol-level tool selection (CRP-SPEC-050 §3–4).
The TCF is the registry + retrieval system that returns the MINIMAL relevant set of capabilities for the current STL operation. Tool selection is a protocol function, not an LLM function: the model never sees the full catalogue, only the 1–3 (or up to 5–7 on frontier) capabilities the protocol determined are relevant to THIS operation.
Selection algorithm (CRP-SPEC-050 §4.1): 1. Retrieve capabilities whose operation_types include the current operation. 2. Apply the policy pre-filter (§3.4). 3. Score by semantic similarity, intent overlap, schema compatibility, inverse cost. 4. Resolve dependencies (deps first) and mutual exclusions. 5. Take the top-K, where K is bounded by the model's capability profile.
Embeddings are optional and supplied by the caller (the TCF is zero-dependency); when absent, a deterministic lexical fallback is used.
PolicyContext dataclass ¶
The active policy pre-filter for capability selection (CRP-SPEC-050 §3.4).
Empty fields mean "no constraint". A capability with no data_residency or allowed_policy_domains is not restricted by those checks.
evaluate(cap) ¶
Return (allowed, reason); reason is the rejection cause when blocked.
ScoredCapability dataclass ¶
A capability with its selection score and the reason it was chosen.
CapabilitySelection dataclass ¶
ToolCapabilityFabric ¶
Registry + retrieval for capability descriptors (CRP-SPEC-050 §3).
register(descriptor) ¶
Register (or replace) a capability. Raises ValueError if invalid.
register_dict(data) ¶
Register a capability from its JSON form; returns the parsed descriptor.
unregister(capability_id) ¶
Remove a capability from the fabric.
get(capability_id) ¶
Return a registered capability by id, or None.
all() ¶
Return all registered capabilities.
retrieve(operation) ¶
Return capabilities whose operation_types include the operation (§4.1.2).
select(operation, query_text='', *, query_embedding=None, profile=CapabilityProfile.FRONTIER, policy=None, available_facts=None, k=None) ¶
Select the minimal positioned capability set for an operation (CRP-SPEC-050 §4.1).
tools.descriptor¶
crp.tools.descriptor ¶
Capability Descriptor - machine-readable declaration of a TCF capability (CRP-SPEC-050 §3).
A capability may be a local function, an MCP tool, a sub-agent, a database query, or a web service. The descriptor tells the protocol which STL operations the capability serves, what it consumes/produces, its cost, and how it is governed - so the Tool Capability Fabric can select it for an operation WITHOUT injecting its schema into the model's prompt (positioning, not injection).
The canonical JSON form is schemas/capability-descriptor.json.
CapabilityKind ¶
Bases: str, Enum
Runtime kind of a capability (CRP-SPEC-050 §3.2).
SafetyClass ¶
Bases: str, Enum
Safety classification used for policy pre-filtering (CRP-SPEC-050 §3.4).
CostProfile dataclass ¶
CapabilityDescriptor dataclass ¶
A single capability registered in the Tool Capability Fabric (CRP-SPEC-050 §3.1).
operation_types is stored as canonical :class:STLOperation members; the JSON form uses uppercase tokens (RETRIEVE …) normalised on load.
description property ¶
Human-readable description from metadata, if present.
serves_operation(op) ¶
Return whether this capability serves the given cognitive operation.
required_inputs() ¶
Return the required argument names declared in input_schema.
from_dict(data) classmethod ¶
Build a descriptor from its JSON form, normalising operation tokens.
Unknown operation tokens are dropped with a warning rather than raising, so a single bad tag does not break registration of an otherwise valid tool.
to_dict() ¶
Render the descriptor as its canonical JSON form.
validate() ¶
Return a list of validation errors (empty list ⇒ valid).
Mirrors the required fields of schemas/capability-descriptor.json so callers can validate without a JSON-Schema dependency in the core.
tools.executor¶
crp.tools.executor ¶
Capability Executor - runs a selected capability and produces a typed observation (CRP-SPEC-050 §6).
The executor is the bridge between a positioned tool selection and effect. It: 1. validates the model's arguments against the capability input_schema, 2. invokes the registered implementation, 3. runs the capability's :class:ToolResultExtractor to turn raw output into a structured payload (the per-tool-parser pattern - see WASA AI's _parse_* functions), and 4. emits a :class:ToolObservation - a typed, provenanced fact destined for the CSO.
Raw output is NEVER returned into the model's window; only the structured observation is stored (in the CSO) and the raw text is handed to the Scratch Buffer by the caller. This keeps the working set bounded across hundreds of tool calls (CRP-SPEC-029/030).
ExecutionStatus ¶
Bases: str, Enum
Outcome of a capability execution.
ToolObservation dataclass ¶
A typed, provenanced fact produced by executing a capability (CRP-SPEC-050 §6.3).
Designed to convert losslessly into a CSO EstablishedFact (provenance=TOOL) in the Operation State Machine integration step.
to_dict() ¶
Render the observation as its CRP-SPEC-050 §6.3 JSON form.
ToolExecutionResult dataclass ¶
The full result of attempting to execute a capability.
ok property ¶
True when execution succeeded and produced an observation.
CapabilityExecutor ¶
Holds capability implementations and executes them into typed observations.
register_impl(capability_id, fn, extractor=None) ¶
Register the implementation (and optional result extractor) for a capability.
has_impl(capability_id) ¶
Return whether an implementation is registered for the capability.
execute(descriptor, args, operation, *, window_id='') ¶
Validate, execute, extract, and produce a :class:ToolObservation.
validate_arguments(descriptor, args) ¶
Validate call arguments against the capability input_schema (lightweight subset).
Checks required keys are present and that declared property types match. Full JSON-Schema validation is intentionally out of the zero-dependency core.
tools.profiles¶
crp.tools.profiles ¶
Capability execution profiles (CRP-SPEC-049 §3.1).
A leaf module (no CRP imports) so that low-level consumers like the Resource Governor can reference the profile taxonomy without pulling in the full Tool Capability Fabric - which would create an import cycle.