Skip to content

Checking a catalog: solvi check

solvi check lints a catalog for mistakes that can sit in it for a long time before a decision shows them:

solvi check myapp.decisions:system            # exit 0: no errors; 1: errors; 2: usage errors
solvi check myapp.decisions:system --strict   # warnings fail too;  --json for data
solvi check gallery/01_support_triage         # a task file or a directory with task.py, as for solvi test
from solvi.check import lint
rep = lint(system)                            # or lint(catalog): the checks that need questions are skipped
print(rep); rep.ok; rep.errors; rep.warnings  # each finding: level, code, where, message

Flows are planned with every given fact present. Errors: a hard check whose then= sets an answer for a question whose flow does not run it (then_not_in_flow: since 1.0 the strategist wires such a check in and System() refuses a strategist that leaves it out, so it fires only for a system whose strategist was swapped afterwards — when the check fails the question would be answered as if it had passed); then= naming no question or an answer outside the question's options (for a then function: a literal it plainly returns); facts that need each other (cycle; facts derived from each other, each with a producer outside the loop, are only a note, mutual_producers, for a System with strategist= — the flows are planned by the system's own strategist); a question no input can answer (a fact nothing can compute, a missing required part, a span / rank / estimate question without a rule); a producer's type its consumer cannot read, or a System(input_model=...) field its typed reader cannot read (type_conflict); a producer's validate that requires an argument no producer of its fact takes as an input (validate_reads_unknown: it cannot run, so every output of that producer would be rejected — System(...) refuses such a catalog, and a part that is not an alternative producer is refused when it is declared); constraints between answers that no combination satisfies — one alone or all together, tried by brute force over the answers' finite domains (yes/no, choice, ordinal, multi-label up to 10 options; up to --max-combos combinations per group of constraints that share questions) — and a constraint reading a name that is not a question (it never applies); a rule with a return <literal> that is not one of its question's options (rule_returns_non_option: return "aprove" — on that path the question abstains); a hard check without -> bool with a return that is plainly not True or False (hard_check_untyped: return 0, return None, a bare return — on that path the check is rejected and the questions it governs abstain); a hard check with no then= that no question requires and no part reads (hard_check_never_runs: no flow reaches it, so it never stops an answer — System(...) warns about it too). Both return checks read the function's source: only literals in return statements (also in a if c else b, and a lambda's body) are judged, a returned variable or call is not; a rule whose source cannot be read (made by exec, a callable object) is the warning rule_unchecked. Warnings: a rule registered for a question the system does not ask (unused_rule); with System(input_model=Model), an argument that no part computes and the model does not declare (input_not_declared: amout for amount — it could only arrive as an extra key, and never when the model forbids extra keys), and a uses hint naming neither a part nor a field of the model (uses_unknown; without an input model such a name is a note when no part computes or reads it — it can only be a given input: a typo, or a raw feature for a future head); uses on a question that has a rule or an answer head (uses_ignored: the rule's or head's inputs make the flow, the hint does nothing); a part no question's flow uses (a question without a rule, fit or uses counts as using everything computable: its future head's candidate features); then= on a soft check (ignored); a rule reading a question's name (answers are not facts); typed readers of a given fact, or alternative producers, whose types no value satisfies together; an option the constraints always rule out (dead_option); a constraint that raises on some answers; and silent defaults: in a function that reads the input (a given fact), x or <literal> and d.get(k, <literal>) on that input (amount or 0, order.get("total", 0), order["tax"] or 0) turn a missing, empty or null input into a value nobody gave — the answer looks decided while it rests on a guess. A lookup in a constant table ({...}.get(kind, 1)) or a default on a computed value is not flagged. Say what a missing input means (check for None and abstain, or declare the default in System(input_model=...)), or mark the line # solvi: ok. Notes never fail: a question without a rule abstains until an answer head is fitted.

The wording of questions (warnings). For a question a model answers (no rule, or a rule backed by a model): a choice with no catch-all option — "other", "none of these", "unknown", "oos", "abstain", "misc", or one described as "anything else" — and no decider other= or "not stated" (Answer.maybe) is no_other_option (a warning since 2026-10-30, a note before: closed label sets such as approve / reject or low / medium / high are normal; add a catch-all only when an input can fit none of the options, since then a model still picks one, often with high confidence); levels that are bare numbers ("1".."5") without a description of each are numeric_levels (give a dict {level: description}; on a choice only when the options read as a small integer scale — consecutive from 0 or 1, the top open: "3+" — so years do not fire it). For every question: a text that asks two things — two question marks (a "?" inside quotes or parentheses is not a question of its own), or "and whether" / "or whether" — is compound_question (split it; a plain "and" inside one judgement is not flagged). With System(input_model=Model), a field that no part, rule, check, constraint, uses hint, span or guarantee (its groups=, or a signal= naming the field; on a System or on a part's or combiner's calibration) reads is unused_given (checked only when every question has a rule or a uses hint, since a learned head may read any given fact). Each names the question (or the field) and the fix.

Sensitive fields. Catalog(sensitive={"age", "sex"}) names given facts no part may read; lint(system, sensitive=...) and solvi check ... --sensitive age,sex add names to the catalog's own. A part that reads one — a fn, extract, check or rule, a then function, an alternative producer, a constraint — is the error reads_sensitive (fn 'young_points' reads 'age': a sensitive field); a fact computed from one is tainted too, and a part that reads it is the error reads_sensitive_via, with the chain (reads 'risk_band', computed from 'age'); a declared field nothing reads is the note sensitive_unread. Nothing changes at ask time: lint, and the Static stage of solvi.experimental.changes, are where such a part is refused. A credit policy's proposed rule young is refused so:

cat = Catalog(sensitive={"age", "sex"})

@cat.fn
def young_points(age):                        # solvi check: error reads_sensitive — young_points reads 'age'
    return 1 if age <= 25 else 0