solvi.check¶
solvi check: catalog lint.
solvi check: catalog lint — mistakes a catalog can carry for a long time before a decision shows them.
from solvi.check import lint
rep = lint(system) # a System (or a Catalog: the question checks are skipped)
print(rep); rep.ok # errors fail; warnings fail with strict=True (solvi check --strict)
solvi check myapp.decisions:system [--strict] [--json] # exit 0: no errors; 1: errors; 2: usage errors
solvi check myapp.decisions:system --sensitive age,sex # parts that read these (or what is computed from them)
solvi check myapp.decisions:system --text POLICY.md # then every part's cite= is looked for in the text
solvi check myapp.decisions:system --spec POLICY.md [--require-cites] # and its clause= against Spec(text)'s clauses
from solvi.check import citations
citations(system, policy_text, spec=None, require=False) # → Report: the citations of the parts (see citations)
Errors (a decision is, or can be, wrong or impossible):
then_not_in_flow a hard check sets then= for a question whose flow does not run it. Since 1.0 the deterministic
strategist (and CostStrategist) puts such a check into the question's flow by itself, and
System() refuses a strategist of your own that leaves it out — so this fires only for a system
built around that (when the check failed, the question would be answered as if it had passed)
then_unknown / then_bad_answer then= names no question / an answer that is not one of the question's options
(for a then function: a literal it plainly returns; None and "abstain" are a named
abstention, not an error)
cycle facts that need each other: none of them can be computed unless one is given (facts derived
from each other, each with a producer outside the loop, are a cycle for the deterministic
strategist only; with System(strategist=...) they are the note mutual_producers)
unanswerable a question no input can answer (its flow needs a fact nothing can compute; a span / rank /
estimate question without a rule — a learned head cannot answer it; a missing required part)
type_conflict a producer's return type that its consumer cannot read; a System(input_model=...) field that a typed
reader cannot read
constraint_never_holds / constraints_conflict constraints between answers that no combination of answers satisfies
(brute force over the answers' finite domains)
constraint_unknown_question a constraint that reads a name that is not a question: it never applies
validate_reads_unknown a producer's validate requires an argument no producer of its fact takes as an input:
it cannot run, so every output of that producer is rejected (a System refuses such a catalog)
hard_check_untyped a hard check without -> bool with a return that is plainly not True or False (return 0,
return None, a bare return, a string): on that path the check is rejected and every
question it governs abstains — return a bool and declare it -> bool
hard_check_never_runs a hard check with no then=, required by no question and read by no part: no question's flow
reaches it, so it never stops an answer (System() warns about it) — add requires=[...] to the
questions it guards, or then=
rule_returns_non_option a rule with return <literal> (also in a if c else b) that is not one of its question's
options (return "aprove"): on that path the question abstains
reads_sensitive a part (fn, extract, check, rule, a then function, an alternative producer, a constraint) reads a
sensitive field: one declared with Catalog(sensitive=...) or given to lint(sensitive=...) /
solvi check --sensitive age,sex
reads_sensitive_via a part reads a fact computed from a sensitive field (the message gives the chain: "reads
'risk_band', computed from 'age'"); a fact a part computes from a tainted fact is tainted too
Warnings:
rule_unchecked a rule of a yes/no, choice, ordinal or multi-label question whose return values cannot be read (no
source: made by exec, a callable object; a lambda that cannot be told apart on its line), so
rule_returns_non_option did not check it
unused_part a part no question's flow uses (a question without a rule, fit or uses uses everything computable:
those are the candidate features of the head it will be fitted with)
then_on_soft_check then= on a check that is not hard: it is ignored
question_as_fact a rule, part or check's then function reads a question's name: answers are not facts,
so it must be given in the input (error for hard checks)
reader_types_differ typed readers of a given fact, or alternative producers of a fact, that no value can satisfy both
dead_option an option the constraints rule out whatever the other answers are
constraint_raises a constraint that raises on some combination of answers (it counts as broken)
unused_rule a rule registered for a question that is not among the System's questions: it never runs
input_not_declared with System(input_model=Model): a part or a rule reads a name that is neither computed by a part nor
a field of the model (amout for amount) — it can only arrive as an extra key of the input;
when the model forbids extra keys it can never arrive
uses_unknown with System(input_model=Model): a question's uses hint names something that is neither a part nor
a field of the model. (Without an input model a uses name that is not a part is taken for a
given fact — a learned head may read given facts directly — so a typo there cannot be told;
a misspelled requires entry is an error: unanswerable)
silent_default in a function that reads the input (a given fact): x or <literal> or .get(k, <literal>) on
that input (amount or 0, order.get("total", 0); not a lookup in a constant table or a
default on a computed value), which turns a missing, empty or null input into a value nobody
gave — say so explicitly (check
for None and abstain, or declare the default in System(input_model=...)); # solvi: ok on the line
accepts it (parts of the solvi package itself are skipped: the user can neither edit them nor
mark them)
check_shares_call a check declared with Catalog.check(shares_call_with=X): it re-reads X's model call, so it agrees
with X's answer whatever that answer is — not an independent check (also when X names no part or
question)
checks_one_family the checks in a question's flow that declare family= are all of one family (two or more): they
err together, so agreeing does not make the answer surer — add a check of another family or code
The wording of a question a model answers (no rule, or a rule with model=) — what the model reads:
no_other_option a choice with no catch-all option ("other", "none of these", "unknown", "oos", "abstain",
"misc", ..., or one described as "anything else"), no decider other= and no "not stated"
(Answer.maybe): when no option fits, the model still picks one, often confidently
numeric_levels a choice or ordinal whose options are bare numbers ("1".."5") without a description of each: say
what each level means (a dict {level: description}). A choice is judged only when its options
read as a small integer scale (consecutive from 0 or 1, the top open: "3+", "3 or more"):
years and other numbers that are not levels do not fire it; an ordinal's numbers always do
Of every question:
compound_question a question text that asks two things (two question marks, or "and whether" / "or whether"; a
"?" inside quotes or parentheses is not a question of its own): one
answer cannot say yes to one half and no to the other — split it
unused_given with System(input_model=Model): a field of the model that no part, rule, check, constraint, uses
hint or span reads (checked only when every question has a rule or a uses hint: a learned
head may read any given fact)
Notes (never fail):
mutual_producers facts derived from each other (net from gross and gross from net), each with a producer
outside the loop: the system's strategist plans around it
no_rule a question without a rule answers only after fit (it abstains until then)
sensitive_unread a sensitive field no part reads (declared, nothing reads it: fine)
Citations (solvi.check.citations; solvi check --text):
cite_not_found a part's quote (cite=) is not in the text — in the catalog's quote mode: "normalized" finds it
across Unicode forms, dashes, spaces and curly quotes (error)
clause_unknown with spec=: the part names a clause the specification does not have (error)
cite_outside_clause with spec=: the quote is in the text but not in the clause the part names (error)
no_cite with require=True: a part without a citation (warning)
The flows are planned with every given fact present (solvi.core.plan.strategist.given_facts), as solvi serve does, by the
system's own strategist (System(strategist=)) — the deterministic one when none is set.
Finding
dataclass
¶
One problem solvi check found: its level (error, warning or note), code (see the module docs), where (a part,
a question, a constraint or file:line) and the message.
Report
dataclass
¶
lint ¶
A System (or a Catalog) → Report. max_combos: the largest number of answer combinations tried per group of
constraints that share questions. sensitive: names of given facts no part may read (age, sex, ...), added to the
catalog's own Catalog(sensitive=...); a part that reads one, or a fact computed from one, is an error
(reads_sensitive, reads_sensitive_via). Nothing changes at ask time: lint is where it is refused.
sensitive_names ¶
The sensitive fields of a catalog: its own Catalog(sensitive=...) and sensitive (a name or names) → set.
silent_defaults ¶
[(line, snippet, why)] in a function's source: x or <literal> and .get(k, <literal>) (the literal not None),
except on lines marked # solvi: ok. [] when the source is not available. names: the function's arguments that are
given inputs — then only a default on one of them counts (amount or 0, order.get("total", 0), order["x"] or
0), not one on a constant table ({...}.get(kind, 1)), a computed value (math.sqrt(v) or 1e-9) or an
exception's attribute (e.lineno or 0).
split_clauses ¶
A text → [(section, clause text)]: each paragraph, list item and table row is a clause (a table row is written
as header: cell; ...); headings name the section and are not clauses themselves.
spec_clauses ¶
A specification's text → {"c1": clause text, ...}: the clauses solvi.core.versions.Spec(text) numbers.
citations ¶
The citations of a catalog's parts (cite= / clause= on the decorators: Part.cites) against the text they
quote → Report. Every quote must be in text, found as solvi.core.catalog.find_quote finds it with the part's
quote mode ("normalized" by default: Unicode form, dashes, spaces, curly quotes; the source's own substring is what
counts) — else the error cite_not_found. With spec (a solvi.core.versions.Spec, or {clause id: text} —
spec_clauses(text) numbers a text's clauses as Spec does) a clause id must be one
of its clauses (clause_unknown) and the quote must lie in that clause's text (cite_outside_clause; a table row,
which the Spec writes as header: cell; ..., is also compared by its cells). A clause id with a ":" — a person's
correction, clause="person:k07" — is no clause of the specification: its quote is looked for in text only.
require=True: a part without a citation is the warning no_cite (a policy catalog that wants every rule to cite
its clause). obj: a System or a Catalog.
cmd_check ¶
solvi check (see solvi.cli) → 0: no errors (with --strict: no warnings either); 1: problems. The target is
module:attr / file.py:attr, or — as for solvi test — a task file or a directory holding task.py (its System:
task.system(), else System(task.cat, task.QUESTIONS)).