ragradar-core 0.1.0__py3-none-any.whl

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/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/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)

ragradar_core/store.py

@@ -0,0 +1,773 @@
+"""Single source of truth for the ragradar SQLite store.
+
+Owns the store location (``~/.ragradar/runs.db``), the schema (always created
+at the LATEST version), the migration chain for databases created by
+older versions, and every run/eval/benchmark/policy persistence
+primitive. All other packages (ragradar_capture, ragradar, ragradar_evaluate) import
+their store access from here — none of them define their own connection
+helper, schema, or version constant.
+
+Environment-setup contract: :func:`connect` guarantees that the ``~/.ragradar``
+directory exists, the database file exists, and its schema is at
+``SCHEMA_VERSION`` — creating fresh databases directly at the latest
+version and migrating old ones in place. Any entry point (library call,
+CLI, example script) therefore works on a fresh machine with no prior
+CLI invocation.
+"""
+
+import json
+import sqlite3
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from ragradar_core.schema import RunRecord
+
+SCHEMA_VERSION = "3"
+
+# How long to keep retrying the one-time WAL-mode switch on a brand-new
+# database file (see _set_wal_mode below) before giving up.
+_WAL_SWITCH_RETRY_SECONDS = 5.0
+
+# Latest schema, created as-is for fresh databases. Databases written by
+# older package versions carry meta.schema_version "1" or "2" and are
+# walked to "3" by _ensure_schema()'s migration chain.
+#
+# One statement per tuple entry (not a single multi-statement string run
+# via executescript()): executescript() implicitly commits any pending
+# transaction before it runs, which would silently release the
+# BEGIN IMMEDIATE lock _ensure_schema() holds while bootstrapping a
+# fresh database — reopening the exact concurrent-bootstrap race this
+# structure exists to close. conn.execute() on one statement at a time
+# respects the ambient transaction instead.
+SCHEMA_STATEMENTS: tuple[str, ...] = (
+    """CREATE TABLE IF NOT EXISTS meta (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+    )""",
+    """CREATE TABLE IF NOT EXISTS sessions (
+        session_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        title      TEXT,
+        pipeline   TEXT,
+        created_at TEXT NOT NULL
+    )""",
+    """CREATE TABLE IF NOT EXISTS runs (
+        session_id   INTEGER NOT NULL REFERENCES sessions(session_id),
+        run_seq      INTEGER NOT NULL,
+        query        TEXT NOT NULL,
+        pipeline     TEXT,
+        created_at   TEXT NOT NULL,
+        run_data     TEXT NOT NULL,
+        eval_scores  TEXT,
+        risk_score   REAL,
+        evaluated_at TEXT,
+        PRIMARY KEY (session_id, run_seq)
+    )""",
+    "CREATE INDEX IF NOT EXISTS idx_runs_created_at ON runs(created_at)",
+    "CREATE INDEX IF NOT EXISTS idx_runs_pipeline   ON runs(pipeline)",
+    """CREATE TABLE IF NOT EXISTS benchmark (
+        pipeline      TEXT NOT NULL,
+        factor        TEXT NOT NULL,
+        threshold     REAL,
+        correlation   REAL,
+        sample_count  INTEGER NOT NULL DEFAULT 0,
+        updated_at    TEXT NOT NULL,
+        PRIMARY KEY (pipeline, factor)
+    )""",
+    """CREATE TABLE IF NOT EXISTS policies (
+        pipeline     TEXT PRIMARY KEY,
+        policy_data  TEXT NOT NULL,
+        updated_at   TEXT NOT NULL
+    )""",
+    """CREATE VIRTUAL TABLE IF NOT EXISTS runs_fts
+    USING fts5(
+        query,
+        content=runs,
+        content_rowid=rowid,
+        tokenize='unicode61 remove_diacritics 1'
+    )""",
+    """CREATE TRIGGER IF NOT EXISTS runs_fts_ins
+    AFTER INSERT ON runs BEGIN
+        INSERT INTO runs_fts(rowid, query) VALUES (new.rowid, new.query);
+    END""",
+    """CREATE TRIGGER IF NOT EXISTS runs_fts_del
+    AFTER DELETE ON runs BEGIN
+        INSERT INTO runs_fts(runs_fts, rowid, query)
+        VALUES ('delete', old.rowid, old.query);
+    END""",
+    """CREATE TRIGGER IF NOT EXISTS runs_fts_upd
+    AFTER UPDATE OF query ON runs BEGIN
+        INSERT INTO runs_fts(runs_fts, rowid, query)
+        VALUES ('delete', old.rowid, old.query);
+        INSERT INTO runs_fts(rowid, query) VALUES (new.rowid, new.query);
+    END""",
+)
+
+
+def _ragradar_dir() -> Path:
+    """Return the ragradar home directory (``~/.ragradar``). Pure — does not create it.
+
+    Tests monkeypatch this one function to isolate the store.
+    """
+    return Path.home() / ".ragradar"
+
+
+def db_path() -> Path:
+    """Return the store's database path. Pure — does not create it."""
+    return _ragradar_dir() / "runs.db"
+
+
+def _column_exists(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    rows = conn.execute(f"PRAGMA table_info({table})").fetchall()
+    return any(row[1] == column for row in rows)
+
+
+def _set_wal_mode(conn: sqlite3.Connection) -> None:
+    """Switch ``conn``'s database to WAL journal mode, retrying briefly
+    under concurrent first-time connects. Writes to store (once ever).
+
+    Changing journal mode requires exclusive access to the database file
+    and, unlike ordinary lock contention on a normal statement, does not
+    reliably back off via sqlite3's own ``timeout``/busy-handler retry —
+    confirmed empirically: many threads opening a brand-new (non-WAL)
+    file at once and each issuing this PRAGMA can raise
+    ``sqlite3.OperationalError: database is locked`` even with a 5s
+    connection timeout. Once the file is already in WAL mode (the
+    common case after the very first connect ever), re-issuing this
+    PRAGMA is a fast no-op read that never contends, so the retry loop
+    below only ever matters for that one-time switch.
+    """
+    deadline = time.monotonic() + _WAL_SWITCH_RETRY_SECONDS
+    while True:
+        try:
+            conn.execute("PRAGMA journal_mode=WAL")
+            return
+        except sqlite3.OperationalError:
+            if time.monotonic() >= deadline:
+                raise
+            time.sleep(0.05)
+
+
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    """Bring ``conn``'s database to SCHEMA_VERSION.
+
+    Fresh (or meta-less) databases get the full latest schema in one
+    shot; version "1"/"2" databases are migrated in place with data
+    intact; anything else raises RuntimeError. Writes to store.
+
+    Runs inside one ``BEGIN IMMEDIATE`` transaction — the same pattern
+    :func:`commit_run` uses for run inserts — so concurrent first-time
+    ``connect()`` calls against a brand-new database can't interleave
+    "check whether meta exists" with "create it and stamp
+    schema_version". Without this, one connection could observe the
+    ``meta`` table (created by another connection's in-flight bootstrap,
+    since plain DDL auto-commits per statement outside an explicit
+    transaction) before that connection had committed the
+    ``schema_version`` row, and raise a bogus "Unsupported schema
+    version: None" error — a real, previously-uncovered race distinct
+    from the run_seq race :func:`commit_run` fixes.
+    """
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        has_meta = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='meta'"
+        ).fetchone()
+        if has_meta is None:
+            for stmt in SCHEMA_STATEMENTS:
+                conn.execute(stmt)
+            conn.execute(
+                "INSERT OR IGNORE INTO meta (key, value) VALUES ('schema_version', ?)",
+                (SCHEMA_VERSION,),
+            )
+            conn.commit()
+            return
+
+        row = conn.execute("SELECT value FROM meta WHERE key = 'schema_version'").fetchone()
+        version = row[0] if row else None
+
+        if version == SCHEMA_VERSION:
+            conn.commit()
+            return
+        if version not in ("1", "2"):
+            raise RuntimeError(
+                f"Unsupported schema version: {version!r}. "
+                f"Expected '1', '2', or '{SCHEMA_VERSION}'. Cannot migrate."
+            )
+
+        if version == "1":
+            for col, col_type in [
+                ("eval_scores", "TEXT"),
+                ("risk_score", "REAL"),
+                ("evaluated_at", "TEXT"),
+            ]:
+                if not _column_exists(conn, "runs", col):
+                    conn.execute(f"ALTER TABLE runs ADD COLUMN {col} {col_type}")
+
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS benchmark (
+                    pipeline      TEXT NOT NULL,
+                    factor        TEXT NOT NULL,
+                    threshold     REAL,
+                    correlation   REAL,
+                    sample_count  INTEGER NOT NULL DEFAULT 0,
+                    updated_at    TEXT NOT NULL,
+                    PRIMARY KEY (pipeline, factor)
+                )"""
+            )
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS policies (
+                    pipeline     TEXT PRIMARY KEY,
+                    policy_data  TEXT NOT NULL,
+                    updated_at   TEXT NOT NULL
+                )"""
+            )
+            conn.execute("UPDATE meta SET value = '2' WHERE key = 'schema_version'")
+            version = "2"
+
+        if version == "2":
+            conn.execute(
+                """CREATE VIRTUAL TABLE IF NOT EXISTS runs_fts
+                USING fts5(
+                    query,
+                    content=runs,
+                    content_rowid=rowid,
+                    tokenize='unicode61 remove_diacritics 1'
+                )"""
+            )
+            conn.execute("INSERT INTO runs_fts(runs_fts) VALUES('rebuild')")
+            conn.execute(
+                """CREATE TRIGGER IF NOT EXISTS runs_fts_ins
+                AFTER INSERT ON runs BEGIN
+                    INSERT INTO runs_fts(rowid, query) VALUES (new.rowid, new.query);
+                END"""
+            )
+            conn.execute(
+                """CREATE TRIGGER IF NOT EXISTS runs_fts_del
+                AFTER DELETE ON runs BEGIN
+                    INSERT INTO runs_fts(runs_fts, rowid, query)
+                    VALUES ('delete', old.rowid, old.query);
+                END"""
+            )
+            conn.execute(
+                """CREATE TRIGGER IF NOT EXISTS runs_fts_upd
+                AFTER UPDATE OF query ON runs BEGIN
+                    INSERT INTO runs_fts(runs_fts, rowid, query)
+                    VALUES ('delete', old.rowid, old.query);
+                    INSERT INTO runs_fts(rowid, query) VALUES (new.rowid, new.query);
+                END"""
+            )
+            conn.execute("DROP INDEX IF EXISTS idx_runs_query")
+            conn.execute("UPDATE meta SET value = '3' WHERE key = 'schema_version'")
+
+        conn.commit()
+    except BaseException:
+        conn.rollback()
+        raise
+
+
+def connect() -> sqlite3.Connection:
+    """Open a Row-factory connection to the store, setting up the environment.
+
+    Side effects (writes to store): creates ``~/.ragradar`` and ``runs.db`` if
+    missing, creates the schema at SCHEMA_VERSION for fresh databases,
+    and migrates version "1"/"2" databases in place.
+
+    Returns an open ``sqlite3.Connection`` with ``sqlite3.Row`` row
+    factory — the caller must close it. Raises RuntimeError for a
+    database whose schema version is unsupported (newer than this
+    package understands).
+    """
+    path = db_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    try:
+        # PRAGMA journal_mode can't be changed from inside a transaction,
+        # so this runs before _ensure_schema()'s BEGIN IMMEDIATE.
+        _set_wal_mode(conn)
+        _ensure_schema(conn)
+    except BaseException:
+        conn.close()
+        raise
+    return conn
+
+
+def ensure_store() -> Path:
+    """Create/migrate the store without keeping a connection open.
+
+    Writes to store (via :func:`connect`). Returns the database path.
+    """
+    connect().close()
+    return db_path()
+
+
+# ---------------------------------------------------------------------------
+# Session / run persistence
+# ---------------------------------------------------------------------------
+
+
+def _get_or_create_session_on(
+    conn: sqlite3.Connection, pipeline: str | None, idle_gap_minutes: int = 30
+) -> int:
+    """Same contract as :func:`get_or_create_session`, on a caller-owned
+    connection/transaction instead of opening its own. Writes to store."""
+    if pipeline is not None:
+        row = conn.execute(
+            "SELECT session_id, created_at FROM sessions "
+            "WHERE pipeline = ? ORDER BY created_at DESC LIMIT 1",
+            (pipeline,),
+        ).fetchone()
+    else:
+        row = conn.execute(
+            "SELECT session_id, created_at FROM sessions "
+            "WHERE pipeline IS NULL ORDER BY created_at DESC LIMIT 1",
+        ).fetchone()
+
+    if row is not None:
+        session_id, session_created = row
+        last_run = conn.execute(
+            "SELECT created_at FROM runs WHERE session_id = ? ORDER BY created_at DESC LIMIT 1",
+            (session_id,),
+        ).fetchone()
+        last_time = datetime.fromisoformat(last_run[0] if last_run else session_created)
+        if last_time.tzinfo is None:
+            last_time = last_time.replace(tzinfo=timezone.utc)
+        now = datetime.now(timezone.utc)
+        if (now - last_time).total_seconds() < idle_gap_minutes * 60:
+            return session_id
+
+    now_iso = datetime.now(timezone.utc).isoformat()
+    cursor = conn.execute(
+        "INSERT INTO sessions (pipeline, created_at) VALUES (?, ?)",
+        (pipeline, now_iso),
+    )
+    return cursor.lastrowid
+
+
+def get_or_create_session(pipeline: str | None, idle_gap_minutes: int = 30) -> int:
+    """Return the current session id for ``pipeline``, creating one if needed.
+
+    Writes to store: reuses the most recent session for ``pipeline`` when
+    its last activity is within ``idle_gap_minutes``, otherwise inserts a
+    new session row. Returns the session id.
+
+    Opens and commits its own transaction, so calling this back-to-back
+    with :func:`next_run_seq`/:func:`write_run` as three separate calls is
+    not race-free under concurrent writers — see :func:`commit_run` for
+    the atomic path used by ``Capture.commit()``.
+    """
+    conn = connect()
+    try:
+        session_id = _get_or_create_session_on(conn, pipeline, idle_gap_minutes)
+        conn.commit()
+        return session_id
+    finally:
+        conn.close()
+
+
+def _next_run_seq_on(conn: sqlite3.Connection, session_id: int) -> int:
+    """Same contract as :func:`next_run_seq`, on a caller-owned connection."""
+    row = conn.execute(
+        "SELECT MAX(run_seq) FROM runs WHERE session_id = ?",
+        (session_id,),
+    ).fetchone()
+    return (row[0] or 0) + 1
+
+
+def next_run_seq(session_id: int) -> int:
+    """Return the next run_seq for ``session_id`` (1 for an empty session).
+
+    Read-only query (though connecting may create/migrate the store).
+    Calling this and then :func:`write_run` as two separate calls has a
+    TOCTOU race under concurrent writers to the same session — see
+    :func:`commit_run` for the atomic path.
+    """
+    conn = connect()
+    try:
+        return _next_run_seq_on(conn, session_id)
+    finally:
+        conn.close()
+
+
+def _write_run_on(
+    conn: sqlite3.Connection,
+    session_id: int,
+    run_seq: int,
+    record: RunRecord,
+    pipeline: str | None,
+) -> None:
+    """Same contract as :func:`write_run`, on a caller-owned connection."""
+    now = datetime.now(timezone.utc).isoformat()
+    conn.execute(
+        "INSERT INTO runs (session_id, run_seq, query, pipeline, created_at, run_data) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (
+            session_id,
+            run_seq,
+            record.query,
+            pipeline,
+            now,
+            json.dumps(record.to_json()),
+        ),
+    )
+
+
+def write_run(session_id: int, run_seq: int, record: RunRecord, pipeline: str | None) -> None:
+    """Insert one run row for ``record``. Writes to store.
+
+    ``created_at`` is stamped with the current UTC time; ``run_data`` is
+    the JSON-serialized record. Raises sqlite3.IntegrityError if
+    (session_id, run_seq) already exists.
+    """
+    conn = connect()
+    try:
+        _write_run_on(conn, session_id, run_seq, record, pipeline)
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def commit_run(
+    pipeline: str | None, record: RunRecord, idle_gap_minutes: int = 30
+) -> tuple[int, int]:
+    """Atomically resolve/create a session, assign the next run_seq, and
+    insert the run row. Writes to store.
+
+    This is the race-free replacement for calling
+    ``get_or_create_session()`` + ``next_run_seq()`` + ``write_run()`` as
+    three separate connections: session resolution, run_seq assignment,
+    and the insert all happen inside one ``BEGIN IMMEDIATE`` transaction,
+    so no other writer can interleave a run insert for the same session
+    between "compute run_seq" and "insert the row" — the exact race that
+    used to raise ``sqlite3.IntegrityError`` on ``(session_id, run_seq)``
+    under concurrent commits and get silently swallowed by the capture
+    layer's fail-open contract.
+
+    ``BEGIN IMMEDIATE`` acquires SQLite's write lock up front rather than
+    on first write, so a concurrent caller blocks (and retries under the
+    connection's default busy timeout) instead of racing to the insert.
+    If a collision is nonetheless detected (belt-and-suspenders — this
+    should be unreachable given the transaction above), this raises
+    ``RuntimeError`` rather than silently retrying or swallowing it, since
+    silent loss of a colliding write is the bug this function exists to
+    eliminate.
+
+    Returns ``(session_id, run_seq)``. Raises ``sqlite3.OperationalError``
+    if the write lock can't be acquired before the connection's busy
+    timeout elapses, and re-raises (after rolling back) any other error —
+    callers (``Capture.commit()``) apply their own fail-open/strict-mode
+    handling on top of this.
+    """
+    conn = connect()
+    try:
+        conn.execute("BEGIN IMMEDIATE")
+        session_id = _get_or_create_session_on(conn, pipeline, idle_gap_minutes)
+        run_seq = _next_run_seq_on(conn, session_id)
+        try:
+            _write_run_on(conn, session_id, run_seq, record, pipeline)
+        except sqlite3.IntegrityError as e:
+            raise RuntimeError(
+                f"run_seq collision on session {session_id} seq {run_seq} inside an "
+                "atomic transaction — this should be unreachable; investigate rather "
+                "than retry."
+            ) from e
+        conn.commit()
+        return session_id, run_seq
+    except BaseException:
+        conn.rollback()
+        raise
+    finally:
+        conn.close()
+
+
+def write_runs_batch(
+    session_id: int,
+    start_seq: int,
+    records: list[RunRecord],
+    pipeline: str | None,
+) -> None:
+    """Insert many run rows in one transaction. Writes to store.
+
+    Records get consecutive run_seq values starting at ``start_seq`` and
+    share one UTC ``created_at`` stamp.
+    """
+    now = datetime.now(timezone.utc).isoformat()
+    rows = [
+        (session_id, start_seq + i, record.query, pipeline, now, json.dumps(record.to_json()))
+        for i, record in enumerate(records)
+    ]
+    conn = connect()
+    try:
+        conn.executemany(
+            "INSERT INTO runs (session_id, run_seq, query, pipeline, created_at, run_data) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            rows,
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+_RUN_COLUMNS = (
+    "session_id, run_seq, query, pipeline, created_at, "
+    "run_data, eval_scores, risk_score, evaluated_at"
+)
+
+
+def get_run(session_id: int, run_seq: int) -> dict | None:
+    """Fetch one run row as a dict, or None if it doesn't exist.
+
+    Read-only query (though connecting may create/migrate the store).
+    """
+    conn = connect()
+    try:
+        row = conn.execute(
+            f"SELECT {_RUN_COLUMNS} FROM runs WHERE session_id = ? AND run_seq = ?",
+            (session_id, run_seq),
+        ).fetchone()
+        return dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def get_latest_run() -> dict | None:
+    """Fetch the most recently created run row, or None if the store is empty.
+
+    Read-only query (though connecting may create/migrate the store).
+    """
+    conn = connect()
+    try:
+        row = conn.execute(
+            f"SELECT {_RUN_COLUMNS} FROM runs ORDER BY created_at DESC LIMIT 1",
+        ).fetchone()
+        return dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def get_runs_in_session(session_id: int) -> list[dict]:
+    """Fetch all run rows in a session, newest first (empty list if none).
+
+    Read-only query (though connecting may create/migrate the store).
+    """
+    conn = connect()
+    try:
+        rows = conn.execute(
+            f"SELECT {_RUN_COLUMNS} FROM runs WHERE session_id = ? ORDER BY created_at DESC",
+            (session_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Eval-score persistence (eval_scores lives on the runs table)
+# ---------------------------------------------------------------------------
+
+
+def write_eval_scores(
+    session_id: int,
+    run_seq: int,
+    eval_scores: dict,
+    risk_score: float,
+) -> None:
+    """Persist eval scores + risk on one run row. Writes to store.
+
+    Stamps ``evaluated_at`` with the current UTC time. Silently updates
+    zero rows if the run doesn't exist.
+    """
+    conn = connect()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "UPDATE runs SET eval_scores = ?, risk_score = ?, evaluated_at = ? "
+            "WHERE session_id = ? AND run_seq = ?",
+            (json.dumps(eval_scores), risk_score, now, session_id, run_seq),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def write_eval_scores_batch(entries: list[tuple]) -> None:
+    """Persist eval scores for many runs in one transaction. Writes to store.
+
+    Each entry is ``(session_id, run_seq, eval_scores_dict, risk_score)``.
+    No-op for an empty list.
+    """
+    if not entries:
+        return
+    conn = connect()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        rows = [
+            (json.dumps(eval_scores), risk_score, now, session_id, run_seq)
+            for session_id, run_seq, eval_scores, risk_score in entries
+        ]
+        conn.executemany(
+            "UPDATE runs SET eval_scores = ?, risk_score = ?, evaluated_at = ? "
+            "WHERE session_id = ? AND run_seq = ?",
+            rows,
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def get_eval_scores(session_id: int, run_seq: int) -> dict | None:
+    """Fetch a run's stored eval scores (with ``risk_score`` merged in).
+
+    Read-only query (though connecting may create/migrate the store).
+    Returns None if the run doesn't exist or was never evaluated.
+    """
+    conn = connect()
+    try:
+        row = conn.execute(
+            "SELECT eval_scores, risk_score FROM runs WHERE session_id = ? AND run_seq = ?",
+            (session_id, run_seq),
+        ).fetchone()
+        if row is None or row["eval_scores"] is None:
+            return None
+        result = json.loads(row["eval_scores"])
+        result["risk_score"] = row["risk_score"]
+        return result
+    finally:
+        conn.close()
+
+
+def get_all_evaluated_runs(pipeline: str | None = None) -> list[dict]:
+    """Fetch every run row with non-null eval_scores, newest first.
+
+    Read-only query (though connecting may create/migrate the store).
+    ``pipeline=None`` means all pipelines, not the "__default" key.
+    """
+    conn = connect()
+    try:
+        sql = f"SELECT {_RUN_COLUMNS} FROM runs WHERE eval_scores IS NOT NULL"
+        params: list = []
+        if pipeline is not None:
+            sql += " AND pipeline = ?"
+            params.append(pipeline)
+        sql += " ORDER BY created_at DESC"
+        return [dict(r) for r in conn.execute(sql, params).fetchall()]
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Benchmark persistence
+# ---------------------------------------------------------------------------
+
+
+def write_benchmark_entry(
+    pipeline: str,
+    factor: str,
+    threshold: float | None,
+    correlation: float | None,
+    sample_count: int,
+) -> None:
+    """Upsert one benchmark row keyed (pipeline, factor). Writes to store."""
+    conn = connect()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "INSERT OR REPLACE INTO benchmark "
+            "(pipeline, factor, threshold, correlation, sample_count, updated_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (pipeline, factor, threshold, correlation, sample_count, now),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def write_benchmark_entries_batch(entries: list[tuple]) -> None:
+    """Upsert many benchmark rows in one transaction. Writes to store.
+
+    Each entry is ``(pipeline, factor, threshold, correlation, sample_count)``.
+    No-op for an empty list.
+    """
+    if not entries:
+        return
+    conn = connect()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        rows = [(p, f, t, c, s, now) for p, f, t, c, s in entries]
+        conn.executemany(
+            "INSERT OR REPLACE INTO benchmark "
+            "(pipeline, factor, threshold, correlation, sample_count, updated_at) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            rows,
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def get_benchmark(pipeline: str) -> list[dict]:
+    """Fetch all benchmark rows for ``pipeline`` (empty list if none).
+
+    Read-only query (though connecting may create/migrate the store).
+    """
+    conn = connect()
+    try:
+        rows = conn.execute(
+            "SELECT factor, threshold, correlation, sample_count, updated_at "
+            "FROM benchmark WHERE pipeline = ?",
+            (pipeline,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Policy persistence
+# ---------------------------------------------------------------------------
+
+
+def write_policy(pipeline: str, policy: dict) -> None:
+    """Upsert the policy dict for ``pipeline``. Writes to store."""
+    conn = connect()
+    try:
+        now = datetime.now(timezone.utc).isoformat()
+        conn.execute(
+            "INSERT OR REPLACE INTO policies (pipeline, policy_data, updated_at) VALUES (?, ?, ?)",
+            (pipeline, json.dumps(policy), now),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def get_policy(pipeline: str) -> dict | None:
+    """Fetch the stored policy dict for ``pipeline``, or None if unset.
+
+    Read-only query (though connecting may create/migrate the store).
+    """
+    conn = connect()
+    try:
+        row = conn.execute(
+            "SELECT policy_data FROM policies WHERE pipeline = ?",
+            (pipeline,),
+        ).fetchone()
+        if row is None:
+            return None
+        return json.loads(row["policy_data"])
+    finally:
+        conn.close()
+
+
+def delete_policy(pipeline: str) -> None:
+    """Delete the stored policy for ``pipeline`` (no-op if unset).
+
+    Writes to store. Subsequent ``get_policy`` calls return None, which
+    callers treat as "use defaults".
+    """
+    conn = connect()
+    try:
+        conn.execute("DELETE FROM policies WHERE pipeline = ?", (pipeline,))
+        conn.commit()
+    finally:
+        conn.close()

ragradar_core/targets.py

@@ -0,0 +1,26 @@
+"""The one sNrN run-id parser, shared by every ragradar package."""
+
+import re
+
+_TARGET_RE = re.compile(r"^s(\d+)r(\d+)$", re.IGNORECASE)
+
+
+def parse_target_id(target: str) -> tuple[int, int]:
+    """Parse an sNrN run identifier into (session_id, run_seq).
+
+    Pure — no store access.
+
+    Inputs: ``target``, a run id like ``"s4r3"`` (case-insensitive).
+    Returns: ``(session_id, run_seq)`` as ints, e.g. ``(4, 3)``.
+    Errors: raises ``TypeError`` if ``target`` is not a string; raises
+    ``ValueError`` if it is a string but not in sNrN format.
+    """
+    if not isinstance(target, str):
+        raise TypeError(
+            f"Run id must be a string in sNrN format (e.g. 's4r3'), "
+            f"got {type(target).__name__}: {target!r}"
+        )
+    m = _TARGET_RE.match(target)
+    if not m:
+        raise ValueError(f"Run id must be in sNrN format (e.g. 's4r3'), got: {target!r}")
+    return int(m.group(1)), int(m.group(2))

ragradar_core-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+ragradar_core/__init__.py,sha256=7j9v3FRH4qNH7I9m0-4Rg7ZU2B0I2z1AOC2A1qqM2Vk,657
+ragradar_core/coerce.py,sha256=_0o71qutmAW5cNmQSaoFGuFJDg2nUM1m9mkiWrZX1dw,9145
+ragradar_core/schema.py,sha256=SQH3_JfaBOEZ6TtS5uN1maTOWW6O6BKVhSJ1xQQZq7s,5960
+ragradar_core/store.py,sha256=DANDgkdSPGUKkEXIMbm3NDnIcav92NeH3vdfYsBhwDQ,27587
+ragradar_core/targets.py,sha256=kaAZ4C4XpxmeYjCPGD4UiBrjREe5NKNSG3BHUyKAraM,940
+ragradar_core-0.1.0.dist-info/METADATA,sha256=4GthQDCvI6HiUfPbjM2QUm_7zUAD1-pix5_530OTSiU,4013
+ragradar_core-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ragradar_core-0.1.0.dist-info/RECORD,,

ragradar_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any