Models¶
sakshi.models
¶
Sakshi data models: DTOs that cross the public API surface.
ESCALATION_THRESHOLDS: dict[str, int] = {'MONITOR': 0, 'WIDEN_PRECISION': 2, 'MUTATE_GOAL': 4, 'DELEGATE_HUMAN': 6}
module-attribute
¶
EscalationLevel = Literal['MONITOR', 'WIDEN_PRECISION', 'MUTATE_GOAL', 'DELEGATE_HUMAN']
module-attribute
¶
GOAL_OPERATION_EVENT_TYPE = 'sakshi.goal.op'
module-attribute
¶
Default event-type string for goal-operation publication.
AnomalyEscalation
¶
Bases: BaseModel
Tracks anomaly persistence and escalation state for a goal.
goal_id: str = Field(..., description='Goal experiencing repeated anomalies')
class-attribute
instance-attribute
¶
anomaly_count: int = Field(..., ge=0, description='Total anomaly occurrences for this goal')
class-attribute
instance-attribute
¶
current_level: EscalationLevel = Field(..., description='Current escalation level')
class-attribute
instance-attribute
¶
threshold_breached: bool = Field(..., description='Whether a new threshold was crossed this cycle')
class-attribute
instance-attribute
¶
recommended_action: str = Field(..., description='Natural language recommended response')
class-attribute
instance-attribute
¶
source: AnomalySourceType = Field(default=(AnomalySourceType.WORLD), description='Origin lane of the anomaly. WORLD anomalies trigger world-model corrections; COGNITIVE anomalies trigger meta-cycle adjustments; COMPOUND anomalies are decomposed before explanation.')
class-attribute
instance-attribute
¶
requires_human: bool
property
¶
Whether this escalation requires human intervention.
from_count(goal_id: str, anomaly_count: int, recommended_action: str = '', source: AnomalySourceType = AnomalySourceType.WORLD) -> AnomalyEscalation
classmethod
¶
Determine escalation level from anomaly count.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
goal_id
|
str
|
The goal being tracked. |
required |
anomaly_count
|
int
|
Current count of anomalies. |
required |
recommended_action
|
str
|
Optional action description. |
''
|
source
|
AnomalySourceType
|
Origin lane of the anomaly stream. Defaults to
|
WORLD
|
Returns:
| Type | Description |
|---|---|
AnomalyEscalation
|
An |
AnomalySourceType
¶
Bases: StrEnum
Origin lane of a detected anomaly.
WORLD anomalies are mismatches between expected and observed
environment state and trigger world-model corrections. COGNITIVE
anomalies are mismatches inside the agent's own reasoning trace
(impasse, expectation violation, plan deviation) and trigger
meta-cycle adjustments. COMPOUND anomalies present in both lanes
and are decomposed at detection, not at explanation.
BlackboardKey
¶
Bases: StrEnum
Typed keys for the cognitive blackboard.
- STATES: current world state (from PERCEIVE)
- GOALS: active goals (from INTEND)
- PLANS: current plans (from PLAN)
- ACTIONS: committed actions (from ACT)
- DISCREPANCY: detected discrepancies (from INTERPRET / EVAL)
- META_MONITOR: meta-loop monitoring data
- META_ASSESS: meta-loop assessment results
- META_CONTROL: meta-loop control actions
- CUSTOM: extension point for ad-hoc data
STATES = 'states'
class-attribute
instance-attribute
¶
GOALS = 'goals'
class-attribute
instance-attribute
¶
PLANS = 'plans'
class-attribute
instance-attribute
¶
ACTIONS = 'actions'
class-attribute
instance-attribute
¶
DISCREPANCY = 'discrepancy'
class-attribute
instance-attribute
¶
META_MONITOR = 'meta_monitor'
class-attribute
instance-attribute
¶
META_ASSESS = 'meta_assess'
class-attribute
instance-attribute
¶
META_CONTROL = 'meta_control'
class-attribute
instance-attribute
¶
CUSTOM = 'custom'
class-attribute
instance-attribute
¶
BlackboardSnapshot
¶
Bases: BaseModel
Immutable snapshot of blackboard state at a point in time.
Created at cycle finalize to record the full inter-phase state
alongside a CycleTrace.
AnomalyType
¶
ControlAction
¶
Bases: BaseModel
A metacognitive control action emitted by the meta-loop.
precision_delta (when set) carries a signed damping adjustment for
ADJUST_PRECISION actions routed to a host's active-inference layer.
Hosts typically clamp to a small range (e.g., [-0.3, +0.3]) at the
consumer.
action_type: ControlActionType
instance-attribute
¶
target: str = ''
class-attribute
instance-attribute
¶
magnitude: float = 1.0
class-attribute
instance-attribute
¶
rationale: str = ''
class-attribute
instance-attribute
¶
precision_delta: float | None = None
class-attribute
instance-attribute
¶
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
ControlActionType
¶
Bases: StrEnum
Types of metacognitive control actions emitted by the meta-loop.
REPLACE_MODULE is distinct from SWAP_MODULE: a swap
exchanges one already-registered service for another already-known
alternative, while a replace installs a fundamentally different
implementation (often after a host or operator decision that the
previous service class was unsuitable).
STRENGTHEN_MODULE = 'STRENGTHEN_MODULE'
class-attribute
instance-attribute
¶
SUPPRESS_MODULE = 'SUPPRESS_MODULE'
class-attribute
instance-attribute
¶
ADJUST_PRECISION = 'ADJUST_PRECISION'
class-attribute
instance-attribute
¶
SWAP_MODULE = 'SWAP_MODULE'
class-attribute
instance-attribute
¶
REPLACE_MODULE = 'REPLACE_MODULE'
class-attribute
instance-attribute
¶
CycleTrace
¶
Bases: BaseModel
Complete record of one cognitive cycle (all six phases).
cycle_id: str
instance-attribute
¶
phase_results: list[PhaseResult] = Field(default_factory=list)
class-attribute
instance-attribute
¶
np_state_at_intend: NPStateSnapshot | None = None
class-attribute
instance-attribute
¶
achieved_goals: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
started_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
finalized_at: datetime | None = None
class-attribute
instance-attribute
¶
get_phase_output(phase_name: str) -> dict[str, Any] | None
¶
Return the output for a specific phase, or None if not recorded.
NPState
¶
Bases: StrEnum
Neuronal Packet lifecycle states (Kavi et al. 2408.15982 §3.1).
UNMANIFESTED = 'Unmanifested'
class-attribute
instance-attribute
¶
INACTIVE = 'Inactive'
class-attribute
instance-attribute
¶
ACTIVATED = 'Activated'
class-attribute
instance-attribute
¶
DOMINANT = 'Dominant'
class-attribute
instance-attribute
¶
DISSIPATED = 'Dissipated'
class-attribute
instance-attribute
¶
NPStateSnapshot
¶
Bases: BaseModel
Snapshot of the dominant thought-seed's NP state at INTEND.
Captures which thought-seed won, its NP lifecycle state, and evolutionary prior type.
dominant_thoughtseed_id: str
instance-attribute
¶
np_state: str = Field(description='NP lifecycle state: Inactive | Activated | Dominant | Dissipated')
class-attribute
instance-attribute
¶
prior_type: str = Field(description='Evolutionary prior: B | L | D | λ')
class-attribute
instance-attribute
¶
captured_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
validate_np_state(v: str) -> str
classmethod
¶
validate_prior_type(v: str) -> str
classmethod
¶
OODAPhase
¶
PhaseConfig
¶
PhaseResult
¶
Bases: BaseModel
Output recorded for a single cycle phase.
PriorType
¶
Bases: StrEnum
Evolutionary prior taxonomy (Kavi et al. 2408.15982 §2.3).
B (Basal): universal across species, survival/threat. Longer baseline. L (Lineage-specific): species-characteristic. D (Dispositional): individual temperamental. λ (Learned): session/experience-acquired. Shorter baseline.
DiscrepancyResolution
¶
Bases: BaseModel
End-to-end record of one symptom-to-plan resolution chain.
The four payload fields mirror the four canonical steps. They are
typed as str rather than richer DTOs because callers wire in
their own world-model, explanation, goal, and plan representations
through the existing GoalStateStore and explanation seams; this
DTO is the join row that ties them together.
cycle_id: str
instance-attribute
¶
level: ResolutionLevel
instance-attribute
¶
source: AnomalySourceType = Field(default=(AnomalySourceType.WORLD), description='Origin lane of the discrepancy. Object-level resolutions default to WORLD; meta-level resolutions should override to COGNITIVE; bridging cases use COMPOUND.')
class-attribute
instance-attribute
¶
symptom: str = Field(..., description='What was observed that diverged from expectation.')
class-attribute
instance-attribute
¶
explanation: str = Field(..., description='Best causal hypothesis linking symptom to a fixable cause.')
class-attribute
instance-attribute
¶
goal_id: str | None = Field(default=None, description='ID of the goal formulated to resolve the cause, if any.')
class-attribute
instance-attribute
¶
plan_id: str | None = Field(default=None, description='ID of the plan generated to achieve the goal, if any.')
class-attribute
instance-attribute
¶
confidence: float = Field(default=0.5, ge=0.0, le=1.0, description='Confidence the host attaches to the explanation step.')
class-attribute
instance-attribute
¶
metadata: dict[str, Any] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
recorded_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
ResolutionLevel
¶
Bases: StrEnum
Whether a discrepancy was resolved at the object or meta level.
Object-level discrepancies are mismatches between expected and observed environment state. Meta-level discrepancies are mismatches inside the agent's own reasoning trace (impasse, expectation violation on a phase output, plan deviation).
ActionExecutionResult
¶
Bases: BaseModel
Result of one action execution.
ActionExecutionStatus
¶
GoalExecutionSummary
¶
Bases: BaseModel
Execution summary for a focused goal.
focus_goal_id: str | None = None
class-attribute
instance-attribute
¶
action_results: list[ActionExecutionResult] = Field(default_factory=list)
class-attribute
instance-attribute
¶
plan_steps: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
cycle_id: str | None = None
class-attribute
instance-attribute
¶
CognitiveExpectation
¶
Bases: BaseModel
A formal expectation about cognitive phase behavior.
The pre and post condition keys reference blackboard keys or phase output fields. An evaluator checks the relationship between the pre-phase and post-phase values.
expectation_id: str
instance-attribute
¶
phase_name: str = Field(description='Phase this expectation guards: PERCEIVE | INTERPRET | EVAL | INTEND | PLAN | ACT')
class-attribute
instance-attribute
¶
description: str = ''
class-attribute
instance-attribute
¶
severity: ExpectationSeverity = ExpectationSeverity.WARNING
class-attribute
instance-attribute
¶
pre_condition_key: str = Field(default='', description='Blackboard key or phase output field to check BEFORE the phase')
class-attribute
instance-attribute
¶
post_condition_key: str = Field(default='', description='Blackboard key or phase output field to check AFTER the phase')
class-attribute
instance-attribute
¶
relationship: str = Field(default='exists', description='Expected relationship between pre and post values: exists | changed | increased | decreased | equals')
class-attribute
instance-attribute
¶
expected_value: Any | None = None
class-attribute
instance-attribute
¶
ExpectationProfile
¶
Bases: BaseModel
Five-property contract a module registers with Sakshi.
The five fields are the typed-monitoring surface: every module that participates in a cycle declares what it is supposed to do, and Sakshi watches the running module against that declaration.
Attributes:
| Name | Type | Description |
|---|---|---|
module_name |
str
|
Identifier for the module the profile guards. |
runtime_bound_seconds |
float
|
Maximum acceptable wall-clock time for
the module's primary entry point. Violations are warnings
unless the module also declares the failure mode
|
output_schema |
dict[str, Any] | str
|
Description of the shape the module is expected to return. Accepts a JSON-schema-like dict, a Python type name (string), or a fully-qualified class path. Sakshi does not enforce the schema — it stores it so observers can validate against it. |
confidence_range |
tuple[float, float]
|
Inclusive [low, high] bounds on the module's self-reported confidence. Used by the calibration tracker to detect drift outside the declared band. |
side_effects_contract |
tuple[str, ...]
|
Tuple of strings naming the modules, blackboard keys, or external services this module is allowed to mutate. Anything outside the contract is a scope violation. |
failure_modes |
tuple[FailureMode, ...]
|
Tuple of |
module_name: str
instance-attribute
¶
runtime_bound_seconds: float = Field(default=2.0, ge=0.0, description='Maximum acceptable wall-clock time for the module call.')
class-attribute
instance-attribute
¶
output_schema: dict[str, Any] | str = Field(default_factory=dict, description='JSON-schema-like dict, type name, or class path.')
class-attribute
instance-attribute
¶
confidence_range: tuple[float, float] = Field(default=(0.0, 1.0), description='Inclusive [low, high] bounds on self-reported confidence.')
class-attribute
instance-attribute
¶
side_effects_contract: tuple[str, ...] = Field(default_factory=tuple, description='Module / blackboard / service names this module may mutate.')
class-attribute
instance-attribute
¶
failure_modes: tuple[FailureMode, ...] = Field(default_factory=tuple, description='Admissible failure shapes the module declares up front.')
class-attribute
instance-attribute
¶
confidence_in_band(confidence: float) -> bool
¶
Return whether confidence falls inside the declared band.
is_declared_failure(name: str) -> bool
¶
Return whether name matches a declared failure mode.
has_side_effect(target: str) -> bool
¶
Return whether target is inside the declared side-effects contract.
ExpectationSeverity
¶
ExpectationViolation
¶
Bases: BaseModel
Record of a violated cognitive expectation.
expectation_id: str
instance-attribute
¶
phase_name: str
instance-attribute
¶
cycle_id: str
instance-attribute
¶
severity: ExpectationSeverity
instance-attribute
¶
description: str
instance-attribute
¶
pre_value: Any | None = None
class-attribute
instance-attribute
¶
post_value: Any | None = None
class-attribute
instance-attribute
¶
detected_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
FailureMode
¶
Goal
¶
Bases: BaseModel
A single goal in the goal graph.
id: str
instance-attribute
¶
predicate: GoalPredicate
instance-attribute
¶
basin_name: str = ''
class-attribute
instance-attribute
¶
status: GoalStatus = GoalStatus.ACTIVE
class-attribute
instance-attribute
¶
mode: GoalMode = GoalMode.FORMULATING
class-attribute
instance-attribute
¶
transitions: list[GoalEvent] = Field(default_factory=list)
class-attribute
instance-attribute
¶
priority: int = 1
class-attribute
instance-attribute
¶
prior_type: str = 'λ'
class-attribute
instance-attribute
¶
source: str = ''
class-attribute
instance-attribute
¶
description: str = ''
class-attribute
instance-attribute
¶
metadata: dict[str, Any] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
goal_type: Literal['achievement', 'maintenance', 'avoidance'] = 'achievement'
class-attribute
instance-attribute
¶
prior_preference_vector: list[float] | None = None
class-attribute
instance-attribute
¶
expected_efe: float | None = None
class-attribute
instance-attribute
¶
is_terminal() -> bool
¶
True if the goal is no longer in active consideration.
record_transition(*, event_type: GoalEventType, to_mode: GoalMode | None = None, cause: str = '', cycle_id: str | None = None) -> GoalEvent
¶
Append a lifecycle transition event and update mode.
Returns the recorded event so callers can attach it to a trace or emit it on the host event bus.
GoalEvent
¶
Bases: BaseModel
One transition record in a goal's lifecycle history.
event_type: GoalEventType
instance-attribute
¶
from_mode: GoalMode | None = None
class-attribute
instance-attribute
¶
to_mode: GoalMode | None = None
class-attribute
instance-attribute
¶
cause: str = Field(default='', description='Short human-readable reason for the transition')
class-attribute
instance-attribute
¶
cycle_id: str | None = None
class-attribute
instance-attribute
¶
occurred_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
GoalEventType
¶
Bases: StrEnum
Causes of a transition recorded on a goal's event history.
FORMULATED = 'formulated'
class-attribute
instance-attribute
¶
SELECTED = 'selected'
class-attribute
instance-attribute
¶
DISPATCHED = 'dispatched'
class-attribute
instance-attribute
¶
MONITOR_OK = 'monitor_ok'
class-attribute
instance-attribute
¶
MONITOR_VIOLATION = 'monitor_violation'
class-attribute
instance-attribute
¶
REPAIR_STARTED = 'repair_started'
class-attribute
instance-attribute
¶
REPAIR_COMPLETED = 'repair_completed'
class-attribute
instance-attribute
¶
DEFERRED = 'deferred'
class-attribute
instance-attribute
¶
RESUMED = 'resumed'
class-attribute
instance-attribute
¶
COMPLETED = 'completed'
class-attribute
instance-attribute
¶
GoalMode
¶
Bases: StrEnum
Active-phase axis for a goal in flight.
Mirrors the goal-lifecycle-network state machine: a goal is
formulated, then selected and dispatched into execution, then
monitored, then either repaired or deferred when monitoring finds
trouble. COMPLETED is a terminal mode independent of whether
GoalStatus recorded the close as ACHIEVED or ABANDONED.
FORMULATING = 'formulating'
class-attribute
instance-attribute
¶
SELECTED = 'selected'
class-attribute
instance-attribute
¶
DISPATCHED = 'dispatched'
class-attribute
instance-attribute
¶
MONITORING = 'monitoring'
class-attribute
instance-attribute
¶
REPAIRING = 'repairing'
class-attribute
instance-attribute
¶
DEFERRED = 'deferred'
class-attribute
instance-attribute
¶
COMPLETED = 'completed'
class-attribute
instance-attribute
¶
GoalOutcomeRecord
¶
Bases: BaseModel
Structured runtime outcome record for a goal closure.
goal_id: str
instance-attribute
¶
instruction_id: str | None = None
class-attribute
instance-attribute
¶
cycle_id: str | None = None
class-attribute
instance-attribute
¶
predicate_name: str = ''
class-attribute
instance-attribute
¶
outcome_status: GoalStatus
instance-attribute
¶
reason: str = ''
class-attribute
instance-attribute
¶
delegate_to: str | None = None
class-attribute
instance-attribute
¶
action_statuses: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
action_count: int = 0
class-attribute
instance-attribute
¶
completed_count: int = 0
class-attribute
instance-attribute
¶
failed_count: int = 0
class-attribute
instance-attribute
¶
deferred_count: int = 0
class-attribute
instance-attribute
¶
plan_steps: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
recorded_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
GoalPlan
¶
Bases: BaseModel
A plan associated with a goal (sequence of steps to achieve it).
GoalPredicate
¶
Bases: BaseModel
Predicate representation for a goal state.
Example: GoalPredicate(name="ON", args={"object": "A", "surface": "table"}).
Inspired by MIDCA-style predicate-based world models.
GoalStatus
¶
Bases: StrEnum
Goal lifecycle status (terminal-state axis).
ComputationalMotivationMetrics
dataclass
¶
Summary of motivation quality over a recent window.
All four fields are bounded scalars in [0, 1] so a host can route on them with simple thresholds.
diversity_score: Shannon entropy of the motivation-type distribution divided bylog2(num_types_present).1.0means every type fired equally; lower means a single drive is dominating.stability_score:1.0 - (acceptance-rate variance over a sliding window). Lower means the host is oscillating between accepting and rejecting motivation impulses.risk_assessment: rolling fraction of events taggedPOWERorSURPRISE(the two motivation classes flagged in the literature as risk-correlated). Higher means more risk-seeking motivation.communication_cost: rolling fraction of events with a non-emptyreasonfield. Approximates how much human-facing narrative the motivation system is producing.
CreativityEnvelope
dataclass
¶
Bounds on the host's motivation creativity.
The envelope is host-declared. Sakshi observes a proposed goal-from-motivation against it; goals that fall outside the envelope are rejected and the rejection is logged.
Attributes:
| Name | Type | Description |
|---|---|---|
allowed_predicates |
tuple[str, ...]
|
Predicate names a motivated goal MAY use. Empty tuple means no constraint. |
forbidden_attributes |
tuple[str, ...]
|
Predicate-argument keys the goal MUST
NOT contain. The classic example is |
max_novelty_score |
float
|
Highest acceptable novelty scalar (host- scored, in [0, 1]). Defaults to 1.0 (no cap). |
forbidden_motivation_types |
tuple[MotivationType, ...]
|
Motivation types forbidden from
generating goals at all. |
allowed_predicates: tuple[str, ...] = ()
class-attribute
instance-attribute
¶
forbidden_attributes: tuple[str, ...] = ()
class-attribute
instance-attribute
¶
max_novelty_score: float = 1.0
class-attribute
instance-attribute
¶
forbidden_motivation_types: tuple[MotivationType, ...] = ()
class-attribute
instance-attribute
¶
description: str = ''
class-attribute
instance-attribute
¶
EnvelopeVerdict
dataclass
¶
GoalRelevanceFilter
dataclass
¶
Filter a motivated goal against a host-defined value taxonomy.
Hosts declare a tuple of allowed_value_tags. A goal proposed
by the motivation system carries one or more value tags (in
Goal.metadata['value_tags'] by convention); the filter accepts
only goals whose tags overlap with the allowed list.
Attributes:
| Name | Type | Description |
|---|---|---|
allowed_value_tags |
tuple[str, ...]
|
Tags the host considers organizationally valuable. Empty tuple short-circuits to "accept any". |
require_value_tag |
bool
|
When |
MotivationEvent
¶
Bases: BaseModel
One immutable record describing a motivation activation.
Hosts emit one of these every time their motivation system produces (or refuses to produce) a goal. The auditor stores them.
motivation_type: MotivationType
instance-attribute
¶
goal_id: str | None = Field(default=None, description='ID of the goal produced by this motivation. ``None`` when the activation was rejected by the envelope.')
class-attribute
instance-attribute
¶
cycle_id: str | None = None
class-attribute
instance-attribute
¶
accepted: bool = Field(default=True, description='True if the resulting goal was accepted into the goal graph; False if the envelope or relevance filter rejected it.')
class-attribute
instance-attribute
¶
reason: str = ''
class-attribute
instance-attribute
¶
occurred_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
MotivationType
¶
Bases: StrEnum
Coarse taxonomy of motivation sources.
Hosts tag every intrinsic goal with the type that produced it so audit logs and the metrics view show motivation diversity without the host having to reverse-engineer it from goal predicates.
ACHIEVEMENT = 'achievement'
class-attribute
instance-attribute
¶
AFFILIATION = 'affiliation'
class-attribute
instance-attribute
¶
POWER = 'power'
class-attribute
instance-attribute
¶
NOVELTY = 'novelty'
class-attribute
instance-attribute
¶
COMPETENCE = 'competence'
class-attribute
instance-attribute
¶
SURPRISE = 'surprise'
class-attribute
instance-attribute
¶
EXTRINSIC = 'extrinsic'
class-attribute
instance-attribute
¶
UNCLASSIFIED = 'unclassified'
class-attribute
instance-attribute
¶
GoalOperation
¶
Bases: StrEnum
A typed verb describing what just happened to a goal.
The first nine entries form the canonical goal-reasoning lifecycle
(formulate, select, expand, commit, dispatch, monitor, evaluate,
repair, defer). DELEGATE and RESUME cover handoff and
deferred-goal restart, which the canonical lifecycle does not name
explicitly.
FORMULATE = 'formulate'
class-attribute
instance-attribute
¶
SELECT = 'select'
class-attribute
instance-attribute
¶
EXPAND = 'expand'
class-attribute
instance-attribute
¶
COMMIT = 'commit'
class-attribute
instance-attribute
¶
DISPATCH = 'dispatch'
class-attribute
instance-attribute
¶
MONITOR = 'monitor'
class-attribute
instance-attribute
¶
EVALUATE = 'evaluate'
class-attribute
instance-attribute
¶
REPAIR = 'repair'
class-attribute
instance-attribute
¶
DEFER = 'defer'
class-attribute
instance-attribute
¶
DELEGATE = 'delegate'
class-attribute
instance-attribute
¶
RESUME = 'resume'
class-attribute
instance-attribute
¶
GoalOperationEvent
¶
Bases: BaseModel
An emitted record of a single goal operation.
Hosts subscribe to goal.op events on the configured EventBus
to receive these. The package itself never publishes directly; it
constructs the DTO and hands it to whichever bus the host injected.
operation: GoalOperation
instance-attribute
¶
goal_id: str
instance-attribute
¶
cycle_id: str | None = None
class-attribute
instance-attribute
¶
cause: str = Field(default='', description='Short human-readable reason for the operation')
class-attribute
instance-attribute
¶
metadata: dict[str, Any] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
occurred_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
ProjectionTransparency
¶
Bases: BaseModel
Tier-3 disclosure: forecasts and risk estimates.
cycle_id: str
instance-attribute
¶
horizon_steps: int = Field(default=1, ge=1)
class-attribute
instance-attribute
¶
forecast_states: list[dict[str, Any]] = Field(default_factory=list)
class-attribute
instance-attribute
¶
resource_forecast: dict[str, float] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
risk_estimates: dict[str, float] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
captured_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
ReasoningTransparency
¶
Bases: BaseModel
Tier-2 disclosure: the most recent decision's reasoning chain.
cycle_id: str
instance-attribute
¶
selected_motivator: str = Field(default='', description='What drove the decision (anomaly, intrinsic goal, instruction)')
class-attribute
instance-attribute
¶
candidate_explanations: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
chosen_explanation: str = ''
class-attribute
instance-attribute
¶
choice_rationale: str = ''
class-attribute
instance-attribute
¶
confidence: float = Field(default=0.0, ge=0.0, le=1.0)
class-attribute
instance-attribute
¶
captured_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
StatusTransparency
¶
Bases: BaseModel
Tier-1 disclosure: current state and active goals.
cycle_id: str
instance-attribute
¶
current_phase: str = ''
class-attribute
instance-attribute
¶
active_goal_ids: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
pending_plan_ids: list[str] = Field(default_factory=list)
class-attribute
instance-attribute
¶
summary: str = ''
class-attribute
instance-attribute
¶
captured_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
TransparencyLevel
¶
Bases: StrEnum
The three published transparency tiers.
STATUS is the lightest disclosure — current state and active
goals only. REASONING adds the chain that produced the most
recent decision: which motivator fired, which candidate
explanations were considered, why the chosen one won. PROJECTION
adds forward-looking forecasts: expected next states, resource
forecasts, risk estimates.
TrustBifurcation
¶
Bases: BaseModel
Two-axis self-trust scalar attached to an event or report.
competence_confidence reports how reliable the producing
capability is, given recent calibration; integrity_confidence
reports how trustworthy the signal pipeline is. A single integrity
breach can collapse trust faster than competence drift; the
separation gives operators a typed handle.
competence_confidence: float = Field(default=0.5, ge=0.0, le=1.0, description='Reliability of the capability that produced this output.')
class-attribute
instance-attribute
¶
integrity_confidence: float = Field(default=1.0, ge=0.0, le=1.0, description='Trust that the signal itself was not tampered with, censored, or otherwise compromised in transit.')
class-attribute
instance-attribute
¶
aggregate: float
property
¶
Single scalar combining both axes via the geometric mean.
The geometric mean penalizes a weakness on either axis: a competent capability with a compromised pipeline scores low, and vice versa.
TrustRepairAction
¶
Bases: StrEnum
Typed repair move a host may take after a degraded trust report.
GATHER_EVIDENCE = 'gather_evidence'
class-attribute
instance-attribute
¶
WIDEN_HYPOTHESES = 'widen_hypotheses'
class-attribute
instance-attribute
¶
RECALIBRATE_MODULE = 'recalibrate_module'
class-attribute
instance-attribute
¶
VERIFY_INTEGRITY = 'verify_integrity'
class-attribute
instance-attribute
¶
ESCALATE_TO_OPERATOR = 'escalate_to_operator'
class-attribute
instance-attribute
¶
REFRAME_MODEL = 'reframe_model'
class-attribute
instance-attribute
¶
TrustRepairRecommendation
¶
Bases: BaseModel
Typed recommendation for restoring or routing trust.
Sakshi records the recommended repair but does not execute it. Hosts decide whether the action means collecting sensor evidence, adjusting module profiles, escalating to an operator, or trying a different model family.
action: TrustRepairAction
instance-attribute
¶
reason: str = Field(min_length=1, description='Why this repair action is recommended.')
class-attribute
instance-attribute
¶
target: str = Field(default='', description='Optional host label for the affected module, goal, plan, or signal.')
class-attribute
instance-attribute
¶
severity: float = Field(default=0.5, ge=0.0, le=1.0, description='How urgently the host should consider this repair.')
class-attribute
instance-attribute
¶
uncertainty_boundary: UncertaintyBoundary | None = Field(default=None, description='Optional boundary classification that motivated the repair.')
class-attribute
instance-attribute
¶
evidence_needed: tuple[str, ...] = Field(default_factory=tuple, description='Host-specific evidence keys that would support the repair.')
class-attribute
instance-attribute
¶
TrustReport
¶
Bases: BaseModel
Composite host-facing trust DTO.
Bundles the bifurcation, uncertainty type, list of competing
hypothesis labels (when uncertainty_type == AMBIGUITY), a
calibration status string, a coarse trajectory band, and a
machine-readable recommendation. Hosts surface this to humans or
to downstream automation.
cycle_id: str
instance-attribute
¶
subject: str = Field(default='', description="What the report is about: 'goal:gid', 'anomaly:event-7', 'plan:p-3', etc. Free-form for host convenience.")
class-attribute
instance-attribute
¶
trust: TrustBifurcation = Field(default_factory=TrustBifurcation)
class-attribute
instance-attribute
¶
uncertainty_type: UncertaintyType = UncertaintyType.PROBABILITY
class-attribute
instance-attribute
¶
uncertainty_boundary: UncertaintyBoundary = UncertaintyBoundary.STOCHASTIC
class-attribute
instance-attribute
¶
competing_hypothesis_labels: tuple[str, ...] = Field(default_factory=tuple)
class-attribute
instance-attribute
¶
calibration_status: str = Field(default='unknown', description="Free-form label: 'well_calibrated', 'overconfident', 'underconfident', 'unknown'.")
class-attribute
instance-attribute
¶
trajectory: str = Field(default='stable', description="Coarse band: 'improving', 'stable', 'deteriorating', 'at_risk_of_collapse'.")
class-attribute
instance-attribute
¶
recommendation: str = Field(default='', description="Free-form, host-facing: 'safe_to_automate', 'verify_before_action', 'escalate'.")
class-attribute
instance-attribute
¶
repair_recommendations: tuple[TrustRepairRecommendation, ...] = Field(default_factory=tuple, description='Typed trust-repair recommendations hosts may route or surface.')
class-attribute
instance-attribute
¶
notes: str = ''
class-attribute
instance-attribute
¶
created_at: datetime = Field(default_factory=(lambda: datetime.now(UTC)))
class-attribute
instance-attribute
¶
UncertaintyBoundary
¶
Bases: StrEnum
Where the uncertainty appears to live.
UncertaintyType answers what kind of confidence statement the
report is making. UncertaintyBoundary answers what response the
host should consider: gather samples, widen hypotheses, admit there
is no model, or reframe the model itself.
STOCHASTIC = 'stochastic'
class-attribute
instance-attribute
¶
AMBIGUOUS = 'ambiguous'
class-attribute
instance-attribute
¶
IGNORANT = 'ignorant'
class-attribute
instance-attribute
¶
EPISTEMIC = 'epistemic'
class-attribute
instance-attribute
¶
ONTOLOGICAL = 'ontological'
class-attribute
instance-attribute
¶
UncertaintyType
¶
Bases: StrEnum
What kind of uncertainty a confidence value reflects.
PROBABILITY— classical: the output is one of N hypotheses, and confidence reports the modeled probability.AMBIGUITY— multiple competing hypotheses are roughly equiprobable; the host should hedge.IGNORANCE— no model; confidence is a placeholder.
WorldStateSnapshot
¶
Bases: BaseModel
Lightweight snapshot of the current world state.
Maps predicate name → args dict (one entry per active predicate instance).
Example
WorldStateSnapshot(facts={"CLEAR": {}})
evaluate_envelope(*, envelope: CreativityEnvelope, motivation_type: MotivationType, predicate_name: str, predicate_args: dict[str, object] | None = None, novelty_score: float = 0.0) -> EnvelopeVerdict
¶
Decide whether a candidate motivation+goal fits the envelope.
The function is pure: same inputs produce the same verdict.
Hosts pass the verdict through MotivationAuditor and to their
own goal-acceptance logic.