shellbrain 0.1.29__tar.gz → 0.1.31__tar.gz

shellbrain-0.1.31/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: shellbrain
+Version: 0.1.31
+Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: PyYAML<7.0,>=6.0
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: pgvector<1.0,>=0.3
+Requires-Dist: sentence-transformers<4.0,>=3.0
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
+</p>
+
+<h3 align="center">ShellBrain</h3>
+
+<p align="center">Long-term Memory for AI Agents.</p>
+
+Agents forget across sessions. They rediscover the same problems, repeat the same mistakes, and relearn what you already taught them. **ShellBrain makes their work compound.**
+
+### Recall in one command.
+Episodic, empirical, conceptual. Three categories, one retrieval surface.
+
+---
+
+## Architecture
+
+**Episodic knowledge** is the _evidence_ layer.
+- What actually happened in the session: your prompts, the agent's steps, tool calls, and outputs.
+
+**Empirical knowledge** is the concrete _extracted_ layer.
+- An ontology of problems, solutions, failed tactics, facts, preferences, changes.
+- This is **case-based reasoning** in a semantic graph.
+
+**Conceptual konwledge** is the _abstractive_ layer.
+- A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
+- **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
+
+The episodic layer is truth. Empirical memory extracts. Concept memory abstracts. **Each layer is grounded in the one beneath it.**
+
+---
+
+## How agents use ShellBrain
+
+**Working agents call `recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
+
+```bash
+shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
+```
+
+Lower-level commands exist for inner agents.
+- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
+
+When a user explicitly says to store or teach Shellbrain something, working agents can call `teach`. It stores the statement as evidence and immediately runs Shellbrain's teach agent.
+
+**Working agents focus on only their work.**
+
+---
+
+## Principled and Disciplined
+
+Memory that is grounded in evidence, small in scope, and asked for rather than pushed is memory that compounds. Everything else is noise for working agents.
+
+**A memory layer that cannot justify itself should not persist.**
+
+---
+
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+
+The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## How to Use ShellBrain
+
+Use Shellbrain in your agent of choice. Then, just work normally.
+
+**Claude Code:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
+
+**Codex:** *Use $shellbrain to remember Shellbrain recall at the right task boundaries.*
+
+**Cursor:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
+
+---
+
+## Repair
+
+`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session — it is not a no-op.
+
+---
+
+## Docs
+
+- [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
+- [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
+- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
+- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
+- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
+- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
+- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors

shellbrain-0.1.31/README.md

@@ -0,0 +1,105 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cucupac/shellbrain/main/docs/assets/shellbrain_logo_badge.png" alt="ShellBrain logo" height="88">
+</p>
+
+<h3 align="center">ShellBrain</h3>
+
+<p align="center">Long-term Memory for AI Agents.</p>
+
+Agents forget across sessions. They rediscover the same problems, repeat the same mistakes, and relearn what you already taught them. **ShellBrain makes their work compound.**
+
+### Recall in one command.
+Episodic, empirical, conceptual. Three categories, one retrieval surface.
+
+---
+
+## Architecture
+
+**Episodic knowledge** is the _evidence_ layer.
+- What actually happened in the session: your prompts, the agent's steps, tool calls, and outputs.
+
+**Empirical knowledge** is the concrete _extracted_ layer.
+- An ontology of problems, solutions, failed tactics, facts, preferences, changes.
+- This is **case-based reasoning** in a semantic graph.
+
+**Conceptual konwledge** is the _abstractive_ layer.
+- A **higher-level concept graph** with claims, relations, and implementations that link back to the concrete layer.
+- **Progressive disclosure.** agents get oriented first, then ask for depth only where tasks require it.
+
+The episodic layer is truth. Empirical memory extracts. Concept memory abstracts. **Each layer is grounded in the one beneath it.**
+
+---
+
+## How agents use ShellBrain
+
+**Working agents call `recall`.** That is the normal interface they have to think about. One command, **one _carefully curated_ compact brief**, with sources cited.
+
+```bash
+shellbrain recall --json '{"query":"what context matters for this migration lock timeout?","current_problem":{"goal":"fix the migration hang","surface":"db admin","obstacle":"lock timeout","hypothesis":"none yet"}}'
+```
+
+Lower-level commands exist for inner agents.
+- `read`, `events`, `concept show`, `memory add`, `memory update`, `concept add`, `concept update`
+
+When a user explicitly says to store or teach Shellbrain something, working agents can call `teach`. It stores the statement as evidence and immediately runs Shellbrain's teach agent.
+
+**Working agents focus on only their work.**
+
+---
+
+## Principled and Disciplined
+
+Memory that is grounded in evidence, small in scope, and asked for rather than pushed is memory that compounds. Everything else is noise for working agents.
+
+**A memory layer that cannot justify itself should not persist.**
+
+---
+
+## Install
+
+```bash
+curl -L shellbrain.ai/install | bash
+```
+
+**Works for Codex, Claude Code, and Cursor.** The installer runs `shellbrain init` for you. Repos register themselves on first use.
+
+Requirements.
+- macOS or Linux, Python 3.11+, Docker for the managed local Postgres+pgvector runtime.
+
+### Upgrade for latest capabilities
+
+```bash
+shellbrain upgrade
+```
+
+The install script also works as an upgrade path: `curl -L shellbrain.ai/upgrade | bash`. Manual alternative: `pipx upgrade shellbrain && shellbrain init`.
+
+---
+
+## How to Use ShellBrain
+
+Use Shellbrain in your agent of choice. Then, just work normally.
+
+**Claude Code:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
+
+**Codex:** *Use $shellbrain to remember Shellbrain recall at the right task boundaries.*
+
+**Cursor:** *Use `/shellbrain` to remember Shellbrain recall at the right task boundaries.*
+
+---
+
+## Repair
+
+`shellbrain admin doctor` to inspect. `shellbrain init` to repair if doctor flags it. Do not rerun init every session — it is not a no-op.
+
+---
+
+## Docs
+
+- [shellbrain.ai/humans](https://shellbrain.ai/humans/) — install, upgrade, getting started
+- [shellbrain.ai/agents](https://shellbrain.ai/agents/) — agent workflow and write discipline
+- [shellbrain.ai/recall](https://shellbrain.ai/recall/) — retrieval pipeline
+- [shellbrain.ai/memory/episodic](https://shellbrain.ai/memory/episodic/) — transcript evidence
+- [shellbrain.ai/memory/semantic](https://shellbrain.ai/memory/semantic/) — facts, preferences, changes
+- [shellbrain.ai/memory/procedural](https://shellbrain.ai/memory/procedural/) — problems, solutions, failed tactics
+- [shellbrain.ai/memory/associative](https://shellbrain.ai/memory/associative/) — explicit links and semantic neighbors

{shellbrain-0.1.29 → shellbrain-0.1.31}/app/__main__.py

@@ -1,6 +1,6 @@
 """Allow `python -m app` to invoke the public CLI."""
 
-from app.periphery.cli.main import main
+from app.entrypoints.cli.main import main
 
 
 if __name__ == "__main__":

shellbrain-0.1.29/app/periphery/admin/init_errors.py → shellbrain-0.1.31/app/core/entities/admin_errors.py

@@ -1,4 +1,4 @@
-"""Shared bootstrap exceptions for Shellbrain init flows."""
+"""Shared bootstrap exceptions for Shellbrain admin flows."""
 
 from __future__ import annotations
 

{shellbrain-0.1.29 → shellbrain-0.1.31}/app/core/entities/associations.py

@@ -3,6 +3,15 @@
 from dataclasses import dataclass
 from enum import Enum
 
+from app.core.entities.ids import (
+    AssociationEdgeId,
+    Confidence,
+    EpisodeId,
+    MemoryId,
+    RepoId,
+    Salience,
+)
+
 
 class AssociationRelationType(str, Enum):
     """This enum defines ratified formal association relation types."""
@@ -32,14 +41,14 @@ class AssociationState(str, Enum):
 class AssociationEdge:
     """This dataclass models a formal association edge between two memories."""
 
-    id: str
-    repo_id: str
-    from_memory_id: str
-    to_memory_id: str
+    id: AssociationEdgeId
+    repo_id: RepoId
+    from_memory_id: MemoryId
+    to_memory_id: MemoryId
     relation_type: AssociationRelationType
     source_mode: AssociationSourceMode = AssociationSourceMode.AGENT
     state: AssociationState = AssociationState.TENTATIVE
-    strength: float = 0.0
+    strength: Confidence = Confidence(0.0)
 
 
 @dataclass(kw_only=True)
@@ -47,13 +56,13 @@ class AssociationObservation:
     """This dataclass models an immutable reinforcement observation for associations."""
 
     id: str
-    repo_id: str
-    from_memory_id: str
-    to_memory_id: str
+    repo_id: RepoId
+    from_memory_id: MemoryId
+    to_memory_id: MemoryId
     relation_type: AssociationRelationType
     source: str
-    valence: float
-    salience: float = 0.5
-    edge_id: str | None = None
-    problem_id: str | None = None
-    episode_id: str | None = None
+    valence: Confidence
+    salience: Salience = Salience(0.5)
+    edge_id: AssociationEdgeId | None = None
+    problem_id: MemoryId | None = None
+    episode_id: EpisodeId | None = None

shellbrain-0.1.31/app/core/entities/backups.py

@@ -0,0 +1,45 @@
+"""Core backup entities and policy errors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+BackupId = str
+
+
+@dataclass(frozen=True)
+class BackupTarget:
+    """Requested restore target database."""
+
+    database_name: str
+
+
+@dataclass(frozen=True)
+class BackupManifest:
+    """Portable metadata stored next to one logical backup artifact."""
+
+    backup_id: BackupId
+    instance_id: str
+    instance_mode: str
+    source: dict[str, str]
+    schema_revision: str
+    created_at: str
+    artifact_filename: str
+    artifact_sha256: str
+    artifact_size_bytes: int
+    compression: str
+
+
+@dataclass(frozen=True)
+class BackupVerificationResult:
+    """Stable result for a verified backup artifact."""
+
+    backup_id: BackupId
+    artifact_sha256: str
+    artifact_size_bytes: int
+    verified: bool
+
+
+class BackupPolicyError(RuntimeError):
+    """Raised when a backup or restore request violates core safety policy."""

{shellbrain-0.1.29 → shellbrain-0.1.31}/app/core/entities/episodes.py

@@ -38,6 +38,34 @@ class Episode:
     created_at: datetime | None = None
 
 
+@dataclass(frozen=True, kw_only=True)
+class EpisodeBuildSnapshot:
+    """This dataclass exposes persisted episode state needed for build planning."""
+
+    episode_id: str
+    status: EpisodeStatus
+    latest_event_seq: int
+    latest_event_at: datetime
+    latest_successful_build_watermark: int | None = None
+
+    def __post_init__(self) -> None:
+        """Reject invalid persisted build-planning state at the core boundary."""
+
+        if not isinstance(self.episode_id, str) or not self.episode_id.strip():
+            raise ValueError("episode_id must be a non-empty string")
+        if not isinstance(self.status, EpisodeStatus):
+            raise ValueError("status must be an EpisodeStatus")
+        if self.latest_event_seq < 1:
+            raise ValueError("latest_event_seq must be positive")
+        if not isinstance(self.latest_event_at, datetime):
+            raise ValueError("latest_event_at must be a datetime")
+        if (
+            self.latest_successful_build_watermark is not None
+            and self.latest_successful_build_watermark < 0
+        ):
+            raise ValueError("latest_successful_build_watermark must be non-negative")
+
+
 @dataclass(kw_only=True)
 class EpisodeEvent:
     """This dataclass models a single immutable event inside an episode."""

{shellbrain-0.1.29 → shellbrain-0.1.31}/app/core/entities/evidence.py

@@ -2,14 +2,22 @@
 
 from dataclasses import dataclass
 
+from app.core.entities.ids import (
+    AssociationEdgeId,
+    EvidenceId,
+    EvidenceRefText,
+    MemoryId,
+    RepoId,
+)
+
 
 @dataclass(kw_only=True)
 class EvidenceRef:
     """This dataclass models a canonical evidence reference entry."""
 
-    id: str
-    repo_id: str
-    ref: str
+    id: EvidenceId
+    repo_id: RepoId
+    ref: EvidenceRefText
     episode_event_id: str | None = None
 
 
@@ -17,13 +25,13 @@ class EvidenceRef:
 class MemoryEvidenceLink:
     """This dataclass models a many-to-many link between shellbrain and evidence."""
 
-    memory_id: str
-    evidence_id: str
+    memory_id: MemoryId
+    evidence_id: EvidenceId
 
 
 @dataclass(kw_only=True)
 class AssociationEdgeEvidenceLink:
     """This dataclass models a many-to-many link between association edges and evidence."""
 
-    edge_id: str
-    evidence_id: str
+    edge_id: AssociationEdgeId
+    evidence_id: EvidenceId

shellbrain-0.1.31/app/core/entities/identity.py

@@ -0,0 +1,69 @@
+"""Core caller-identity concepts used across runtime, episodes, and telemetry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class IdentityTrustLevel(str, Enum):
+    """Supported caller-identity trust levels."""
+
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+    UNSUPPORTED = "unsupported"
+
+
+SUPPORTED_HOST_APPS = frozenset({"codex", "claude_code", "cursor"})
+
+
+def build_canonical_caller_id(
+    *, host_app: str, host_session_key: str, agent_key: str | None = None
+) -> str:
+    """Build the canonical caller identifier from one host session and optional agent key."""
+
+    canonical = f"{host_app}:{host_session_key}"
+    if agent_key:
+        canonical = f"{canonical}:agent:{agent_key}"
+    return canonical
+
+
+@dataclass(frozen=True, kw_only=True)
+class CallerIdentity:
+    """Canonical caller identity used to scope episodes, session state, and guidance."""
+
+    host_app: str
+    host_session_key: str
+    agent_key: str | None = None
+    canonical_id: str | None = None
+    trust_level: IdentityTrustLevel = IdentityTrustLevel.UNTRUSTED
+
+    def __post_init__(self) -> None:
+        """Validate caller identity and fill the canonical id when omitted."""
+
+        host_app = self.host_app.strip()
+        host_session_key = self.host_session_key.strip()
+        if not host_app:
+            raise ValueError("host_app must be non-empty")
+        if not host_session_key:
+            raise ValueError("host_session_key must be non-empty")
+        if host_app not in SUPPORTED_HOST_APPS:
+            raise ValueError(
+                f"host_app must be one of: {', '.join(sorted(SUPPORTED_HOST_APPS))}"
+            )
+        object.__setattr__(self, "host_app", host_app)
+        object.__setattr__(self, "host_session_key", host_session_key)
+        if not isinstance(self.trust_level, IdentityTrustLevel):
+            object.__setattr__(
+                self, "trust_level", IdentityTrustLevel(str(self.trust_level))
+            )
+        canonical_id = build_canonical_caller_id(
+            host_app=host_app,
+            host_session_key=host_session_key,
+            agent_key=self.agent_key,
+        )
+        if self.canonical_id is not None and self.canonical_id != canonical_id:
+            raise ValueError(
+                "canonical_id must match host_app, host_session_key, and agent_key"
+            )
+        object.__setattr__(self, "canonical_id", canonical_id)

shellbrain-0.1.31/app/core/entities/ids.py

@@ -0,0 +1,18 @@
+"""Semantic identifiers and value aliases used across core contracts."""
+
+from __future__ import annotations
+
+from typing import NewType
+
+
+MemoryId = NewType("MemoryId", str)
+RepoId = NewType("RepoId", str)
+EpisodeId = NewType("EpisodeId", str)
+EvidenceRefText = NewType("EvidenceRefText", str)
+EvidenceId = NewType("EvidenceId", str)
+InvocationId = NewType("InvocationId", str)
+AssociationEdgeId = NewType("AssociationEdgeId", str)
+
+Confidence = NewType("Confidence", float)
+Salience = NewType("Salience", float)
+UtilityVote = NewType("UtilityVote", float)

shellbrain-0.1.31/app/core/entities/inner_agents.py

@@ -0,0 +1,70 @@
+"""Core settings for bounded inner-agent execution."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+InnerAgentName = Literal["build_context", "build_knowledge", "teach"]
+InnerAgentProviderName = str
+InnerAgentReasoningLevel = Literal["none", "minimal", "low", "medium", "high", "xhigh"]
+BuildContextStrategy = Literal[
+    "deterministic_synthesis", "deterministic_only", "autonomous"
+]
+TokenCaptureQuality = Literal["exact", "estimated"]
+InnerAgentRunStatus = Literal[
+    "ok",
+    "no_context",
+    "provider_unavailable",
+    "timeout",
+    "invalid_output",
+    "error",
+]
+
+
+class BuildContextSettings(_StrictModel):
+    """Typed model/runtime settings for the build_context recall agent."""
+
+    strategy: BuildContextStrategy = "deterministic_synthesis"
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str = Field(min_length=1)
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int = Field(ge=1, le=600)
+    max_private_reads: int = Field(default=0, ge=0, le=10)
+    max_candidate_tokens: int = Field(ge=1, le=200_000)
+    max_brief_tokens: int | None = Field(default=None, ge=1, le=100_000)
+
+
+class BuildKnowledgeSettings(_StrictModel):
+    """Typed model/runtime settings for the build_knowledge maintenance agent."""
+
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str = Field(min_length=1)
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int = Field(ge=1, le=1200)
+    max_shellbrain_reads: int = Field(default=8, ge=1, le=50)
+    max_code_files: int = Field(default=24, ge=0, le=200)
+    max_write_commands: int = Field(default=20, ge=1, le=200)
+    idle_stable_seconds: int = Field(default=900, ge=60, le=86_400)
+    running_run_stale_seconds: int = Field(default=3600, ge=60, le=86_400)
+
+
+class TeachKnowledgeSettings(_StrictModel):
+    """Typed model/runtime settings for explicit teaching consolidation."""
+
+    provider: InnerAgentProviderName = Field(min_length=1)
+    model: str = Field(min_length=1)
+    reasoning: InnerAgentReasoningLevel
+    timeout_seconds: int = Field(ge=1, le=1200)
+    max_shellbrain_reads: int = Field(default=6, ge=1, le=50)
+    max_code_files: int = Field(default=5, ge=0, le=200)
+    max_write_commands: int = Field(default=12, ge=1, le=200)
+
+
+InnerAgentSettings = BuildContextSettings

shellbrain-0.1.31/app/core/entities/knowledge_builder.py

@@ -0,0 +1,100 @@
+"""Entities for knowledge-builder lifecycle tracking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+
+class KnowledgeBuildTrigger(str, Enum):
+    """Episode lifecycle events that can trigger build_knowledge."""
+
+    SESSION_REPLACED = "session_replaced"
+    IDLE_STABLE = "idle_stable"
+    WATERMARK_STABLE = "watermark_stable"
+    EXPLICIT_TEACH = "explicit_teach"
+
+
+class KnowledgeBuildRunStatus(str, Enum):
+    """Durable statuses for one build_knowledge run."""
+
+    RUNNING = "running"
+    OK = "ok"
+    SKIPPED = "skipped"
+    PROVIDER_UNAVAILABLE = "provider_unavailable"
+    TIMEOUT = "timeout"
+    INVALID_OUTPUT = "invalid_output"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, kw_only=True)
+class KnowledgeBuildRun:
+    """One durable build_knowledge run record."""
+
+    id: str
+    repo_id: str
+    episode_id: str
+    trigger: KnowledgeBuildTrigger
+    status: KnowledgeBuildRunStatus
+    event_watermark: int
+    previous_event_watermark: int | None
+    provider: str
+    model: str
+    reasoning: str
+    write_count: int = 0
+    skipped_item_count: int = 0
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    reasoning_output_tokens: int | None = None
+    cached_input_tokens_total: int | None = None
+    cache_read_input_tokens: int | None = None
+    cache_creation_input_tokens: int | None = None
+    capture_quality: str | None = None
+    run_summary: str | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+    read_trace: dict[str, object] = field(default_factory=dict)
+    code_trace: dict[str, object] = field(default_factory=dict)
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    created_at: datetime | None = None
+
+    def __post_init__(self) -> None:
+        """Keep invalid run records from crossing the core boundary."""
+
+        for field_name in ("id", "repo_id", "episode_id", "provider", "model"):
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field_name} must be a non-empty string")
+        if self.event_watermark < 0:
+            raise ValueError("event_watermark must be non-negative")
+        if (
+            self.previous_event_watermark is not None
+            and self.previous_event_watermark < 0
+        ):
+            raise ValueError("previous_event_watermark must be non-negative")
+        if self.write_count < 0:
+            raise ValueError("write_count must be non-negative")
+        if self.skipped_item_count < 0:
+            raise ValueError("skipped_item_count must be non-negative")
+        for field_name in (
+            "input_tokens",
+            "output_tokens",
+            "reasoning_output_tokens",
+            "cached_input_tokens_total",
+            "cache_read_input_tokens",
+            "cache_creation_input_tokens",
+        ):
+            value = getattr(self, field_name)
+            if value is not None and value < 0:
+                raise ValueError(f"{field_name} must be non-negative")
+        if self.capture_quality is not None and self.capture_quality not in {
+            "exact",
+            "estimated",
+        }:
+            raise ValueError("capture_quality must be exact or estimated")
+        if not isinstance(self.read_trace, dict):
+            raise ValueError("read_trace must be a dict")
+        if not isinstance(self.code_trace, dict):
+            raise ValueError("code_trace must be a dict")