ragradar-core 0.1.0__tar.gz

ragradar_core-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+*.so
+
+# uv
+.uv/
+uv.lock
+
+# ragradar runtime — never commit user run data
+.ragradar/
+
+# environment
+.env
+*.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# test output
+.pytest_cache/
+htmlcov/
+.coverage
+
+# example output
+examples/rag_pipeline/output/
+.claude/

ragradar_core-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: ragradar-core
+Version: 0.1.0
+Summary: Shared schema, store, and target parsing for the ragradar observability system
+Project-URL: Homepage, https://github.com/pleokarthik/RAGRadar
+Project-URL: Repository, https://github.com/pleokarthik/RAGRadar
+Project-URL: Issues, https://github.com/pleokarthik/RAGRadar/issues
+Author-email: Leo Karthik Paramasivan <pleokarthik@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# ragradar-core
+
+Shared kernel for the ragradar observability system: the run-record schema, the
+single SQLite store, and the sNrN target parser. `ragradar-capture`, `ragradar`, and
+`ragradar-evaluate` all depend on it — it depends on nothing.
+
+**You normally do not import this directly.** Instrument pipelines with
+`ragradar_capture`, evaluate with `ragradar_evaluate` — both re-export the schema
+dataclasses. `ragradar_core` exists so those packages share one store contract
+instead of three copies of it.
+
+## Zero-dependency guarantee
+
+`ragradar_core` imports only the Python standard library (`sqlite3`,
+`dataclasses`, `json`, `re`, `pathlib`, `datetime`). This is enforced by a
+test (`tests/test_zero_deps.py`) that imports the package in a subprocess
+and asserts nothing outside the stdlib was loaded.
+
+## What lives here
+
+| Module | Contents |
+|---|---|
+| `ragradar_core.schema` | `RunRecord` and its child dataclasses (`ChunkRecord`, `TokenBudget`, `TokenUsage`, `Turn`, `CacheEvent`, `ToolCallRecord`), all tolerant of unknown kwargs |
+| `ragradar_core.store` | store location, schema + migrations, and every persistence primitive (runs, eval scores, benchmark, policies) |
+| `ragradar_core.targets` | `parse_target_id("s4r3") -> (4, 3)` — the one sNrN parser |
+
+## Environment setup contract
+
+`ragradar_core.store.connect()` guarantees the environment before returning a
+connection:
+
+1. `~/.ragradar/` exists (created if missing),
+2. `~/.ragradar/runs.db` exists (created if missing),
+3. the schema is at the latest version — fresh databases are created
+   directly at the latest version; databases written by older package
+   versions are migrated in place.
+
+Any entry point — a library call, a CLI command, an example script — works
+on a fresh machine with no prior CLI invocation.
+
+## Schema version + migration story
+
+One constant, `ragradar_core.store.SCHEMA_VERSION` (currently `"3"`), recorded
+in the `meta` table. The migration chain walks old databases forward on
+first connect:
+
+- **v1 → v2**: adds `eval_scores` / `risk_score` / `evaluated_at` columns
+  to `runs`; creates the `benchmark` and `policies` tables.
+- **v2 → v3**: creates the `runs_fts` FTS5 index over run queries (with
+  insert/update/delete sync triggers, backfilled from existing rows) and
+  drops the now-redundant `idx_runs_query` index.
+
+A database reporting a version this package doesn't know raises
+`RuntimeError` rather than guessing.
+
+## DB location and layout
+
+The store lives at `~/.ragradar/runs.db` (SQLite, WAL mode).
+
+| Table | Columns |
+|---|---|
+| `meta` | `key`, `value` — holds `schema_version` |
+| `sessions` | `session_id`, `title`, `pipeline`, `created_at` |
+| `runs` | `session_id`, `run_seq`, `query`, `pipeline`, `created_at`, `run_data` (JSON `RunRecord`), `eval_scores` (JSON), `risk_score`, `evaluated_at` |
+| `benchmark` | `pipeline`, `factor`, `threshold`, `correlation`, `sample_count`, `updated_at` |
+| `policies` | `pipeline`, `policy_data` (JSON), `updated_at` |
+| `runs_fts` | FTS5 index over `runs.query` |
+
+Runs are addressed as `s{session_id}r{run_seq}` (e.g. `s2r3`) everywhere —
+"run" is the data noun; capturing is the verb, and belongs to
+`ragradar-capture`.

