Skip to content

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

Violation(code: str, message: str)

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

applies(state) -> tuple

Is the precondition met on these given facts? → (True, None) or (False, why).

echo_inputs

echo_inputs(given, read=None)

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

echoes(answer, answer_type=None) -> bool

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

violations(answer, inputs=None, answer_type=None, *, echo_type=None) -> list

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

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

canon(v)

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

refusal(violations, answer)

The reason an answer is refused for its violations (one line).