dongarandClaude Fable 5
ac81dd6234
Build-order step 4, sequenced before the LLM client (step 3) because the client interface consumes the canonical log. - canonical.py: typed events for the full A10 table (user_message through compaction); canonical tool-call IDs minted locally, provider IDs never a join key; strict payload validation on load - StateStore: canonical_events table via schema v2 — the first real migration, exercised in a test against a hand-built v1 database — with append_event/read_events on the same fsync-per-commit path - render.py: request bodies rendered from the log at call time; first adapter targets the OpenAI-compatible shape of LiteLLM's normalized route; compaction events replace their id range at render time while staying in the durable log - Crash integration test now also verifies transcript appends survive process death Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
134 lines
2.9 KiB
Python
134 lines
2.9 KiB
Python
"""Canonical transcript schema (spec A10).
|
|
|
|
The durable record is this event log, never a provider-shaped ``messages``
|
|
array; provider request bodies are rendered from it at call time. Canonical
|
|
tool-call IDs are minted locally — provider IDs are mapped at the boundary and
|
|
never used as a join key.
|
|
|
|
Transcript appends are the conversation record itself, not state-machine
|
|
mutations, so they are deliberately outside the A9 state-change taxonomy.
|
|
"""
|
|
|
|
import uuid
|
|
from dataclasses import asdict, dataclass, fields
|
|
from typing import Any
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class UserMessage:
|
|
text: str
|
|
source: str # e.g. a Matrix event ID
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class AssistantText:
|
|
text: str
|
|
model: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ToolCall:
|
|
call_id: str # canonical, minted locally via mint_call_id()
|
|
tool: str
|
|
arguments: dict[str, Any]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ToolResult:
|
|
call_id: str
|
|
result: str
|
|
success: bool
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PlanSubmitted:
|
|
plan: str
|
|
model: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class GateOpened:
|
|
gate: str
|
|
reason: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class DelegationStarted:
|
|
brief: str
|
|
role: str
|
|
model: str
|
|
caps: dict[str, Any] # turns / tokens / wall-clock limits
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class DelegationCompleted:
|
|
handback: str
|
|
artifacts: list[str]
|
|
tokens: int
|
|
duration_s: float
|
|
exit_status: str
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class Compaction:
|
|
summary: str
|
|
model: str
|
|
replaces: list[int] # [first_id, last_id] inclusive range replaced
|
|
|
|
|
|
CanonicalEvent = (
|
|
UserMessage
|
|
| AssistantText
|
|
| ToolCall
|
|
| ToolResult
|
|
| PlanSubmitted
|
|
| GateOpened
|
|
| DelegationStarted
|
|
| DelegationCompleted
|
|
| Compaction
|
|
)
|
|
|
|
EVENT_TYPES: dict[str, type] = {
|
|
"user_message": UserMessage,
|
|
"assistant_text": AssistantText,
|
|
"tool_call": ToolCall,
|
|
"tool_result": ToolResult,
|
|
"plan_submitted": PlanSubmitted,
|
|
"gate_opened": GateOpened,
|
|
"delegation_started": DelegationStarted,
|
|
"delegation_completed": DelegationCompleted,
|
|
"compaction": Compaction,
|
|
}
|
|
|
|
_TYPE_NAMES = {cls: name for name, cls in EVENT_TYPES.items()}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class StoredEvent:
|
|
id: int
|
|
ts: str
|
|
event: CanonicalEvent
|
|
|
|
|
|
def mint_call_id() -> str:
|
|
return f"call-{uuid.uuid4().hex}"
|
|
|
|
|
|
def event_type(event: CanonicalEvent) -> str:
|
|
return _TYPE_NAMES[type(event)]
|
|
|
|
|
|
def to_payload(event: CanonicalEvent) -> dict[str, Any]:
|
|
return asdict(event)
|
|
|
|
|
|
def from_payload(type_name: str, payload: dict[str, Any]) -> CanonicalEvent:
|
|
cls = EVENT_TYPES.get(type_name)
|
|
if cls is None:
|
|
raise ValueError(f"unknown canonical event type: {type_name!r}")
|
|
known = {f.name for f in fields(cls)}
|
|
unknown = payload.keys() - known
|
|
if unknown:
|
|
raise ValueError(f"unknown fields for {type_name}: {sorted(unknown)}")
|
|
return cls(**payload)
|