ragradar_core-0.1.0/README.md

@@ -0,0 +1,71 @@
+# ragradar-core
+
+Shared kernel for the ragradar observability system: the run-record schema, the
+single SQLite store, and the sNrN target parser. `ragradar-capture`, `ragradar`, and
+`ragradar-evaluate` all depend on it — it depends on nothing.
+
+**You normally do not import this directly.** Instrument pipelines with
+`ragradar_capture`, evaluate with `ragradar_evaluate` — both re-export the schema
+dataclasses. `ragradar_core` exists so those packages share one store contract
+instead of three copies of it.
+
+## Zero-dependency guarantee
+
+`ragradar_core` imports only the Python standard library (`sqlite3`,
+`dataclasses`, `json`, `re`, `pathlib`, `datetime`). This is enforced by a
+test (`tests/test_zero_deps.py`) that imports the package in a subprocess
+and asserts nothing outside the stdlib was loaded.
+
+## What lives here
+
+| Module | Contents |
+|---|---|
+| `ragradar_core.schema` | `RunRecord` and its child dataclasses (`ChunkRecord`, `TokenBudget`, `TokenUsage`, `Turn`, `CacheEvent`, `ToolCallRecord`), all tolerant of unknown kwargs |
+| `ragradar_core.store` | store location, schema + migrations, and every persistence primitive (runs, eval scores, benchmark, policies) |
+| `ragradar_core.targets` | `parse_target_id("s4r3") -> (4, 3)` — the one sNrN parser |
+
+## Environment setup contract
+
+`ragradar_core.store.connect()` guarantees the environment before returning a
+connection:
+
+1. `~/.ragradar/` exists (created if missing),
+2. `~/.ragradar/runs.db` exists (created if missing),
+3. the schema is at the latest version — fresh databases are created
+   directly at the latest version; databases written by older package
+   versions are migrated in place.
+
+Any entry point — a library call, a CLI command, an example script — works
+on a fresh machine with no prior CLI invocation.
+
+## Schema version + migration story
+
+One constant, `ragradar_core.store.SCHEMA_VERSION` (currently `"3"`), recorded
+in the `meta` table. The migration chain walks old databases forward on
+first connect:
+
+- **v1 → v2**: adds `eval_scores` / `risk_score` / `evaluated_at` columns
+  to `runs`; creates the `benchmark` and `policies` tables.
+- **v2 → v3**: creates the `runs_fts` FTS5 index over run queries (with
+  insert/update/delete sync triggers, backfilled from existing rows) and
+  drops the now-redundant `idx_runs_query` index.
+
+A database reporting a version this package doesn't know raises
+`RuntimeError` rather than guessing.
+
+## DB location and layout
+
+The store lives at `~/.ragradar/runs.db` (SQLite, WAL mode).
+
+| Table | Columns |
+|---|---|
+| `meta` | `key`, `value` — holds `schema_version` |
+| `sessions` | `session_id`, `title`, `pipeline`, `created_at` |
+| `runs` | `session_id`, `run_seq`, `query`, `pipeline`, `created_at`, `run_data` (JSON `RunRecord`), `eval_scores` (JSON), `risk_score`, `evaluated_at` |
+| `benchmark` | `pipeline`, `factor`, `threshold`, `correlation`, `sample_count`, `updated_at` |
+| `policies` | `pipeline`, `policy_data` (JSON), `updated_at` |
+| `runs_fts` | FTS5 index over `runs.query` |
+
+Runs are addressed as `s{session_id}r{run_seq}` (e.g. `s2r3`) everywhere —
+"run" is the data noun; capturing is the verb, and belongs to
+`ragradar-capture`.

ragradar_core-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "ragradar-core"
+version = "0.1.0"
+description = "Shared schema, store, and target parsing for the ragradar observability system"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "Leo Karthik Paramasivan", email = "pleokarthik@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/pleokarthik/RAGRadar"
+Repository = "https://github.com/pleokarthik/RAGRadar"
+Issues = "https://github.com/pleokarthik/RAGRadar/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragradar_core"]

ragradar_core-0.1.0/src/ragradar_core/__init__.py

