Skip to content

Examples

Each file is a self-contained script. Run from the repository root with uv run python examples/<file>.

file domain what it shows needs
30_checked_csv_operations.py CSV/SQLite learns a boolean operation, checks its complete finite domain, applies it to new rows and restores without repeating effects core, experimental
01_leave_request.py HR rules and hard checks over a plain dict; the strategist skips catalog parts the questions do not need core
02_shop_order.py e-commerce two answers by rules, one ("suspicious?") learned from labeled history with fit core
03_invoices.py accounts payable fields extracted from invoice text with quotes, checks on computed facts, a learned risk level core
04_refunds.py customer support a learned yes/no that a hard "within 30 days" check always overrides core
05_tic_tac_toe.py games an agent from small functions over the board; never loses (checked exhaustively) core
06_learned_rules.py logistics learn_rule: a readable if-then list learned from labeled addresses core
09_strategy_at_scale.py insurance a different generated plan per question set on a big catalog, early exit on hard checks, parallel slow services; timed core
10_learn_in_milliseconds.py any fit: learn a question in milliseconds and absorb each correction instantly with teach core
11_answer_types_and_constraints.py trust & safety multi-label and ordinal answers, constraints between answers, joint decoding core
12_grounded_audit.py expenses one catalog with and without models: provenance, res.audit(), a hallucinated quote caught, a decision outside its options, a changed model, safeguard stats core
13_decide_model.py customer support a decider model as a catalog part: bias correction without labels, few-shot shift with teach, "other" as a threshold, abstention, constraints, audit, escalation for a target error rate, a JSON ticket core (stand-in); the real model with solvi[onnx] or solvi[model]
14_typed_catalog.py customs typed facts: type hints checked between producers and consumers at registration, a pydantic request (System(input_model=...)), answer types from the rules' return types, type_rejected → fallback / abstention, the response as JSON that loads back and replays core
15_typed_decisions.py customer support typed decisions: the questions as a pydantic model's fields (choice, ordinal score, yes/no, multi-label) about a pydantic ticket, four answers (one forward pass when the model shares passes), act / escalate, a hard check, a constraint and a rule over the model, audit and stats core (stand-in); the real model with solvi[onnx] or solvi[model]
16_primitives.py insurance claims answer primitives, each a value and a confidence: "not stated" (Maybe[bool]) vs abstain, a span parsed into a float, evidence quotes checked in the text (require_evidence), a ranking (Rank), an estimate with an interval (Estimate) — from plain rules and from a decider with the typed v2 contract; the confidence table, JSON round trip and replay core (stand-in); a typed v2 checkpoint with SOLVI_DECIDE_MODEL
17_cost_strategist.py payments the code strategist: a dead end the deterministic strategist cannot plan around, the cheapest verified plan with declared costs, the plan in the trace core
18_several_models.py customer support several models, one decision (solvi.core.deciders.combine): a cascade small → large, a vote of two model families, a route by code — each under one guarantee from act_guard (P(answered alone and wrong) ≤ 10%), with cost per question; the audit lists every stage and the trace replays core (stand-ins); checkpoints with SOLVI_DECIDE_SMALL / SOLVI_DECIDE_MODEL
19_agent_guard.py accounts payable an agent's tool calls through solvi.solutions.guard.Guard: the agent proposes, solvi checks (catalog, types, arguments quoted from the conversation, instructions hidden in tool outputs, policies, an authorizer with act_guard and perturb) and allows, denies or escalates; a person's approval recorded; every decision stored and replayed core (a scripted agent and a stand-in authorizer)
20_vote_across_families.py customer support a vote of two model families behind the System One API (stand-in servers started in-process): each alone and the vote under one guarantee (act_guard, P(answered alone and wrong) ≤ 10%) — the vote answers more alone than either model; a sure mistake of one family escalates; a hard check first; the audit and the replay core (stand-in servers); real servers with systemone(URL, MODEL)
21_verified_chart.py reports, press releases a verified chart (solvi.experimental.charts, preview): a proposer writes a chart spec with a quote per value; code checks every number (the quote, the unit, the scale), the chart type (a pie only for shares of a whole) and a stated total; a careless model's swapped digit, invented share, percentage points drawn as percent and unquoted value are dropped with reasons; a deterministic accessible SVG; the trace replays to identical bytes core
22_coding_agent_hooks.py software development a coding agent behind solvi hook (Claude Code's hooks): solvi hook install in a temporary project, then three edits (allowed; denied with the rule and the line; a comment that tries to talk past the rules, denied and flagged) and two prompts for the skill picker, run through the installed commands as Claude Code runs them; the store verified, one decision audited and replayed. The rules it installs: coding_agent_rules.toml core
23_pokemon_world_map.py games System 1 and System 2 on the world map of Pokémon Red (recorded: place names and exits, no ROM): System 1 is two rules over compiled routes, System 2 a search over the player's WorldMap (solvi.core.dispatch with a SearchPath), consolidation after each goal turns what System 2 found into System 1's routes; run 1 makes 147 slow decisions of 183, run 2 makes 2 of 62 (the fewest moves); every decision replays, System.report at the end; --live plays again, --rom checks your own ROM first. The player and the replay viewer are in spaces/pokemon core
24_one_entry_point.py support one entry point (solvi.solutions.decisions.build): a question, 2,000 labelled refund requests, a promise (≤ 2% answered alone and wrong) and a slow reader of free-text notes in; System 1 fitted, its guarantee and the slice handed to the slow path calibrated on examples it did not see, every decision stored and replayed; explain() says who answers what core
25_environment_agent.py games an environment agent (solvi.Agent) with solvi.Knowledge on a toy crafting world: System 1 on what the action model and the skills predict, System 2 a search, hard checks from the agenda; run 1 takes 61 steps all by System 2, run 2 on the same world 12 steps (11 by System 1), a new world keeps the rules and re-learns the map; then protection vs RiskBudget at a bridge that breaks one time in three (iron in 2 vs 24 of 30 episodes, falls 1 vs 6), the written gate held in both; every decision replays core
26_build_head_update.py support a solvi.build system updated through the change pipeline (solvi.experimental.changes): each re-build on new labels is a candidate checked on two held-out shops (per-shop slices against the version in force and the original), canaries drawn per change, and requests that must stay with a person; more data is promoted, a batch with bad labels refused, the same batch again refused by the failure memory, then a rollback core
07_receipts_model.py expenses a receipts-tuned ModernBERT extractor cites each field; rules decide solvi[model]
08_contracts_by_description.py legal fields defined only by description, read from a whole contract, cited or "absent" solvi[model]

Models for 07 and 08 load from Hugging Face (solvi-ai/extract-receipts, solvi-ai/extract-base) or from a local directory given in SOLVI_MODEL. Examples 13, 15, 16 and 18 use the decider from SOLVI_DECIDE_MODEL (a checkpoint folder or a Hugging Face id) when it is set, and a keyword stand-in otherwise.

  • 31_counterexample_learning.py: bounded counterexample refinement, useful paid observations and durable SQLite/journal recovery; no model or network required.
  • 32_bounded_observations.py: ordered one-pass committee synthesis and bounded paid observation selection against the original algorithms on known scalar programs; prints actual work debits without a general performance claim. No model, dataset, oracle or network required.

  • 33_stratified_observations.py: paid bounded label-aware planning over an unread host pool; no authority or oracle reads.

  • 34_packed_observations.py: immutable packed bins, fixed pilot cuts, adaptive feedback and paid snapshot replay; explicit host labels, no oracle or network.
  • 35_verified_computation.py: verified scheduling, selective updates and acquisition of a parameterized operation from accepted traces; independent finite-domain admission and actual reuse in a new composition. No network or model required.

Decision workflow examples: 36_cooperative_solvers.py, 37_teach_concepts.py, 38_preference_elicitation.py, 39_decision_learning.py, and the composed 40_decision_workflow.py. All are finite, CPU-only and require no external model service.