neurosymbolic-arithmetic 0.1.0__tar.gz

neurosymbolic_arithmetic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 outlawsujith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neurosymbolic_arithmetic-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: neurosymbolic-arithmetic
+Version: 0.1.0
+Summary: Neurosymbolic AI from scratch in NumPy: a neural net learns digits through differentiable symbolic reasoning, with an explainable logic reasoner.
+Author: outlawsujith
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/outlawsujith/neurosymbolic-arithmetic
+Project-URL: Issues, https://github.com/outlawsujith/neurosymbolic-arithmetic/issues
+Keywords: neurosymbolic,neuro-symbolic,logic,datalog,semantic-loss,numpy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Dynamic: license-file
+
+# Neurosymbolic Arithmetic
+
+A small, dependency-light neurosymbolic AI system written from scratch in NumPy.
+A neural network learns to **read digits** from noisy images while being told only
+the **result of a symbolic program** run on those digits (for example, their sum).
+No digit is ever labelled. A logic reasoner then draws conclusions from what the
+network perceives and explains each one with a proof.
+
+```
+ image 1 ──► neural net ──► P(digit 1) ─┐
+                                        ├─► symbolic program ──► P(sum) ──► loss vs. observed sum
+ image 2 ──► neural net ──► P(digit 2) ─┘        (exact probabilistic inference,
+              (shared)                             gradients flow back through it)
+```
+
+## Why this is neurosymbolic
+
+| Part | File | Role |
+|---|---|---|
+| Neural perception | [nesy/perception.py](nesy/perception.py) | MLP with hand-written backprop and Adam; maps an image to a distribution over digits |
+| Differentiable reasoning | [nesy/semantic.py](nesy/semantic.py) | Sums the probability of every world `(a, b)` that the symbolic program maps to the observed answer; `-log P(answer)` is the training loss |
+| Symbolic reasoning | [nesy/logic.py](nesy/logic.py) | Datalog-style forward chainer with unification, arithmetic built-ins and proof traces |
+| Pipeline | [nesy/pipeline.py](nesy/pipeline.py) | Training loops, a pure-neural baseline, and perceive-then-reason |
+| Data | [nesy/data.py](nesy/data.py) | Synthetic noisy, randomly shifted digit glyphs (nothing to download) |
+
+The training signal is the approach used by DeepProbLog and the semantic loss,
+written out explicitly for programs over two digits:
+
+```
+P(y) = Σ  p1[a] · p2[b]      over all digits a, b with f(a, b) = y
+loss = −log P(y_observed)
+```
+
+## Quick start
+
+Requires Python 3.9+ and NumPy.
+
+```bash
+pip install git+https://github.com/outlawsujith/neurosymbolic-arithmetic.git
+nesy-train                 # learn digits from sums, compare with a neural baseline
+nesy-demo                  # perceive, reason, explain
+```
+
+To work on the code instead, clone the repo and install it in editable mode:
+
+```bash
+git clone https://github.com/outlawsujith/neurosymbolic-arithmetic.git
+cd neurosymbolic-arithmetic
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+If the `nesy-train` command is not on your PATH (or is blocked on your machine), use
+`python -m nesy.train` and `python -m nesy.demo` instead.
+
+Other tasks: `nesy-train --task product` (also `difference`, `concat`).
+Add your own in `TASKS` in [nesy/semantic.py](nesy/semantic.py) as any Python function of two digits.
+
+## Results
+
+`nesy-train --sweep` (seed 0, 2000 unseen test pairs, both models given the
+same data and the same number of gradient steps):
+
+| Training pairs | Neurosymbolic (sum accuracy) | Neural baseline (sum accuracy) | Digit accuracy (neurosymbolic) |
+|---:|---:|---:|---:|
+| 100  | 8.9%  | 8.3%  | 14.9% |
+| 250  | 17.8% | 8.6%  | 35.0% |
+| 500  | 23.1% | 9.7%  | 38.5% |
+| 1000 | 95.3% | 10.8% | 97.6% |
+| 2000 | 97.2% | 14.4% | 98.6% |
+| 4000 | 97.7% | 26.9% | 98.9% |
+
+The baseline is an MLP that takes both images and predicts the sum directly, so
+it has to rediscover addition from examples. The neurosymbolic model is given
+addition as knowledge and only has to learn perception. On the `product` task
+with 2000 pairs the gap is 97.1% vs 37.9%.
+
+Limits worth knowing: with fewer than about 1000 pairs the answer-only signal is
+too weak and the neurosymbolic model also fails; these are single-seed numbers on
+synthetic data; and exact inference enumerates all 100 digit pairs, which does not
+scale to long programs without approximation.
+
+## Demo output
+
+```
+Neural perception:  left = 4 (100% confident), right = 5 (100% confident)   [truth: 4, 5]
+
+Symbolic reasoning derived:
+    odd_sum
+    product(20)
+    right_greater
+    sum(9)
+
+Why does `odd_sum` hold?
+    odd_sum   [by rule: odd_sum :- sum(Z), mod(Z, 2, 1).]
+      sum(9)   [by rule: sum(Z) :- left(X), right(Y), add(X, Y, Z).]
+        left(4)   [perceived]
+        right(5)   [perceived]
+        add(4, 5, 9)   [arithmetic]
+      mod(9, 2, 1)   [arithmetic]
+
+Abduction: told only that the true sum is 9, the most probable digits are (4, 5) with posterior 100%
+```
+
+## Using the reasoner on its own
+
+```python
+from nesy import KnowledgeBase
+
+kb = KnowledgeBase([
+    "path(X, Y) :- edge(X, Y).",
+    "path(X, Z) :- edge(X, Y), path(Y, Z).",
+])
+for fact in ("edge(a, b)", "edge(b, c)"):
+    kb.add_fact(fact)
+kb.forward_chain()
+print(kb.holds("path(a, c)"))            # True
+print("\n".join(kb.explain("path(a, c)")))
+```
+
+## References
+
+- Manhaeve et al., *DeepProbLog: Neural Probabilistic Logic Programming*, NeurIPS 2018
+- Xu et al., *A Semantic Loss Function for Deep Learning with Symbolic Knowledge*, ICML 2018
+- Garcez & Lamb, *Neurosymbolic AI: The 3rd Wave*, 2020
+
+## License
+
+MIT. See [LICENSE](LICENSE).

neurosymbolic_arithmetic-0.1.0/README.md

@@ -0,0 +1,129 @@
+# Neurosymbolic Arithmetic
+
+A small, dependency-light neurosymbolic AI system written from scratch in NumPy.
+A neural network learns to **read digits** from noisy images while being told only
+the **result of a symbolic program** run on those digits (for example, their sum).
+No digit is ever labelled. A logic reasoner then draws conclusions from what the
+network perceives and explains each one with a proof.
+
+```
+ image 1 ──► neural net ──► P(digit 1) ─┐
+                                        ├─► symbolic program ──► P(sum) ──► loss vs. observed sum
+ image 2 ──► neural net ──► P(digit 2) ─┘        (exact probabilistic inference,
+              (shared)                             gradients flow back through it)
+```
+
+## Why this is neurosymbolic
+
+| Part | File | Role |
+|---|---|---|
+| Neural perception | [nesy/perception.py](nesy/perception.py) | MLP with hand-written backprop and Adam; maps an image to a distribution over digits |
+| Differentiable reasoning | [nesy/semantic.py](nesy/semantic.py) | Sums the probability of every world `(a, b)` that the symbolic program maps to the observed answer; `-log P(answer)` is the training loss |
+| Symbolic reasoning | [nesy/logic.py](nesy/logic.py) | Datalog-style forward chainer with unification, arithmetic built-ins and proof traces |
+| Pipeline | [nesy/pipeline.py](nesy/pipeline.py) | Training loops, a pure-neural baseline, and perceive-then-reason |
+| Data | [nesy/data.py](nesy/data.py) | Synthetic noisy, randomly shifted digit glyphs (nothing to download) |
+
+The training signal is the approach used by DeepProbLog and the semantic loss,
+written out explicitly for programs over two digits:
+
+```
+P(y) = Σ  p1[a] · p2[b]      over all digits a, b with f(a, b) = y
+loss = −log P(y_observed)
+```
+
+## Quick start
+
+Requires Python 3.9+ and NumPy.
+
+```bash
+pip install git+https://github.com/outlawsujith/neurosymbolic-arithmetic.git
+nesy-train                 # learn digits from sums, compare with a neural baseline
+nesy-demo                  # perceive, reason, explain
+```
+
+To work on the code instead, clone the repo and install it in editable mode:
+
+```bash
+git clone https://github.com/outlawsujith/neurosymbolic-arithmetic.git
+cd neurosymbolic-arithmetic
+pip install -e .
+python -m unittest discover -s tests -v
+```
+
+If the `nesy-train` command is not on your PATH (or is blocked on your machine), use
+`python -m nesy.train` and `python -m nesy.demo` instead.
+
+Other tasks: `nesy-train --task product` (also `difference`, `concat`).
+Add your own in `TASKS` in [nesy/semantic.py](nesy/semantic.py) as any Python function of two digits.
+
+## Results
+
+`nesy-train --sweep` (seed 0, 2000 unseen test pairs, both models given the
+same data and the same number of gradient steps):
+
+| Training pairs | Neurosymbolic (sum accuracy) | Neural baseline (sum accuracy) | Digit accuracy (neurosymbolic) |
+|---:|---:|---:|---:|
+| 100  | 8.9%  | 8.3%  | 14.9% |
+| 250  | 17.8% | 8.6%  | 35.0% |
+| 500  | 23.1% | 9.7%  | 38.5% |
+| 1000 | 95.3% | 10.8% | 97.6% |
+| 2000 | 97.2% | 14.4% | 98.6% |
+| 4000 | 97.7% | 26.9% | 98.9% |
+
+The baseline is an MLP that takes both images and predicts the sum directly, so
+it has to rediscover addition from examples. The neurosymbolic model is given
+addition as knowledge and only has to learn perception. On the `product` task
+with 2000 pairs the gap is 97.1% vs 37.9%.
+
+Limits worth knowing: with fewer than about 1000 pairs the answer-only signal is
+too weak and the neurosymbolic model also fails; these are single-seed numbers on
+synthetic data; and exact inference enumerates all 100 digit pairs, which does not
+scale to long programs without approximation.
+
+## Demo output
+
+```
+Neural perception:  left = 4 (100% confident), right = 5 (100% confident)   [truth: 4, 5]
+
+Symbolic reasoning derived:
+    odd_sum
+    product(20)
+    right_greater
+    sum(9)
+
+Why does `odd_sum` hold?
+    odd_sum   [by rule: odd_sum :- sum(Z), mod(Z, 2, 1).]
+      sum(9)   [by rule: sum(Z) :- left(X), right(Y), add(X, Y, Z).]
+        left(4)   [perceived]
+        right(5)   [perceived]
+        add(4, 5, 9)   [arithmetic]
+      mod(9, 2, 1)   [arithmetic]
+
+Abduction: told only that the true sum is 9, the most probable digits are (4, 5) with posterior 100%
+```
+
+## Using the reasoner on its own
+
+```python
+from nesy import KnowledgeBase
+
+kb = KnowledgeBase([
+    "path(X, Y) :- edge(X, Y).",
+    "path(X, Z) :- edge(X, Y), path(Y, Z).",
+])
+for fact in ("edge(a, b)", "edge(b, c)"):
+    kb.add_fact(fact)
+kb.forward_chain()
+print(kb.holds("path(a, c)"))            # True
+print("\n".join(kb.explain("path(a, c)")))
+```
+
+## References
+
+- Manhaeve et al., *DeepProbLog: Neural Probabilistic Logic Programming*, NeurIPS 2018
+- Xu et al., *A Semantic Loss Function for Deep Learning with Symbolic Knowledge*, ICML 2018
+- Garcez & Lamb, *Neurosymbolic AI: The 3rd Wave*, 2020
+
+## License
+
+MIT. See [LICENSE](LICENSE).

neurosymbolic_arithmetic-0.1.0/nesy/__init__.py

@@ -0,0 +1,21 @@
+"""Neurosymbolic arithmetic: neural perception + symbolic reasoning in pure NumPy."""
+
+__version__ = "0.1.0"
+
+from .data import make_pairs, render_digit, to_ascii
+from .logic import KnowledgeBase, parse_atom, parse_rule
+from .perception import MLP, softmax
+from .semantic import SymbolicTask, TASKS
+
+__all__ = [
+    "make_pairs",
+    "render_digit",
+    "to_ascii",
+    "KnowledgeBase",
+    "parse_atom",
+    "parse_rule",
+    "MLP",
+    "softmax",
+    "SymbolicTask",
+    "TASKS",
+]

neurosymbolic_arithmetic-0.1.0/nesy/data.py

@@ -0,0 +1,63 @@
+"""Synthetic noisy digit images.
+
+Each digit is a 5x7 bitmap glyph dropped at a random offset into a 9x7 canvas,
+then corrupted with pixel flips and Gaussian noise. No download required, and
+hard enough that perception has to be learned rather than looked up.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+GLYPHS = {
+    0: [" ### ", "#   #", "#  ##", "# # #", "##  #", "#   #", " ### "],
+    1: ["  #  ", " ##  ", "  #  ", "  #  ", "  #  ", "  #  ", " ### "],
+    2: [" ### ", "#   #", "    #", "   # ", "  #  ", " #   ", "#####"],
+    3: [" ### ", "#   #", "    #", "  ## ", "    #", "#   #", " ### "],
+    4: ["   # ", "  ## ", " # # ", "#  # ", "#####", "   # ", "   # "],
+    5: ["#####", "#    ", "#### ", "    #", "    #", "#   #", " ### "],
+    6: [" ### ", "#    ", "#    ", "#### ", "#   #", "#   #", " ### "],
+    7: ["#####", "    #", "   # ", "  #  ", "  #  ", "  #  ", "  #  "],
+    8: [" ### ", "#   #", "#   #", " ### ", "#   #", "#   #", " ### "],
+    9: [" ### ", "#   #", "#   #", " ####", "    #", "    #", " ### "],
+}
+
+GLYPH_H, GLYPH_W = 7, 5
+HEIGHT, WIDTH = 9, 7
+IMAGE_DIM = HEIGHT * WIDTH
+
+_BITMAPS = np.array(
+    [[[c == "#" for c in row] for row in GLYPHS[d]] for d in range(10)], dtype=float
+)
+
+
+def render_digit(digit: int, rng: np.random.Generator, noise: float = 0.2,
+                 flip: float = 0.02) -> np.ndarray:
+    """Return one noisy image of `digit` as a flat vector of length IMAGE_DIM."""
+    canvas = np.zeros((HEIGHT, WIDTH))
+    dy = rng.integers(0, HEIGHT - GLYPH_H + 1)
+    dx = rng.integers(0, WIDTH - GLYPH_W + 1)
+    canvas[dy:dy + GLYPH_H, dx:dx + GLYPH_W] = _BITMAPS[digit]
+    flips = rng.random(canvas.shape) < flip
+    canvas = np.where(flips, 1.0 - canvas, canvas)
+    canvas = canvas + rng.normal(0.0, noise, canvas.shape)
+    return canvas.ravel()
+
+
+def make_pairs(n: int, rng: np.random.Generator, **kwargs):
+    """Sample `n` pairs of digit images.
+
+    Returns (X1, X2, d1, d2): two image arrays of shape (n, IMAGE_DIM) and the
+    hidden digit labels. Training only ever sees a function of (d1, d2).
+    """
+    d1 = rng.integers(0, 10, n)
+    d2 = rng.integers(0, 10, n)
+    X1 = np.stack([render_digit(d, rng, **kwargs) for d in d1])
+    X2 = np.stack([render_digit(d, rng, **kwargs) for d in d2])
+    return X1, X2, d1, d2
+
+
+def to_ascii(image: np.ndarray, threshold: float = 0.5) -> list[str]:
+    """Render a flat image as lines of text for terminal display."""
+    grid = image.reshape(HEIGHT, WIDTH)
+    return ["".join("#" if v > threshold else "." for v in row) for row in grid]

neurosymbolic_arithmetic-0.1.0/nesy/demo.py

@@ -0,0 +1,73 @@
+"""Perceive two noisy digit images, reason about them, and explain the answer.
+
+    nesy-demo                   # uses model.npz, training one first if missing
+    nesy-demo --seed 7 --examples 3
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+import numpy as np
+
+from nesy import MLP, TASKS, make_pairs, to_ascii
+from nesy.logic import format_atom
+from nesy.pipeline import perceive_and_reason, train_neurosymbolic
+
+
+def load_or_train(path: str) -> MLP:
+    if os.path.exists(path):
+        return MLP.load(path)
+    print("No saved model found; training one from sum labels (a few seconds)...\n")
+    task = TASKS["sum"]
+    X1, X2, d1, d2 = make_pairs(2000, np.random.default_rng(0))
+    net = train_neurosymbolic(task, X1, X2, task.encode(d1, d2), epochs=60)
+    net.save(path)
+    return net
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--model", default="model.npz")
+    parser.add_argument("--seed", type=int, default=1)
+    parser.add_argument("--examples", type=int, default=2)
+    args = parser.parse_args()
+
+    net = load_or_train(args.model)
+    X1, X2, d1, d2 = make_pairs(args.examples, np.random.default_rng(args.seed))
+
+    for i in range(args.examples):
+        print("=" * 64)
+        print(f"Example {i + 1}: the network sees two noisy images")
+        for a, b in zip(to_ascii(X1[i]), to_ascii(X2[i])):
+            print(f"    {a}     {b}")
+
+        kb, derived, (c1, c2) = perceive_and_reason(net, X1[i], X2[i])
+        left = kb.query("left(X)")[0]["X"]
+        right = kb.query("right(X)")[0]["X"]
+        print(f"\nNeural perception:  left = {left} ({c1:.0%} confident), "
+              f"right = {right} ({c2:.0%} confident)   [truth: {d1[i]}, {d2[i]}]")
+
+        print("\nSymbolic reasoning derived:")
+        for fact in sorted(derived, key=format_atom):
+            print(f"    {format_atom(fact)}")
+
+        total = kb.query("sum(Z)")[0]["Z"]
+        target = "carry" if kb.holds("carry") else "even_sum" if kb.holds("even_sum") else "odd_sum"
+        print(f"\nWhy does `{target}` hold?")
+        for line in kb.explain(target):
+            print(f"    {line}")
+
+        # Abduction: reason backwards from a known answer to the likeliest inputs.
+        p1 = net.predict_proba(X1[i][None])[0]
+        p2 = net.predict_proba(X2[i][None])[0]
+        a, b, post = TASKS["sum"].abduce(p1, p2, int(d1[i] + d2[i]))
+        print(f"\nAbduction: told only that the true sum is {d1[i] + d2[i]}, the most "
+              f"probable digits are ({a}, {b}) with posterior {post:.0%}")
+        print(f"Predicted sum: {total}   True sum: {d1[i] + d2[i]}\n")
+
+
+if __name__ == "__main__":
+    main()

neurosymbolic_arithmetic-0.1.0/nesy/logic.py

@@ -0,0 +1,206 @@
+"""The symbolic half: a small Datalog-style forward-chaining reasoner.
+
+Rules are Horn clauses written in Prolog-like syntax:
+
+    sum(Z) :- left(X), right(Y), add(X, Y, Z).
+
+Names starting with an uppercase letter are variables; integers and lowercase
+names are constants. Arithmetic is provided by built-in predicates. Every
+derived fact remembers the rule and premises that produced it, so any
+conclusion can be explained with a proof tree.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable, Iterator
+
+Atom = tuple  # (predicate, arg1, arg2, ...)
+
+
+def is_var(term) -> bool:
+    return isinstance(term, str) and (term[0].isupper() or term[0] == "_")
+
+
+def _parse_term(text: str):
+    text = text.strip()
+    return int(text) if re.fullmatch(r"-?\d+", text) else text
+
+
+def parse_atom(text: str) -> Atom:
+    m = re.fullmatch(r"\s*([a-z]\w*)\s*(?:\((.*)\))?\s*", text)
+    if not m:
+        raise ValueError(f"cannot parse atom: {text!r}")
+    args = [_parse_term(a) for a in m.group(2).split(",")] if m.group(2) else []
+    return (m.group(1), *args)
+
+
+def _split_body(text: str) -> list[str]:
+    parts, depth, current = [], 0, ""
+    for ch in text:
+        if ch == "," and depth == 0:
+            parts.append(current)
+            current = ""
+            continue
+        depth += ch == "("
+        depth -= ch == ")"
+        current += ch
+    return parts + [current]
+
+
+@dataclass(frozen=True)
+class Rule:
+    head: Atom
+    body: tuple
+
+    def __str__(self) -> str:
+        return f"{format_atom(self.head)} :- {', '.join(map(format_atom, self.body))}."
+
+
+def parse_rule(text: str) -> Rule:
+    text = text.strip().rstrip(".")
+    head, sep, body = text.partition(":-")
+    if not sep:
+        raise ValueError(f"rule needs a body: {text!r}")
+    return Rule(parse_atom(head), tuple(parse_atom(a) for a in _split_body(body)))
+
+
+def format_atom(atom: Atom) -> str:
+    pred, *args = atom
+    return f"{pred}({', '.join(map(str, args))})" if args else pred
+
+
+def _builtin_add(x, y, z):
+    if x is not None and y is not None:
+        yield (x, y, x + y)
+    elif x is not None and z is not None:
+        yield (x, z - x, z)
+    elif y is not None and z is not None:
+        yield (z - y, y, z)
+
+
+def _builtin_mul(x, y, z):
+    if x is not None and y is not None:
+        yield (x, y, x * y)
+
+
+def _builtin_mod(x, y, z):
+    if x is not None and y is not None and y != 0:
+        yield (x, y, x % y)
+
+
+def _comparison(test: Callable[[int, int], bool]):
+    def builtin(x, y):
+        if x is not None and y is not None and test(x, y):
+            yield (x, y)
+    return builtin
+
+
+BUILTINS: dict[str, Callable] = {
+    "add": _builtin_add,
+    "mul": _builtin_mul,
+    "mod": _builtin_mod,
+    "lt": _comparison(lambda x, y: x < y),
+    "gt": _comparison(lambda x, y: x > y),
+    "le": _comparison(lambda x, y: x <= y),
+    "ge": _comparison(lambda x, y: x >= y),
+    "neq": _comparison(lambda x, y: x != y),
+}
+
+
+def _unify(pattern: Atom, fact: Atom, theta: dict):
+    """Match a possibly non-ground atom against a ground fact."""
+    if len(pattern) != len(fact) or pattern[0] != fact[0]:
+        return None
+    theta = dict(theta)
+    for p, f in zip(pattern[1:], fact[1:]):
+        if is_var(p):
+            if theta.setdefault(p, f) != f:
+                return None
+        elif p != f:
+            return None
+    return theta
+
+
+class KnowledgeBase:
+    def __init__(self, rules=(), builtins: dict | None = None):
+        self.rules: list[Rule] = []
+        self.facts: set[Atom] = set()
+        # fact -> (rule, premises) for derived facts, None for given facts
+        self.provenance: dict[Atom, tuple | None] = {}
+        self.builtins = dict(BUILTINS if builtins is None else builtins)
+        for rule in rules:
+            self.add_rule(rule)
+
+    def add_rule(self, rule) -> None:
+        self.rules.append(parse_rule(rule) if isinstance(rule, str) else rule)
+
+    def add_fact(self, fact) -> None:
+        atom = parse_atom(fact) if isinstance(fact, str) else tuple(fact)
+        if any(is_var(t) for t in atom[1:]):
+            raise ValueError(f"facts must be ground: {format_atom(atom)}")
+        if atom not in self.facts:
+            self.facts.add(atom)
+            self.provenance[atom] = None
+
+    def _solve(self, body: tuple, theta: dict, support: tuple) -> Iterator[tuple]:
+        if not body:
+            yield theta, support
+            return
+        first, rest = body[0], body[1:]
+        pred = first[0]
+        if pred in self.builtins:
+            args = [theta.get(t) if is_var(t) else t for t in first[1:]]
+            candidates = [(pred, *result) for result in self.builtins[pred](*args)]
+        else:
+            candidates = [f for f in self.facts if f[0] == pred]
+        for fact in candidates:
+            new_theta = _unify(first, fact, theta)
+            if new_theta is not None:
+                yield from self._solve(rest, new_theta, support + (fact,))
+
+    def forward_chain(self) -> set[Atom]:
+        """Apply every rule until no new fact appears. Returns the new facts."""
+        derived: set[Atom] = set()
+        changed = True
+        while changed:
+            changed = False
+            for rule in self.rules:
+                for theta, support in list(self._solve(rule.body, {}, ())):
+                    head = (rule.head[0], *(theta.get(t, t) for t in rule.head[1:]))
+                    if any(is_var(t) for t in head[1:]):
+                        raise ValueError(f"unsafe rule, unbound head variable: {rule}")
+                    if head not in self.facts:
+                        self.facts.add(head)
+                        self.provenance[head] = (rule, support)
+                        derived.add(head)
+                        changed = True
+        return derived
+
+    def holds(self, query) -> bool:
+        atom = parse_atom(query) if isinstance(query, str) else tuple(query)
+        return atom in self.facts
+
+    def query(self, pattern) -> list[dict]:
+        """All variable bindings under which `pattern` matches a known fact."""
+        atom = parse_atom(pattern) if isinstance(pattern, str) else tuple(pattern)
+        matches = (_unify(atom, f, {}) for f in self.facts)
+        return [m for m in matches if m is not None]
+
+    def explain(self, fact, indent: int = 0) -> list[str]:
+        """Proof tree for a fact, as indented lines of text."""
+        atom = parse_atom(fact) if isinstance(fact, str) else tuple(fact)
+        pad = "  " * indent
+        if atom[0] in self.builtins:
+            return [f"{pad}{format_atom(atom)}   [arithmetic]"]
+        if atom not in self.facts:
+            return [f"{pad}{format_atom(atom)}   [not provable]"]
+        source = self.provenance[atom]
+        if source is None:
+            return [f"{pad}{format_atom(atom)}   [perceived]"]
+        rule, premises = source
+        lines = [f"{pad}{format_atom(atom)}   [by rule: {rule}]"]
+        for premise in premises:
+            lines += self.explain(premise, indent + 1)
+        return lines