@@ -0,0 +1,25 @@
+# ragradar-core is internal plumbing shared by ragradar-capture, ragradar, and
+# ragradar-evaluate: the run-record dataclasses, the single SQLite store, and
+# the sNrN target parser. End users normally import from ragradar_capture or
+# ragradar_evaluate, both of which re-export the dataclasses.
+from ragradar_core.schema import (
+    CacheEvent,
+    ChunkRecord,
+    RunRecord,
+    TokenBudget,
+    TokenUsage,
+    ToolCallRecord,
+    Turn,
+)
+from ragradar_core.targets import parse_target_id
+
+__all__ = [
+    "ChunkRecord",
+    "TokenBudget",
+    "TokenUsage",
+    "Turn",
+    "CacheEvent",
+    "ToolCallRecord",
+    "RunRecord",
+    "parse_target_id",
+]

ragradar_core-0.1.0/src/ragradar_core/coerce.py

@@ -0,0 +1,229 @@
+"""Coercion of plain-Python inputs into the ragradar_core schema dataclasses.
+
+This is the shared user-input boundary: ragradar_capture's entry points
+(Capture methods, capture(), the thread-local proxies) and ragradar_evaluate's
+target resolution (evaluate()/check() on a hand-built RunRecord) route
+user input through these functions, so naive callers can pass primitives
+— shorthand dicts, tuples, a bare int budget — without knowing the
+dataclasses exist. The dataclasses (Turn, ChunkRecord, TokenBudget,
+CacheEvent, TokenUsage, ToolCallRecord) remain the advanced path and
+always pass through untouched; explicitly provided fields always win
+over computed defaults.
+
+Token counts are estimated with a deterministic ~4-characters-per-token
+heuristic (no tokenizer dependency — ragradar-core stays stdlib-only). Pass
+explicit ``tokens`` / ``token_count`` values to override.
+
+All functions are pure and raise TypeError/KeyError on unusable input;
+callers decide the failure policy (ragradar_capture swallows/logs by default
+and raises in strict mode; ragradar_evaluate raises ValueError).
+"""
+
+from collections.abc import Mapping
+
+from ragradar_core.schema import (
+    CacheEvent,
+    ChunkRecord,
+    RunRecord,
+    TokenBudget,
+    TokenUsage,
+    ToolCallRecord,
+    Turn,
+)
+
+
+def estimate_tokens(text) -> int:
+    """Deterministic token estimate: ~4 characters per token. Pure.
+
+    Returns 0 for None/empty text, at least 1 for any non-empty text.
+    Used wherever a token count is derivable but not explicitly given.
+    """
+    if not text:
+        return 0
+    return max(1, round(len(text) / 4))
+
+
+def coerce_turn(turn) -> Turn:
+    """Coerce one history turn. Pure.
+
+    Accepts: a Turn (passed through untouched); a ("role", "content")
+    pair; a full dict with a "role" key; or the shorthand single-entry
+    dict {"user": "..."} / {"assistant": "..."} (optionally with a
+    "tokens" entry alongside). Tokens are estimated from the content
+    unless explicitly provided.
+    """
+    if isinstance(turn, Turn):
+        return turn
+    if isinstance(turn, (tuple, list)):
+        if len(turn) != 2:
+            raise TypeError(f"Turn tuples must be (role, content), got {len(turn)} items: {turn!r}")
+        role, content = turn
+        return Turn(role=role, content=content, tokens=estimate_tokens(content))
+    if isinstance(turn, Mapping):
+        d = dict(turn)
+        if "role" in d:
+            content = d.get("content", "")
+            tokens = d["tokens"] if d.get("tokens") is not None else estimate_tokens(content)
+            return Turn(role=d["role"], content=content, tokens=tokens)
+        tokens = d.pop("tokens", None)
+        if len(d) != 1:
+            raise TypeError(
+                "Shorthand turn dicts must have exactly one role entry, e.g. "
+                f'{{"user": "..."}} (plus an optional "tokens"), got: {turn!r}'
+            )
+        ((role, content),) = d.items()
+        if tokens is None:
+            tokens = estimate_tokens(content)
+        return Turn(role=role, content=content, tokens=tokens)
+    raise TypeError(f"Cannot coerce {type(turn).__name__} into a history turn: {turn!r}")
+
+
+def coerce_turns(turns) -> list[Turn]:
+    """Coerce a sequence of history turns (see coerce_turn). Pure."""
+    return [coerce_turn(t) for t in turns]
+
+
+def coerce_chunk(chunk, index: int) -> ChunkRecord:
+    """Coerce one retrieval chunk. Pure.
+
+    Accepts a ChunkRecord (passed through untouched) or a dict; "content"
+    is the only required key. Missing boilerplate is filled: chunk_id
+    defaults to "chunk_{index}", source_doc_id to "unknown", token_count
+    to an estimate of the content. Score/path/flag fields keep their
+    dataclass defaults when absent.
+    """
+    if isinstance(chunk, ChunkRecord):
+        return chunk
+    if isinstance(chunk, Mapping):
+        d = dict(chunk)
+        d.setdefault("chunk_id", f"chunk_{index}")
+        d.setdefault("source_doc_id", "unknown")
+        if d.get("token_count") is None:
+            d["token_count"] = estimate_tokens(d.get("content"))
+        return ChunkRecord(**d)
+    raise TypeError(f"Cannot coerce {type(chunk).__name__} into a chunk: {chunk!r}")
+
+
+def coerce_chunks(chunks) -> list[ChunkRecord]:
+    """Coerce a sequence of retrieval chunks (see coerce_chunk). Pure."""
+    return [coerce_chunk(c, i) for i, c in enumerate(chunks)]
+
+
+def coerce_token_budget(budget, final_prompt=None) -> TokenBudget:
+    """Coerce a token budget. Pure.
+
+    Accepts a TokenBudget (passed through untouched), a bare int (the
+    total limit), or a dict with at least "total_limit". Allocation
+    fields default to 0. A missing headroom is derived, in order of
+    preference: total_limit minus the given allocations (when any
+    allocation was provided), total_limit minus the estimated
+    final_prompt tokens (when a prompt is available), else total_limit.
+    Derived headroom may be negative — that is the over-budget signal.
+    """
+    if isinstance(budget, TokenBudget):
+        return budget
+    if isinstance(budget, bool) or not isinstance(budget, (int, Mapping)):
+        raise TypeError(f"Cannot coerce {type(budget).__name__} into a token budget: {budget!r}")
+    d = {"total_limit": budget} if isinstance(budget, int) else dict(budget)
+
+    alloc_keys = ("chunks_allocated", "history_allocated", "system_allocated")
+    alloc_given = any(d.get(k) is not None for k in alloc_keys)
+    for k in alloc_keys:
+        if d.get(k) is None:
+            d[k] = 0
+
+    if d.get("headroom") is None:
+        total = d["total_limit"]
+        if alloc_given:
+            d["headroom"] = total - sum(d[k] for k in alloc_keys)
+        elif final_prompt:
+            d["headroom"] = total - estimate_tokens(final_prompt)
+        else:
+            d["headroom"] = total
+    return TokenBudget(**d)
+
+
+def coerce_cache_events(events) -> list[CacheEvent]:
+    """Coerce cache events. Pure.
+
+    Accepts a mapping of {chunk_id: hit} for the whole call, or a
+    sequence whose items are CacheEvents (passed through untouched),
+    dicts, or ("chunk_id", hit) pairs.
+    """
+    if isinstance(events, Mapping):
+        return [CacheEvent(chunk_id=k, hit=bool(v)) for k, v in events.items()]
+    out = []
+    for e in events:
+        if isinstance(e, CacheEvent):
+            out.append(e)
+        elif isinstance(e, Mapping):
+            out.append(CacheEvent(**e))
+        elif isinstance(e, (tuple, list)) and len(e) == 2:
+            out.append(CacheEvent(chunk_id=e[0], hit=bool(e[1])))
+        else:
+            raise TypeError(f"Cannot coerce {type(e).__name__} into a cache event: {e!r}")
+    return out
+
+
+def coerce_token_usage(usage) -> TokenUsage:
+    """Coerce token usage. Pure.
+
+    Accepts a TokenUsage (passed through untouched) or a dict; a missing
+    total_tokens is derived as input_tokens + output_tokens.
+    """
+    if isinstance(usage, TokenUsage):
+        return usage
+    if isinstance(usage, Mapping):
+        d = dict(usage)
+        if d.get("total_tokens") is None:
+            d["total_tokens"] = d.get("input_tokens", 0) + d.get("output_tokens", 0)
+        return TokenUsage(**d)
+    raise TypeError(f"Cannot coerce {type(usage).__name__} into token usage: {usage!r}")
+
+
+def coerce_tool_call(call) -> ToolCallRecord:
+    """Coerce one tool call: a ToolCallRecord (untouched) or a dict. Pure."""
+    if isinstance(call, ToolCallRecord):
+        return call
+    if isinstance(call, Mapping):
+        return ToolCallRecord(**call)
+    raise TypeError(f"Cannot coerce {type(call).__name__} into a tool call: {call!r}")
+
+
+def coerce_run_record(record: RunRecord) -> RunRecord:
+    """Normalized copy of ``record`` with every nested field coerced. Pure.
+
+    RunRecord's constructor stores nested values as given, so a
+    hand-built record may carry primitive chunks/turns/budget where the
+    metric layers expect dataclasses. This runs each nested field
+    through its coercer (dataclass instances pass through untouched)
+    and returns a new RunRecord; the input is never mutated.
+    """
+    return RunRecord(
+        query=record.query,
+        response=record.response,
+        chunks=(coerce_chunks(record.chunks) if record.chunks is not None else None),
+        final_prompt=record.final_prompt,
+        token_budget=(
+            coerce_token_budget(record.token_budget, record.final_prompt)
+            if record.token_budget is not None
+            else None
+        ),
+        history_pre=(coerce_turns(record.history_pre) if record.history_pre is not None else None),
+        history_post=(
+            coerce_turns(record.history_post) if record.history_post is not None else None
+        ),
+        eviction_reason=record.eviction_reason,
+        cache_events=(
+            coerce_cache_events(record.cache_events) if record.cache_events is not None else None
+        ),
+        tool_calls=(
+            [coerce_tool_call(c) for c in record.tool_calls]
+            if record.tool_calls is not None
+            else None
+        ),
+        model=record.model,
+        token_usage=(
+            coerce_token_usage(record.token_usage) if record.token_usage is not None else None
+        ),
+    )

