Skip to content

solvi.experimental.relations

Relations over a state and rules found over them (experimental): packed-bit Relations, the relation algebra, a bottom-up enumerator with observational equivalence (enumerate_programs, synthesize, top_programs), a Library of accepted programs, compilation into plain set code or index arrays with a differential check (compile_program, check_program), encoders (encode, encode_paths), RelAlgProposer for the laws' held-out test, CompositionTable (a composition table of relations learned by counting, derivation over every bracketing, refusal of what it cannot derive), forward_chain (its rules applied to the facts of a knowledge store to a fixed point), RulesFirst (the table answers first, a model only what it refuses), synthesize_residual (top-down synthesis of chain programs through residuals), why_not (why a relation was not derived: the missing cell or fact) and GuardedRules / chain_rules (Datalog-lite rules with unary guards and a negative stratum, learned by counting on labelled pairs).

Composites with a library

solvi.experimental.relations.library.find_rules(examples, targets, base=..., size=..., budget=..., library=(), test=HeldOut(other_worlds, targets)) enumerates small programs over relations, admits only what passes the held-out test, and builds the next rules on the admitted ones (Library entries as new terminals); run(program, world, library=) runs a found rule on any world. The search is this package's enumerator and the programs are its tuples; library= takes a Library (the collection of accepted programs) or a sequence of Entry (one accepted program: program, name, examples, test), and admitted rules are Entry objects. include_universal=False leaves the universal relation U out of the enumerator's terminals (opt-in; the default keeps it).

Operators: unary T (converse), NOT (bounded complement), PLUS (transitive closure), CNT2 / CNT3 (the nodes with at least 2 / 3 successors, as a diagonal) and CNT1 (at least one successor) — CNT1 is opt-in: known to the algebra, the enumerator and both compile backends, but not in the default OPS (pass it in ops=; find_rules uses it through counts=(1,)); binary OR, AND, MINUS, XOR, COMP, C2, C3.

Composition tables over kinship chains

CompositionTable(majority=0.9, support=2) learns which relation a chain of two relations composes to (father ∘ sister → aunt) by exact counting, derives longer chains by composing over every bracketing, and refuses what the table cannot derive.

from solvi.experimental.relations import CompositionTable, base_rates, sized_admit

examples = [(("father", "sister"), "aunt"), (("father", "sister"), "aunt"), (("aunt", "son"), "cousin"), ...]
t = CompositionTable(majority=0.9, support=2).fit(examples)   # chains of length 2 vote; length 3 fill residuals
d = t.derive(("father", "sister", "son"))
d.relation, d.reason          # "cousin", "derived" — or None, "underivable" / "disagree" / "identity"
d.candidates, d.cells         # bracketings per relation; the cells (left, right, relation, hits, support) used
t.derive_paths([chain_a, chain_b])                            # one query reached by several chains
t.to_knowledge(store, {"domain": "kinship"})                  # "rule" items with their support
  • Fit. A chain (r1, r2) labelled r is a vote for the cell r1 ∘ r2 → r; a cell is admitted when its majority relation has a share ≥ majority and at least support votes. Residual fill: a chain (a, b, c) labelled r with a ∘ b = x in the table votes for x ∘ c → r, and with b ∘ c = y for a ∘ y → r; the residual votes are recomputed from the current table each round (a chain counts once per round) until the table stops changing (rounds= caps it). fit is deterministic and independent of the order of the examples; other chain lengths are counted in ignored.
  • Derive. CYK over the chain: each span keeps the relations it composes to and how many bracketings give each; a bracketing that meets an empty cell gives nothing. agree="all" (default): answered only when every bracketing that gives a relation gives the same one; agree="majority": the relation of strictly the most bracketings. Refusals: "underivable" (no bracketing composes), "disagree" (two relations), "identity" (only a learned identity). explain(chain, relation=None) returns the cells used.
  • Identity (opt-in). identity="self": a chain (a, b, c) labelled c votes a ∘ b → self where the pairs admit no cell; self composes as neutral and is never an answer. In domains where a cell depends on an attribute the chain does not carry (whose son's mother is "self" depends on the subject's gender), a learned identity adds wrong answers.
  • Admission hook. admit=(cell, relation, hits, support, tested) → bool is an extra gate after the thresholds; sized_admit(base_rates(examples), delta=0.1) is the sized acceptance of solvi.experimental.laws with a base-rate null: P[Binomial(support, base_rate(r)) ≥ hits] ≤ δ / N, N the cells tested.

Residual synthesis: top-down, for chains

synthesize_residual(examples, target, depth=12, budget=500_000) finds the shortest chain program (fewest atoms) equal to a target on every example by working down from the target instead of enumerating up from the terminals. A subgoal is an interval Lo ⊆ X ⊆ Up on the pairs that matter; the step X = A ∘ Y (A a base relation, a library entry or the converse of one) gives Y's interval through the residual A \ Up = ¬(Aᵀ ∘ ¬Up) and the pairs of Lo with a single witness; a pair with no witness left prunes the step; X = Y ∖ I drops the diagonal. Iterative deepening on the number of atoms; failed subgoals are remembered.

from solvi.experimental.relations import synthesize_residual, synthesize
from solvi.experimental.relations.library import HeldOut

r = synthesize_residual(worlds, cousin, name="cousin", test=HeldOut(other_worlds, {"cousin": cousin}))
r.program, r.atoms, r.steps, r.seconds, r.stopped, r.rejected
# (Eᵀ ∘ (((Eᵀ ∘ E) ∖ I) ∘ E)), 4, 118, 0.01, "found", 0
f = synthesize(examples, targets, size=12, method="residual-first")   # residuals, then the enumerator
f.by, f.steps                                                         # "residual" | "enumerate", residual steps
  • Inputs as synthesize (a sequence of Relations, targets as matrices) or as find_rules (worlds: name → (n, n) boolean matrix; a target may be a function of a world). names= the relations used as atoms, library= entries as more atoms, converses= / masks= (both on).
  • Checks. A candidate is accepted only when the package's evaluator gives the target exactly on every example, then on check=(examples, targets) and by test= (a HeldOut, with name=); one that fails is counted in rejected and the search goes on. One chain reached from both ends is checked once.
  • Stops. depth atoms, budget residual steps (one atom tried at one subgoal), seconds; stopped is "found", "budget", "seconds" or "exhausted" (no program of the grammar with at most depth atoms fits the examples). Deterministic: atoms in the order of the names, then the library. log= gets one line per depth.
  • The grammar is chains of atoms and converses peeled one atom at a time from either end, with ∖ I on any segment of two atoms or more. Not covered: union, intersection, closure, counts, and two masked segments side by side (((…) ∖ I) ∘ ((…) ∖ I)) unless one is a library entry. synthesize(method="residual-first") runs the enumerator on what the residuals do not find; method="residual" runs them alone. Residual steps and enumerated behaviours are different units: compare what is found and the time.

Measured (benchmarks/relations_residual.py, CPU, five seeds, no library): on the kinship ladder of benchmarks/relations_library_toy.py the residuals found all nine rungs on every seed (45 of 45; the top rung, second cousin once removed, in 0.40–0.55 s and 7,628–9,306 steps; 3 s for all 45) with 0 false accepts on the check worlds, where the enumerator (size 12, U left out, a cap of 100,000 behaviours) found the four rungs up to great-grandparent and none above (20 of 45, ≈ 6 s per rung at the cap, 0 false accepts). On a five-level path-tree policy («denied if an ancestor directory is named secret and the depth is at least 3») only one level is a chain: the residuals found it (PARENT ∘ PARENT) on every seed, ran the closure level to its budget, and ruled out the three levels that need a count or an intersection in 506 steps (0.04 s), accepting nothing false; the enumerator without a library (size 12, 100,000 behaviours) did not find the top level on four seeds and on the fifth returned a program exact on the three example trees and wrong on the check trees — an exact match on few examples is not a rule; give the search a held-out test.

Why a relation was not derived

why_not(table, facts, x, y, relation=None) is the mirror of explain: over every path x → y through the pair facts (at most max_len facts, max_paths paths; inverse= a relation → its converse opens reverse paths) it reports status — "derivable" (with the pooled derivation), "disputed" (the paths read as two relations: readings), "other" (the table derives another relation), "missing_cell", "identity", "underivable" or "no_path" (a missing fact, not a missing rule) — and gaps: the absent cells left ∘ right → ? that block the paths deriving nothing, ranked by how many paths one cell would unblock.

from solvi.experimental.relations import why_not, first_missing_step
rep = why_not(table, [("don", "father", "mike"), ("mike", "sister", "dot")], "don", "dot", "aunt")
rep.status, rep.gaps[0], rep.summary()     # "missing_cell", Gap("father", "sister", 1, ...), one line
rep.agenda_items()                         # [{"kind": "cell", "goal": "learn cell father ∘ sister", ...}]
rep.to_agenda(agenda, table)               # a goal per gap, done when the table has the cell
  • The refusal's detail. CompositionTable.derive and derive_paths put the blocking cells of an "underivable" refusal into Derivation.missing (on the shortest span that composes to nothing, the pairs of its two composed parts with no cell; pooled chains: most blocked first). why_not reads it per path.
  • A learning target. agenda_items() turns the report into plain records: a cell to learn, a fact to learn, a dispute to settle, or the cells of another reading to check. to_agenda(agenda, table) declares an Agenda goal «learn cell r1 ∘ r2» per gap whose done check reads the table, so refitting the table on new labelled chains closes it. A missing fact and a dispute stay records: a dispute is already a person question in the knowledge store (forward_chain), and a fact is not a check in code over the table.
  • With a reference derivation. first_missing_step(steps, derived) → the first step «head ⟸ body» whose head was not derived, with its rule schema (rule_schema: entities abstracted, r(X,Y) ⟸ r1(X,Z), r2(Z,Y)); counted over many refusals, the schemas name the missing rules.

Forward chaining over the rules in a knowledge store

forward_chain(store, scope=..., rule_scope=...) applies the composition rules kept in a KnowledgeStore (the cells CompositionTable.to_knowledge writes) to the store's pair facts until nothing new follows, and writes every derived fact through the store's gates.

from solvi.core.knowledge import KnowledgeStore
from solvi.experimental.relations import CompositionTable, explain, forward_chain, pair_fact

store = KnowledgeStore()
table.to_knowledge(store, {"domain": "kinship"})                       # the rules
for x, y, rel in edges:                                                # the story: who is what of whom
    store.add("fact", pair_fact(x, y, rel), {"story": 7}, source="outcome")
rep = forward_chain(store, scope={"story": 7}, rule_scope={"domain": "kinship"})
rep.rounds, rep.facts_added, rep.disputes_opened, rep.hypotheses       # the fixed point and what it wrote
explain(store, fact_id).cells                                          # the rule cells the derivation used
  • Facts are pairs. pair_fact(x, y, relation) = {"s": [x, y], "r": "relation", "o": relation}: the store's key is the ordered pair and its value the relation, so two different relations of one pair meet on one key.
  • Chaining. Semi-naive rounds: the facts new in one round are joined with every fact of the same scope; for (x r1 y), (y r2 z) and a rule r1 ∘ r2 → r the fact (x r z) is proposed with derived_from = the two facts and the rule, inferred=True, the source of the weaker premise and evidence {"rule", "via", "depth"}. Facts join only within one exact scope; scope=None chains every scope apart.
  • What the store does with it. The same relation is one more justification; a different relation from an equal-rank derivation makes the pair disputed — the table's refusal by disagreement, kept as a question for a person (store.disputes(), store.resolve); a retracted or refuted premise takes its consequences along. Disputed facts are chained too, so both sides carry their consequences as hypotheses, and a person's answer settles them without a re-run. rules="any" also applies hypothesis rules: what they derive is a hypothesis until the rule is promoted. A justification that would rest on the fact it justifies (a cycle in the graph) is not written.
  • Guards. max_rounds= stops early (fixed_point=False; a later call resumes); max_facts= (default |entities|² × |relations| per scope) raises ChainLimit. A second call writes nothing.
  • explain(store, fact_id) → Explanation: every live justification of the fact, recursively down to the facts asserted without premises (facts), the rules (rules) and their cells (cells); tree() gives one derivation as a nested dict. On a chain it gives the cells CompositionTable.derive(chain).cells gives.
  • Limits. Composition of two relations over pair facts only — no general rules, negation or aggregation; a learned identity relation is chained as an ordinary relation.

Measured on CLUTRR (Sinha et al., 2019), the clean split's training file only (the relation graph of each story, not its text): on 1,816 held-out stories (a fifth of the training file by a hash of the id, chains of 2 and 3 relations; the table fitted on the other four fifths, 111 cells) the store's reading of the query pair after chaining to the fixed point was compared with the table's derivation over the shortest paths: 1,675 equal (0.922), 11 disputed where the bracketings disagree (0.006), 130 with nothing derived where the table cannot derive (0.072), 0 differences; the fixed point took 0 rounds for 72 stories, 1 for 826 and 2 for 918; 2.6 s of chaining in all, 1.4 ms a story, on CPU; one run, the test file not read. On 120 random chains of 2–7 relations over 12 random tables whose bracketings can disagree: 0 differences (2 answers equal to the table's rest only on a disputed pair and stay hypotheses until a person answers it) (benchmarks/relations_chain.py, tests/test_relations_chain.py).

Guarded rules: Datalog-lite with a negative stratum

GuardedRules(majority=0.9, support=2) learns rules over pair facts and unary facts by exact counting on labelled query pairs, applies them by forward chaining to a fixed point, and answers a pair with the set of relations derived on it — or the empty set, a refusal.

from solvi.experimental.relations import GuardedRules, Story, chain_rules, pair_fact, unary_fact

