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`.