ragradar_core-0.1.0/src/ragradar_core/schema.py

@@ -0,0 +1,183 @@
+"""Run record dataclasses shared by every ragradar package.
+
+Pure data definitions — nothing in this module touches the store. All
+dataclasses are decorated with ``_flexible`` so unknown keyword arguments
+are silently dropped: instrumentation with extra fields never raises
+``TypeError`` in a caller's pipeline, and future fields never break old
+readers.
+"""
+
+import functools
+from dataclasses import asdict, dataclass, fields
+from typing import Optional
+
+
+def _flexible(cls):
+    """Make dataclass __init__ accept and ignore unknown keyword arguments."""
+    original_init = cls.__init__
+
+    @functools.wraps(original_init)
+    def init(self, *args, **kwargs):
+        valid = {f.name for f in fields(cls)}
+        original_init(self, *args, **{k: v for k, v in kwargs.items() if k in valid})
+
+    cls.__init__ = init
+    return cls
+
+
+@_flexible
+@dataclass
+class ChunkRecord:
+    """One retrieved chunk in a run's context window.
+
+    The advanced/typed path — most callers never construct this directly.
+    ``ragradar.capture()``/``cap.chunks()`` accept plain dicts (only
+    ``content`` is required; everything else, including ``chunk_id`` and
+    ``source_doc_id``, gets a sensible default) and coerce them into this
+    shape internally. Construct ``ChunkRecord`` yourself only if you want
+    static typing or are round-tripping data you already have in this form.
+    """
+
+    chunk_id: str
+    source_doc_id: str
+    content: str
+    token_count: int
+    retrieval_score: Optional[float] = None
+    rerank_score: Optional[float] = None
+    retrieval_path: Optional[str] = None
+    truncated: bool = False
+    cache_hit: Optional[bool] = None
+
+
+@_flexible
+@dataclass
+class TokenBudget:
+    """How a run's token limit was allocated across chunks/history/system.
+
+    Advanced/typed path — ``cap.context(prompt, token_budget=...)`` also
+    accepts a bare int (the total limit) or a partial dict; missing
+    allocations default to 0 and ``headroom`` is derived when omitted.
+    """
+
+    total_limit: int
+    chunks_allocated: int
+    history_allocated: int
+    system_allocated: int
+    headroom: int
+
+
+@_flexible
+@dataclass
+class TokenUsage:
+    """Actual token counts an LLM call reported (as opposed to the budget).
+
+    Advanced/typed path — ``cap.response(text, token_usage=...)`` also
+    accepts a dict; a missing ``total_tokens`` is derived as
+    ``input_tokens + output_tokens``.
+    """
+
+    input_tokens: int
+    output_tokens: int
+    total_tokens: int
+
+
+@_flexible
+@dataclass
+class Turn:
+    """One turn of conversation history, before or after eviction.
+
+    Advanced/typed path — ``cap.history(pre=..., post=...)`` also accepts
+    shorthand ``{"user": "..."}`` / ``{"assistant": "..."}`` dicts or
+    ``(role, content)`` tuples; a missing ``tokens`` count is estimated
+    from the content.
+    """
+
+    role: str
+    content: str
+    tokens: Optional[int] = None
+
+
+@_flexible
+@dataclass
+class CacheEvent:
+    """Whether one chunk was served from cache for this run.
+
+    Advanced/typed path — ``cap.cache(...)`` also accepts a whole-call
+    ``{chunk_id: hit}`` mapping or ``(chunk_id, hit)`` pairs.
+    """
+
+    chunk_id: str
+    hit: bool
+    cache_source: Optional[str] = None
+
+
+@_flexible
+@dataclass
+class ToolCallRecord:
+    """One tool/function call made while producing a run's response.
+
+    Advanced/typed path — ``cap.tool_call(...)`` also accepts a plain
+    dict with the same field names.
+    """
+
+    tool_name: str
+    arguments: dict
+    result: Optional[str] = None
+    error: Optional[str] = None
+    latency_ms: Optional[float] = None
+
+
+@_flexible
+@dataclass
+class RunRecord:
+    """The complete captured record of one pipeline run.
+
+    This is what ``ragradar.capture()``/``Capture`` build up and persist,
+    and what ``ragradar.evaluate()``/``check()`` score. Everything past
+    ``query``/``response`` is optional — instrument as much or as little
+    of your pipeline as you have. Most callers never construct one by
+    hand; it is assembled for you from the primitives passed to
+    ``capture()`` or the staged ``Capture`` methods.
+    """
+
+    query: str
+    response: str
+    chunks: Optional[list[ChunkRecord]] = None
+    final_prompt: Optional[str] = None
+    token_budget: Optional[TokenBudget] = None
+    history_pre: Optional[list[Turn]] = None
+    history_post: Optional[list[Turn]] = None
+    eviction_reason: Optional[str] = None
+    cache_events: Optional[list[CacheEvent]] = None
+    tool_calls: Optional[list[ToolCallRecord]] = None
+    model: Optional[str] = None
+    token_usage: Optional[TokenUsage] = None
+
+    def to_json(self) -> dict:
+        """This record as a plain, JSON-serializable dict. Pure."""
+        return asdict(self)
+
+    @classmethod
+    def from_json(cls, data: dict) -> "RunRecord":
+        """Rebuild a ``RunRecord`` from ``to_json()``'s output. Pure.
+
+        Nested dicts are reinflated into their dataclasses (``chunks``
+        into ``ChunkRecord``s, etc.) so the result is fully typed, not
+        just a dict of dicts.
+        """
+        data = dict(data)
+        if data.get("chunks") is not None:
+            data["chunks"] = [ChunkRecord(**c) for c in data["chunks"]]
+        if data.get("token_budget") is not None:
+            data["token_budget"] = TokenBudget(**data["token_budget"])
+        if data.get("history_pre") is not None:
+            data["history_pre"] = [Turn(**t) for t in data["history_pre"]]
+        if data.get("history_post") is not None:
+            data["history_post"] = [Turn(**t) for t in data["history_post"]]
+        if data.get("cache_events") is not None:
+            data["cache_events"] = [CacheEvent(**e) for e in data["cache_events"]]
+        if data.get("tool_calls") is not None:
+            data["tool_calls"] = [ToolCallRecord(**t) for t in data["tool_calls"]]
+        if data.get("token_usage") is not None:
+            data["token_usage"] = TokenUsage(**data["token_usage"])
+        return cls(**data)