API reference¶
Generated from the docstrings of the public modules, grouped like the documentation: the high level you use, the
building blocks it is made of, and the experimental pieces. The guide explains how the parts fit
together; this reference lists what each module exports and the signatures. Modules whose name starts with _ are
internal and have no page.
High level: ready to use¶
Using solvi explains these. Stable in ordinary 1.x updates; the planned breaking 1.5 transition is documented in the candidate migration notes.
| Module | What it holds |
|---|---|
solvi |
the entry points build, Agent, Guard and Knowledge, Budget, and the shared vocabulary: catalog, questions and answers, System and Response, typed answers |
solvi.solutions.decisions |
one entry point: a question, labelled examples, a promise and a slow path → System 1 fitted, its guarantee and the dispatcher calibrated, the store wired, the choices explained (solvi.build) |
solvi.solutions.wrap |
explicit external-agent decision points, durable evidence-backed overrides and training-only component selection |
solvi.solutions.document |
a decision over a document: one read per field, each fact found in the text, code computes the answer, checks, a calibrated threshold, a replayable record (solvi.document) |
solvi.solutions.agent |
the environment agent: Agent — System 1 on what the knowledge predicts, System 2 a search, hard checks, replay |
solvi.solutions.knowledge |
Knowledge: the store, agenda, action model and failure memory behind one object |
solvi.solutions.guard |
guarding an agent's tool calls: Guard, the "user asked" and "user confirmed" policies |
solvi.models |
the models by name — decider("solvi-base"), llm(url, model), systemone(url, model) — and the published and cached deciders (solvi models: list, pull, check) |
solvi.serve |
solvi serve: HTTP, MCP and the System One API; the MCP proxy with a guard (run_proxy) |
solvi.show |
printing a response |
solvi.check |
solvi check: catalog lint |
solvi.testing |
decision regression tests from cases.json |
solvi.testing.corrupt |
corruption tests for specialists: how many corrupted proposals a specialist's check catches |
solvi.testing.history |
verdicts across runs: stable / flaky / regression / fixed, quarantine, known bugs, a degraded run |
solvi.testing.conformance |
conformance checks for your implementations of the extension points of solvi.core (stores, slow paths, strategists, heads, deciders, extractors, monitors, environments) |
solvi.testing.honesty |
the honesty suite |
solvi.solutions |
the ready-made systems, one module each (above) |
solvi.cli |
the solvi command line |
Fact aliases connect external names to unchanged consumers.
Hypothetical rule evaluation tests intermediate values without production bookkeeping.
Structured rule answers carry typed JSON values and explicit field explanations.
Ordinary function calls record JSON inputs, outputs and parent calls in the same storage chain.
Unrecorded decisions evaluate a supported synchronous catalog with System.decide.
Low level: building blocks¶
solvi.core and its areas, plus the shared statistics in solvi.stat; Building blocks has
one reference per extension point and describes the stability policy and planned transition exception.
| Module | What it holds |
|---|---|
solvi.core |
the low level: the catalog and its value classes, and the extension points (protocols and base classes, see Building blocks); one module per area under solvi.core |
solvi.core.deciders |
the decider: typed questions about a text or a state answered by a model |
solvi.core.deciders.protocols |
the extension points of the parts: Scorer, Decider, Adapter, Head |
solvi.core.deciders.llm |
an OpenAI-compatible chat-completions server (an LLM) as a decider |
solvi.core.deciders.systemone |
a model behind the System One HTTP API as a decider |
solvi.core.deciders.combine |
cascade, vote and route over several models |
solvi.core.deciders.heads |
the learned answer heads: System.fit's FastHead and select_features, CandidateHead, Head (solvi.fast up to 0.7) |
solvi.core.deciders.rulelist |
a readable rule list learned from examples (System.learn_rule; solvi.rules up to 0.7) |
solvi.core.deciders.longdoc |
long texts: sections, BM25 retrieval, the window a decider reads |
solvi.core.deciders.perturb |
instruction-like sentences in an input and the variants without them (perturb=k) |
solvi.core.extract |
@extract by description for long documents (LongSpanExtractor; torch) |
solvi.core.textin |
text in: a message → the question it asks and its typed input state, read with quotes |
solvi.core.sets |
decisions over a set: answers of many items made consistent under at-most / exactly-one / capacity constraints |
solvi.core.plan.strategist |
the strategist: a flow per request (Flow, PlanError), the learned order of hard checks and producer policy |
solvi.core.plan.cost |
the code strategist (CostStrategist): dead ends dropped, the cheapest verified plan |
solvi.core.plan.answer_policy |
conditional candidate reliability, expected-utility planning, stored-answer replay and check budgets |
solvi.core.plan.check_policy |
finite check acquisition with declared prices and replayable decisions |
solvi.core.costs |
measured run times (CostBook), the dollars of recorded model calls (price_of), Budget and Cost |
solvi.stat |
bounded-mean e-processes, reusable checkpoint state, delta budgets, e-BH and sequential e-LOND |
solvi.core.calibration |
reliability, expected calibration error, coverage at a target accuracy |
solvi.core.calibfile |
calibration files (save_calibration / load_calibration) and solvi calibrate |
solvi.core.guarantees.guarantee |
a calibrated threshold with a stated promise on a question (System.guarantee), a computed fact or any scalar |
solvi.core.guarantees.openset |
inputs from outside the calibration set: a threshold sized for the share of them, estimated as the stream goes, and a change flag |
solvi.core.guarantees.canary |
an identity canary for a remote decider: a fixed probe set whose answers fingerprint the model behind the name; a change marks the decisions, flags drift or escalates |
solvi.core.guarantees.drift |
drift: has the stream moved away from the one the thresholds were calibrated on? |
solvi.core.guarantees.monitor |
the Monitor protocol: a watcher of the decision stream |
solvi.core.store |
TraceStorage: JSONL, SQLite, PostgreSQL and DuckDB stores, queries, replay |
solvi.core.signed |
signed JSON snapshots, bounded shared MAC cache, freshness and local replay checks |
solvi.core.store.audit |
res.audit(): what each answer rests on and which safeguards fired; to_dict() as JSON-ready data |
solvi.core.store.report |
reports of one decision or a period of stored decisions (Markdown, HTML, data) |
solvi.core.store.sysreport |
the system report: who answered, the cost, the promise against the stored labels, drift — from the store alone |
solvi.core.store.signature |
a signature of a trace or a store that names the one changed record |
solvi.core.store.diff |
solvi diff and shadow mode |
solvi.core.explain |
explaining a decision: the smallest change of the given inputs that changes an answer (counterfactuals), the cost of a change a parameter |
solvi.core.specialist |
the specialist contract: propose a typed spec, check it against the source, render, replay; runs stored as records of kind "specialist"; two readers aligned (align) |
solvi.core.versions |
versions of a document: clauses (Spec), catalog versions citing them, versions with parents and rollback, the decisions a new version moves (decision_diff) |
solvi.core.slow.generate |
generation by an LLM: a text or validated JSON, quotes checked in a text, recorded as a model's output |
solvi.core.slow.agree |
agreement of generated candidates under a key: the chosen one, its share as a fact, the tally |
solvi.core.slow.refine |
a check that says why (Fail); the loop propose → check → re-ask with the reasons → escalate |
solvi.core.slow.proposals |
one proposed / dropped / refuted / admitted count for laws, refine and compile |
solvi.core.slow.search |
search over alternatives: candidates through the System's checks, the best by an objective, pruned, recorded |
solvi.core.dispatch |
who answers: System 1 within its guarantee, a slow path (a System, refine or search) or a person — one recorded decision per input, with a budget |
solvi.core.environment |
the Environment protocol and Outcome: a world an agent acts in |
solvi.core.knowledge |
what a system knows across decisions: the knowledge store, write gates, the action model, risk policies, the agenda, the failure memory |
solvi.core.knowledge.store |
the knowledge store: a hash-chained journal of items with provenance, disputes, retraction, staleness flags, snapshots |
solvi.core.knowledge.gates |
write gates: WriteGate, the source check, the consistency check |
solvi.core.knowledge.actions |
the action model: accept / refuse / unknown with risk and support, learned over an explicit vocabulary |
solvi.core.knowledge.risk |
protection (Protect), justified risk (RiskBudget), a bounded learned gate (LearnedGate) |
solvi.core.knowledge.agenda |
goals with done checks in code, gates, order; a dry run that validates gates |
solvi.core.knowledge.failures |
do not repeat a plan that failed recently: a hard check with an expiry and a bound |
solvi.core.knowledge.memory |
a memory of corrected cases: nearest neighbours with an abstain threshold; with a store, its correction facts |
solvi.core.knowledge.episodes |
an agent's memory (what was tried, what failed, what worked) as an input |
solvi.core.knowledge.worldmap |
a map of an environment an agent builds by acting: claims with provenance, a view over "leads_to" facts |
Module by module¶
The modules solvi.core is made of. Their public names are re-exported by solvi.core (or the package named), so you rarely import from them directly; the 1.0 migration table points to some of them (solvi.core.runtime for Trace, Record, Result, MISSING; solvi.core.types for FactTypeError).
| Module | What it holds |
|---|---|
solvi.core.catalog |
the catalog: Catalog, Question, Answer and the decorators that register parts (re-exported by solvi.core and solvi) |
solvi.core.system |
System: catalog + questions → ask → answers with flow, trace and safeguards; fit / teach; storage |
solvi.core.response |
Response: the answers of one ask with the flow, the trace, the values and the safeguards |
solvi.core.runtime |
flow execution and replay: Trace, Record, Result, Replay, MISSING, the hash chain of the steps |
solvi.core.types |
typed facts: the types a catalog function's hints give the facts it reads and sets, Scale, FactTypeError |
solvi.core.provenance |
provenance of facts and answers, model identity and fingerprints, grounding of quotes (matches) |
solvi.core.primitives |
answer primitives: "not stated" (Unknown), evidence, spans, rankings and estimates |
solvi.core.schema |
pydantic models of solvi's public data: answer types, questions, results, trace records, flows, responses |
solvi.core.contract |
the contract of an answer: its type, no echo of the input, applicability checked before the answerer is called |
solvi.core.chain |
the hash chain of a trace: records added after the flow's steps |
solvi.core.sources |
where a label may come from: the trusted sources and the check every channel runs |
solvi.core.plan |
planning a question's flow: the strategist protocol and the built-in strategists |
solvi.core.guarantees |
promises on answers: calibrated thresholds, drift, open-set inputs |
solvi.core.slow |
the deliberate path (System 2): generate, agree, refine, search |
solvi.core.deciders.model |
DecideModel: a decider checkpoint (or any scorer) — load, score, decide, adapt, make decision parts |
solvi.core.deciders.part |
DecisionPart: a decider bound to one question, with its gates, guarantees and files |
solvi.core.deciders.adapt |
adapting one question: label-bias correction, few-shot shift and scale, temperature |
solvi.core.deciders.backends |
the encoders: ONNX and torch scorers, tokenizing, file fingerprints |
solvi.core.deciders.capabilities |
a checkpoint's declared capabilities (solvi_decide.json) with their defaults |
solvi.core.deciders.gate |
what decides alone: the act features, thresholds, promises (act_guard) |
solvi.core.deciders.kinds |
question kinds, wire markers and the options each kind takes |
solvi.core.deciders.state |
the input a decider reads: a text, or a state serialized by state_text |
solvi.core.deciders.wire |
what the scorer sees: items, passes, prompts, logits, the pointer's spans |
Experimental¶
solvi.experimental: may change in any release; each piece graduates or is removed by 1.2
(Experimental says what each one is missing).
| Module | What it holds |
|---|---|
solvi.experimental |
STATUS: what each experimental piece is, what it is missing, its deadline |
solvi.experimental.lora |
a LoRA adapter per question, fitted on a few hundred labelled examples |
solvi.experimental.injection |
a detector of instruction-like text in tool outputs, fitted and thresholded on your own tool outputs |
solvi.experimental.compile |
a specification compiled by an LLM into catalog parts citing its clauses, accepted when two drafts agree and the spec's tests pass; a person for what the drafts dispute; recompile, an agent guard (versions and the decisions a change moves: solvi.core.versions) |
solvi.experimental.compile.sandbox |
code a model wrote, held to pure functions: ast allowlist, a subprocess with limits, a restricted load |
solvi.experimental.hooks |
a coding agent's hooks: edits checked against rules, a skill picked for a prompt, install / uninstall (Claude Code; Codex, preview) |
solvi.experimental.charts |
verified charts: a text with numbers → an SVG in which every number is quoted from the text |
solvi.experimental.changes |
one change pipeline for a document version, verified experience, a person's correction or a search proposal: pluggable stages, a journal, promote, versions, rollback; a labelled update (LearningTarget) is a candidate change |
solvi.experimental.regime_memory |
bounded asynchronous finite-regime filtering over declared LawSet IDs; delayed observations and owner-managed snapshots, without automatic law activation |
solvi.experimental.experience |
finite joint alternatives, paid observations, external outcomes and empirically admitted scalar programs in a recoverable loop |
solvi.experimental.laws |
laws of an environment from prediction mismatches: a grammar of atoms, candidates from each wrong prediction, acceptance only by a held-out test on other worlds / sessions / paths, retirement, a probe planner (read-only before write), export into the knowledge store |
solvi.experimental.skills |
learning in a world described by code: planning on an exact model (a copy of the environment), verified plans compiled into System 1 skills over a grammar of atoms, each used alone only under an anytime-valid certificate of its outcomes, the planner as System 2 of solvi.Agent, export into the knowledge store |
solvi.experimental.ood |
an out-of-domain watch next to the default Platt calibration: "out of domain" in why, shift(batch) for a batch unlike the calibration answers |
solvi.experimental.audit |
a watch on a check run on a random share of decisions: a Bernoulli CUSUM whose threshold knows the audit share |
solvi.experimental.process |
a process of several systems: nodes, edges with predicates as data, loops with a limit; a JSON spec with a hash, diff, render, from_spec checking fingerprints; run / explain across the nodes' stores, questions to a person through a queue (HumanChannel) with resume, replay of a run, and the path promise (guarantee() in the modes union, per_node and end_to_end after calibrate, PathWatch) |
solvi.experimental.stream |
a promise earned on the stream: an anytime-valid learn-then-test certificate on a threshold grid (an e-process per grid point, fixed-sequence, the threshold only loosens, δ spent over restarts), installed with System.guarantee(promise=); measured, see the documented limits |
solvi.experimental.numguard |
exact values through a side channel: pointers to the input's numerals and exact <calc> / <date> calls filled in by code, a guard that names the source of every number in a text or refuses it, one retry with what failed |
solvi.experimental.relations |
relations over a state (packed bits) and rules over them: the relation algebra, a bottom-up enumerator with observational equivalence on the full relations, a library of accepted programs, compilation into set code or index arrays with a differential check, encoders (a grid window seen from the player, a path tree) and a proposer of relational atoms for the laws' held-out test; composites by enumeration with a library of rules that passed a held-out test (relations.library.find_rules), a fallback slot for a learned proposer; composition tables (relations.CompositionTable) and forward chaining over their rules in a knowledge store (relations.forward_chain); rules first, a model second (relations.RulesFirst: the table answers what it derives, a fallback model what it refuses) |