solvi.core.contract¶
The contract of an answer: its type matches what the question asks, it is not the input it was read from, and an
applicability precondition is checked before the answerer is called (Catalog.contract, a slow path's contract=,
Specialist.applicable).
The echo clause's default (echo=None) follows the answer's kind: it is checked for free text (a span, a str
answer, returns=str) and not for a declared choice, yes / no, enumeration or number, which may rightly equal an
input field; an explicit echo=True, False or a list of fact names always overrides it.
A contract on an answer: what it must be before it counts, checked by code (stable since 1.1).
A check that an answerer runs correctly — a program that passes its examples, a part whose replay matches — says nothing about whether it was the right answerer for this input: a program that counts words, run on a question that asks for a name, returns a number, and returns it correctly. A certificate certifies execution, not reading. The contract states what reading the question right looks like, in three declarative checks:
returns the answer's type matches what the question asks: a Python type (or a tuple of them; an int is a float,
a bool is not a number) or an answer type (Answer.choice(...), Answer.estimate(), ...); None — the
question's declared answer type
echo the answer is not the input it was read from (a "summary" that is the text, a "label" that is the
field it was given): True — every given fact the question's rule reads, directly or through computed
facts; a list of fact names; False — off; None (the default) — by the answer's kind: checked for free
text (a str answer, a span, returns=str), not for a declared choice, yes / no, enumeration or number,
which may rightly equal an input field. An explicit value always overrides. Compared after
normalisation (case, spacing; a number and its digits are one value)
applicable a precondition applicable(state) -> bool over the given facts, checked BEFORE the answerer is called:
an answerer is called because its question applies, not because the input has the right form. One that
raises counts as not met.
Where it applies (each violation is a hard refusal with a named reason, whatever the confidence):
cat.contract("first_word", returns=str, applicable=one_line) # in a System: the guard "contract"
AskPath(system2, contract=Contract(applicable=asks_a_count)) # a slow path: not called, not accepted
class MySpecialist(Specialist):
def applicable(self, source, question): ... # a specialist: blocked, not proposed
In a System an answer that breaks the contract abstains (Result.guard == "contract", the violations in
Result.extra["contract"]); a question whose precondition is not met is not computed (guard == "not_applicable").
In the dispatcher a slow path whose contract does not apply is not called — a person gets the input, and the
decision records "not applicable" — and an answer of the slow path that breaks it is not accepted
(Thought.contract); both replay. Hard checks forcing an answer (then=) are the author's answers and are not
checked against the contract.
Violation
dataclass
¶
One broken clause of a contract: code ("wrong_type", "echo") and message (for people).
Contract
dataclass
¶
Contract(returns: Any = None, echo: Any = None, applicable: Callable | None = None, applicable_inputs: tuple[str, ...] | None = None)
The contract of an answer (see the module docs). returns: a Python type, a tuple of types or an answer type (None: the question's own); echo: True, a list of fact names, False, or None (by the answer's kind: free text only); applicable: a function of the given facts → bool (None: always applies). applicable_inputs: declared INITIAL given-fact names, never computed predicate dependencies. None leaves reads undeclared; () explicitly means no inputs. Arbitrary Python callables can read keys via helpers/closures, so exported input schemas require this declaration (or an explicit Question.uses fallback) rather than guessing reads from source/AST. Local applies()/System.ask retain their existing execution semantics.
applies ¶
Is the precondition met on these given facts? → (True, None) or (False, why).
echo_inputs ¶
The given facts an answer must not equal: all those the answerer read (read; None — every given fact) when
echo is True or None, the named ones when echo names facts, none when False.
echoes ¶
Is the echo clause checked for this answer? An explicit echo= decides; else (None) by the answer's kind:
free text — a span or a str answer type (returns, else the question's answer type, else the answer's own
value) — is checked; a declared choice, yes / no, ordinal, multi, rank, estimate, an enumeration, a number or
a bool is not.
violations ¶
The clauses an answer breaks → [Violation] ([] when it keeps the contract; an answer of None — an
abstention — is not checked). inputs: {fact: value} the answer must not equal (see echo_inputs);
answer_type: the question's, used for the type clause when returns is None and for the echo default;
echo_type: the question's answer type for the echo default only (a System, whose answers already hold their
type).
fingerprint ¶
Contract identity: the type, echo setting, declared applicability inputs and code of applicable (its source,
or its bytecode when there is none) → a short hash. Changing any of them changes the fingerprint of the
System or slow path that carries the contract, so a decision made under another contract does not replay.
canon ¶
A value as the echo check compares it: a number (or its digits) by value, a string by its words without case, a list or tuple item by item; None, a bool and an empty string compare to nothing.
refusal ¶
The reason an answer is refused for its violations (one line).