API Reference

Complete reference for all public classes and methods in the alethic package.

Kernel

alethic.kernel.Kernel — The central orchestrator. Manages the blackboard, enforces permissions, and runs validation pipelines.

Constructor

Kernel(
    min_confidence: float = 0.5,
    conflict_confidence_threshold: float = 0.7,
    store: Optional[StoreProtocol] = None,
)

Methods

write()

write(
    role: Role,
    slot: Slot,
    mode: WriteMode,
    kind: str,
    payload: Dict[str, Any],
    trace_id: str,
    input_refs: Optional[List[str]] = None,
    confidence: Optional[float] = None,
    ttl_ms: Optional[int] = None,
    evidence_refs: Optional[List[str]] = None,
    scope: Literal["episode", "persistent"] = "episode",
) -> Record

Write a record to the blackboard. Raises PermissionError if the role is not authorized for the given slot+mode combination.

Returns the created Record.

current_view()

current_view(
    trace_id: str,
    include_persistent: bool = False,
) -> Dict[str, Dict[str, Any]]

Returns a snapshot of the blackboard for a given trace. The result maps each slot name to its contents. Committed records appear as slot[kind] = payload. Proposals appear under slot["_proposals"].

commit_belief_from_proposal()

commit_belief_from_proposal(
    proposal_id: str,
    trace_id: str,
) -> Tuple[bool, str]

Validate and commit a belief proposal. Runs evidence validation, confidence checks, and conflict arbitration.

validate_plan()

validate_plan(
    proposal_id: str,
    trace_id: str,
) -> Tuple[bool, str]

Pre-flight feasibility check on a plan proposal.

commit_prediction()

commit_prediction(
    proposal_id: str,
    trace_id: str,
) -> Tuple[bool, str]

Validate and commit a prediction proposal.

commit_action_from_proposal()

commit_action_from_proposal(
    proposal_id: str,
    trace_id: str,
    require_prediction: bool = False,
) -> Tuple[bool, str]

Validate and commit an action proposal. Optionally gates on predictions.

Schema

Record

alethic.schema.Record — A single entry on the blackboard.

@dataclass
class Record:
    id: str                                              # Auto-generated: "{slot}:{trace_id}:{n}"
    slot: Slot                                           # Target slot
    mode: WriteMode                                      # "PROPOSE" or "COMMIT"
    kind: str                                            # Record kind identifier
    payload: Dict[str, Any]                              # Arbitrary data
    prov: Provenance                                     # Provenance metadata
    evidence_refs: List[str] = []                        # IDs of evidence records
    status: Literal["ACTIVE", "INVALIDATED", "EXPIRED"] = "ACTIVE"
    reason: Optional[str] = None                         # Why invalidated/expired
    scope: Literal["episode", "persistent"] = "episode"  # Lifetime scope

Provenance

alethic.schema.Provenance — Metadata attached to every record.

@dataclass
class Provenance:
    writer_id: str                          # Role that wrote the record
    trace_id: str                           # Episode trace identifier
    ts_ms: int                              # Timestamp (milliseconds since epoch)
    input_refs: List[str] = []              # IDs of input records
    confidence: Optional[float] = None      # Confidence score (0.0 to 1.0)
    ttl_ms: Optional[int] = None            # Time-to-live in milliseconds

Type Aliases

Slot = Literal["percepts", "beliefs", "constraints", "plans", "evidence", "predictions", "actions"]
WriteMode = Literal["PROPOSE", "COMMIT"]

Stores

StoreProtocol

alethic.store_protocol.StoreProtocol — Interface that any backing store must satisfy. Decorated with @runtime_checkable.

MemoryStore

alethic.store.MemoryStore — In-process thread-safe store. Implements StoreProtocol. Uses threading.RLock for concurrency.

Constructor: MemoryStore() — no parameters.

SqliteStore

alethic.sqlite_store.SqliteStore — SQLite-backed persistent store. WAL mode, indexed queries.

Constructor:

SqliteStore(path: str = "blackboard.db")

Implements all StoreProtocol methods plus:

Validators

ValidationResult

alethic.validators.ValidationResult — Result of a validation check.

@dataclass
class ValidationResult:
    ok: bool                                # Whether validation passed
    code: str                               # Result code (e.g., "OK", "STALE_EVIDENCE")
    detail: str                             # Human-readable description
    context: Dict[str, Any] = {}            # Additional context (e.g., {"percept_key": "charge"})

EvidenceValidator

alethic.validators.EvidenceValidator — Checks whether beliefs are supported by evidence.

Codes: OK, MISSING_EVIDENCE, STALE_EVIDENCE, CONFLICTING_EVIDENCE

SymbolicValidator

alethic.validators.SymbolicValidator — Checks whether actions satisfy beliefs and constraints.

Codes: OK, NO_COMMITTED_BELIEF, BELIEF_NOT_SATISFIED, {CONSTRAINT}_BLOCKED

Permissions

Role

Role = Literal["kernel", "tool", "planner", "symbolic_validator", "evidence_validator", "sim_validator"]

PERMISSIONS

alethic.permissions.PERMISSIONS — Maps each role to its allowed slot+mode combinations.

Session

alethic.session.Session — Groups multiple episodes under a single persistent context.

@dataclass
class Session:
    session_id: str          # Auto-generated 12-char hex
    metadata: Dict[str, Any] # Arbitrary session metadata