Protocols

sakshi.protocols

Public protocols defining the Sakshi seam.

Hosts supply concrete implementations of these protocols; Sakshi's pure-core modules accept them by parameter so the package itself never depends on a specific runtime, persistence layer, web framework, or LLM SDK.

EventBus

Bases: Protocol

Async pub/sub seam for emitting cycle and goal events.

A host wraps its own bus implementation in an adapter that satisfies this protocol.

emit(event_type: str, payload: Mapping[str, Any]) -> None async

Clock

Bases: Protocol

Time source.

Allows tests and deterministic replays to substitute a fake clock.

now() -> datetime

GoalStateStore

Bases: Protocol

Goal-related world-state persistence and retrieval seam.

Hosts that persist world state in a graph database, vector store, or any other backend wrap that backend in an adapter implementing this protocol. Sakshi never imports a specific persistence layer.

fetch_world_state(query: Mapping[str, Any]) -> WorldStateSnapshot async

record_goal_outcome(record: GoalOutcomeRecord) -> None async

BasinHook

Bases: Protocol

Optional hook for hosts that maintain an attractor-basin field.

Sakshi calls these on goal lifecycle transitions. Hosts that do not use a basin field supply a no-op implementation; see NoOpBasinHook for the package default.

on_goal_achieved(goal_id: str) -> None async

on_goal_abandoned(goal_id: str) -> None async

WriteGuard

Bases: Protocol

Pre-write safety check seam.

Hosts can route Sakshi-originated writes through their own write- safety policy. Returns True if the write is permitted, False otherwise.

check(source_origin: str, payload: Mapping[str, Any]) -> bool async

NoOpBasinHook

Default BasinHook that does nothing.

Use this when the host does not maintain an attractor-basin field.

on_goal_achieved(goal_id: str) -> None async

on_goal_abandoned(goal_id: str) -> None async

NoOpEventBus

Default EventBus that drops emitted events.

emit(event_type: str, payload: Mapping[str, Any]) -> None async

AlwaysPermitWriteGuard

Default WriteGuard that permits every write.

Use this only in tests or in hosts where Sakshi-originated writes do not require external safety review.

check(source_origin: str, payload: Mapping[str, Any]) -> bool async

DenyByDefaultWriteGuard

Safe WriteGuard that denies every write until a host policy replaces it.

This is the right placeholder for production scaffolds: it preserves the protocol shape while failing closed instead of silently permitting writes. Tests and quickstarts can continue using AlwaysPermitWriteGuard when they deliberately do not exercise host write policy.

check(source_origin: str, payload: Mapping[str, Any]) -> bool async