story = Story.from_edges(edges, types)               # a self-loop is_* / no_* is a unary fact
rules = GuardedRules(0.9, 2, complements={"Not_living_in": "living_in"})
rules.fit(examples, check=other_examples)           # (story, (x, y), set of relations) each
rules.predict(story, (x, y))                        # frozenset of relations; ∅ = refused
c = rules.closure(story); c.status(x, y, "living_in")   # "active" | "hypothesis" | "disputed"
rules.to_knowledge(store, {"domain": "kin"})        # one "rule" item per rule
chain_rules(store, scope={"story": 7}, rule_scope={"domain": "kin"}, complements=...)
  • Bodies. An atom is a relation read forwards, s(x, y), or backwards, s⁻(x, y) = s(y, x). B1 r ← s(x,y); B1u r ← s(x,y) ∧ u(x) (or u(y)); B2 r ← s1(x,z) ∧ s2(z,y); B2z the same ∧ u(z); BNE r ← s(x,z) ∧ z ≠ y ∧ u(y) («lives somewhere else»); NEG r ← u1(x) ∧ u2(y) ∧ ¬s(x,y). Unary predicates are the story's own (no invented predicates); depth comes from rounds — a derived fact feeds further bodies — never from longer bodies.
  • Learning. A body true on a labelled pair is one vote; each relation of the pair's label set one hit. A rule needs hits ≥ support and a share ≥ majority of its votes; r ← r (∧ u) is never admitted, and a guarded body leaves when its unguarded generalization is admitted. Rounds recount the votes on the fixed point of the rules admitted so far; the rule set only grows, so the rounds stop at its fixed point (or rounds=). check=: an independent labelled slice where a rule's share must also reach majority (and check_min= hits).
  • Rules wrong together (verify=True). Each rule is counted on the fixed point of the rules before it, but rules admitted in one round can be wrong together: one right at the labelled pairs and wrong elsewhere derives facts that make others fire wrongly. After each round the new rules are recounted on the fixed point of the whole new set (on the check slice when given); the worse half of those it contradicts is retracted for good (retracted), and the recount repeats until none falls. When labels exist only on query pairs, a loose admission (a small support) admits many such rules and this recount then retracts most of a round, so prefer a support well above 2 there.
  • Residual votes (residual=True, the composition table's residual fill generalised): within a round, the rules admitted on the direct votes are applied to the length-3 walks of each labelled pair; where one gives a middle fact that is not yet in the fixed point, the body that needs it gets the pair's vote. In the measurements so far this only reaches in one round what the next round's fixed point shows anyway.
  • The negative stratum. After the positive fixed point, a NEG rule fires on (x, y) only when nothing of s and nothing of the head's own key holds there; its facts never feed positive rules. NEG bodies are learned on the final fixed point, counted on the pairs where the head's key is empty, and only for an s that holds on at least support labelled pairs of the same unary types.
  • Pairs carry sets; complements dispute. Every relation is its own key on a pair, so two relations of one pair are two facts; relations declared complements (complements={"Not_living_in": "living_in"}) share a key, and two of them on one pair are a dispute: the pair is answered on neither. Statuses at the fixed point: disputed, active (given, or derived from active premises), hypothesis (derived only through disputed facts).
  • A closed world by declaration (functional=, since 1.1.1). GuardedRules(..., complements={"Not_living_in": "living_in"}, functional={"living_in": "person"}) states that a subject of type person (the unary is_person) has at most one object for living_in; ("person", "place") names the object type too (without it the candidates are the entities carrying every is_* unary of the known object). Nothing is learned about which relations are functional: a wrong declaration makes false negatives, so it is the caller's statement, and each declared relation needs a declared complement. After the positive fixed point and the negative stratum, the closed-world stratum gives, for each subject of the type with a known positive r(x, z) — given or derived by a positive rule, active (not a hypothesis, not disputed) — the complement r̄(x, y) on every other candidate object y. A subject with no known positive stays open (nothing is derived); a subject with two or more known positives contradicts the declaration and is left open too (Closure.closed_conflicts); a closed fact that meets a present r(x, y) that is not known (a hypothesis) is a dispute, and the pair is refused (Closure.closed_disputes). Closed facts never feed a rule. Closure.info(x, y, r) and GuardedRules.statuses(story, pair) give each fact's status with its stratum ("given", "positive", "negative", "closed"); templates_on names "closed"; Closure.closed lists the positives each closed fact rests on. Learning is untouched: the stratum is applied when answering, and enters the fixed points learning counts on only with closed_world_in_rounds=True. why_not(rules, story, x, y, relation) reads a refusal of a guarded rule set: "no_known_positive" (the complement of a declared relation for a subject with no known positive — the fact to learn is the agenda item), "functional_conflict", "disputed", "hypothesis" or "underivable". In a knowledge store, to_knowledge writes each declaration as a "rule" item of source "spec" (a declaration is a specification, not an observation; chain_rules(..., functional=) writes it too), and chain_rules writes the closed facts last with the positive and the declaration as premises (the positive's source; evidence stratum 3): explain shows the declaration as a premise, and retracting it takes the closed facts along.
  • Two engines, one answer. closure(story) (bitset joins, statuses) is what predict and the learner use; closure(story, justify=True) also lists every justification — what chain_rules writes. The tests check that both give the same facts and statuses, and that the store's active facts after chain_rules equal answer.
  • In a knowledge store. pair_fact(x, y, r, multi=True, family=...) is a pair fact keyed by pair and family; unary_fact(x, u) a unary fact. chain_rules writes each derived fact through store.add with every justification (premise facts including the unary guards, and the rule; inferred=True, the weakest premise's source), then the NEG stratum with its absent relation in the evidence; a NEG fact whose condition ended is retracted on the next call; a second call writes nothing. explain(store, id) shows guards among the premises and stratum / absent for the negative stratum. forward_chain(..., multi=True) keeps several relations per pair for composition rules too.
  • Diagnostics. votes_for(head, body) (the last round's counts, fit and check), near_misses(heads) (bodies often right about a head and not admitted), templates_on(closure, pair, relations) (which templates give an answer), history (per round: rules added, time).
  • Limits. Two binary atoms per body; unary predicates only as given (no learned or invented ones, so a guard that is itself derived — «underage» from «school mates» — is out of reach); the store path writes every justification and is slow on dense stories (seconds to minutes for tens of thousands of derived facts); a wrong rule admitted at a small support spreads through the fixed point, so an independent check slice matters.

Measured on a planted world (benchmarks/relations_rules_toy.py: families of three generations, genders, homes, colleagues; every ordered pair labelled by an independent oracle; 8 fit stories = 4,106 pairs, 4 check stories, 10 test stories = 4,992 pairs): 242 rules in 4 rounds (3.0 s on CPU), exact set match 1.000 on the test pairs, all 8 planted rules found (a guard over a derived relation, a chain through a derived relation, the «elsewhere» rule, the negative stratum); without residual votes the same 242 rules; one round without them 35 rules, exact 0.975, precision 0.941; the store path on 3 more stories (1,568 pairs, 723 new fact items — 3,110 in 1.1.0 counted justifications written in one batch) 0 differences from the in-memory fixed point. One deterministic run.

Measured in a first run on the held-out part of the benchmark's training file (NoRA, Das et al., NeurIPS 2025, the no-ambiguity configuration; two splits by a hash of the row index, about 9,250 fit / 2,000 check / 1,970 held-out query pairs each; one run per split), exact set match / precision among answered / coverage: the strict setting (majority 1.0, support 10 on the labelled pairs plus two confirmations on the check slice) 0.328 / 0.681 / 0.482 with 469 rules and 0.485 / 0.743 / 0.652 with 436 rules; the default counting setting (majority 0.9, support 2) 0.274 / 0.568 / 0.482 with 720 rules and 0.398 / 0.609 / 0.653 with 838 rules; the most frequent label set per entity kinds 0.335 and 0.341; (benchmarks/relations_rules_nora.py, --salt nora and nora-b). Limits found there: labels exist only on the query pairs, so a derived fact cannot be checked where it lands, and counting at the looser setting admits rules right on the labelled pairs and wrong elsewhere (the joint recount after each round keeps the set from collapsing); the stricter setting does better here, but which chain rules it keeps depends on the split (0.328 against 0.485: whether living_in ← living_in_same_place ∘ living_in survives the strict share on derived facts); the «elsewhere» relation (Not_living_in, about a third of the rows) is refused by every setting without a declaration — a closed-world default per entity type was not built in 1.1.0 (since 1.1.1: functional=); residual votes only bring forward what the next round's fixed point shows anyway (identical rule sets on the planted world); two binary atoms per body, unary predicates only as given (none learned or invented), and a store path that writes every justification (slow on dense stories).

Measured once on the benchmark's three no-ambiguity test files, whole (NoRA, Das et al., NeurIPS 2025; D-na 3,345, OPEC-na 1,683 and BL-na 67,549 query pairs), with the rules learned on a third hash split of the training file (9,238 fit / 2,033 check; the strict setting — majority 1.0, support 10, two confirmations on the check slice — chosen on that split's held-out part, 1,973 pairs, before the test files were read; the bars pre-registered before the run); exact set match / precision among answered / coverage: BL-na (reasoning off the query path) 0.734 / 0.734 / 0.999; D-na (depth beyond the training depth) 0.477 / 0.961 / 0.496 — the rules refuse half of the queries, and the most frequent label set per entity kinds answers 0.491 there, more than the rules by exact match; OPEC-na 0.093 / 0.093 / 0.999; the held-out part of the training file 0.501 / 0.759 / 0.659. The default counting setting (majority 0.9, support 2) gave 0.593 / 0.603 / 0.984 on BL-na, 0.007 / 0.293 / 0.022 on D-na and 0.032 on OPEC-na. The benchmark paper reports, for its best model trained without ambiguity (an Edge Transformer, single-edge), 0.104 on BL-na, 0.822 on D-na and 0.110 on OPEC-na; models trained with ambiguity reach 0.785 on the ambiguous BL split, which was not measured here. The pre-registered bars (BL-na ≥ 0.50 and OPEC-na ≥ 0.20; D-na and held-out ≥ 0.80; precision among answered ≥ 0.95 on every split; the control ≤ 0.30) were not met — none of the four (BL-na's exact match 0.734 clears its 0.50 line, but its precision among answered, 0.734, is below the 0.95 required of every split). What the test shows: labels exist only on the query pairs, so a derived fact cannot be checked where it lands, and the looser admission admits rules right on the labelled pairs and wrong elsewhere (0.593 against 0.734 on BL-na); which chain rules the strict setting keeps depends on the split of the training file (held-out 0.328 / 0.485 / 0.501 on three splits; the test numbers are from the third, one run); the «elsewhere» relation (Not_living_in, about a third of the depth split's rows) is refused by every setting without the declaration, so the depth split is answered on half of its pairs (with the declaration, coverage 0.933 — below); the OPEC split needs a gender guard on the middle entity of a chain (maternal / paternal), which no template carries. Next, each with its own bar: a gender guard on the middle entity, and labels or a structural check on intermediate facts; a closed-world default per entity type beyond a declaration stays unbuilt (the declaration itself is measured on the test files below). The ground truth of this benchmark is computed from published rules, so an exact rule set exists by construction; what is measured is how much of it counting on query-pair labels recovers. The dataset is released under CC BY-NC 2.0: the script reads the files in place; no data and no learned rules ship with the library.

Since 1.1.1, with the closed world declared (functional={"living_in": "person"}, the strict setting otherwise unchanged — the same rules), measured on the held-out part of the same two hash splits of the training file (one run per split): 0.337 / 0.684 / 0.492 and 0.674 / 0.798 / 0.844, exact set match / precision among answered / coverage; the rows holding Not_living_in answered exactly: 17 of 590 and 373 of 588 (0 of each without the declaration); answered wrongly on the other rows: 307 against 303 and 301 against 296 without it. The stratum answers only where living_in is known for the subject, and in this benchmark it is never given for a query subject — it is derived through the living_in chain rule, which the strict setting keeps on one split and not on the other; subjects with two derived places are left open. Measured once on the benchmark's three no-ambiguity test files with the declaration (the same strict rules, learned on the third hash split of the training file — 493 rules, unchanged; the bars pre-registered before the run): D-na 0.914 / 0.979 / 0.933 (exact set match / precision among answered / coverage) against 0.477 / 0.961 / 0.496 without it — 1,463 closed answers, all right, every one from a derived home (no query subject has a given one); BL-na 0.734 / 0.734 / 0.999 and OPEC-na 0.093 unchanged row for row; new wrong answers on the rows without «elsewhere» 0 of 70,943; the 170 «elsewhere» rows of D-na left unanswered are subjects with no known home (58) or with two derived ones (112 rows — the declaration is contradicted and the stratum stays silent). With the closed facts visible to the learning rounds (closed_world_in_rounds=True) the rule set changes (499 rules) and 110 right answers are lost on D-na, so the default stays off. The gain hangs on the living_in chain rule, which the strict setting keeps on this split and not on a neutral one (17 of 590 «elsewhere» rows on the held-out part there); the benchmark paper's best model reports 0.822 on D-na in a different setting — trained end to end without the world rules (the declaration is one of them), answering every pair, one relation per pair — so the number is above the paper's, not a like-for-like comparison; the declaration restates a constraint of the benchmark's own world rules (one home per person), so the gain is the caller's knowledge, not a learned rule. (benchmarks/relations_rules_nora.py --settings strict-closed) On the planted world with only the positive templates (no «elsewhere» rule and no negative stratum to learn) the declaration answers 340 test pairs, all right: exact 0.983 against 0.915 without it (benchmarks/relations_rules_toy.py).

See the module docstring. majority: the least share (> 0.5); support: the least hits; residual: residual votes from length-3 walks; rounds: the cap on rounds; neg: learn the NEG stratum; templates: the bodies counted; complements: relation → the relation whose key it shares (its complement); check_min: the least hits a rule needs on the check slice (0: a rule the check slice never meets is kept; its share there must be ≥ majority whenever the slice meets it); verify: after each round, recount the round's new rules on the fixed point of the whole new rule set (on the check slice, else on the examples) and retract — for good — each whose share there falls below majority, until none does (retracted); functional: relation → the entity type of its subject, or (subject type, object type) — a declaration that a subject of that type has at most one object for the relation (a type "t" is the unary is_t; a name starting with "is_" is the unary itself; without an object type the candidates are the entities carrying every is_* unary of the known object); each needs a declared complement; it adds the closed-world stratum at prediction time (closed_world_in_rounds=True: also in the fixed points learning counts on).

with_rules

with_rules(rules: Iterable[GuardedRule]) -> 'GuardedRules'

Use these rules (no learning).

closure

closure(story: Story, *, justify: bool = False) -> Closure

The fixed point on one story with every fact's status. justify=True: also every justification of every derived fact (just, absent; slower — what chain_rules writes); the facts and statuses are the same.

predict

predict(story: Story, query) -> frozenset

The active relations on the query pair (x, y) at the fixed point; the empty set is a refusal.

statuses

statuses(story: Story, query) -> dict

Every relation present on the query pair at the fixed point → {"status", "stratum" ("given" | "positive" | "negative" | "closed"), "depth"}.

fit

fit(examples: Iterable, check: Iterable | None = None) -> 'GuardedRules'

Learn from labelled query pairs (story, (x, y), relations); check: labelled pairs of an independent slice. Deterministic and independent of the order of the examples.

votes_for

votes_for(head: str, body: tuple) -> dict

The counts of the last round for one body (template, atoms, unary) and head: hits / support on the fit examples and on the check slice (None when no check slice was given).

near_misses

near_misses(heads: Iterable[str], min_support: int = 20, k: int = 15) -> list[dict]

The bodies of the last round most often right about each head without being admitted (share ≥ 0.5, support ≥ min_support), best share first: why a head has no rule.

templates_on

templates_on(c: Closure, query, relations: Iterable[str]) -> dict

Which rules give each relation on the query pair at the fixed point c: "given" (a story fact), "NEG" (the negative stratum), "closed" (the closed-world stratum) or the sorted templates of the positive rules whose body holds there (+ "closed" when the closed world gives it too).

to_knowledge

to_knowledge(store, scope: dict | None = None, *, by: str = 'relations:GuardedRules') -> dict

Write each rule into a KnowledgeStore as a "rule" item: body {"kind": "guarded", "template", "atoms", "unary", "s": [the body's text, head], "r": "guarded", "o": head} (one key per body and head), source "outcome" (labelled pairs), evidence = hits, support, share, origin, round; and each functional declaration as a "rule" item of source "spec" (a declaration is a specification, not an observation; functional_body). Idempotent. → rule → item id (the guarded rules).

One rule: head ← body. template: one of TEMPLATES; atoms: ((relation, inverse 0|1), ...) — one atom (B1, B1u, BNE; NEG: the negated relation) or two (B2, B2z); unary: ((predicate, "x" | "y" | "z"), ...) — B1u one on x or y, B2z one on z, BNE one on y, NEG two (x, y). hits / support: the counts it was admitted with (support = the pairs where the body held); origin "direct" | "residual" | "given"; round: the round it was admitted in. Equality and hashing use the rule only, not its counts.

The facts of one story: binary (x, y, relation) in order, unary (x, predicate). from_edges(edges, types) reads a story graph: a self-loop whose type starts with one of unary_prefixes is a unary fact; other self-loops are dropped (counted in dropped).

The fixed point of a rule set on one story. pairs: (x, y) → {relation: (stratum, depth)} (stratum 0 given, 1 positive rule, 2 negative stratum, 3 closed world — STRATA names them; depth: how deep in rule applications it appeared — the worklist engine counts the first derivation found, the bitset engine the sweep it appeared in: a report figure); unary: x → set; just (with justifications): fact → [(premises, rule index)] — premises are binary facts (x, y, r) and unary facts (x, u); absent: NEG fact → [the negated relation per justification]; statuses: fact → status (see the module); closed: closed-world fact → [the known positives r(x, z) it rests on] (also for a fact present through another stratum); closed_disputes: the keys (x, y, family) disputed only once the closed-world stratum ran; closed_conflicts: (x, relation, objects) for subjects with several known positives (left open).

relations

relations(x, y) -> set

Every relation present on (x, y) at the fixed point (any status).

info

info(x, y, rel) -> dict | None

{"status", "stratum": "given" | "positive" | "negative" | "closed", "depth"} of one fact, None when absent.

answer

answer(x, y) -> frozenset

The active relations on (x, y): the answer; the empty set is a refusal.

facts

facts()

Every binary fact (x, y, relation) at the fixed point.

Apply the guarded rules kept in store to the pair facts (pair_fact, single or multi) and unary facts (unary_fact) of each exact scope matching scope, to the positive fixed point, then the NEG stratum.

rule_scope: where the rules are (default: scope); rules: "active" | "any" (hypothesis rules too: what they give is a hypothesis); complements: relation → the relation whose key it shares; derived pair facts are written as multi pair facts (pair_fact(x, y, r, multi=True, family=complements.get(r, r))). Every justification of a derived fact is written (premises: the binary and unary facts, and the rule; a justification that would rest on the fact it justifies is skipped), with inferred=True and the weakest premise's source; evidence {"rule", "premises" (in body order), "via", "depth", "stratum"} (+ "absent" for NEG). A NEG fact written by an earlier call whose condition no longer holds is retracted.

The closed-world stratum last: the functional declarations kept in the rule scope (to_knowledge writes them; functional= writes them there first, as "spec" rule items) — for each active pair fact r(x, z) of a declared relation (given or derived, not of the NEG stratum) whose subject has the declared type, r̄(x, y) on every candidate object y ≠ z, justified by r(x, z) and the declaration (derived_from; the source of r(x, z); evidence stratum 3). Retracting the declaration or the positive takes the facts along; a closed fact that meets an explicit r(x, y) is a dispute. Idempotent. → ChainReport.

The body of the unary fact u(x): {"s": x, "r": "unary/", "o": True} (one key per entity and predicate).

Text frontend: a story's text read into a relation graph

from solvi.experimental.relations import TextFrontend, GraphCheck, CompositionTable

fe = TextFrontend()                          # KINSHIP (16 relations: gender, inverse by the other's gender), check on
g = fe.read("[Ann] took her son [Bob] out. [Bob]'s sister [Kim] sang.",
            genders={"Ann": "female", "Bob": "male", "Kim": "female"})
g.edges        # TextEdge(x, relation, y, pattern, sentence, inverse): «y is relation of x», inverse edges included
g.genders      # name → GenderFact(name, gender, source): "declared" | "inferred:<word>" | "inferred:pronoun" | "conflict" | "unknown"
g.dropped      # Dropped(edge, reason, detail): reason "gender" | "pair" | "functional"
g.no_inverse   # stated edges whose owner's gender is unknown (no inverse added)
table.derive_paths(g.paths("Ann", "Kim"))    # every shortest path as relation chains → the table's answer
g.story()      # Story(facts (x, y, relation), unary is_male / is_female) for GuardedRules; fe.story(text) does both
fe.read("Ann took her son Bob out.", names=["Ann", "Bob"])     # unbracketed names, given as a list
  • Patterns (PATTERNS, one sentence at a time): x_rel_y «[X]'s REL,? [Y]»; y_x_rel «[Y], [X]'s REL»; y_is_rel_of_x «[Y],? is / was (the | a | an)? REL of [X]»; y_the_rel_of_x «[Y], (the | a | an)? REL of [X]»; his_her_rel_y «his / her REL,? [Y]» — the owner is the nearest earlier name of the sentence with the pronoun's gender that is not itself the object of a relation phrase of the sentence (an enumeration «[R] took his son [P] and his daughter [J]» keeps R for both); no such name, no edge. Each reads «Y is REL of X» as (X, REL, Y).
  • Inverses. relations= maps a relation to (the gender it names, the inverse when the other person is male, the inverse when female); every stated edge carries its inverse, chosen by the owner's gender (the same inverse for both genders needs none). Both directions stated: no duplicate.
  • Genders. Declared first; else inferred from the relation words naming the person (mother ⇒ female); words that disagree give "conflict" (unknown). An owner of unknown gender is taken only when it is the one eligible earlier name.
  • Check (check=True, or a GraphCheck(functional=FUNCTIONAL); check=False keeps the raw edges): a relation whose gender contradicts the person's (or the person's relation words disagree), two relations on one ordered pair, two people as one person's father / mother / husband / wife — every stated edge involved is dropped with its inverse and named; the check never chooses between them. TextGraph.raw keeps the edges before the check.
  • Limits. English kinship phrasings of the five patterns; a miss is a refusal and an edge read wrongly a wrong answer (on the benchmark's test split 9 of the 13 wrong answers rest on a reversed label and 4 on a pair the labels do not mark); not a general relation extractor.

Rules first, a model second

RulesFirst(rules, *, fallback=None, render=None, by="relations:RulesFirst"): rules is a CompositionTable (its derive_paths) or a callable (chains) -> Derivation; fallback(question, options) returns (answer, confidence), (answer, confidence, raw) (raw kept in the record), a plain answer, or None (the model refuses).

from solvi.experimental.relations import RulesFirst, decider_fallback, render_chains

rf = RulesFirst(table, fallback=decider_fallback(model, task="What is Z to A?"))
a = rf.answer([("father", "sister")], options, tail="Z")   # one chain or several chains of one query
a.value, a.who, a.reason       # "aunt", "rules", "derived" — or the model's answer, "model", "underivable"
rec = a.to_record()            # plain JSON: the path, the cells used or the model's output, options, confidence
rf.replay(rec).ok              # derives again; re-reads the model's recorded output; never calls the model
rf.stats                       # {"rules": n, "model": n, "refused": n, "by_reason": {...}}
  • Rules first. A "derived" derivation is the answer; the question is not even rendered and the model is not called. On "disagree" / "underivable" (or "identity") the fallback answers; without a fallback the refusal stays a refusal (value None, who None) with the rules' reason.
  • The question. render_chains(chains, head="A", tail=None) reads a chain the table's way: (father, sister) is "B is the father of A. C is the sister of B. What is C to A?"; several chains share the head and the tail, the people in between are new per chain. Pass your own render(chains, head, tail) for another wording.
  • The answer. who is the path that answered; reason is always the rules' reason (why the model was asked on the model path); confidence is the model's — the rules give none per answer, their precision is measured. A model answer outside the options is not an answer (note says so) and counts as refused in stats.
  • Replay. replay(record) requires the same derivation (relation, reason, candidates, cells), the same rendered question and the same value from the recorded model output; an edited record or a changed table is a problem (Replay.ok False, Replay.problems).
  • Limits. A model answer is taken as given (no confidence gate). An empty reply (a reasoning model at its token cap) or a word outside the options counts as refused; no retry or budget check is built. Whole-graph questions over forward_chain and the text setting are not covered.

Measured once on the frozen test split of CLUTRR (Sinha et al., 2019), the clean split (the relation graph of each story, not its text; 1,146 queries, chains of 2–10 relations; the table fitted on the whole training file, the same 111 cells; the rules' answers byte-identical to the composition table's own measurement on this split): the rules answered 1,087 with 0 wrong and refused 59 (21 disagreeing bracketings, 38 underivable). With a small hosted LLM (z-ai/glm-5.3-flash) as the fallback (temperature 0, reasoning effort low, 2,000 output tokens; the first of two drafts answers; the refused queries rendered in words with the 18 relation names as options), 50 of the 59 refused queries got a readable option and 39 were right; 8 replies were empty because the model's reasoning used the whole output budget (finish reason "length"), and 1 named a relation outside the option list: overall 0.983 at coverage 0.992 (1,126 right of 1,137 answered; 11 wrong, 10 of them one chain of three relations whose gold in this split is itself split between mother and mother-in-law), against 0.949 at coverage 0.949 and 0 wrong for the rules alone. On an equal-size sample of queries the rules answered, the same LLM gave a readable option to 42 of 59 and was right on 41; on chains of 4 or more relations its precision among readable replies was the same on the refused and on the answered queries (34 of 35 each), the loss being empty replies (9 of 44 and 17 of 52). solvi-base as the fallback answered all 59 and was right on 2 (11 of 59 on the sample): it does not compose relations. Every answer replayed from its record without the model (0 failures). One run; $0.017 after the proxy's cache; the pre-registered bar of coverage 1.0 was missed. A first run before the test run, on the training file only (1,816 held-out stories, a fifth of it by a hash of the id, chains of 2 and 3 relations; the table fitted on the other four fifths): the table answered 1,675 (4 wrong) and refused 141 (11 disagreeing bracketings, 130 underivable); the same LLM got 137 of the 141 right and solvi-base 11 of 141; one run, secondary to the test numbers (tests/test_relations_first.py).

See the module docstring. rules: a CompositionTable or a callable (chains) → Derivation; fallback: (question, options) → (answer, confidence) or None; render: (chains, head, tail) → question (default render_chains); by: the name written into every record.

answer

answer(chains, options: Sequence[str] = (), *, head: str = 'A', tail: str | None = None) -> RulesFirstAnswer

Rules first: the derivation over chains (one chain, or several chains of one query); on a refusal the fallback answers the rendered question among options. → RulesFirstAnswer.

replay

replay(record: dict, *, head: str = 'A', tail: str | None = None)

Replay a recorded answer (a to_record() dict) without calling the model → solvi.core.specialist.Replay (ok, problems, from_record=True).

See the module docstring.

to_record

to_record() -> dict

Plain JSON: the path (who), the value, the rules' reason, the derivation (cells as [left, right, relation]), the question and the model's output (model path), the options, the chains, the confidence, a note.

The default question for a query reached by chains (each a sequence of relation names, read the table's way: (r1, r2) is "B is the r1 of A. C is the r2 of B."). head: the first person's name; tail: the last person's (default: the name after every person in between). Several chains share the head and the tail; the people in between are new for each chain.

A fallback over a DecideModel (anything with decide(text, task, options, **spec) → Decision): → (value, confidence, {"probs": the decision's probabilities}).

Derive the consequences of the pair facts in store under its composition rules, to a fixed point.

scope: the facts to chain over (a scope pattern, store.find's; None: every scope) — facts join only within one exact scope, and a derived fact is written in its premises' scope; rule_scope: where the rules are (default: the same pattern as scope); rules: "active" (promoted rules only) or "any" (hypothesis rules too: what they derive is a hypothesis, by the store's own premise rule); max_rounds: stop after this many rounds (the report says fixed_point=False; a later call resumes); max_facts: a hard stop on new facts per scope (default |entities|² × |relations|; ChainLimit); multi: derived facts are multi pair facts (pair_fact(..., multi=True): a pair carries one fact per relation, and only relations of one family — complements: relation → the relation whose key it shares — dispute). Facts of either form are read. Every write goes through store.add (the write gates). Idempotent: a second call writes nothing. → ChainReport.

What forward_chain did. rounds: rounds that proposed something (the depth of the fixed point); fixed_point: False when max_rounds stopped it first; facts_read / rules_read: what it started from; facts_proposed: new justifications written; facts_added: new fact items among them; refused: proposals a write gate refused (e.g. a derivation that would refute its own premise); circular: justifications not written because they would rest on the fact they justify; retracted: facts of an earlier call taken back (chain_rules: a negative-stratum fact whose condition ended); disputes_opened: new person questions; hypotheses: derived facts that are hypotheses at the end; closed_conflicts: subjects with several known positives of a declared functional relation (chain_rules: the closed world is not applied to them); per_round: [{"round", "proposed", "added", "refused", "circular"}]; seconds: wall time.

The derivation of a fact read back from the store: its live justifications (a rule and two facts; a premise retracted or refuted ends one), recursively down to the facts asserted without premises.

What explain() returns. fact: the id explained; nodes: id → {"body", "status", "source", "original" (asserted without premises), "derivations": [{"rule", "cell": (r1, r2, relation), "premises": (left fact, right fact)}]}, every fact the derivation reaches; facts: the original facts it rests on; rules: the rule ids used; cells: the rule cells used, as (r1, r2, relation), sorted. A guarded rule (chain_rules) gives "cell": (template, body text, head), "premises" in body order with the unary guards among them, "stratum" (1 positive, 2 negative) and "absent" (the negated relation of a negative-stratum fact, else None); a closed-world fact gives "cell": ("closed", " functional for ", head), "premises" (the known positive, the declaration — a spec item, shown as a premise), "stratum" 3.

tree

tree(iid=None) -> dict

One derivation as a nested dict (the first justification of each fact, in journal order): {"id", "body", "status", "rule": {"id", "cell"} or None, "premises": [subtree, subtree] or []}.

See the module docstring. majority: the least share of the majority relation (> 0.5); support: the least votes for it; residual: fill from chains of length 3; rounds: the cap on residual rounds; agree: "all" | "majority"; identity: the name of a learned identity relation (None: off); admit: an extra gate (cell, relation, hits, support, tested) → bool, e.g. sized_admit(base_rates(examples)).

conflicts property

conflicts: int

Cells whose votes name more than one relation.

fit

fit(examples: Iterable) -> 'CompositionTable'

Learn from (chain, relation) pairs: chains of length 2 vote, chains of length 3 fill residuals; other lengths are counted in ignored. Deterministic and independent of the order of the examples.

derive

derive(chain: Sequence[str]) -> Derivation

The relation the chain composes to under the table, or a refusal with its reason (see the module).

derive_paths

derive_paths(chains: Iterable[Sequence[str]]) -> Derivation

One query reached by several chains (e.g. every shortest path between two people): the bracketings of every chain are pooled under the same agreement rule; the cells are the union of the cells each chain used.

explain

explain(chain: Sequence[str], relation: str | None = None) -> tuple

The cells the bracketings that give relation use (default: the derived answer; () when refused).

to_knowledge

to_knowledge(store, scope: dict | None = None, *, by: str = 'relations:CompositionTable') -> dict

Write each cell into a KnowledgeStore as a "rule" item: body {"kind": "composition", "s": [left, right], "r": "compose", "o": relation} (one value per cell and scope), source "outcome" (labelled chains), evidence = hits, support, share, origin. Idempotent. → (left, right) → item id.

What derive() returns. relation: the answer or None; reason: "derived" | "underivable" | "disagree" | "identity"; candidates: relation → number of bracketings giving it; cells: the cells used by the answer's bracketings (empty for a refusal; explain(chain, relation) shows a candidate's); missing: for an "underivable" refusal, the absent cells (left, right) that block it — on the shortest span no bracketing composes, the pairs of its two composed parts that have no cell, most blocked chains first (derive_paths) — the rule to learn, by name (why_not reads it over a story's paths); () otherwise.

One admitted cell: left ∘ right → relation, with hits votes for it among support votes (the votes of chains of length 2 and the residual votes of chains of length 3 together); origin "pair" (the cell has votes from chains of length 2), "residual" (only from chains of length 3) or "identity".

See the module docstring. relations: the relation table (relation → (gender it names, inverse if the other person is male, inverse if female)); genders: default declared genders (name → "male" / "female"), overridden per call; check: True (the default GraphCheck), a GraphCheck, or False (raw edges — the control).

mark staticmethod

mark(text: str, names: Iterable[str]) -> str

Bracket every whole-word occurrence of each name not already bracketed (longest names first).

read

read(text: str, names: Iterable[str] | None = None, genders: Mapping[str, str] | None = None) -> TextGraph

Read a story into a TextGraph (see the module).

story

story(text: str, names: Iterable[str] | None = None, genders: Mapping[str, str] | None = None) -> Story

read(...).story(): the facts (x, y, relation) and the gender facts as a Story.

What TextFrontend.read returns: the kept edges (stated and inverse, in reading order), the genders, the dropped edges with their reasons, the stated edges with no inverse (the owner's gender unknown), the names.

facts

facts() -> list[tuple[str, str, str]]

(x, y, relation) per kept edge — the Story / pair_fact order.

paths

paths(x: str, y: str, cap: int = 32) -> list[tuple[str, ...]]

Every shortest directed path x → y over the kept edges, as relation chains (at most cap) — the input of CompositionTable.derive_paths; [] when y is not reachable.

«y is relation of x» — the edge (x, relation, y) as a Story fact (x, y, relation); pattern the one that read it (an inverse carries its source's), sentence its index, inverse True for the edge added by the table.

A person's gender (None: unknown) and where it came from: "declared", "inferred:", "inferred:pronoun", "conflict" (relation words disagree) or "unknown".

The global check (see the module): gender consistency, one relation per ordered pair, at most one person per functional relation (functional, default father / mother / husband / wife). __call__(claims, genders) → (kept claims, dropped); a claim is a stated edge with its inverse (or None).

An edge the check removed (with its inverse): reason "gender" | "pair" | "functional" and the contradiction.

The shortest chain program (fewest atoms) equal to target on every example, found top-down through residuals (see the module docstring), or None.

base: the examples — a sequence of Relations (as synthesize takes) or of worlds, mappings name → (n, n) boolean matrix (as find_rules takes). target: per-example (n, n) matrices, one padded (B, n, n) array, or (with worlds) a function world → matrix. names: the relations used as atoms (default every relation of the examples; with worlds every square matrix); library: a Library or a sequence of Entry — each entry is one more atom ("L", name). depth: the most atoms; budget: the most residual steps; seconds: a wall-clock stop. check=(examples, targets): a candidate must also be exact there (examples in either form, targets as above); test: a HeldOut or any test(name, program, library) → a record with "passed" — name is then required. converses / masks: allow Aᵀ and ∖ I (both on by default). log: called with one line per depth. Deterministic: atoms in the order of names, then the library; no randomness.

Bases: NamedTuple

What synthesize_residual returns. program: the package's program tuple, or None; steps: residual steps taken (one per atom tried at a subgoal — not the enumerator's programs: another unit); seconds: wall time; atoms: the program's number of atoms (None when nothing was found); stopped: "found" | "budget" | "seconds" | "exhausted" (every chain up to depth atoms was ruled out); rejected: candidates equal to the target on the examples that failed the check worlds or the test.

Why relation (or any relation) between x and y is not derived from the pair facts by the table — see the module docstring. facts: (a, relation, b) triples, read from a to b, as the chains the table was fitted on.

With guarded rules (why_not(rules, story, x, y, relation); a GuardedRules and a Story): "derivable" (active on the pair), "disputed" (its key holds two values), "no_known_positive" (the complement of a declared functional relation, for a subject of the type with no active positive of it — positive names the relation, the agenda item is the fact to learn), "functional_conflict" (the subject has several known positives: the declaration is contradicted and the closed world left open there), "hypothesis" (present, resting on a disputed fact) or "underivable".

See the module docstring. readings: relation → the number of paths that give it under some bracketing; derivation: the pooled Derivation over every path (None without a path); paths: how many were read; truncated: max_paths cut the list.

agenda_items

agenda_items() -> list[dict]

The refusal as learning targets (plain records): one per gap {"kind": "cell", "goal": "learn cell l ∘ r", "left", "right", "unblocks", "example", "between"} for "missing_cell"; {"kind": "fact", ...} for "no_path"; {"kind": "dispute", "readings", ...} for "disputed"; {"kind": "other", "derived", "cells"} for "other"; [] when derivable.

to_agenda

to_agenda(agenda, table: CompositionTable) -> list[str]

Declare a goal «learn cell l ∘ r» per gap in agenda (an Agenda), done when table has that cell; a goal already declared is kept. → the goal names.

Bases: NamedTuple

An absent cell left ∘ right → ?, the number of paths x → y it blocks (one such cell would unblock them), and the first such path's chain.

steps: [(head, [body facts]), ...] of a reference derivation in order, facts as (relation, a, b); derived: the facts the system derived. → (head, body, schema) of the first step whose head was not derived, or None when every head was (the refusal is not the rules').

Relations over a state and rules found over them (experimental): a relation-algebra enumerator proposes relational atoms, the held-out test of a law set judges them, and a found rule runs as plain set code after a differential check.

from solvi.experimental.relations import (Relations, RelAlgProposer, PathTree, Library, compile_program,
                                          check_program, enumerate_programs, synthesize, top_programs, show)

r = Relations(["PARENT", "NAME=secret"], 4)               # one state: nodes 0..3, packed-bit matrices
r.update("PARENT", [(1, 2), (2, 0), (3, 1)]); r.mark("NAME=secret", [1])
ancestor_secret = ("COMP", ("PLUS", ("T", ("R", "PARENT"))), ("R", "NAME=secret"))
show(ancestor_secret)                                     # '((PARENTᵀ)⁺ ∘ NAME=secret)'
found = synthesize(examples, targets, size=7)             # the first program equal to the targets on every example
top = top_programs(examples, y, size=4, k=20)             # ranked by the readout's precision; noise-tolerant
lib = Library(); lib.add(("PLUS", ("T", ("R", "PARENT"))), "ancestor")    # a terminal of later searches
fn = compile_program(ancestor_secret)                     # plain set code: fn(r.sets(), r.n) → {(x, y), ...}
check_program(ancestor_secret, worlds).differences        # 0: compiled == interpreted, pair for pair
laws = LawSet(grammar, base=...)
laws.proposer = RelAlgProposer(grammar, k=20, encoder=PathTree("path", names=("secret",)), rows=held_out)

Relations. Relations(names, n): named binary relations over nodes 0..n−1 of one state, stored as packed bits (uint8 (K, n, ⌈n/8⌉)); a unary predicate is a diagonal relation (mark). Node 0 is the subject (the player, the path acted on). The algebra on boolean matrices: compose(a, b, k=1) (at least k paths), converse, union, intersect, minus, complement(a, mask) (bounded by the real pairs), closure (transitive, to a fixed point), count_at_least(a, k) (a unary: the nodes with at least k successors).

Programs are tuples: terminals ("R", name), ("I",), ("U",) (every real pair), ("L", name) (a library entry); unary ("T", x) converse, ("NOT", x), ("PLUS", x) closure, ("CNT1", x) / ("CNT2", x) / ("CNT3", x) (CNT1 is opt-in: not in the default OPS); binary ("OR" | "AND" | "MINUS" | "XOR" | "COMP" | "C2" | "C3", a, b), C2 / C3 = at least 2 / 3 paths. show, size (nodes), evaluate(ast, relations), readout(value) — a relation as a state bit: does node 0 relate to anything.

The enumerator. enumerate_programs(examples, size, library=(), ops=...) builds programs bottom-up by size and keeps one per behaviour: two programs are equivalent when their full relations on every example are equal (the packed bits, a 16-byte hash) — never when only a readout agrees, which would merge relations that differ off node 0 and lose what composes from them. Deterministic (a fixed order); caps on behaviours, evaluations or seconds. synthesize(examples, target, size) returns the first program equal to the target on every example (exact). score(ast, examples, y) is the support and precision of the readout against target bits; top_programs / rank score every behaviour (no stop at the first match) and keep the top k by the lower bound of the precision, at most per_readout per readout pattern: labels with noise still rank the rule first.

The library. Library: accepted programs (Entry(program, name, examples, test) — the examples it was accepted on and its test record), each a terminal ("L", name) of later searches, so a composite rule is a small program over earlier ones; expand inlines them.

Composites with a library of held-out-tested rules (solvi.experimental.relations.library):

from solvi.experimental.relations.library import HeldOut, find_rules
r = find_rules(worlds, targets, base=["PARENT", "IS_DIR", "NAME=secret"], size=6, budget=50_000, library=(),
               test=HeldOut(other_worlds, targets))
r.found["denied"].program            # e.g. (under_secret ∩ depth3), over earlier finds in r.library

find_rules enumerates small programs bottom-up (observational equivalence on the examples), admits only what passes the held-out test on other worlds, and enumerates again with the admitted rules as new terminals, so a rule three levels deep is a small program over earlier finds; the targets are given (an unordered set), the search finds which is within reach and the programs. A learned proposer has a slot (proposer=) as a fallback when the budget runs out; none ships. A world there is a mapping name → (n, n) boolean matrix; library= takes a Library or a sequence of Entry, and each admitted rule is an Entry whose test is the held-out record. include_universal=False (find_rules, Enumerator) leaves U out of the terminals — opt-in, for searches whose rules never need every pair.

Compiled rules. compile_ast(ast) writes plain Python over sets of pairs (an index per relation; composition a join; closure joins of the new pairs to a fixed point; counts per pair) that imports nothing; compile_program executes it. backend="arrays" writes the same over index arrays for large graphs: a relation is a sorted int64 array of keys x·n + y (to_keys, from_keys), composition a join by binary search, closure the new pairs joined to a fixed point. A dense answer — a complement or U outside ∩ / ∖ with a sparse side — is refused (DenseAnswer) unless the domain is declared bounded (dense=True; a state's window is). check_program(ast, worlds) is the differential check against the interpreter, pair for pair; the bar is 0 differences.

Encoders and the laws adapter. encode(state, window=3) / Egocentric: a grid state seen from the player (node 0; a 3×3 or 5×5 window; EAST, SOUTH, AT, FACE; diagonal MAT_ and CRT_); the inventory stays flat atoms. encode_paths(root, focus=, names=) / PathTree(key, names): a path tree (PARENT, SAME_DIR, IS_DIR, NAME=x). relational_atom(ast, encoder) is a laws Atom("rel:<program>", ..., feature="rel") whose code is the compiled program, so a law over it compiles with LawSet.to_module and passes check_compiled. RelAlgProposer(grammar, base=None, k=20, encoder=, rows=): for a mismatch, enumerate on the rows of the mismatched transition's own group, score each behaviour against "the effect predicts this row", and hand the top k as candidates (rel_atom,) + flat atoms to the law set's unchanged held-out test (other groups only) — the test does the work.

Measured: benchmarks/relations_battery.py (the enumerator on a pre-registered battery of random rules over three relations), benchmarks/relations_compile.py (compiled rules on a forest of 100,000 nodes and on 100,000 law rows) and benchmarks/relations_library_toy.py (the library on a path tree and on kinship, with and without it); the numbers are in their docstrings, tests/test_relations_gate.py and tests/test_relations_library_toy.py (pytest -m slow).

Pitfalls built in. Equivalence holds on the examples only: the program kept for a class is its smallest member and may not generalise, so every find needs a held-out check on other sizes and families (the proposer's candidates go through LawSet.test on other groups; the battery script re-checks on larger graphs). The order of terminals and the one-sided commutative operators only choose which equivalent program represents a class. A complement is taken within each example's real pairs, so padding stays empty. Memory: a behaviour is B·n² bits; keys are 16-byte hashes, never the bytes, and max_bytes caps the store — with many or large examples search a subset and re-check on all (synthesize(..., check=(examples, targets))). With noisy labels compare by agreement (score, top_programs), never by the exact target hash; deduplication stays exact. A rule that needs four variables at once (x and y in a common 4-clique) is out of reach, and the battery script's control checks it is never accepted.

Composition tables (CompositionTable): which relation a chain of two relations composes to (father ∘ sister → aunt), learned by exact counting from labelled chains of length 2 (majority share ≥ m, support ≥ s), empty cells filled by residuals from chains of length 3, a longer chain derived by CYK over every bracketing — answered only when the bracketings agree, refused with the reason ("underivable", "disagree") otherwise; explain gives the cells used, to_knowledge writes them as rule items, admit=sized_admit(base_rates(examples)) gates cells by the laws' sized acceptance with a base-rate null.

Forward chaining (forward_chain(store, scope=, rule_scope=)): the composition rules in a KnowledgeStore applied to its pair facts (pair_fact(x, y, relation)) in semi-naive rounds to a fixed point, every derived fact written through the store's gates with its two premises and the rule as derived_from (inferred=True, the weaker premise's source); two derived relations of one pair are a dispute, a retracted premise takes its consequences along, a promoted rule or an answered dispute makes them facts without a re-run; explain(store, id) reads the derivation back (ChainReport, Explanation, ChainLimit). Measured by benchmarks/relations_chain.py.

Guarded rules (GuardedRules, chain_rules): Datalog-lite over pair facts and the story's unary facts — bodies r ← s, r ← s ∧ u, r ← s1 ∘ s2, r ← s1 ∘ s2 ∧ u(z), r ← s(x,z) ∧ z ≠ y ∧ u(y) and a negative stratum r ← u1(x) ∧ u2(y) ∧ ¬s(x,y) — learned by exact counting on labelled query pairs whose label is a set of relations, rounds over the fixed point of the rules admitted so far, residual votes for chain bodies whose middle fact is not yet derivable, a check slice; predict answers a pair with its active relations (∅ = refusal), declared complements dispute; chain_rules applies the rules kept in a KnowledgeStore with every justification. functional= declares a relation functional for a subject type (one object at most): a closed-world stratum then gives the complement on every other candidate object of a subject with one known positive (the declaration a "spec" item and a premise in the store; why_not(rules, story, x, y, relation) names a missing positive). Measured by benchmarks/relations_rules_toy.py. Text frontend (TextFrontend(relations=KINSHIP, genders=None, check=True)): a kinship story's text read into a relation graph by code — five sentence patterns (PATTERNS), the owner of «his / her REL [Y]» the nearest earlier name of the pronoun's gender that is not itself the object of a relation phrase, every edge with its inverse by the relation table, gender facts with their source; GraphCheck drops a gender contradiction, two relations on one pair or a second father / mother / husband / wife and names it (check=False keeps the raw edges); read(text) → TextGraph (edges, genders, dropped, paths(x, y) for CompositionTable.derive_paths, story() for GuardedRules). Rules first, a model second (RulesFirst(table, fallback=, render=)): the table answers the queries it derives and the model is never called for them; a refusal ("disagree", "underivable") goes to the fallback with the question rendered in words from the chains and the options, or stays a refusal without one; every answer names the path that answered (who), is journal-ready (to_record) and replays from its record without the model (replay); decider_fallback(model) adapts a DecideModel; stats counts the paths per reason.

Residual synthesis (synthesize_residual(examples, target, depth=, budget=, test=, name=)): the shortest chain program found top-down from the target — X = A ∘ Y gives Y's bounds through the residual ¬(Aᵀ ∘ ¬Up) and the single-witness pairs, X = Y ∖ I drops the diagonal, a step without a witness is pruned — checked exactly by evaluate, on check= worlds and by a HeldOut; ResidualFound (program, steps, seconds, atoms, stopped, rejected). synthesize(..., method="residual-first") runs it before the enumerator. Measured by benchmarks/relations_residual.py.

Why not derived (why_not(table, facts, x, y, relation)): over every path x → y through the pair facts, why the table does not derive the relation — a missing cell r1 ∘ r2 → ? ranked by the paths it would unblock (Gap), a dispute, another relation, or no path (a missing fact); Derivation.missing carries the blocking cells of every underivable refusal, WhyNot.to_agenda(agenda, table) makes each gap a goal done when the table has the cell, and first_missing_step names the first underived step of a reference derivation.

What is not done: - the enumeration grows as (terminals × operators)^size: with the twenty-odd relations of a grid window, programs of four or five nodes are the practical depth, and the behaviour cap bounds memory; - three-variable logic with counting: a rule that needs four variables at once (a 4-clique) is out of reach; - the proposer enumerates on one group's rows; with few rows many programs share a readout, and only the held-out test separates them; - relational atoms stay in the grammar once proposed (every row evaluates them); nothing prunes unused ones yet; - the library's intermediate concepts are given as targets; find_rules finds the order and the programs, not the concepts; library entries are never retired, and every entry makes the rules it does not help dearer; - forward chaining: composition of two relations over pair facts only (no general rules, negation or aggregation); a learned identity relation is chained as an ordinary relation; - guarded rules: two binary atoms per body, unary predicates only as given (none learned or invented); the store path writes every justification and is slow on dense stories; a wrong rule admitted at a small support spreads through the fixed point; - residual synthesis: chains only (atoms, converses, ∖ I on segments) — no union, intersection, closure or counts, and two masked segments side by side only through a library entry; - the text frontend: English kinship phrasings of five patterns; a miss is a refusal and an edge read wrongly a wrong answer; not a general relation extractor; the owner of «his / her» is an earlier name of the sentence, never one in another sentence; - composition tables: one relation per cell; a cell that depends on something the chain does not carry (a gender) stays below the majority and its chains are refused, not split by that attribute; - the compiled atom of a state's graph allows complements (its domain, the window or the path's chain, is bounded); compile_ast refuses them by default.

Egocentric

Egocentric(window: int = 3, materials: Sequence[str] = MATERIALS, creatures: Sequence[str] = CREATURES)

Bases: _Encoder

A grid state seen from the player: node 0 is the player, nodes 1..w² the cells of a w×w window around it (row by row from the top left). Relations: EAST, SOUTH (a cell → its right / lower neighbour; west and north are their converses), AT (the player → the cell under it), FACE (the player → the faced cell), MAT_ and CRT_ (diagonal: the cell's material, the creature on it). The inventory is not a relation: keep it as flat atoms. The state: {"pos": (x, y), "facing": (dx, dy), "mats": {(x, y): material}, "objs": {(x, y): kind}, ...}.

PathTree

PathTree(key: str = 'path', names: Iterable[str] = ())

Bases: _Encoder

The path a state acts on, as a path tree: node 0 the path (state[key]), then its ancestors; relations PARENT, SAME_DIR, IS_DIR, NAME=x for x in names (see encode_paths).

RelAlgProposer

RelAlgProposer(grammar: Grammar, base: Sequence[str] | None = None, k: int = 20, *, encoder: _Encoder | None = None, rows=None, size: int = 4, ops: Sequence[str] = PROPOSER_OPS, library: Library | None = None, per_readout: int = 8, include_flat: bool = True, max_rows: int = 256, max_behaviours: int = 200000, min_support: int = 1)

A laws proposer that invents relational atoms. For one mismatch: the rows of the mismatched transition's own group (from rows: a Buffer, or a function (lawset, state, action) → transitions) plus the transition itself are encoded, the enumerator runs once over them (programs of at most size nodes over the base relations base, default all of the encoder's, the operators ops, the library), and every behaviour is scored by the support / precision of its readout against "the effect predicts this row" for each effect variant; the top k (at most per_readout per readout pattern, each true in the mismatched state) become atoms "rel:" (added to the grammar once) and candidates (rel_atom,) + the flat conditions true in the state, of at most k − 1 atoms. include_flat: also the flat candidates (as Enumerate). The held-out test of the law set judges, unchanged.

atom

atom(ast) -> Atom

The relational atom of a program, created once and added to the grammar.

ChainLimit

Bases: RuntimeError

forward_chain proposed more new facts in one scope than max_facts (default |entities|² × |relations|, which no correct run exceeds).

ChainReport dataclass

ChainReport(rounds: int = 0, fixed_point: bool = True, facts_read: int = 0, rules_read: int = 0, facts_proposed: int = 0, facts_added: int = 0, refused: int = 0, circular: int = 0, retracted: int = 0, disputes_opened: int = 0, hypotheses: int = 0, closed_conflicts: int = 0, per_round: list = list(), seconds: float = 0.0)

What forward_chain did. rounds: rounds that proposed something (the depth of the fixed point); fixed_point: False when max_rounds stopped it first; facts_read / rules_read: what it started from; facts_proposed: new justifications written; facts_added: new fact items among them; refused: proposals a write gate refused (e.g. a derivation that would refute its own premise); circular: justifications not written because they would rest on the fact they justify; retracted: facts of an earlier call taken back (chain_rules: a negative-stratum fact whose condition ended); disputes_opened: new person questions; hypotheses: derived facts that are hypotheses at the end; closed_conflicts: subjects with several known positives of a declared functional relation (chain_rules: the closed world is not applied to them); per_round: [{"round", "proposed", "added", "refused", "circular"}]; seconds: wall time.

Explanation dataclass

Explanation(fact: str, nodes: dict, facts: tuple, rules: tuple, cells: tuple)

What explain() returns. fact: the id explained; nodes: id → {"body", "status", "source", "original" (asserted without premises), "derivations": [{"rule", "cell": (r1, r2, relation), "premises": (left fact, right fact)}]}, every fact the derivation reaches; facts: the original facts it rests on; rules: the rule ids used; cells: the rule cells used, as (r1, r2, relation), sorted. A guarded rule (chain_rules) gives "cell": (template, body text, head), "premises" in body order with the unary guards among them, "stratum" (1 positive, 2 negative) and "absent" (the negated relation of a negative-stratum fact, else None); a closed-world fact gives "cell": ("closed", " functional for ", head), "premises" (the known positive, the declaration — a spec item, shown as a premise), "stratum" 3.

tree

tree(iid=None) -> dict

One derivation as a nested dict (the first justification of each fact, in journal order): {"id", "body", "status", "rule": {"id", "cell"} or None, "premises": [subtree, subtree] or []}.

Closure

Closure(rules, complements)

The fixed point of a rule set on one story. pairs: (x, y) → {relation: (stratum, depth)} (stratum 0 given, 1 positive rule, 2 negative stratum, 3 closed world — STRATA names them; depth: how deep in rule applications it appeared — the worklist engine counts the first derivation found, the bitset engine the sweep it appeared in: a report figure); unary: x → set; just (with justifications): fact → [(premises, rule index)] — premises are binary facts (x, y, r) and unary facts (x, u); absent: NEG fact → [the negated relation per justification]; statuses: fact → status (see the module); closed: closed-world fact → [the known positives r(x, z) it rests on] (also for a fact present through another stratum); closed_disputes: the keys (x, y, family) disputed only once the closed-world stratum ran; closed_conflicts: (x, relation, objects) for subjects with several known positives (left open).

relations

relations(x, y) -> set

Every relation present on (x, y) at the fixed point (any status).

info

info(x, y, rel) -> dict | None

{"status", "stratum": "given" | "positive" | "negative" | "closed", "depth"} of one fact, None when absent.

answer

answer(x, y) -> frozenset

The active relations on (x, y): the answer; the empty set is a refusal.

facts

facts()

Every binary fact (x, y, relation) at the fixed point.

GuardedRule dataclass

GuardedRule(head: str, template: str, atoms: tuple, unary: tuple = (), hits: int = 0, support: int = 0, origin: str = 'given', round: int = 0)

One rule: head ← body. template: one of TEMPLATES; atoms: ((relation, inverse 0|1), ...) — one atom (B1, B1u, BNE; NEG: the negated relation) or two (B2, B2z); unary: ((predicate, "x" | "y" | "z"), ...) — B1u one on x or y, B2z one on z, BNE one on y, NEG two (x, y). hits / support: the counts it was admitted with (support = the pairs where the body held); origin "direct" | "residual" | "given"; round: the round it was admitted in. Equality and hashing use the rule only, not its counts.

GuardedRules

GuardedRules(majority: float = 0.9, support: int = 2, *, residual: bool = True, rounds: int = 10, neg: bool = True, templates: Iterable[str] = TEMPLATES, complements: Mapping[str, str] | None = None, check_min: int = 0, verify: bool = True, functional: Mapping | None = None, closed_world_in_rounds: bool = False, log=None)

See the module docstring. majority: the least share (> 0.5); support: the least hits; residual: residual votes from length-3 walks; rounds: the cap on rounds; neg: learn the NEG stratum; templates: the bodies counted; complements: relation → the relation whose key it shares (its complement); check_min: the least hits a rule needs on the check slice (0: a rule the check slice never meets is kept; its share there must be ≥ majority whenever the slice meets it); verify: after each round, recount the round's new rules on the fixed point of the whole new rule set (on the check slice, else on the examples) and retract — for good — each whose share there falls below majority, until none does (retracted); functional: relation → the entity type of its subject, or (subject type, object type) — a declaration that a subject of that type has at most one object for the relation (a type "t" is the unary is_t; a name starting with "is_" is the unary itself; without an object type the candidates are the entities carrying every is_* unary of the known object); each needs a declared complement; it adds the closed-world stratum at prediction time (closed_world_in_rounds=True: also in the fixed points learning counts on).

with_rules

with_rules(rules: Iterable[GuardedRule]) -> 'GuardedRules'

Use these rules (no learning).

closure

closure(story: Story, *, justify: bool = False) -> Closure

The fixed point on one story with every fact's status. justify=True: also every justification of every derived fact (just, absent; slower — what chain_rules writes); the facts and statuses are the same.

predict

predict(story: Story, query) -> frozenset

The active relations on the query pair (x, y) at the fixed point; the empty set is a refusal.

statuses

statuses(story: Story, query) -> dict

Every relation present on the query pair at the fixed point → {"status", "stratum" ("given" | "positive" | "negative" | "closed"), "depth"}.

fit

fit(examples: Iterable, check: Iterable | None = None) -> 'GuardedRules'

Learn from labelled query pairs (story, (x, y), relations); check: labelled pairs of an independent slice. Deterministic and independent of the order of the examples.

votes_for

votes_for(head: str, body: tuple) -> dict

The counts of the last round for one body (template, atoms, unary) and head: hits / support on the fit examples and on the check slice (None when no check slice was given).

near_misses

near_misses(heads: Iterable[str], min_support: int = 20, k: int = 15) -> list[dict]

The bodies of the last round most often right about each head without being admitted (share ≥ 0.5, support ≥ min_support), best share first: why a head has no rule.

templates_on

templates_on(c: Closure, query, relations: Iterable[str]) -> dict

Which rules give each relation on the query pair at the fixed point c: "given" (a story fact), "NEG" (the negative stratum), "closed" (the closed-world stratum) or the sorted templates of the positive rules whose body holds there (+ "closed" when the closed world gives it too).

to_knowledge

to_knowledge(store, scope: dict | None = None, *, by: str = 'relations:GuardedRules') -> dict

Write each rule into a KnowledgeStore as a "rule" item: body {"kind": "guarded", "template", "atoms", "unary", "s": [the body's text, head], "r": "guarded", "o": head} (one key per body and head), source "outcome" (labelled pairs), evidence = hits, support, share, origin, round; and each functional declaration as a "rule" item of source "spec" (a declaration is a specification, not an observation; functional_body). Idempotent. → rule → item id (the guarded rules).

Story

Story(facts: Iterable = (), unary: Iterable = (), dropped: int = 0)

The facts of one story: binary (x, y, relation) in order, unary (x, predicate). from_edges(edges, types) reads a story graph: a self-loop whose type starts with one of unary_prefixes is a unary fact; other self-loops are dropped (counted in dropped).

RulesFirst

RulesFirst(rules, *, fallback: Callable | None = None, render: Callable | None = None, by: str = 'relations:RulesFirst')

See the module docstring. rules: a CompositionTable or a callable (chains) → Derivation; fallback: (question, options) → (answer, confidence) or None; render: (chains, head, tail) → question (default render_chains); by: the name written into every record.

answer

answer(chains, options: Sequence[str] = (), *, head: str = 'A', tail: str | None = None) -> RulesFirstAnswer

Rules first: the derivation over chains (one chain, or several chains of one query); on a refusal the fallback answers the rendered question among options. → RulesFirstAnswer.

replay

replay(record: dict, *, head: str = 'A', tail: str | None = None)

Replay a recorded answer (a to_record() dict) without calling the model → solvi.core.specialist.Replay (ok, problems, from_record=True).

RulesFirstAnswer dataclass

RulesFirstAnswer(value: Any, who: str | None, reason: str, derivation: Derivation | None = None, model_output: dict | None = None, confidence: float | None = None, question: str | None = None, options: tuple = (), chains: tuple = (), note: str = '', by: str = 'relations:RulesFirst', extra: dict = dict())

See the module docstring.

to_record

to_record() -> dict

Plain JSON: the path (who), the value, the rules' reason, the derivation (cells as [left, right, relation]), the question and the model's output (model path), the options, the chains, the confidence, a note.

Relations

Relations(names: Iterable[str], n: int, nodes: Sequence | None = None)

Named binary relations over the nodes 0..n-1 of one state (node 0: the subject — the player, the path acted on), stored as packed bits: bits is uint8 (K, n, ⌈n/8⌉), row x of relation k packs the y with (x, y) in it. A unary predicate is a diagonal relation (mark). nodes: optional labels of the nodes (e.g. paths).

mark

mark(name: str, nodes: Iterable[int])

A unary predicate: the diagonal pairs (v, v).

dense

dense() -> np.ndarray

bool (K, n, n).

sets

sets() -> dict[str, set[tuple[int, int]]]

{name: set of pairs}: the input of compiled set code.

DenseAnswer

Bases: ValueError

A program whose compiled answer would be a complement over every pair of nodes (¬x or U outside ∩ / ∖ with a sparse side): refused unless the domain is declared bounded (dense=True).

ProgramCheck dataclass

ProgramCheck(worlds: int, differences: int, pairs: int)

Compiled code against the interpreter: worlds compared, differing pairs over all of them (the bar is 0), pairs in the interpreter's answers.

Entry dataclass

Entry(program: tuple, name: str, examples: tuple = (), test: dict | None = None)

An accepted program kept as a new terminal: the program (a tuple), its name, the examples it was accepted on (ids or labels) and its test record (whatever the test reported: support, precision, held-out groups, ...).

Enumerator

Enumerator(base, size: int = 5, library=(), *, ops: Sequence[str] = OPS, names: Sequence[str] | None = None, max_behaviours: int | None = None, max_evals: int | None = None, seconds: float | None = None, max_bytes: int | None = 1500000000, chunk: int = 2048, include_universal: bool = True)

Programs bottom-up by size (size 1: the base relations, I, U, then the library entries; size s: every unary operator over size s−1, then every binary operator over sizes s1 + s2 = s−1, commutative ones once), keeping one program per behaviour — two programs are the same when their full relations on every example are the same (packed bits, a 16-byte hash), never when only a readout agrees. Deterministic: the order is fixed. Iterate it for the new behaviours in order; evals, behaviours, stopped ("exhausted" | "cap" | "found" | "seconds") after.

base: the examples (a sequence of Relations with the same relation names). ops: the operators to use (default all but CNT1: T, NOT, PLUS, CNT2, CNT3, OR, AND, MINUS, XOR, COMP, C2, C3; CNT1 — at least one successor — is opt-in). max_behaviours / max_evals / seconds: caps; max_bytes (default 1.5 GB): the store of behaviours (B·n² bits each, packed, plus a 16-byte key) is capped to fit — with many or large examples search on a subset and re-check on all (synthesize(check=...)). include_universal=False leaves U out of the terminals (opt-in; the default keeps it).

Equivalence is on the examples only: two programs that agree on every example are one class, represented by the first (smallest) found, even if they differ elsewhere — so a find must be checked on held-out examples of other sizes and families (LawSet.test does that for the proposer). The order of terminals and the one-sided commutative operators only decide which equivalent program represents a class. A complement is taken within the real pairs of each example (padding stays empty).

Found

Bases: NamedTuple

The first program whose relation equals the target on every example (None if none within the size or caps), with the evaluations and the distinct behaviours the search took; by: the search that found it (or ran last) — "enumerate" or "residual"; steps: residual steps spent (method="residual-first" / "residual"; another unit than evaluations).

Library

Library(entries: Iterable[Entry] = ())

Accepted programs, in order of admission; each is a terminal ("L", name) of later enumerations, so a composite rule becomes a small program over earlier ones. An entry may use earlier entries, never itself.

expand

expand(ast)

The program with every library entry replaced by its own program (recursively).

Program

Bases: NamedTuple

One behaviour class: its first (smallest, earliest) program, its size and its value on every example, bool (B, n, n) padded.

Score

Bases: NamedTuple

Of a program's readout against the target bits: on how many examples it is true (support), on how many of those the target is true too (hits), hits / support (0.0 without support).

Scored dataclass

Scored(ast: tuple, score: Score, readout: ndarray, order: int = 0)

A ranked program: its tuple, its score, its readout (one bit per example) and its place in the enumeration.

ResidualFound

Bases: NamedTuple

What synthesize_residual returns. program: the package's program tuple, or None; steps: residual steps taken (one per atom tried at a subgoal — not the enumerator's programs: another unit); seconds: wall time; atoms: the program's number of atoms (None when nothing was found); stopped: "found" | "budget" | "seconds" | "exhausted" (every chain up to depth atoms was ruled out); rejected: candidates equal to the target on the examples that failed the check worlds or the test.

Cell dataclass

Cell(left: str, right: str, relation: str, hits: int, support: int, origin: str)

One admitted cell: left ∘ right → relation, with hits votes for it among support votes (the votes of chains of length 2 and the residual votes of chains of length 3 together); origin "pair" (the cell has votes from chains of length 2), "residual" (only from chains of length 3) or "identity".

CompositionTable

CompositionTable(majority: float = 0.9, support: int = 2, *, residual: bool = True, rounds: int = 10, agree: str = 'all', identity: str | None = None, admit: Admit | None = None)

See the module docstring. majority: the least share of the majority relation (> 0.5); support: the least votes for it; residual: fill from chains of length 3; rounds: the cap on residual rounds; agree: "all" | "majority"; identity: the name of a learned identity relation (None: off); admit: an extra gate (cell, relation, hits, support, tested) → bool, e.g. sized_admit(base_rates(examples)).

conflicts property

conflicts: int

Cells whose votes name more than one relation.

fit

fit(examples: Iterable) -> 'CompositionTable'

Learn from (chain, relation) pairs: chains of length 2 vote, chains of length 3 fill residuals; other lengths are counted in ignored. Deterministic and independent of the order of the examples.

derive

derive(chain: Sequence[str]) -> Derivation

The relation the chain composes to under the table, or a refusal with its reason (see the module).

derive_paths

derive_paths(chains: Iterable[Sequence[str]]) -> Derivation

One query reached by several chains (e.g. every shortest path between two people): the bracketings of every chain are pooled under the same agreement rule; the cells are the union of the cells each chain used.

explain

explain(chain: Sequence[str], relation: str | None = None) -> tuple

The cells the bracketings that give relation use (default: the derived answer; () when refused).

to_knowledge

to_knowledge(store, scope: dict | None = None, *, by: str = 'relations:CompositionTable') -> dict

Write each cell into a KnowledgeStore as a "rule" item: body {"kind": "composition", "s": [left, right], "r": "compose", "o": relation} (one value per cell and scope), source "outcome" (labelled chains), evidence = hits, support, share, origin. Idempotent. → (left, right) → item id.

Derivation dataclass

Derivation(chain: tuple, relation: str | None, reason: str, candidates: dict = dict(), cells: tuple = (), missing: tuple = ())

What derive() returns. relation: the answer or None; reason: "derived" | "underivable" | "disagree" | "identity"; candidates: relation → number of bracketings giving it; cells: the cells used by the answer's bracketings (empty for a refusal; explain(chain, relation) shows a candidate's); missing: for an "underivable" refusal, the absent cells (left, right) that block it — on the shortest span no bracketing composes, the pairs of its two composed parts that have no cell, most blocked chains first (derive_paths) — the rule to learn, by name (why_not reads it over a story's paths); () otherwise.

Dropped dataclass

Dropped(edge: TextEdge, reason: str, detail: str)

An edge the check removed (with its inverse): reason "gender" | "pair" | "functional" and the contradiction.

GenderFact dataclass

GenderFact(name: str, gender: str | None, source: str)

A person's gender (None: unknown) and where it came from: "declared", "inferred:", "inferred:pronoun", "conflict" (relation words disagree) or "unknown".

GraphCheck

GraphCheck(functional: Sequence[str] = FUNCTIONAL, relations: Mapping[str, tuple] = KINSHIP)

The global check (see the module): gender consistency, one relation per ordered pair, at most one person per functional relation (functional, default father / mother / husband / wife). __call__(claims, genders) → (kept claims, dropped); a claim is a stated edge with its inverse (or None).

TextEdge dataclass

TextEdge(x: str, relation: str, y: str, pattern: str, sentence: int, inverse: bool = False)

«y is relation of x» — the edge (x, relation, y) as a Story fact (x, y, relation); pattern the one that read it (an inverse carries its source's), sentence its index, inverse True for the edge added by the table.

TextFrontend

TextFrontend(relations: Mapping[str, tuple] = KINSHIP, genders: Mapping[str, str] | None = None, check: bool | GraphCheck = True)

See the module docstring. relations: the relation table (relation → (gender it names, inverse if the other person is male, inverse if female)); genders: default declared genders (name → "male" / "female"), overridden per call; check: True (the default GraphCheck), a GraphCheck, or False (raw edges — the control).

mark staticmethod

mark(text: str, names: Iterable[str]) -> str

Bracket every whole-word occurrence of each name not already bracketed (longest names first).

read

read(text: str, names: Iterable[str] | None = None, genders: Mapping[str, str] | None = None) -> TextGraph

Read a story into a TextGraph (see the module).

story

story(text: str, names: Iterable[str] | None = None, genders: Mapping[str, str] | None = None) -> Story

read(...).story(): the facts (x, y, relation) and the gender facts as a Story.

TextGraph dataclass

TextGraph(edges: tuple[TextEdge, ...], genders: Mapping[str, GenderFact], dropped: tuple[Dropped, ...] = (), no_inverse: tuple[TextEdge, ...] = (), names: tuple[str, ...] = (), raw: tuple[TextEdge, ...] = ())

What TextFrontend.read returns: the kept edges (stated and inverse, in reading order), the genders, the dropped edges with their reasons, the stated edges with no inverse (the owner's gender unknown), the names.

facts

facts() -> list[tuple[str, str, str]]

(x, y, relation) per kept edge — the Story / pair_fact order.

paths

paths(x: str, y: str, cap: int = 32) -> list[tuple[str, ...]]

Every shortest directed path x → y over the kept edges, as relation chains (at most cap) — the input of CompositionTable.derive_paths; [] when y is not reachable.

Gap

Bases: NamedTuple

An absent cell left ∘ right → ?, the number of paths x → y it blocks (one such cell would unblock them), and the first such path's chain.

WhyNot dataclass

WhyNot(x: object, y: object, relation: str | None, status: str, derivation: Derivation | None = None, paths: int = 0, truncated: bool = False, readings: dict = dict(), gaps: list = list(), positive: str | None = None)

See the module docstring. readings: relation → the number of paths that give it under some bracketing; derivation: the pooled Derivation over every path (None without a path); paths: how many were read; truncated: max_paths cut the list.

agenda_items

agenda_items() -> list[dict]

The refusal as learning targets (plain records): one per gap {"kind": "cell", "goal": "learn cell l ∘ r", "left", "right", "unblocks", "example", "between"} for "missing_cell"; {"kind": "fact", ...} for "no_path"; {"kind": "dispute", "readings", ...} for "disputed"; {"kind": "other", "derived", "cells"} for "other"; [] when derivable.

to_agenda

to_agenda(agenda, table: CompositionTable) -> list[str]

Declare a goal «learn cell l ∘ r» per gap in agenda (an Agenda), done when table has that cell; a goal already declared is kept. → the goal names.

HeldOut

HeldOut(examples: Sequence[Mapping[str, ndarray]], targets: Mapping[str, Any], *, exact: bool = True, min_support: int = 5, min_precision: float = 0.9, min_recall: float = 0.9)

The judge: the program against the targets on held-out worlds (other worlds than the examples; any sizes).

exact (default): every pair of every world right. Otherwise: support (predicted pairs) ≥ min_support, precision ≥ min_precision, recall ≥ min_recall and net = hits − false pairs > 0 — for noisy labels. A target with no true pair in the held-out worlds cannot be tested and never passes. → a record: passed, support, hits, positives, precision, recall, net, errors, worlds, why.

RuleProposer

Bases: Protocol

A fallback proposer for find_rules — the slot for a gradient-trained rule memory (none ships: solvi's core has no torch). Called once per open target when enumeration ran out: propose(name, examples, target, library) → programs (ASTs); each is checked on the examples and by the held-out test like any enumerated program.

Rules dataclass

Rules(library: list, found: dict, order: list, records: dict, programs: int = 0, rounds: int = 0)

The result: library (the given entries, then the admitted ones in order: a list of Entry, which library= and run take), found (name → its Entry, test = the held-out record), order (the names admitted, in order), records (name → TargetRecord), programs (enumerated in total), rounds.

TargetRecord dataclass

TargetRecord(name: str, programs: int | None = None, round_programs: int | None = None, round: int | None = None, size: int | None = None, rejected: int = 0, recheck_failed: int = 0, by: str | None = None)

Per target: programs = the enumerated programs spent (cumulative, all rounds) when it was admitted, or None; round_programs = those of its own round only (from the round's start to its admission: the search it needed with the library of that moment); round = the round it was admitted in; size = its program's size; rejected = programs that fit the examples but failed the held-out test; recheck_failed = matches on the search subset that failed on all the examples (search_on); by = "enumerate" or the proposer's name.

encode

encode(state, window: int = 3, materials: Sequence[str] = MATERIALS, creatures: Sequence[str] = CREATURES) -> Relations

An egocentric graph of a grid state (see Egocentric): node 0 the player, a 3×3 (or 5×5) window of cells.

encode_paths

encode_paths(root, focus: str | None = None, names: Iterable[str] | None = None) -> Relations

A path tree as relations: nodes are the paths and every ancestor (node 0: focus, default the first path or the root), PARENT (a directory → an entry in it), SAME_DIR (two entries of one directory), IS_DIR (diagonal) and NAME=x (diagonal: the last component is x; names default every name that occurs). root: an iterable of '/' separated paths (a trailing '/' marks a directory) or a directory on disk, walked (its ancestors left out). .nodes gives the path of each node.

relational_atom

relational_atom(ast, encoder: _Encoder, library: Library | None = None, *, compiled: bool = True) -> Atom

A program as a laws atom: Atom("rel:", fn, feature="rel", code=..., defs=...). fn: the readout of the interpreted program on the encoded state (does node 0 relate to anything); code: the same through compiled set code (RUNTIME, the encoder's source, the program) — a state's graph is bounded, so complements compile against its nodes. compiled=False: no code (the atom then cannot be compiled into a law module).

explain

explain(store, fact_id) -> Explanation

The derivation of a fact read back from the store: its live justifications (a rule and two facts; a premise retracted or refuted ends one), recursively down to the facts asserted without premises.

forward_chain

forward_chain(store, *, scope=None, rule_scope=None, rules='active', max_rounds=None, max_facts=None, by='relations:forward_chain', multi=False, complements=None) -> ChainReport

Derive the consequences of the pair facts in store under its composition rules, to a fixed point.

scope: the facts to chain over (a scope pattern, store.find's; None: every scope) — facts join only within one exact scope, and a derived fact is written in its premises' scope; rule_scope: where the rules are (default: the same pattern as scope); rules: "active" (promoted rules only) or "any" (hypothesis rules too: what they derive is a hypothesis, by the store's own premise rule); max_rounds: stop after this many rounds (the report says fixed_point=False; a later call resumes); max_facts: a hard stop on new facts per scope (default |entities|² × |relations|; ChainLimit); multi: derived facts are multi pair facts (pair_fact(..., multi=True): a pair carries one fact per relation, and only relations of one family — complements: relation → the relation whose key it shares — dispute). Facts of either form are read. Every write goes through store.add (the write gates). Idempotent: a second call writes nothing. → ChainReport.

pair_fact

pair_fact(x, y, relation, multi=False, family=None) -> dict

The body of the fact «x is relation of … y» as forward_chain reads it: {"s": [x, y], "r": "relation", "o": relation} (the key is the ordered pair; x and y are strings or integers). multi=True: a pair may carry several relations — {"s": [x, y], "r": "relation/", "o": relation}, one key per pair and family (family defaults to the relation itself; relations given one family, e.g. a relation and its complement, share a key and dispute).

chain_rules

chain_rules(store, *, scope=None, rule_scope=None, rules='active', complements: Mapping[str, str] | None = None, neg: bool = True, functional: Mapping | None = None, max_facts=None, by='relations:chain_rules')

Apply the guarded rules kept in store to the pair facts (pair_fact, single or multi) and unary facts (unary_fact) of each exact scope matching scope, to the positive fixed point, then the NEG stratum.

rule_scope: where the rules are (default: scope); rules: "active" | "any" (hypothesis rules too: what they give is a hypothesis); complements: relation → the relation whose key it shares; derived pair facts are written as multi pair facts (pair_fact(x, y, r, multi=True, family=complements.get(r, r))). Every justification of a derived fact is written (premises: the binary and unary facts, and the rule; a justification that would rest on the fact it justifies is skipped), with inferred=True and the weakest premise's source; evidence {"rule", "premises" (in body order), "via", "depth", "stratum"} (+ "absent" for NEG). A NEG fact written by an earlier call whose condition no longer holds is retracted.

The closed-world stratum last: the functional declarations kept in the rule scope (to_knowledge writes them; functional= writes them there first, as "spec" rule items) — for each active pair fact r(x, z) of a declared relation (given or derived, not of the NEG stratum) whose subject has the declared type, r̄(x, y) on every candidate object y ≠ z, justified by r(x, z) and the declaration (derived_from; the source of r(x, z); evidence stratum 3). Retracting the declaration or the positive takes the facts along; a closed fact that meets an explicit r(x, y) is a dispute. Idempotent. → ChainReport.

unary_fact

unary_fact(x, u) -> dict

The body of the unary fact u(x): {"s": x, "r": "unary/", "o": True} (one key per entity and predicate).

decider_fallback

decider_fallback(model, task: str = 'What is the relation?', **spec) -> Callable

A fallback over a DecideModel (anything with decide(text, task, options, **spec) → Decision): → (value, confidence, {"probs": the decision's probabilities}).

render_chains

render_chains(chains: Sequence[Sequence[str]], head: str = 'A', tail: str | None = None) -> str

The default question for a query reached by chains (each a sequence of relation names, read the table's way: (r1, r2) is "B is the r1 of A. C is the r2 of B."). head: the first person's name; tail: the last person's (default: the name after every person in between). Several chains share the head and the tail; the people in between are new for each chain.

closure

closure(a, mask=None)

The transitive closure a⁺ (paths of length ≥ 1): Warshall on row bitmasks up to 64 nodes, else squaring to a fixed point.

complement

complement(a, mask=None)

The complement bounded by mask (the real pairs; default: every pair of the matrix).

compose

compose(a, b, k: int = 1, mask=None)

(x, z) with at least k paths x→y→z (k=1: the composition a∘b).

count_at_least

count_at_least(a, k: int, mask=None)

A unary from a relation: the diagonal relation of the nodes with at least k successors in a.

evaluate

evaluate(ast, rel, library=None)

A program on one Relations → bool (n, n); on a list of them → a list of per-example matrices.

readout

readout(value) -> bool | np.ndarray

A relation read as a state bit: does node 0 relate to anything? bool for one (n, n) matrix, a bool array for a batch (B, n, n).

show

show(ast) -> str

A program as text: E0, (E0 ∘ E1), (E0)⁺, E2ᵀ, ¬E1, #≥2(E0), (E0 #2∘ E1).

size

size(ast) -> int

The number of nodes of a program (a terminal or a library entry counts 1).

check_program

check_program(ast, worlds: Sequence[Relations], library=None, *, dense: bool = False, backend: str = 'sets') -> ProgramCheck

Run the compiled program (either backend) and the interpreter on every world: the sets of pairs must be equal.

compile_ast

compile_ast(ast, name: str = 'rel', library=None, *, dense: bool = False, backend: str = 'sets') -> str

The source of def <name>(R, n) → the program's relation, where R maps each base relation's name to its pairs and n is the node count. backend "sets": pairs are sets of (x, y) tuples and the code calls the helpers in RUNTIME (plain Python, no import); "arrays": pairs are sorted int64 key arrays x·n + y and the helpers are in RUNTIME_ARRAYS (numpy) — for large graphs. Library entries are inlined. DenseAnswer: a complement or U outside ∩ / ∖ with a sparse side (dense=True allows them, computed against all n·n pairs: only for a bounded domain such as one state's window).

compile_program

compile_program(ast, library=None, *, dense: bool = False, backend: str = 'sets') -> Callable

The compiled program as a function f(R, n) (the backend's runtime and the source executed in a fresh namespace): sets → a set of pairs from sets of pairs; arrays → a key array from key arrays (to_keys, from_keys convert).

from_keys

from_keys(keys, n: int) -> set

The arrays backend's keys → a set of (x, y) pairs.

to_keys

to_keys(pairs, n: int) -> np.ndarray

A set of (x, y) pairs → the arrays backend's sorted int64 keys x·n + y.

enumerate_programs

enumerate_programs(base, size: int = 5, library=(), **kw) -> Enumerator

An Enumerator over the examples base (see Enumerator): iterate it for Program(ast, size, value) in order.

lower_bound

lower_bound(hits: int, support: int, z: float = 1.645) -> float

The Wilson lower bound of the precision: what ranks programs (a high precision on a large support first).

rank

rank(en: Enumerator, ys: Sequence, *, k: int = 20, per_readout: int = 1, must: int | None = None, min_support: int = 1) -> list[list[Scored]]

One pass over an enumeration, scored against each of several target vectors: per target the top k programs by the lower bound of the precision (then support, then enumeration order), at most per_readout per readout pattern (the earliest, i.e. smallest, ones), each true on example must if given. Every behaviour is scored: the search does not stop at the first exact match.

score

score(ast, examples, y, library=None) -> Score

Support and precision of the program's readout (node 0 relates to something) against the bits y, one per example.

synthesize

synthesize(base, target, size: int = 7, library=(), *, check=None, method: str = 'enumerate', residual_budget: int = 100000, **kw) -> Found

The first (smallest, in enumeration order) program equal to target — per-example (n_b, n_b) matrices or one padded (B, n, n) array — on every example: exact equality, byte for byte. check=(examples, targets): search on base (e.g. a subset, to bound memory) and accept a match only if it is also exact on these; a failed re-check continues the search.

method: "enumerate" (default: the bottom-up enumerator), "residual-first" (synthesize_residual first — chains of at most size atoms, residual_budget steps, the same check; the enumerator only when it finds nothing) or "residual" (residuals only). Residuals use converses and ∖ I only when "T" and "MINUS" are among ops, and run only when "COMP" is; seconds caps each search.

top_programs

top_programs(examples, y, *, size: int = 4, k: int = 20, library=(), ops: Sequence[str] = OPS, per_readout: int = 1, must: int | None = None, min_support: int = 1, **kw) -> list[Scored]

The top k programs of size ≤ size for the target bits y (see rank): noise-tolerant — ranked by the lower bound of the precision of the readout, never stopped at the first exact match.

synthesize_residual

synthesize_residual(base, target, *, depth: int = 12, budget: int = 500000, seconds: float | None = None, library=(), names: Sequence[str] | None = None, check=None, test: Callable[..., dict] | None = None, name: str | None = None, converses: bool = True, masks: bool = True, log: Callable[[str], None] | None = None) -> ResidualFound

The shortest chain program (fewest atoms) equal to target on every example, found top-down through residuals (see the module docstring), or None.

base: the examples — a sequence of Relations (as synthesize takes) or of worlds, mappings name → (n, n) boolean matrix (as find_rules takes). target: per-example (n, n) matrices, one padded (B, n, n) array, or (with worlds) a function world → matrix. names: the relations used as atoms (default every relation of the examples; with worlds every square matrix); library: a Library or a sequence of Entry — each entry is one more atom ("L", name). depth: the most atoms; budget: the most residual steps; seconds: a wall-clock stop. check=(examples, targets): a candidate must also be exact there (examples in either form, targets as above); test: a HeldOut or any test(name, program, library) → a record with "passed" — name is then required. converses / masks: allow Aᵀ and ∖ I (both on by default). log: called with one line per depth. Deterministic: atoms in the order of names, then the library; no randomness.

base_rates

base_rates(examples: Iterable) -> dict[str, float]

The share of each relation among the labels of the chains of length 2 in examples ((chain, relation) pairs) — the base-rate null of sized_admit.

sized_admit

sized_admit(null: Mapping[str, float] | float, delta: float = 0.1) -> Admit

An admit= hook with the sized acceptance of solvi.experimental.laws: a cell whose majority relation r has hits of support votes passes when P[Binomial(support, null_r) ≥ hits] ≤ δ / N, N the number of cells tested (cells with votes; a declared space, Bonferroni). null: per relation (base_rates) or one number.

first_missing_step

first_missing_step(steps: Sequence, derived) -> tuple | None

steps: [(head, [body facts]), ...] of a reference derivation in order, facts as (relation, a, b); derived: the facts the system derived. → (head, body, schema) of the first step whose head was not derived, or None when every head was (the refusal is not the rules').

rule_schema

rule_schema(head: Sequence, body: Sequence[Sequence]) -> str

('r', a, b) ⟸ [('r1', a, c), ('r2', c, b)] → 'r(X,Y) ⟸ r1(X,Z), r2(Z,Y)': entities abstracted in order.

why_not

why_not(table: CompositionTable, facts: Iterable[Sequence], x, y, relation: str | None = None, *, max_len: int = 6, max_paths: int = 2000, inverse: Mapping[str, str] | None = None) -> WhyNot

Why relation (or any relation) between x and y is not derived from the pair facts by the table — see the module docstring. facts: (a, relation, b) triples, read from a to b, as the chains the table was fitted on.

With guarded rules (why_not(rules, story, x, y, relation); a GuardedRules and a Story): "derivable" (active on the pair), "disputed" (its key holds two values), "no_known_positive" (the complement of a declared functional relation, for a subject of the type with no active positive of it — positive names the relation, the agenda item is the fact to learn), "functional_conflict" (the subject has several known positives: the declaration is contradicted and the closed world left open there), "hypothesis" (present, resting on a disputed fact) or "underivable".

find_rules

find_rules(examples: Sequence[Mapping[str, ndarray]], targets: Mapping[str, Any], *, base: Sequence[str], size: int = 6, budget: int = 50000, library: '_En.Library | Sequence[Entry]' = (), test: Callable[..., dict], proposer: RuleProposer | None = None, grow: bool = True, tolerance: float = 0.0, ops1: Sequence[str] = OPS1, ops2: Sequence[str] = OPS2, counts: Sequence[int] = (1,), search_on: int | None = None, include_universal: bool = True) -> Rules

Find a program for each target, building composites on earlier finds.

Rounds: enumerate programs of size ≤ size from base (relation names in every example), the identity and the library (bottom-up, observational equivalence on the examples); a program whose relation equals a target's on every example (or misses at most tolerance × its true pairs) goes to test(name, program, library) — a HeldOut, or any function returning a record with "passed"; the first that passes is admitted (an Entry) and, with grow, the next round starts with it as a terminal. A round that admits nothing ends the search; then proposer (if any) proposes for the open targets, its programs checked the same way. budget caps the enumerated programs over all rounds. search_on=k: enumerate on the first k examples only (cheaper keys), and re-check a match on all the examples before the test (observational equivalence on a subset merges programs that differ elsewhere: a failed re-check is counted, recheck_failed, and the search goes on). grow=False: one flat pass, finds are recorded but never used as terminals (the control). include_universal=False: U is not a terminal (both arms; the default keeps it, as the package's enumerator does). Deterministic; targets are taken in name order, so the caller's order is no curriculum.

Composites by enumeration with a library: find rules over relations, admit only what passes a held-out test, and build the next rules on the admitted ones.

from solvi.experimental.relations.library import HeldOut, find_rules, run

test = HeldOut(held_out_worlds, targets)                  # the judge: other worlds than the examples
r = find_rules(worlds, targets, base=["PARENT", "IS_DIR", "NAME=secret"], size=6, budget=50_000,
               library=(), test=test)
r.found["denied"].program                                  # an AST over the base relations and earlier finds
run(r.found["denied"].program, new_world, library=r.library)   # runs on any world, of any size

A world is a mapping name → (n, n) boolean matrix (a unary predicate such as IS_DIR is a diagonal matrix). A target is, per name, a function world → (n, n) boolean matrix, or the matrices of the examples in order.

The construction rule: 1. Enumerate small programs bottom-up with observational equivalence, from the base relations plus the library. 2. Accept only what passes the held-out test (exact, or support / precision / recall / net). 3. Put accepted rules into the library as new terminals, so composites become small programs; enumerate again. 4. Use a learned proposer (a gradient-trained rule memory, for example) only when the enumeration budget runs out or the labels are noisy, and only as a proposer: its programs are checked like any other candidate (proposer=). 5. Rank candidates only when a check is expensive (solvi.experimental.laws.RankedProposer): by the joint statistic of the whole condition first (JointRanker, no training), a learned ranker only after it.

What it does not do: invent the intermediate concepts. The targets are given (as an unordered set: find_rules sorts them by name, so the caller's order is not a curriculum); what it finds by itself is which target is within reach of the current library, and the programs. No gradient learner ships with solvi (its core has no torch): the proposer= slot is documented and tested with a stand-in. The search is the package's relation-algebra enumerator (Enumerator, with the operators ops1 / ops2 / counts name; the identity I and the universal relation U are always terminals) and the programs are the package's tuples (show, size, evaluate). library= takes the package's Library or a sequence of its Entry (program, name, examples, test); admitted rules are Entry objects whose test is the held-out record. include_universal=False leaves the universal relation U out of the terminals (an opt-in: a search whose rules never need every pair spends fewer programs per level).

HeldOut

HeldOut(examples: Sequence[Mapping[str, ndarray]], targets: Mapping[str, Any], *, exact: bool = True, min_support: int = 5, min_precision: float = 0.9, min_recall: float = 0.9)

The judge: the program against the targets on held-out worlds (other worlds than the examples; any sizes).

exact (default): every pair of every world right. Otherwise: support (predicted pairs) ≥ min_support, precision ≥ min_precision, recall ≥ min_recall and net = hits − false pairs > 0 — for noisy labels. A target with no true pair in the held-out worlds cannot be tested and never passes. → a record: passed, support, hits, positives, precision, recall, net, errors, worlds, why.

RuleProposer

Bases: Protocol

A fallback proposer for find_rules — the slot for a gradient-trained rule memory (none ships: solvi's core has no torch). Called once per open target when enumeration ran out: propose(name, examples, target, library) → programs (ASTs); each is checked on the examples and by the held-out test like any enumerated program.

TargetRecord dataclass

TargetRecord(name: str, programs: int | None = None, round_programs: int | None = None, round: int | None = None, size: int | None = None, rejected: int = 0, recheck_failed: int = 0, by: str | None = None)

Per target: programs = the enumerated programs spent (cumulative, all rounds) when it was admitted, or None; round_programs = those of its own round only (from the round's start to its admission: the search it needed with the library of that moment); round = the round it was admitted in; size = its program's size; rejected = programs that fit the examples but failed the held-out test; recheck_failed = matches on the search subset that failed on all the examples (search_on); by = "enumerate" or the proposer's name.

Rules dataclass

Rules(library: list, found: dict, order: list, records: dict, programs: int = 0, rounds: int = 0)

The result: library (the given entries, then the admitted ones in order: a list of Entry, which library= and run take), found (name → its Entry, test = the held-out record), order (the names admitted, in order), records (name → TargetRecord), programs (enumerated in total), rounds.

expand

expand(program, library=()) -> tuple

The program with every library entry replaced by its own program, down to base relations.

run

run(program, world: Mapping[str, ndarray], library: Sequence[Entry] = ()) -> np.ndarray

The program's relation on one world: an (n, n) boolean matrix.

find_rules

find_rules(examples: Sequence[Mapping[str, ndarray]], targets: Mapping[str, Any], *, base: Sequence[str], size: int = 6, budget: int = 50000, library: '_En.Library | Sequence[Entry]' = (), test: Callable[..., dict], proposer: RuleProposer | None = None, grow: bool = True, tolerance: float = 0.0, ops1: Sequence[str] = OPS1, ops2: Sequence[str] = OPS2, counts: Sequence[int] = (1,), search_on: int | None = None, include_universal: bool = True) -> Rules

Find a program for each target, building composites on earlier finds.

Rounds: enumerate programs of size ≤ size from base (relation names in every example), the identity and the library (bottom-up, observational equivalence on the examples); a program whose relation equals a target's on every example (or misses at most tolerance × its true pairs) goes to test(name, program, library) — a HeldOut, or any function returning a record with "passed"; the first that passes is admitted (an Entry) and, with grow, the next round starts with it as a terminal. A round that admits nothing ends the search; then proposer (if any) proposes for the open targets, its programs checked the same way. budget caps the enumerated programs over all rounds. search_on=k: enumerate on the first k examples only (cheaper keys), and re-check a match on all the examples before the test (observational equivalence on a subset merges programs that differ elsewhere: a failed re-check is counted, recheck_failed, and the search goes on). grow=False: one flat pass, finds are recorded but never used as terminals (the control). include_universal=False: U is not a terminal (both arms; the default keeps it, as the package's enumerator does). Deterministic; targets are taken in name order, so the caller's order is no curriculum.