solvi

Build decision systems from a catalog of Python functions and checks plus typed questions, and get answers you can verify.

Why

You describe a task with plain Python functions (computations, checks, answer rules) and questions with typed answers (yes/no, a choice, a score, "not stated", a span of the text, a ranking, a number range). For each request, a strategist plans which functions and checks to run for the asked questions. Every answer comes with:

• a confidence (calibratable per question);
• a reason you can check: the rule inputs, a formula over computed facts, or a quote with character offsets in the source document;
• a hash-chained trace of every step, which can be re-executed later to confirm the answer or pinpoint the step that was altered.

When something cannot be computed, a function fails, or a rule returns an answer outside the allowed options, solvi abstains instead of guessing. A failed hard check always overrides any model confidence.

Grounded decisions. Fuzzy proposes, deterministic decides, everything is in the trace. Each fact and answer records its provenance — given, computed, quoted, decided (a model's choice among options, with probabilities) or learned — and model-backed steps record the model's id and fingerprint, so a replay can tell when the model changed since a decision. A model's quote that is not literally the text at its offsets, or a choice outside its options, is rejected and counted (system.stats); a fallback producer runs or the question abstains. print(res.audit()) shows what each answer rests on, which safeguards fired, and how much of its support is deterministic. A decision without models and one with models are the same system (examples/12_grounded_audit.py).

And it is fast. The strategist plans a flow over a 10 000-part catalog in about 6 ms and runs only the parts the questions need (2.4% of that catalog). Hard checks run first, so a failing one skips the expensive rest; independent slow parts (API calls, model inference) run in parallel. On an insurance-claim desk with slow services (examples/09_strategy_at_scale.py) a full decision takes 463 ms instead of 1 122 ms for a script that computes everything, and 152 ms when an expired policy settles the claim first.

Try it

• solvi playground: write a decision task in Python and run it, watch the strategist's plan, tamper with a trace and see the replay catch it, learn rules from examples.
• solvi documents: cited, typed answers from contracts, invoices, receipts, leases and more — the ModernBERT extractor (ONNX) and the decisions both run in your browser; add a field by describing it.
• solvi arcade: game agents that explain every move — tic-tac-toe, maze, minesweeper, 20 questions, Mafia detective, a bot arena, and "hack the trace".
• solvi realms: an endless strategy game whose factions are solvi systems — tested for 100 000 turns: flat decision time (~0.3–0.6 ms), bounded memory and state, every sampled trace replay OK.
• All run entirely in your browser (Pyodide): no server, no GPU, nothing you type leaves the page.
• Models: solvi-ai/solvi-large (typed decisions, 396M, preview), solvi-ai/solvi-base (the same answers on a CPU / in ONNX, 150M, preview), solvi-ai/extract-base (fields by description) and solvi-ai/extract-receipts. Each model card states what the model was measured on, how well it does, and its limits; all models are listed at huggingface.co/solvi-ai.

Gallery

gallery/ — twelve decision tasks across directions (support triage, email routing, content guard, security alerts, AI-agent audit, release rollout, KYC/AML, clinical screening, credit with adverse-action reasons, procurement 3-way match, double-charge refunds, predictive maintenance), each with scenarios, a runner and a side-by-side against an answer-only model.

Install

pip install solvi              # core: rules, checks, learned answer heads (numpy, scipy, pydantic)
pip install "solvi[model]"     # + torch, transformers: ModernBERT field extractors for documents and the decider
pip install "solvi[onnx]"      # + onnxruntime, tokenizers: the decider (solvi.decide) on CPU without torch

Requires Python 3.10+.

Quickstart (core only, no model)

from datetime import date
from solvi import Answer, Catalog, Question, System

cat = Catalog()

@cat.fn                                            # argument names = facts it reads; function name = fact it sets
def days_requested(start, end):
    return (end - start).days + 1

@cat.fn
def remaining_after(balance, days_requested):
    return balance - days_requested

@cat.check(hard=True, then={"approve": "reject"})  # if this check is False, "approve" is forced to "reject"
def enough_balance(remaining_after):
    return remaining_after >= 0

@cat.check
def enough_notice(start, today, days_requested):
    return days_requested < 5 or (start - today).days >= 14

@cat.rule("approve")
def approve(enough_notice):
    return "approve" if enough_notice else "needs_manager"

system = System(cat, [Question("approve", "Approve the leave?",
                               Answer.choice(["approve", "needs_manager", "reject"]),
                               checkpoints=["enough_balance"])])
res = system.ask({"start": date(2026, 10, 19), "end": date(2026, 10, 23),
                  "today": date(2026, 9, 25), "balance": 14})
print(res["approve"].answer, res["approve"].confidence, res["approve"].why)
print(res.computed_state)
print(res.trace.replay(cat))

Output:

approve 1.0 enough_notice = True
days_requested           = 5
remaining_after          = 9
enough_balance           = True
enough_notice            = True
{'ok': True, 'steps': 5, 'mismatches': [], 'models': []}

With "balance": 3 the hard check fails and the answer is reject with status == "forced", whatever the rule says. solvi.show.show(res, cat) prints answers, the planned flow, the computed state and the replay result in one go.

How it works

• Catalog. @cat.fn (computation), @cat.check (bool), @cat.extract (value from text, returned as a Quote with offsets) and @cat.rule(question) (answer rule). A part's contract is its signature: argument names are the facts it reads, the function name is the fact it sets. Type hints are optional and become the facts' types (def risk_score(risk_points: dict[str, float]) -> float): producer and consumer types are checked when a part is registered, values are validated / coerced with pydantic at run time, and a value that fails is rejected like an ungrounded quote (safeguard type_rejected). Untyped parts cost nothing.
• Questions. Question(name, text, Answer.yes_no() | Answer.choice([...]), checkpoints=[...]). Questions without a rule get a small answer head trained from labeled examples (system.fit) or a readable learned rule list (system.learn_rule).
• Strategist. For each question it walks backwards from the rule's arguments (or the learned features) through the catalog signatures to the keys of init_state, adds the question's checkpoints and every check that touches a computed fact. Everything else in the catalog is not executed; the flow records why each part was taken or skipped.
• Execution. Each part runs once, even if several questions need it. Hard checks and their inputs run first; when one fails, the steps only the settled questions needed are skipped (res.trace.skipped). With System(..., workers=8) independent steps run in parallel threads as soon as their inputs are ready. Results go into computed_state with their provenance; extracted values keep their quote. Each step record is hashed and chained to the previous one in flow order, so the trace does not depend on scheduling.
• Answers and trace. res[q].answer / .confidence / .why / .status (ok, forced, abstain), plus res.trace.replay(catalog), which recomputes every step from recorded inputs and reports mismatches, broken hash links and quotes outside the text.

Typed decisions with a model

Types declare questions; the model proposes; checks decide. The fields of a pydantic model are the questions, their types the kinds (one option, several, an ordered score, yes/no); a decider (solvi.decide, solvi[onnx] or solvi[model]) answers them about a text or a JSON / pydantic state — several in one forward pass when the checkpoint can — with probabilities, a calibrated confidence and act / escalate. Hard checks, constraints and rules still decide.

from typing import Literal
from pydantic import BaseModel, Field
from solvi import Catalog, Scale, System
from solvi.decide import DecideModel

class Triage(BaseModel):
    team: Literal["billing", "technical", "shipping"] = Field(description="Which team should handle this ticket?")
    urgency: Scale[Literal["low", "medium", "high", "critical"]] = Field(description="How urgent is it?")
    angry: bool = Field(description="Is the customer angry?")
    topics: list[Literal["refund", "delay", "bug"]] = Field(description="What does the ticket mention?")

model = DecideModel.load("solvi-ai/solvi-base")         # or a local folder; solvi_decide.json says what it can do
cat = Catalog()
questions = model.questions(cat, Triage, text_fact="ticket", escalate_below=0.6)

@cat.check(hard=True, then={"urgency": "critical"})         # a legal threat is critical, whatever the model says
def no_legal_threat(ticket) -> bool:
    return "lawyer" not in str(ticket).lower()
questions[1].checkpoints.append("no_legal_threat")

res = System(cat, questions).ask({"ticket": {"subject": "Charged twice", "body": "Refund my double payment!",
                                             "customer": {"tier": "pro"}}})
print({q: (r.answer, r.status) for q, r in res.results.items()})
print(res.audit("team"))           # probabilities, the model's fingerprint, the shared pass, what escalated and why

A state is read as key paths (customer.tier: pro), the format the decider is trained on; an unsure or escalated answer abstains with the reason (system.stats["model_escalated"], ["low_confidence"]). The checkpoint contract is in docs/decide_format.md; examples/15_typed_decisions.py runs the whole story with a stand-in model. Published deciders are previews: read the model card before relying on one, and fit it on 30–60 labelled examples of your task (part.fit, part.calibrate_for) — checks, constraints and escalation are what make the answers safe to act on, not the model alone.

Every answer is a value and a confidence, and the types also declare answer primitives: Maybe[T] ("not stated" — solvi.Unknown — is a real answer, unlike an abstention), Span[float] (an exact piece of the text, parsed), Rank[...] (the top k, in order), Estimate[0, 7, 14] (a number with an interval), and evidence quotes on any answer (Claim(value, evidence=[...]), Question(require_evidence=True)) — each checked in the text, from rules or a model (guide, examples/16_primitives.py).

Planning around dead ends and costs (code strategist)

The default strategist needs the inputs of every producer of a fact. solvi.strategy.ModelStrategist() plans around producers whose inputs are never given, and with producers="equivalent" picks the cheapest verified plan by declared cost= (an exact 0/1 program; hard checks that govern a question always stay in the plan). No model is involved; the plan is one hashed record in the trace and replay re-verifies it.

from solvi.strategy import ModelStrategist
system = System(cat, questions, strategist=ModelStrategist(producers="equivalent"))

A segment model that proposes producers when costs are not declared, and solvi.aliases (wiring parameter names that match no fact), ship as experimental; their weights are not published. See docs/strategist.md and examples/17_model_strategist.py.

Extract from documents

With solvi[model], fields are found by a fine-tuned ModernBERT extractor. The extracted value is always a span of the document, so every answer built on it can be cited.

from solvi.extract_multi import MultiSpanExtractor

ex = MultiSpanExtractor(["total", "date"])          # ModernBERT-large, one pass per document for all fields
ex.fit(train_docs, train_spans, epochs=4)           # train_spans: [{"total": (start, end), "date": (start, end) | None}]
cat.extract(ex.field("total"))                      # doc -> Quote(text, start, end, confidence)
cat.extract(ex.field("date"))

@cat.fn
def amount(total):                                  # extracted values are strings; parse them in ordinary functions
    return float(total.replace(",", ""))

For long documents (contracts), solvi.extract_long.LongSpanExtractor reads the whole text in overlapping 1024-token windows, takes a field description instead of a fixed field list, and supports "no answer" with a per-field threshold. See docs/guide.md.

Results

Same training documents for both sides. The baseline, Laya, is a ModernBERT-large model that answers the typed questions directly, fine-tuned with its authors' recipe. Details and caveats: docs/benchmarks.md.

• Calibrated confidence: ECE 0.008 (SROIE), 0.011 (CORD), 0.027 (CUAD).
• On the document benchmarks, 100% of answers are backed by a quote at stated offsets, or the system abstains.
• Speed: about 0.4 ms per decision when no model is involved; about 39 ms per receipt with the one-pass extractor on an A100 GPU.

Speed

Strategist on random layered catalogs (benchmarks/strategist_scale.py, one CPU core):

Insurance claim desk with six slow services of 100-300 ms (examples/09_strategy_at_scale.py):

A rule-only decision on a small catalog takes well under a millisecond; on documents the extractor dominates (about 39 ms per receipt with the one-pass extractor on an A100).

When to use it

• The answer is a computation or a rule over a few values found in a document or a record: receipts, invoices, contracts, requests, orders.
• You need to show why: auditors, compliance, or a human reviewing low-confidence cases.
• Some rules are non-negotiable (hard checks), and the rest can be learned from about 100 labeled examples.

When not to use it

• Open-ended free-text questions or generated answers. solvi answers typed questions only: yes/no, choices, scores, multi-label, "not stated", exact spans of the text, rankings and number ranges.
• New fields with no labeled examples. Extracting a field from its description alone does not work yet (14% and 66% on two held-out fields); a universal extractor is coming.
• No labels at all. Plan on roughly 100 labeled documents (field positions) per task.
• CPU-only deployment with a quantized model: the int8 ONNX extractor loses up to 12 points on amounts, company names and addresses. fp32 on CPU keeps accuracy but takes about 0.7 s per receipt on 2 cores.

Examples

Run them from a clone: python examples/01_leave_request.py.

More

• docs/guide.md: full API walkthrough.
• docs/decide_format.md: the decider checkpoint contract (for training your own).
• docs/strategist.md: the code strategist and the experimental model strategist and name matching.
• ROADMAP.md, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md.
• docs/benchmarks.md: setups, per-question numbers, caveats.
• benchmarks/: dataset loaders and benchmark scripts (SROIE, CORD, CUAD, Kleister-NDA).
• Tests: pytest.

License

Apache-2.0. See LICENSE.

Citation

A paper is in preparation. Until then, please cite the repository:

@software{solvi,
  title  = {solvi: verifiable decision systems from catalogs of functions and checks},
  author = {mxkuzn and solvi contributors},
  year   = {2026},
  url    = {https://github.com/solvi-ai/solvi}
}