crp.cognition¶
Auto-generated reference for the crp.cognition subpackage.
cognition¶
crp.cognition ¶
User-defined cognition layer for CRP agents (CRP-SPEC-046 §2).
crp.cognition lets users declare thinking presets, reasoning scaffolds, operating modes, safeguards, emotions, and tool/knowledge bundles in simple YAML or Python and apply them to crp.Agent. A preset turns the user's intent into a compiled agent configuration: system prompt enrichment, policy context, operation-sequence hints, registered tools, output-format constraints, and optional emotion/safeguard hooks.
Example::
import crp
from crp.cognition import CognitivePreset
agent = crp.Agent(model="local/llama3.1", preset="socratic_tutor")
result = agent.run("Explain quantum computing")
PresetCompiler ¶
Compile a :class:CognitivePreset into a :class:CompiledPreset.
compile() ¶
Return a runtime-ready configuration.
CognitivePreset dataclass ¶
A complete user-defined thinking/reasoning/operating preset.
A preset is a declarative bundle of
- persona (who the agent is)
- reasoning scaffold (how it thinks)
- operating modes (when to change behavior)
- safeguards (hard rules)
- emotions / affect (optional)
- output profile (length, format, tone)
- tool/knowledge bundles
EmotionConfig dataclass ¶
Optional affect preset and emotion-recognition hook.
OutputProfile dataclass ¶
Constraints on the agent's output.
ReasoningPhase dataclass ¶
One phase in a reasoning scaffold.
ReasoningScaffold dataclass ¶
An ordered list of phases that guide the agent's thinking process.
Safeguard dataclass ¶
A declarative safety rule attached to a preset.
ToolBundle dataclass ¶
A named bundle of tools and knowledge sources a preset can reference.
cognition.compiler¶
crp.cognition.compiler ¶
cognition.emotion¶
crp.cognition.emotion ¶
Lightweight emotion/affect detection for cognitive presets (CRP-SPEC-046 §2.2).
The default detector is rule-based and runs locally with no model dependencies. When transformers is available, a preset can opt into an ML recognizer via emotions.recognizer: ml; if the model is missing or slow, the rule-based fallback is used automatically.
detect_emotion(text, *, top_n=2) ¶
Return rule-based affect labels and scores for text.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text | str | User message or tool output to classify. | required |
top_n | int | Number of top affect labels to return. | 2 |
Returns:
| Type | Description |
|---|---|
dict[str, Any] | Dict with |
detect_emotion_ml(text, *, model_id='j-hartmann/emotion-english-distilroberta-base') ¶
Optional ML-based emotion recognition with graceful fallback.
This is intentionally not a hard dependency. If transformers is not installed or the model cannot load, the rule-based detector is used.
cognition.loader¶
crp.cognition.loader ¶
Load cognitive presets from YAML, JSON, Python dicts, or the built-in library.
load_preset(source) ¶
Load a preset from a file path or a dict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source | str | Path | dict[str, Any] | Path to a YAML/JSON file, or a dict with the preset schema. | required |
Returns:
| Name | Type | Description |
|---|---|---|
A | CognitivePreset | class: |
list_builtin_presets() ¶
Return metadata for all built-in presets.
resolve_preset_id(preset_id) ¶
Load a built-in preset by id, or by file path if it exists.
cognition.phase_machine¶
crp.cognition.phase_machine ¶
Hard-enforced reasoning-phase state machine (CRP-SPEC-046 §2.3).
A CognitivePreset's reasoning.phases[] is not merely a prompt hint. When a preset is loaded, :class:PhasePlan compiles the phases into an explicit operation plan that the positioned loop follows step-by-step. Each phase restricts which STL operation may run and which tools may be selected, so the agent's reasoning process becomes a protocol-level state machine rather than a best-effort instruction.
Tool semantics per phase
toolsomitted ornull→ no tool restriction.tools: []→ no tools are allowed in this phase.tools: ["id1", "id2"]→ only those tools may be selected.
Phase dataclass ¶
One hard-enforced phase of a reasoning scaffold.
operation property ¶
The single STL operation this phase executes.
allows_tool(capability_id) ¶
Return True when the phase does not restrict tools or includes this one.
None means no restriction. An explicit empty list means no tools are allowed in this phase.
allows_operation(operation) ¶
Return True when the phase does not restrict operations or includes this one.
PhasePlan dataclass ¶
Compiled, ordered plan of reasoning phases.
to_operations() ¶
Return the STL operation sequence the positioned loop should execute.
copy() ¶
Return an independent copy so each run advances its own cursor.
to_dict() ¶
Return a serialisable representation of the phase plan.
advance() ¶
Move to the next phase and return it, or None if finished.
violation_frame(*, operation=None, capability_id='') ¶
Build a preventive-safety halt frame for a phase-plan violation.
from_reasoning_scaffold(phases, loop_until='complete') classmethod ¶
Build a PhasePlan from raw preset phase dicts.
cognition.preset¶
crp.cognition.preset ¶
Data model for user-defined cognitive presets (CRP-SPEC-046 §2.1).
ReasoningPhase dataclass ¶
One phase in a reasoning scaffold.
ReasoningScaffold dataclass ¶
An ordered list of phases that guide the agent's thinking process.
Safeguard dataclass ¶
A declarative safety rule attached to a preset.
EmotionConfig dataclass ¶
Optional affect preset and emotion-recognition hook.
OutputProfile dataclass ¶
Constraints on the agent's output.
ToolBundle dataclass ¶
A named bundle of tools and knowledge sources a preset can reference.
CognitivePreset dataclass ¶
A complete user-defined thinking/reasoning/operating preset.
A preset is a declarative bundle of
- persona (who the agent is)
- reasoning scaffold (how it thinks)
- operating modes (when to change behavior)
- safeguards (hard rules)
- emotions / affect (optional)
- output profile (length, format, tone)
- tool/knowledge bundles
cognition.safeguard¶
crp.cognition.safeguard ¶
Runtime safeguard engine for cognitive presets (CRP-SPEC-046 §2.4).
Safeguards declared in a preset are evaluated at runtime against user input, tool selections, tool arguments, and generated output. They are advisory or enforcing depending on their action (warn, ask, halt). The engine returns a structured result that the agent loop can act on.