Skip to content

solvi.core.store

TraceStorage: stored responses and traces, queries and replay; JSONL, SQLite, PostgreSQL and DuckDB backends.

TraceStorage: stored responses with their traces, a hash chain across them, queries, a replay of everything stored, and provenance questions over the store (which stored decisions rest on a fact found to be wrong; what a forgotten given fact touches).

Every stored decision is one record (a dict of plain JSON):

kind "ask" the 0.5 journal line's keys — init_hash, answers {question: [answer, confidence, status]}, flow, records [[step, name, hash]] (and producers) — plus index fields (guards, safeguards, models) and the whole response (Response.to_dict(): answers, flow, trace), which get() loads back and replay_all() re-checks; kind "teach" a correction (System.teach): {"teach": question, "init": ..., "answer": ...} and, when given, its "source" ("outcome", "rule", "verified"; none: a human), "by" and "of" (the stored id of the decision it corrects; for "verified", the System 2 decision the label is); kind "update" a labelled update (solvi.experimental.changes, LearningTarget): what changed, the gates' results, the state to roll back to; kind "specialist" a specialist's run (solvi.core.specialist): the source's hash, the proposal, the check, the output's hash; kind "stream" a state change of a Dispatcher's stream certificate (promise=, audit="adaptive"): {"stream": {"event": "grid" | "certified" | "loosened" | "alarm" | "recertify", "question", "decision", "v_index", "delta_v", "threshold", "n", ...}}; a dispatch record of such a dispatcher carries "stream" too (its sample, certificate and detector state). "stream" is KEPT: a redaction leaves it; kind "pending" a ticket issued to an oracle outside the process (solvi.experimental.stream.tickets): {"pending": {"ticket", "question", "n", "created", "ttl", "kind_hidden", "rho", "probation", "sampled"}, "issue": the decision begun (Dispatcher.start: the input, System 1's response, the draws)}; its dispatch record, written when the ticket is resolved or expires, carries "pending": the ticket. kind "pending_expired": {"pending": {"ticket", "question", "n", "at", "why"}} — no verdict came. "pending" is KEPT; kind "loop" one decision of the closed learning loop (solvi.experimental.stream.versions): "question", "stream" (KEPT: the served and candidate versions, the coin, the scores, both certificates' states) and "loop" (the input, the would-be answers, the label: not kept); its freeze / promote / discard / rollback are records of kind "stream"; every record seq (0, 1, 2, ...), time (seconds since the epoch), meta (optional, yours; a decision made with solvi.experimental pieces has meta["experimental"]: their names), prev and hash.

A record is written with every dict's keys in their own order (a decider reads a dict's keys in that order, so a stored trace gives its dicts back as they were). hash is the SHA-256 of the record's canonical JSON (keys sorted, without id and hash) — it does not depend on the order the record was written in — which includes prev, the hash of the record before it: editing, deleting, inserting or reordering a stored record breaks the chain at that point (verify()). Cutting records off the end leaves a shorter chain that is still valid, so the store keeps its head — the count and the last hash (head()) — next to the log and verify() checks it; a head you published elsewhere (verify(anchor=head)) also catches a rewrite of the whole chain together with the stored head.

Backends: JSONLStorage (append-only file, one record per line; what System(storage="file.jsonl") writes), SQLiteStorage (stdlib sqlite3; indexed by question, answer, status, safeguard, model fingerprint and time; several processes may write), PostgresStorage (psycopg 3; the same tables, several services writing) and DuckDBStorage (duckdb; the same tables in a DuckDB file, for analytics).

UntrustedLabel

Bases: ValueError

A label from a source outside TRUSTED_SOURCES (the model, the system itself, an unknown process), or a "verified" label offered to a channel that does not take it.

CompactRecord

Bases: ValueError

A stored decision kept compact (record="compact"): its trace is not in the store, so it cannot be loaded as a Response. TraceStorage.rederive(id, system) re-runs it from the recorded input and checks every step against the recorded hashes; replay_all does so too.

Stored dataclass

Stored(id: str, seq: int, time: float, kind: str, data: dict, catalog: object = None)

One stored record: its id, position, time (seconds since the epoch), kind ("ask": a decision; "teach": a correction; "redaction": the mark of an erasure, see TraceStorage.redact) and the record itself.

