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 ≥
majorityand at leastsupportvotes. 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).fitis deterministic and independent of the order of the examples; other chain lengths are counted inignored. - 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) → boolis an extra gate after the thresholds;sized_admit(base_rates(examples), delta=0.1)is the sized acceptance ofsolvi.experimental.lawswith 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 ofRelations, targets as matrices) or asfind_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 bytest=(aHeldOut, withname=); one that fails is counted inrejectedand the search goes on. One chain reached from both ends is checked once. - Stops.
depthatoms,budgetresidual steps (one atom tried at one subgoal),seconds;stoppedis "found", "budget", "seconds" or "exhausted" (no program of the grammar with at mostdepthatoms 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.deriveandderive_pathsput the blocking cells of an "underivable" refusal intoDerivation.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_notreads 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 anAgendagoal «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=Nonechains 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) raisesChainLimit. 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 cellsCompositionTable.derive(chain).cellsgives.- 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).
B1r ← s(x,y);B1ur ← s(x,y) ∧ u(x) (or u(y));B2r ← s1(x,z) ∧ s2(z,y);B2zthe same ∧ u(z);BNEr ← s(x,z) ∧ z ≠ y ∧ u(y) («lives somewhere else»);NEGr ← 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 ≥
supportand a share ≥majorityof 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 (orrounds=).check=: an independent labelled slice where a rule's share must also reachmajority(andcheck_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
NEGrule 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 leastsupportlabelled 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 unaryis_person) has at most one object forliving_in;("person", "place")names the object type too (without it the candidates are the entities carrying everyis_*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)andGuardedRules.statuses(story, pair)give each fact's status with its stratum ("given","positive","negative","closed");templates_onnames"closed";Closure.closedlists 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 withclosed_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_knowledgewrites each declaration as a"rule"item of source"spec"(a declaration is a specification, not an observation;chain_rules(..., functional=)writes it too), andchain_ruleswrites the closed facts last with the positive and the declaration as premises (the positive's source; evidence stratum 3):explainshows the declaration as a premise, and retracting it takes the closed facts along. - Two engines, one answer.
closure(story)(bitset joins, statuses) is whatpredictand the learner use;closure(story, justify=True)also lists every justification — whatchain_ruleswrites. The tests check that both give the same facts and statuses, and that the store's active facts afterchain_rulesequalanswer. - 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_ruleswrites each derived fact throughstore.addwith 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 andstratum/absentfor 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 ¶
Use these rules (no learning).
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 ¶
The active relations on the query pair (x, y) at the fixed point; the empty set is a refusal.
statuses ¶
Every relation present on the query pair at the fixed point → {"status", "stratum" ("given" | "positive" | "negative" | "closed"), "depth"}.
fit ¶
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 ¶
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 ¶
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 ¶
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 ¶
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).
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 aGraphCheck(functional=FUNCTIONAL);check=Falsekeeps 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.rawkeeps 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 (
valueNone,whoNone) 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 ownrender(chains, head, tail)for another wording. - The answer.
whois the path that answered;reasonis always the rules' reason (why the model was asked on the model path);confidenceis the model's — the rules give none per answer, their precision is measured. A model answer outside the options is not an answer (notesays so) and counts as refused instats. - 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.okFalse,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_chainand 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 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 ¶
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", "
tree ¶
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)).
fit ¶
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 ¶
The relation the chain composes to under the table, or a refusal with its reason (see the module).
derive_paths ¶
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 ¶
The cells the bracketings that give relation use (default: the derived answer; () when refused).
to_knowledge ¶
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
¶
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.
«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:
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 ¶
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 ¶
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_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_
PathTree ¶
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:
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
¶
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", "
tree ¶
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 ¶
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).
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 ¶
Use these rules (no learning).
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 ¶
The active relations on the query pair (x, y) at the fixed point; the empty set is a refusal.
statuses ¶
Every relation present on the query pair at the fixed point → {"status", "stratum" ("given" | "positive" | "negative" | "closed"), "depth"}.
fit ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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 ¶
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 ¶
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).
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
¶
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
¶
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 ¶
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 ¶
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
¶
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
¶
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)).
fit ¶
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 ¶
The relation the chain composes to under the table, or a refusal with its reason (see the module).
derive_paths ¶
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 ¶
The cells the bracketings that give relation use (default: the derived answer; () when refused).
to_knowledge ¶
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
¶
An edge the check removed (with its inverse): reason "gender" | "pair" | "functional" and the contradiction.
GenderFact
dataclass
¶
A person's gender (None: unknown) and where it came from: "declared", "inferred:
GraphCheck ¶
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
¶
«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
¶
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.
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 ¶
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 ¶
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
¶
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 ¶
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:
explain ¶
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 ¶
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/
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 ¶
The body of the unary fact u(x): {"s": x, "r": "unary/", "o": True} (one key per entity and predicate).
decider_fallback ¶
A fallback over a DecideModel (anything with decide(text, task, options, **spec) → Decision): → (value,
confidence, {"probs": the decision's probabilities}).
render_chains ¶
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 ¶
The transitive closure a⁺ (paths of length ≥ 1): Warshall on row bitmasks up to 64 nodes, else squaring to a fixed point.
complement ¶
The complement bounded by mask (the real pairs; default: every pair of the matrix).
compose ¶
(x, z) with at least k paths x→y→z (k=1: the composition a∘b).
count_at_least ¶
A unary from a relation: the diagonal relation of the nodes with at least k successors in a.
evaluate ¶
A program on one Relations → bool (n, n); on a list of them → a list of per-example matrices.
readout ¶
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).
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 ¶
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).
to_keys ¶
A set of (x, y) pairs → the arrays backend's sorted int64 keys x·n + y.
enumerate_programs ¶
An Enumerator over the examples base (see Enumerator): iterate it for Program(ast, size, value) in order.
lower_bound ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
('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
¶
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 ¶
The program with every library entry replaced by its own program, down to base relations.
run ¶
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.