Skip to content

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)