answers property

answers

question → the stored answer (JSON form: tuples as lists, "not stated" as "").

run property

run

The id of the run that wrote this record (see run_context), or None.

parent property

parent

The id of the decision this record follows from (run_context(parent=)), or None.

compact property

compact

Was this decision stored compact (record="compact", or not drawn for a full record under "sample:N")?

input property

input

The given facts of a stored decision as JSON data (full or compact; None for a redacted one).

response

response(catalog=None)

The stored response, loaded back (typed values restored from catalog — a Catalog or a System — or from the store's own). A compact record raises CompactRecord: re-derive it with TraceStorage.rederive(id, system).

TraceStorage

TraceStorage(system=None, clock=None, record='full')

Bases: ABC

A store of responses and their traces with a hash chain across the stored records (see the module docstring).

The base class of every store (an extension point: from solvi.core import TraceStorage). A backend of your own implements five methods — _append(body) (assign seq, time, prev, hash and id atomically; → the record), _raw(snap=None) (every chained record in stored order: (position, dict or None when unreadable)), _find(id) (the record or None), head() ({"count", "hash"}) and _rewrite(rec) (replace the record with that seq: redact uses it) — and may override close(), _snapshot(), _backend_problems(rows, snap), iter / query (for an index). It gets for free: the hash chain and verify (with an anchor and a signature), save / get / rederive (full and compact records), corrections and verified labels with their source checks, query, report, replay_all, quarantine / where_is, redact, signature, and every reader of a store (the audit, the system report, diff). solvi.testing.conformance.check_storage(MyStorage) checks a backend. Stability: stable; the record format is stable (stores of 0.7 to 0.9 read and verify).

save(response, meta=None) → id; save_many(responses, metas=None) → [id]; batch() (a context: the saves inside it share one lock, one head write / one commit); get(id) → Response; record(id) → the stored dict; iter() / query(...) → [Stored]; corrections() → the teach records; head() → {"count", "hash"}; signature(); verify(anchor=None, signature=None); replay_all(system); quarantine(fact, value=...); where_is(fact, value=...).

system: the System (or a Catalog) used to restore typed values (dates, enums, models) when loading responses; System(storage=...) sets it to that system when it is not set. clock: a function → seconds since the epoch.

record: what a decision's record holds — "full" (default: the whole response, every step's value and inputs), "compact" (for frequent decisions: the input, the answers, every check's result and reasons, the model-backed steps whole with the models' ids, fingerprints and tokens, and every step's hash; not the computed values, the planned flow or the timings — see compact_content) or "sample:N" (one decision in N, counted by this store object, in full, the others compact). A compact record is hashed into the chain like any other: verify() checks it, its kept steps' places and links in the chain of step hashes, and its answers. What it does not keep is re-computed, not read: replay_all re-runs the decision from the recorded input and compares every step's hash (rederive); a model step that is not re-run on replay (trust_models=True, a generator) leaves the decision unchecked past the chain, and the replay says so (mismatch kind "not_kept") instead of passing it. get(id) raises CompactRecord; the reports read the answers, checks, models and costs from what is kept; quarantine re-derives compact decisions when the store knows the System; diff compares their answers only (no steps are kept to say what changed them).

head abstractmethod

head()

{"count", "hash"}: the number of chained records and the last record's hash (GENESIS when empty). Publish it somewhere else (a ticket, a log, a signed message) to later catch a rewrite of the whole store: verify(anchor=...).

save

save(response, meta=None, *, record=None)

Store a response (its answers, flow and whole trace) → its id. meta: your own JSON data kept with it (a ticket id, a user) — hashed into the chain like the rest. What the record holds follows the store's record=; record="full" or "compact" overrides it for this response (System(cache=) stores a served decision compact).

batch

batch()

A batch of writes: with store.batch(): for r in responses: store.save(r). JSONLStorage takes its locks once and writes the head (and, with fsync=True, syncs) once at the end, not per record; the SQL stores run the batch as one transaction — one commit, and an exception inside rolls the whole batch back (JSONL keeps the records written before it, with their head). Other threads and processes wait for the batch to end. Inside a batch only save, save_correction and reads that need no lock (get, iter, query, head) are for this thread; verify and redact raise. A backend without its own batch saves one record at a time, as outside one.

save_many

save_many(responses, metas=None)

save() each response in one batch() → their ids. metas: None or one meta (or None) per response.

save_correction

save_correction(question, init_state, answer, meta=None, *, label_source='human', by=None, of=None, note=None)

Store a correction (what System.teach records) → its id. label_source (source= in 0.7; stored as the record's "source"): where the label comes from — "human" (a person corrected or confirmed the answer), "outcome" (what really happened: the parcel was lost, the loan defaulted) or "rule" (code rejected a model's proposal and decided instead), or "verified" — a System 2 answer that passed the checks and a guarantee: of must then name that decision, stored in this store, which answered question alone (status "ok", not escalated or abstained) under a guarantee (System.guarantee) with this very answer; anything else raises UntrustedLabel, and the label is not stored. Anything else is refused (UntrustedLabel): the system's own unverified answers are never labels. by: who (a user, a reviewer, a process); of: the stored id of the decision it corrects (for "verified", the one it is); note: a line of text kept with it (what happened — System.outcome writes it). Every record writes its "source" (since 2026-10-30 the default too); records of 0.6 have no source: they are human corrections. Storing a verified label teaches nothing by itself: which channel may read it, see check_source.

record

record(id)

The stored record (a dict) with this id; KeyError if there is none.

get

get(id, system=None)

The stored response with this id, loaded back with system (default: the store's; see Stored.response).

rederive

rederive(id, system=None, trust_models=False)

A stored decision as a Response — a full record loaded as get() loads it; a compact one re-run with system (default: the store's) from its recorded input, every step checked against the recorded hashes (see the module function rederive). Raises CompactRecord with the reasons when a compact decision cannot be rebuilt.

iter

iter(kind='ask', redacted=False, after=None)

Stored records in order (kind "ask": responses; "teach": corrections; None: all) → iterator of Stored. A redacted record (see redact) has no content left and is passed over; redacted=True: it is yielded too. after: only the records stored after this sequence number (Stored.seq) — the cursor of a reader that keeps its own index over the append-only store and reads only what was appended since (JSONLStorage serves it from its parsed-lines cache without walking the whole store).

__len__

__len__()

The number of chained records — decisions, corrections and redaction marks (head()["count"]); the decisions alone: len(list(store.iter())).

close

close()

Release what the store holds open (a database connection; nothing for a JSON-lines file). A store is also a context manager: with SQLiteStorage("decisions.db") as store: ... closes it at the end.

corrections

corrections(label_source=None)

The stored corrections → [{"id", "time", "question", "init", "answer", "source", "by", "of"}] (feed them to fit / learn_rule, a CorrectionMemory or an update target of solvi.experimental.changes). source: "human" (also every record without one), "outcome", "rule", "verified" — or, for a record written around save_correction, whatever it says (solvi.core.knowledge.memory and the update target of solvi.experimental.changes refuse anything outside TRUSTED_SOURCES, "verified" included; System.guarantee takes "verified" when told to). label_source: only the corrections from this source (or these sources) — e.g. "audit", the labels of the decisions drawn at random (Dispatcher(audit=)).

query

query(question=None, answer=ANY, status=None, safeguard=None, model=None, since=None, until=None, catalog_fp=None, run=None)

Stored responses that match every filter given → [Stored] in stored order. question: asked this question; answer: answered this (with question: that question's answer; None matches an abstention); status: "ok" / "forced" / "abstain" (with question: of that question); safeguard: a safeguard of this kind fired ("grounding", "hard_check", "low_confidence", ...; with question: one that concerns it); model: a model with this fingerprint, id or type produced a step; since / until: stored in [since, until) — seconds since the epoch, a datetime, a date or an ISO string; catalog_fp: decided by the catalog with this fingerprint (System.fingerprint()["catalog"]); run: written inside run_context(run) with this run id (records written outside a run_context have none). An answer is matched in its stored form: answer=True finds a yes/no "yes" (see _answer_key).

report

report(since=None, until=None, question=None, format='md', examples=3, system=None, **filters)

A human-readable report of the stored decisions in [since, until) (optionally of one question): counts by answer, status and safeguard, the escalation rate, the guarantee coverage of the answers a model took part in, changes of the catalog's and the models' fingerprints, and examples stored ids per answer, escalation and safeguard. format: "md", "html" (one self-contained page) or "data" (a dict); other filters as query. See solvi.core.store.report.

redact

redact(id, by=None, note=None, keep_answers=True)

Erase a stored record's content — a person's data that must go — and keep the chain whole.

The record keeps its place, its time, its hash and its id, so every link after it still verifies; its content (the response with its trace and input, the meta; a correction's input and answer) is removed and it is marked redacted with who and why and the digest of what was removed. A record of kind "redaction" is appended that names the erased record and its hash: the erasure is itself in the chain, with its time. keep_answers=False removes the answers too (their digest stays in the mark). The record no longer replays and is passed over by iter / query / replay_all / reports; record(id) returns what is left. → the redaction record's id.

What is left stays verified: a record's hash is taken over its lasting fields, the digest of its answers and the digest of its content (record_body), so verify() recomputes the hash of a redacted record like any other — an answer edited in it afterwards, or a record passed off as redacted with other answers, does not verify — and a signature taken before the erasure still holds. A record written by solvi ≤ 0.7.1 (format 1) has one flat hash: redacting it leaves its kept fields unverifiable, which verify() lists under "unverified". What it cannot do: copies made before (a backup, an exported report, a published anchor's holder) are not touched, and derived state (a correction memory, a fitted head) keeps what it learned — rebuild those.

signature

signature(alg='syndrome')

The signature of the chained records (solvi.core.store.signature.sign): {"alg", "count", "root"} — with the default "syndrome" code two numbers (64 bytes). Keep it where you keep the head: verify(signature=...) then names the one record that changed — even when every hash after it and the stored head were recomputed — and restores its content hash.

verify

verify(anchor=None, signature=None, candidates=None, *, deep=True)

Check the chain across stored records: each record's hash, its link to the record before it, the sequence numbers, the stored response against its own summary, and the stored head (a cut-off tail). anchor: a head() taken earlier and kept elsewhere — the chain must still contain it (catches a rewrite of the whole store). signature: a signature() taken earlier and kept elsewhere — the records it covers must be the ones signed; when one changed, its seq is named and signature in the result holds solvi.core.store.signature.check's answer (the original content hash; candidates: records, e.g. from a backup, one of which may be the original → its "match"). → {"ok", "count", "head", "legacy", "problems": [(seq, id, reason)]} (+ "signature" when given; + "unverified": [(seq, id, reason)] — redacted records of format 1, whose kept fields no hash covers). Records written before the chain (0.5 journal lines) are counted in legacy and not checked. A store that is being written to verifies as it stands at one moment: the stored head is read first and the records are checked against it, so a record appended while verify runs is not reported as damage. deep: True (default) also re-checks each stored response against its own summary (the answers, their confidence, the trace's hashes and links, guards, safeguards, models, flow); False skips that re-check and keeps every chain check (each record's hash, links, sequence, ids, redactions, the head, anchor, signature) — an edit is still caught unless the editor recomputed the record's hash and every hash after it, which only an anchor or a signature kept elsewhere catches.

replay_all

replay_all(system, trust_models=False, **filters)

Replay every stored trace (or those matching query filters) against system (a System or a Catalog): each step is re-computed from its recorded inputs (see Trace.replay). → the ones that fail: [{"id", "seq", "time", "mismatches": [(step, name, reason)], "models": [(step, name, verdict)], "catalog", "kinds", "summary"}] — empty when all replay. Each mismatch has a .kind, and "summary" tells damaged data from a catalog or a model that changed since (see solvi.core.runtime.Mismatch). A stored record that cannot be loaded is one mismatch (0, "load", ...), a replay that raises is (0, "replay", ...): both of kind "error", no verdict on the data. "note" (a record of format 1 whose model step does not recompute): it was stored with sorted dict keys, see LEGACY_ORDER. A compact record (record="compact") is re-run from its recorded input and every step compared with its recorded hash (rederive), then replayed like a full one; one that cannot be — a model step not re-run (kind "not_kept": no verdict on the data past the chain), a step whose hash differs (kind "recompute": the old value is not kept) — is listed with "record": "compact".

One store, several systems: pass them all, replay_all([system_a, system_b]) — each record is replayed against the system that asks every question it answers (the one whose catalog fingerprint is the recorded one first). A record that no given system asks any question of is listed with a mismatch of kind "other_system" instead of the missing parts and inputs a foreign catalog would report — not an integrity verdict: which questions a record answers is its own (editable) content. What does not depend on the system is still checked: a full record's trace hashes (kind "integrity"); a compact one keeps no trace ("not_kept"), and a trace that cannot be loaded with this system is an "error" mismatch, never passed over. Every record's own hash is checked as verify() checks it (an edited record: kind "integrity"). question= / catalog_fp= filters replay one system's records only.

provenance_index

provenance_index()

An index of which stored records read or hold which fact → ProvenanceIndex. Its quarantine(fact, value) and where_is(fact, value) answer as this store's do, looking only at the records that can match instead of every record; it follows records saved after it was built (it reads the new ones on the next query).

quarantine

quarantine(fact, value=ANY, *, _rows=None)

A fact (or a given input) found to be wrong: the stored decisions whose answers rest on it — through the trace's provenance graph (each step's recorded inputs, from the answer back to the fact; a hard check that ran for the question counts, passed or failed: the answer stood because it passed). value: only where the fact had this value (compared by its hash as the consumers recorded it). → [{"id", "seq", "time", "questions": {question: {"answer", "status", "path": [fact, ..., "answer:question"]}}}]. Nothing is changed: re-decide or review these. A compact record keeps no step inputs: it is re-derived with the store's System (rederive) and its rebuilt trace is searched; one that cannot be (no System, a model step not re-run, a step that no longer recomputes) is not searched, and a UserWarning names how many and their ids.

where_is

where_is(fact, value=ANY, *, _rows=None)

Where a given fact (e.g. a person's data) is held, and what removing it would touch (forget in 0.7) — a report only: nothing is deleted (deleting a stored record breaks the chain by design; keep the report as the record of the request, and erase the records it lists with redact). → {"fact", "value", "dependent": the stored decisions whose answers rest on it (as quarantine), "stored": ids of the stored records that hold it without an answer resting on it (responses and corrections), "deleted": 0}. A compact record that holds it in its input is listed under "stored": it keeps no step inputs to say what rests on it (quarantine re-derives it for that).

ProvenanceIndex

ProvenanceIndex(storage)

Which stored records read which fact (as a step's recorded input) and which hold it as a given input — built from a store in one pass (TraceStorage.provenance_index()), so that quarantine(fact, value) and where_is(fact, value) visit only the records that can match. The answers are the store's own (the same lists, in stored order): the candidates are then checked by the store's quarantine / where_is. A compact record keeps no step inputs: it is always a candidate of quarantine (re-derived there, as the store does). Records saved after the index was built are read on the next query; a record redacted since is passed over, as the store passes it over. In memory only: {fact: {record id: value hashes}}, nothing is written to the store.

refresh

refresh()

Read the records saved since the last refresh (cheap when there are none: one head() read).

quarantine

quarantine(fact, value=ANY)

As TraceStorage.quarantine, over the records that read fact (with this value, when given).

where_is

where_is(fact, value=ANY)

As TraceStorage.where_is, over the records that read or hold fact.

JSONLStorage

JSONLStorage(path, system=None, clock=None, fsync=False, index=True, *, record='full', rotate_bytes=None, rotate_records=None)

Bases: TraceStorage

Append-only JSON lines, one record per line (the file System(storage="file.jsonl") writes). The head (count and last hash) is kept in <path>.head. Threads of a process may write; several processes may too where the system has advisory file locks (POSIX: an append takes an exclusive flock on the file, reads what other processes appended since it last looked, then writes its record and the head) — on Windows keep to one writing process, or use SQLiteStorage. Lines of a 0.5 journal at the start of the file are kept and skipped (verify reports them as legacy). fsync=True: flush every record to disk before save returns (slower; without it a power failure can lose the last records, which the OS had not yet written). index=False: open from the stored head (checked against the file's last line) without reading every record — a long file opens at once, for a process that only appends; get(id) then scans the file. A head that does not match the last line is not trusted: the file is read. record: "full", "compact" or "sample:N" (see TraceStorage).

Rotation. rotate_bytes / rotate_records: when the file has reached that many bytes (or chained records), the next append first moves it to a closed segment <name>.000001.jsonl (with its head; the number counts up) and starts path again with a record of kind "segment" that names the closed segment, its record count and its last hash — so each file verifies on its own, the first record of a file is linked to the head of the one before it, and verify_segments() checks every segment and every link (a segment replaced, cut short or removed breaks a link). Reads (iter, query, get, replay_all) and redact see the current file; segments() lists the closed ones, each readable as a JSONLStorage of its own. A closed segment is not written to: redacting one of its records there would append to it and break the link of the file after it (not supported yet). With rotation, writers of the same path lock <path>.lock (a file that is never moved): every process writing a rotated store must open it with rotation on.

segments

segments()

The closed segments of a rotated store, oldest first → [path] (the current file, path, is not listed).

verify_segments

verify_segments(anchor=None, *, deep=True)

Verify a rotated store whole: every closed segment and the current file (each as verify() checks it) and every link — the first record of each file after the first is a "segment" record naming the file before it, its record count and its last hash, which must be that file's. anchor: a head() of the current file kept elsewhere; deep: as verify(). → {"ok", "files": [{"path", "ok", "count", "head"}], "count": records in all files, "problems": [(path, seq, id, reason)]}.

batch

batch()

See TraceStorage.batch: the thread lock and the file locks are taken once, the head is written (and, with fsync=True, the file synced) once at the end — also when the batch ends with an exception.

iter

iter(kind='ask', redacted=False, after=None)

As TraceStorage.iter, with after served from the parsed-lines cache: only the records past that sequence number are walked to (a bisect on the cache's seq index), so a reader that keeps its own cursor — the process store's index over tickets, answers and segments — costs O(new), not O(store) (S267/S277).

SQLiteStorage

SQLiteStorage(path, system=None, clock=None, timeout=30.0, *, record='full')

Bases: _SQLStorage

SQLite (stdlib sqlite3): one row per record with the record's JSON, plus index tables — answers (question, answer, status), safeguards (kind, question), models (fingerprint, id, type) — and the time. The head is kept in the meta table. Appends run in a write transaction, so several processes may write to one file. Each record is one committed transaction: durable once save returns (unlike JSONLStorage without fsync=True), at the cost of a disk sync.

PostgresStorage

PostgresStorage(conninfo, system=None, clock=None, prefix='solvi_', *, record='full')

Bases: _SQLStorage

PostgreSQL (psycopg 3, pip install solvi[postgres]): the tables of SQLiteStorage, named with prefix ("solvi_records", ...), created when missing. Several processes and services may write: an append locks the head table (LOCK TABLE ... IN SHARE ROW EXCLUSIVE MODE — readers are not blocked) for its transaction, so the chain has no forks. conninfo: a connection string ("postgresql://user@host/db") or an open psycopg connection in autocommit mode (the store runs its own BEGIN / COMMIT).

DuckDBStorage

DuckDBStorage(path, system=None, clock=None, prefix='', *, record='full')

Bases: _SQLStorage

DuckDB (pip install solvi[duckdb]): the tables of SQLiteStorage in a DuckDB file (":memory:" for none) — for analytics over the stored decisions next to JSONL or Parquet files (store.db.sql(...)). One writing process at a time (DuckDB's own rule); threads of that process are fine.

check_source

check_source(source, accept=(), channel=None)

A label's source → itself, when it is trusted: "human", "outcome", "rule" or "audit" (a person's or an outcome's label of a decision drawn at random for it; the store checks the decision was) — or "verified" when the channel lists it in accept (only System.guarantee(..., sources=) does: see VERIFIED); else UntrustedLabel, with the measured reason when a channel (channel, a key of VERIFIED_REFUSED) refuses a verified label.

record_body

record_body(rec)

What a record's hash is taken over. Format 1 (solvi ≤ 0.7.1): the record without id and hash. Format 2: the fields that stay for ever (KEPT), the digest of its answers and the digest of everything else (its content: the response, the input, the meta) — three parts, so that redact can remove the content, or the answers too, leave their digests in the record's mark, and the hash still recomputes: what is left of a redacted record is verified like any other record, and a record cannot be passed off as redacted with other answers.

record_hash

record_hash(rec)

The hash of a stored record: SHA-256 of the canonical JSON of its body (record_body; it covers prev).

plain

plain(v)

A value as stored: JSON data (sets sorted as vhash sorts them, dates as ISO strings, "not stated" as "").

record_mode

record_mode(record)

A store's record= → ("full", None), ("compact", None) or ("sample", N); ValueError for anything else.

compact_content

compact_content(d)

A response's dict (Response.to_dict()) → what a compact record keeps of it (see TraceStorage, record="compact"): the given facts (the input as read, with the types that restore it), each answer with its why / guard / source / evidence / guarantee (not its probabilities), each check's result and reasons, the model-backed steps and the answer heads, guarantees, plan, text and then records whole (with the models' ids, fingerprints and token usage), the steps skipped, the catalog's and questions' fingerprints, and the time. Left out: the values of the computed facts (they are re-computed), the other steps' records (their hashes stay in the record's records), the planned flow, the timings and the per-part fingerprints.

entry

entry(resp, meta=None, record='full')

The stored content of a response (without seq, time, prev, hash). record: "full" (the whole response) or "compact" (compact_content: the input, answers, checks and model steps — see TraceStorage).

run_context

run_context(run=None, parent=None)

Within it, every record solvi writes to a store (decisions, corrections, knowledge, dispatch and change records — JSONLStorage and the SQL stores, any of them) carries "run": {"id": run, "parent": parent} — hashed into the chain like the rest — so the records of one run, written to several stores, can be put in one order (chronology). run: the run's id (default: inherited from an enclosing run_context, else a new random one); give the same id to the other processes of a run. parent: the id of the decision the records inside follow from (a nested with run_context(parent=decision_id): keeps the run id). → an object with .id and .parent. Opt-in: outside a run_context nothing is added, and readers take records without "run" as before. A store of your own sees the field when its _append writes the body it is given. store.query(run=id) finds the decisions of one run. The run lives in a context variable: a thread started inside does not inherit it — submit work to a pool as pool.submit(contextvars.copy_context().run, fn, *args), or open run_context(run=id) in the thread.

current_run

current_run()

The run_context in force → {"id", "parent"} or None.

chronology

chronology(*stores, run=None, kinds=None)

The records of several stores in one order → [{"store", "id", "seq", "time", "kind", "run", "parent"}] by time (ties: the order the stores are given, then seq). stores: TraceStorage objects (or KnowledgeStore / anything with a .storage that is one), or one dict {name: store} — "store" is then the name, else the position. run: only the records of this run id; kinds: only these kinds. Records written outside a run_context have run None.

view

view(d)

A stored decision's response as a dict, for readers that do not need the whole trace (reports): the stored response, or for a compact record what it kept, shaped the same way ("results", "trace" with "init" and the kept "records", "ms", "safeguards"). None for a record without either (a redacted one).

chained

chained(d)

Is this a record of the chain (a dict with its hash)? A JSON object without one — a line another tool appended to the file, a hand edit — is not: it is passed over by iter / query / replay_all, and verify reports it.

rederive

rederive(d, system, trust_models=False)

A compact record (dict) → (Response or None, [Mismatch]): its decision rebuilt with system from the recorded input. The flow is planned again for the recorded questions and run; a model-backed step whose model is not re-run on replay (trust_models=True, a generator, a model not available) gives its kept output instead of calling the model (a compact record keeps every model step whole), and a model step that is re-run and gives the kept output takes the kept record (its latency and usage); then every step's hash is chained again and compared with the recorded one — a hash covers the step's inputs, value, error and the link to the step before, so equal hashes mean the step gave what it gave then — and the kept records after the flow (answer heads, guarantees, plan, text, then) are appended. The Response is the decision as it was: replay it like a stored one. None, with the reasons, when it cannot be rebuilt: a step whose hash differs (kind "recompute": the catalog changed since — the old value is not kept, only its hash), a kept model output that does not give its record again or a model step of several producers that is not re-run (kind "not_kept": no verdict past it), the input not restored.

open_storage

open_storage(where, system=None)

A TraceStorage from a path: .db / .sqlite / .sqlite3 → SQLiteStorage, .duckdb → DuckDBStorage (in any case), a postgresql:// (or postgres://) URL → PostgresStorage, anything else → JSONLStorage; a TraceStorage is returned as it is.