tiny-datalog 0.6.0__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. {tiny_datalog-0.6.0/tiny_datalog.egg-info → tiny_datalog-0.8.0}/PKG-INFO +98 -39
  2. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/README.md +96 -37
  3. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/pyproject.toml +8 -2
  4. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/__init__.py +8 -4
  5. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/core.py +3 -2
  6. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/datalog.py +102 -52
  7. tiny_datalog-0.8.0/tiny_datalog/diagnose.py +446 -0
  8. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/engines.py +74 -15
  9. tiny_datalog-0.8.0/tiny_datalog/foil.py +352 -0
  10. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/incremental.py +2 -1
  11. tiny_datalog-0.8.0/tiny_datalog/lattice.py +206 -0
  12. tiny_datalog-0.8.0/tiny_datalog/mutation.py +252 -0
  13. tiny_datalog-0.8.0/tiny_datalog/sat.py +73 -0
  14. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/semantics.py +92 -10
  15. tiny_datalog-0.8.0/tiny_datalog/slg.py +695 -0
  16. tiny_datalog-0.8.0/tiny_datalog/synthesis.py +309 -0
  17. tiny_datalog-0.8.0/tiny_datalog/tablespace.py +430 -0
  18. tiny_datalog-0.8.0/tiny_datalog/tabling.py +451 -0
  19. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0/tiny_datalog.egg-info}/PKG-INFO +98 -39
  20. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/SOURCES.txt +8 -0
  21. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/entry_points.txt +5 -0
  22. tiny_datalog-0.6.0/tiny_datalog/tabling.py +0 -253
  23. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/LICENSE +0 -0
  24. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/setup.cfg +0 -0
  25. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/chase.py +0 -0
  26. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/containment.py +0 -0
  27. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/defeasible.py +0 -0
  28. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/magic.py +0 -0
  29. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/prolog.py +0 -0
  30. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/semiring.py +0 -0
  31. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog/subsumption.py +0 -0
  32. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
  33. {tiny_datalog-0.6.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: tiny-datalog
3
- Version: 0.6.0
3
+ Version: 0.8.0
4
4
  Summary: A Datalog engine whose core you can read in an afternoon, and a course built on it
5
5
  Author: Andrew Goodchild
6
6
  License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: Source, https://github.com/andrewgoodchild/tiny-datalog
9
9
  Project-URL: Issues, https://github.com/andrewgoodchild/tiny-datalog/issues
10
10
  Project-URL: Changelog, https://github.com/andrewgoodchild/tiny-datalog/releases
11
11
  Project-URL: Lessons, https://github.com/andrewgoodchild/tiny-datalog/tree/main/lessons
12
- Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,defeasible logic,teaching
12
+ Keywords: datalog,logic programming,deductive database,semi-naive evaluation,magic sets,provenance,stable models,defeasible logic,inductive logic programming,teaching
13
13
  Classifier: Development Status :: 3 - Alpha
14
14
  Classifier: Intended Audience :: Developers
15
15
  Classifier: Intended Audience :: Education
@@ -127,7 +127,7 @@ Nothing to install:
127
127
 
128
128
  ```sh
129
129
  git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
130
- python3 tests.py # 362 tests, ~20s
130
+ python3 tests.py # 487 tests, ~30s
131
131
  ```
132
132
 
133
133
  ## Why the language choice decides what you can ask later
@@ -186,7 +186,10 @@ catches circularity, `--models` catches contradiction and ambiguity,
186
186
  `containment.py` catches redundancy, integrity constraints catch a rule
187
187
  set that breaks the policy stated another way, warnings catch the typo
188
188
  that silently empties a relation, and `--explain` produces the
189
- derivation somebody has to sign off on.
189
+ derivation somebody has to sign off on. When an answer is wrong,
190
+ `diagnose.py` walks that derivation to the rule at fault, and
191
+ `mutation.py` measures whether the checks you wrote would notice a
192
+ broken rule at all.
190
193
 
191
194
  Two limits. An engine checks coherence, not intent: a rule set can pass
192
195
  every check above and still be the wrong policy. And the trade only
@@ -196,7 +199,7 @@ the better tool, and that covers most problems.
196
199
 
197
200
  ## What else you can ask it
198
201
 
199
- The worked example above is one row of a table. The full version — 32
202
+ The worked example above is one row of a table. The full version — 45
200
203
  questions, each with the command that answers it and the lesson that
201
204
  builds the machinery — is in
202
205
  [getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
@@ -229,20 +232,33 @@ is the whole relation the guards are pure overhead.
229
232
  [Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
230
233
 
231
234
  Correctness is checked by a seeded differential fuzzer that generates
232
- stratified programs and demands semi-naive, naive, magic-sets and
233
- tabled evaluation all agree, and that incremental maintenance matches
234
- recomputation under random updates. 400 programs per run;
235
+ stratified programs, aggregates and integrity constraints included,
236
+ and demands that all five engines agree, on the answers and on the
237
+ counterexamples, with every query of a program sent to one engine (so
238
+ the tabled engines answer later queries from their table space); that
239
+ SLG matches the well-founded model on unstratified
240
+ ones, with and without subsumptive tabling; and that incremental
241
+ maintenance, bottom-up and in the tabled engines' table spaces,
242
+ matches recomputation under random updates. 400 programs
243
+ per run;
235
244
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
236
245
 
237
246
  Answers are also checked against engines this repository did not write.
238
247
  [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
239
248
  runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
240
- corpus, harvested from Soufflé, Nemo and Crepe, through all four
249
+ corpus, harvested from Soufflé, Nemo and Crepe, through all five
241
250
  strategies, and its defeasible theories, from SPINdle and the papers,
242
251
  through `defeasible.py`: 195 cases pass. Every skip is named with its
243
252
  reason: arithmetic and 10⁵-fact joins, which this course omits on
244
253
  purpose, or cases written for a different logic.
245
254
 
255
+ And the tests themselves are checked: `benchmarks/mutate.py` makes
256
+ each one-line break a bug could make (a `<` for a `<=`, a dropped
257
+ `not`, a deleted statement) and runs the suite against each. At 0.7.0
258
+ the suite caught 91% of 3,322 such mutants. Most of the rest change
259
+ nothing a user could observe, such as a counter's starting value or a
260
+ default limit raised by one; the others are mainly CLI printing.
261
+
246
262
  ## Learning Datalog
247
263
 
248
264
  `lessons/` is a complete course, no prior exposure assumed, every
@@ -258,6 +274,13 @@ work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/
258
274
  [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
259
275
  [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
260
276
  and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
277
+ Three more run the course backwards:
278
+ [learning rules from examples](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/25-finding-rules.md) with
279
+ FOIL, the classic algorithm,
280
+ [learning them by rule selection](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/26-synthesis.md), after
281
+ recent research in which the engine's provenance steers a SAT solver,
282
+ and [validating rules](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/27-validating-rules.md), whoever or
283
+ whatever wrote them.
261
284
  And it is built to be
262
285
  inherited: `git clone`, no dependencies, no hosted anything, and every
263
286
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -296,8 +319,11 @@ regression test without writing Python.
296
319
 
297
320
  ## What this is not, and what is missing on purpose
298
321
 
299
- Not an engine to build a product on. Joins are nested-loop,
300
- stable-model search is exhaustive, evaluation is batch. For real
322
+ Not an engine to build a product on. The bottom-up engines join by
323
+ nested loop with no join planning, stable-model search grounds the
324
+ whole program and uses a forty-line SAT solver,
325
+ and evaluation starts from scratch, apart from `incremental.py` and
326
+ the tabled engines' incremental tabling. For real
301
327
  workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
302
328
  Python application, with arithmetic and queries over SQL databases,
303
329
  see [pyDatalog](https://pypi.org/project/pyDatalog/).
@@ -309,9 +335,13 @@ quietly:
309
335
  a relation infinite, and the termination theorem goes with it.
310
336
  [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
311
337
  story, including what to do instead.
312
- - **Indexes and join planning.** Every join is a nested loop so the
313
- algorithms stay one-screen readable. It is also why the magic-sets
314
- timing above goes the way it does.
338
+ - **Indexes and join planning.** The bottom-up engines join every
339
+ body by nested loop, left to right, so the algorithms stay
340
+ one-screen readable. It is also why the magic-sets timing above goes
341
+ the way it does. The only indexes are the ones `slg.py -s` builds
342
+ for the call patterns it serves, the one `--explain` uses to find
343
+ an earlier derivation, and the one `slg.py` keeps while it
344
+ simplifies.
315
345
  - **⊤ and role hierarchies** in the classifier — what ships is EL⊥
316
346
  (disjointness and unsatisfiability detection included). SNOMED needs
317
347
  ELH (EL plus role hierarchies) with right identities, which is what
@@ -320,7 +350,10 @@ quietly:
320
350
 
321
351
  Aggregation used to be on this list;
322
352
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
323
- into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
353
+ into a feature looks like, and
354
+ [lesson 15](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/15-tabling.md) goes a step further: the tabled
355
+ engines let `min` and `max` recurse, by answer subsumption, where
356
+ stratification refuses them. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
324
357
  `!=`) used to share arithmetic's entry. They check values and never
325
358
  make them, so they can only filter, and lesson 14's own argument lets
326
359
  them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
@@ -363,7 +396,8 @@ engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
363
396
  A rule with no head is an integrity constraint, a situation that must
364
397
  never arise. `engine.violations()` lists each broken one with its
365
398
  counterexamples, and the command line prints them and exits with
366
- status 3:
399
+ status 3, under every engine (`--engine tabling` asks each constraint
400
+ as one more query):
367
401
 
368
402
  ```python
369
403
  checked = run_program(rules + ":- exposed(S, C).", facts={
@@ -380,9 +414,9 @@ trusting, state properties as constraints); copy it into your agent's
380
414
  skills directory.
381
415
 
382
416
  The command-line interface installs too, as `tiny-datalog` (and
383
- `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
384
- `-containment`, `-defeasible`, `-prolog` for the other engines and the
385
- extensions):
417
+ `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
418
+ `-containment`, `-defeasible`, `-prolog`, `-chase`, `-foil`, `-synthesis`,
419
+ `-diagnose`, `-mutation` for the other engines and the extensions):
386
420
 
387
421
  ```sh
388
422
  tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -398,15 +432,27 @@ tiny_datalog/ the code you read, in three tiers:
398
432
  core.py the common core — the language every module shares:
399
433
  AST, parser, safety checks, comparisons, stratification,
400
434
  matching, formatting, query helpers, warnings
401
- engines — four strategies, one answer (engines.py lists them):
435
+ engines — five strategies, one answer (engines.py lists them):
402
436
  datalog.py the base engine: semi-naive and naive bottom-up
403
437
  evaluation, aggregation, integrity constraints,
404
438
  --explain / why-not, --assume, the CLI
405
439
  magic.py the magic-sets rewriting (a program-to-program pass)
406
- tabling.py tabled top-down evaluation (iterative QSQR)
407
- engines.py the registry and the interface the four share
440
+ tabling.py tabled top-down evaluation (iterative QSQR), and the
441
+ front end both tabled engines share
442
+ tablespace.py the table space both tabled engines keep through
443
+ updates: incremental tabling, eager or lazy, and
444
+ explanations read off the tables
445
+ lattice.py answer subsumption: recursion through min and max,
446
+ for both tabled engines
447
+ engines.py the registry and the interface the five share (the
448
+ fifth is SLG, from slg.py below, held to stratified
449
+ programs)
408
450
  extensions — other questions asked of the same programs:
409
- semantics.py grounding, stable models, the well-founded model
451
+ semantics.py grounding, stable models (a SAT solver proposes, the
452
+ definition checks), the well-founded model
453
+ sat.py the forty-line SAT solver that semantics.py and
454
+ synthesis.py share
455
+ slg.py SLG resolution: the well-founded model, top-down
410
456
  semiring.py semiring-valued evaluation (costs, counts, provenance,
411
457
  probabilities)
412
458
  incremental.py insertions + DRed deletions over a live materialisation
@@ -416,20 +462,31 @@ tiny_datalog/ the code you read, in three tiers:
416
462
  defeasible.py defeasible logic: exceptions, priorities, defeaters
417
463
  chase.py existential rules: the chase, labelled nulls, weak
418
464
  acyclicity
465
+ foil.py learning rules from examples: FOIL
466
+ synthesis.py learning rules by selection: a SAT solver, steered by
467
+ why and why-not provenance
468
+ diagnose.py algorithmic debugging: from a wrong or missing answer
469
+ to the rule at fault
470
+ mutation.py mutation testing for rules, with equivalent mutants
471
+ proved by containment
419
472
  *.py three-line launchers, so `python3 datalog.py ...` works
420
473
  straight from a checkout with nothing installed
421
474
  programs/ teaching programs, named for what they model; each
422
475
  lesson says which ones it runs
423
- lessons/ getting started, glossary, and lessons 0–24
476
+ lessons/ getting started, glossary, and lessons 0–27
424
477
  exercises/ worked answers, verified by the test suite
425
478
  cases/ golden test cases — add one without writing Python
426
479
  skills/ an Agent Skill that teaches coding agents to use the engine
427
480
  conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
428
481
  Crepe, SPINdle), run against every evaluation strategy
429
482
  benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
430
- ontology, and the N-queens puzzle)
431
- tests.py 362 tests: every shipped program and exercise answer is
432
- executed, a conformance suite runs every query through
483
+ ontology, and the N-queens puzzle), and mutate.py,
484
+ which breaks the code one line at a time to measure
485
+ how much of it the tests would notice (91% at 0.7.0)
486
+ tests.py 487 tests: every shipped program and exercise answer is
487
+ executed, every program is held to the expectations
488
+ file beside it (programs/*.expect, lesson 27) and
489
+ mutation-tested, a conformance suite runs every query through
433
490
  every engine that handles it, and a seeded fuzzer checks
434
491
  the same property on random programs
435
492
  ```
@@ -444,8 +501,8 @@ used.
444
501
  This project started as an attempt at a tiny implementation of
445
502
  Datalog, small enough to read in an afternoon. It grew with the
446
503
  course. Each lesson that taught a new technique — magic sets, stable models,
447
- semirings, incremental maintenance, tabling, subsumption, containment,
448
- defeasible logic, the chase — brought a module to run it, and the repository is
504
+ semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
505
+ defeasible logic, the chase, rule learning, rule debugging — brought a module to run it, and the repository is
449
506
  now several thousand lines. The core idea stayed small, and the code
450
507
  is laid out so you can still read just that: the common core and the
451
508
  base engine, below, are the original tiny Datalog. Everything else is
@@ -455,23 +512,25 @@ Measured in lines, comments, docstrings and blank lines included:
455
512
 
456
513
  | Tier | Lines |
457
514
  |---|---|
458
- | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,056 |
515
+ | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,057 |
459
516
  | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 423 |
460
- | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 621 |
461
- | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 578 |
462
- | the eight extensions | 2,860 |
517
+ | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 669 |
518
+ | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`, with `tablespace.py` and `lattice.py`, the incremental tabling, explanations and answer subsumption both tabled engines share), plus the `engines.py` registry (naive evaluation is a flag on the base engine; the fifth engine, SLG, is counted with the extensions) | 1,469 |
519
+ | the thirteen extensions, and the SAT solver two of them share (`sat.py`) | 5,052 |
463
520
 
464
521
  So the smallest complete Datalog system here — parse, check, stratify,
465
522
  evaluate semi-naively — is the core plus the evaluator, about 1,500
466
- lines. All of it is 5.5k lines of toolkit (every module but the
523
+ lines. All of it is 8.7k lines of toolkit (every module but the
467
524
  re-export list in `__init__.py`), roughly a quarter of it commentary,
468
- and 3.9k of tests.
525
+ and 6.2k of tests.
469
526
 
470
527
  "Tiny" is a claim about that core and evaluator, and about each module
471
- built on them singly: none of the eleven (`magic.py`, `tabling.py`,
472
- `engines.py` and the eight extensions) exceeds 500 lines, which a test asserts. It is not a
473
- claim about the repository, which is a dozen modules because it
474
- teaches a dozen things.
528
+ built on them singly: none of the nineteen (`magic.py`, `tabling.py`,
529
+ `tablespace.py`, `lattice.py`, `engines.py`, `sat.py` and the thirteen extensions)
530
+ exceeds 500 lines, except `slg.py`, allowed 700 because it is tabling
531
+ plus a scheduler. A test asserts the limits. It is not a
532
+ claim about the repository, which is a score of modules because it
533
+ teaches a score of things.
475
534
 
476
535
  There is no dead code to golf away (checked); shrinking further means
477
536
  deleting either a technique or an explanation.
@@ -94,7 +94,7 @@ Nothing to install:
94
94
 
95
95
  ```sh
96
96
  git clone https://github.com/andrewgoodchild/tiny-datalog && cd tiny-datalog
97
- python3 tests.py # 362 tests, ~20s
97
+ python3 tests.py # 487 tests, ~30s
98
98
  ```
99
99
 
100
100
  ## Why the language choice decides what you can ask later
@@ -153,7 +153,10 @@ catches circularity, `--models` catches contradiction and ambiguity,
153
153
  `containment.py` catches redundancy, integrity constraints catch a rule
154
154
  set that breaks the policy stated another way, warnings catch the typo
155
155
  that silently empties a relation, and `--explain` produces the
156
- derivation somebody has to sign off on.
156
+ derivation somebody has to sign off on. When an answer is wrong,
157
+ `diagnose.py` walks that derivation to the rule at fault, and
158
+ `mutation.py` measures whether the checks you wrote would notice a
159
+ broken rule at all.
157
160
 
158
161
  Two limits. An engine checks coherence, not intent: a rule set can pass
159
162
  every check above and still be the wrong policy. And the trade only
@@ -163,7 +166,7 @@ the better tool, and that covers most problems.
163
166
 
164
167
  ## What else you can ask it
165
168
 
166
- The worked example above is one row of a table. The full version — 32
169
+ The worked example above is one row of a table. The full version — 45
167
170
  questions, each with the command that answers it and the lesson that
168
171
  builds the machinery — is in
169
172
  [getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
@@ -196,20 +199,33 @@ is the whole relation the guards are pure overhead.
196
199
  [Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
197
200
 
198
201
  Correctness is checked by a seeded differential fuzzer that generates
199
- stratified programs and demands semi-naive, naive, magic-sets and
200
- tabled evaluation all agree, and that incremental maintenance matches
201
- recomputation under random updates. 400 programs per run;
202
+ stratified programs, aggregates and integrity constraints included,
203
+ and demands that all five engines agree, on the answers and on the
204
+ counterexamples, with every query of a program sent to one engine (so
205
+ the tabled engines answer later queries from their table space); that
206
+ SLG matches the well-founded model on unstratified
207
+ ones, with and without subsumptive tabling; and that incremental
208
+ maintenance, bottom-up and in the tabled engines' table spaces,
209
+ matches recomputation under random updates. 400 programs
210
+ per run;
202
211
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
203
212
 
204
213
  Answers are also checked against engines this repository did not write.
205
214
  [`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
206
215
  runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
207
- corpus, harvested from Soufflé, Nemo and Crepe, through all four
216
+ corpus, harvested from Soufflé, Nemo and Crepe, through all five
208
217
  strategies, and its defeasible theories, from SPINdle and the papers,
209
218
  through `defeasible.py`: 195 cases pass. Every skip is named with its
210
219
  reason: arithmetic and 10⁵-fact joins, which this course omits on
211
220
  purpose, or cases written for a different logic.
212
221
 
222
+ And the tests themselves are checked: `benchmarks/mutate.py` makes
223
+ each one-line break a bug could make (a `<` for a `<=`, a dropped
224
+ `not`, a deleted statement) and runs the suite against each. At 0.7.0
225
+ the suite caught 91% of 3,322 such mutants. Most of the rest change
226
+ nothing a user could observe, such as a counter's starting value or a
227
+ default limit raised by one; the others are mainly CLI printing.
228
+
213
229
  ## Learning Datalog
214
230
 
215
231
  `lessons/` is a complete course, no prior exposure assumed, every
@@ -225,6 +241,13 @@ work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/
225
241
  [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
226
242
  [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
227
243
  and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
244
+ Three more run the course backwards:
245
+ [learning rules from examples](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/25-finding-rules.md) with
246
+ FOIL, the classic algorithm,
247
+ [learning them by rule selection](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/26-synthesis.md), after
248
+ recent research in which the engine's provenance steers a SAT solver,
249
+ and [validating rules](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/27-validating-rules.md), whoever or
250
+ whatever wrote them.
228
251
  And it is built to be
229
252
  inherited: `git clone`, no dependencies, no hosted anything, and every
230
253
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -263,8 +286,11 @@ regression test without writing Python.
263
286
 
264
287
  ## What this is not, and what is missing on purpose
265
288
 
266
- Not an engine to build a product on. Joins are nested-loop,
267
- stable-model search is exhaustive, evaluation is batch. For real
289
+ Not an engine to build a product on. The bottom-up engines join by
290
+ nested loop with no join planning, stable-model search grounds the
291
+ whole program and uses a forty-line SAT solver,
292
+ and evaluation starts from scratch, apart from `incremental.py` and
293
+ the tabled engines' incremental tabling. For real
268
294
  workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
269
295
  Python application, with arithmetic and queries over SQL databases,
270
296
  see [pyDatalog](https://pypi.org/project/pyDatalog/).
@@ -276,9 +302,13 @@ quietly:
276
302
  a relation infinite, and the termination theorem goes with it.
277
303
  [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
278
304
  story, including what to do instead.
279
- - **Indexes and join planning.** Every join is a nested loop so the
280
- algorithms stay one-screen readable. It is also why the magic-sets
281
- timing above goes the way it does.
305
+ - **Indexes and join planning.** The bottom-up engines join every
306
+ body by nested loop, left to right, so the algorithms stay
307
+ one-screen readable. It is also why the magic-sets timing above goes
308
+ the way it does. The only indexes are the ones `slg.py -s` builds
309
+ for the call patterns it serves, the one `--explain` uses to find
310
+ an earlier derivation, and the one `slg.py` keeps while it
311
+ simplifies.
282
312
  - **⊤ and role hierarchies** in the classifier — what ships is EL⊥
283
313
  (disjointness and unsatisfiability detection included). SNOMED needs
284
314
  ELH (EL plus role hierarchies) with right identities, which is what
@@ -287,7 +317,10 @@ quietly:
287
317
 
288
318
  Aggregation used to be on this list;
289
319
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
290
- into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
320
+ into a feature looks like, and
321
+ [lesson 15](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/15-tabling.md) goes a step further: the tabled
322
+ engines let `min` and `max` recurse, by answer subsumption, where
323
+ stratification refuses them. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
291
324
  `!=`) used to share arithmetic's entry. They check values and never
292
325
  make them, so they can only filter, and lesson 14's own argument lets
293
326
  them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
@@ -330,7 +363,8 @@ engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
330
363
  A rule with no head is an integrity constraint, a situation that must
331
364
  never arise. `engine.violations()` lists each broken one with its
332
365
  counterexamples, and the command line prints them and exits with
333
- status 3:
366
+ status 3, under every engine (`--engine tabling` asks each constraint
367
+ as one more query):
334
368
 
335
369
  ```python
336
370
  checked = run_program(rules + ":- exposed(S, C).", facts={
@@ -347,9 +381,9 @@ trusting, state properties as constraints); copy it into your agent's
347
381
  skills directory.
348
382
 
349
383
  The command-line interface installs too, as `tiny-datalog` (and
350
- `tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
351
- `-containment`, `-defeasible`, `-prolog` for the other engines and the
352
- extensions):
384
+ `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
385
+ `-containment`, `-defeasible`, `-prolog`, `-chase`, `-foil`, `-synthesis`,
386
+ `-diagnose`, `-mutation` for the other engines and the extensions):
353
387
 
354
388
  ```sh
355
389
  tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -365,15 +399,27 @@ tiny_datalog/ the code you read, in three tiers:
365
399
  core.py the common core — the language every module shares:
366
400
  AST, parser, safety checks, comparisons, stratification,
367
401
  matching, formatting, query helpers, warnings
368
- engines — four strategies, one answer (engines.py lists them):
402
+ engines — five strategies, one answer (engines.py lists them):
369
403
  datalog.py the base engine: semi-naive and naive bottom-up
370
404
  evaluation, aggregation, integrity constraints,
371
405
  --explain / why-not, --assume, the CLI
372
406
  magic.py the magic-sets rewriting (a program-to-program pass)
373
- tabling.py tabled top-down evaluation (iterative QSQR)
374
- engines.py the registry and the interface the four share
407
+ tabling.py tabled top-down evaluation (iterative QSQR), and the
408
+ front end both tabled engines share
409
+ tablespace.py the table space both tabled engines keep through
410
+ updates: incremental tabling, eager or lazy, and
411
+ explanations read off the tables
412
+ lattice.py answer subsumption: recursion through min and max,
413
+ for both tabled engines
414
+ engines.py the registry and the interface the five share (the
415
+ fifth is SLG, from slg.py below, held to stratified
416
+ programs)
375
417
  extensions — other questions asked of the same programs:
376
- semantics.py grounding, stable models, the well-founded model
418
+ semantics.py grounding, stable models (a SAT solver proposes, the
419
+ definition checks), the well-founded model
420
+ sat.py the forty-line SAT solver that semantics.py and
421
+ synthesis.py share
422
+ slg.py SLG resolution: the well-founded model, top-down
377
423
  semiring.py semiring-valued evaluation (costs, counts, provenance,
378
424
  probabilities)
379
425
  incremental.py insertions + DRed deletions over a live materialisation
@@ -383,20 +429,31 @@ tiny_datalog/ the code you read, in three tiers:
383
429
  defeasible.py defeasible logic: exceptions, priorities, defeaters
384
430
  chase.py existential rules: the chase, labelled nulls, weak
385
431
  acyclicity
432
+ foil.py learning rules from examples: FOIL
433
+ synthesis.py learning rules by selection: a SAT solver, steered by
434
+ why and why-not provenance
435
+ diagnose.py algorithmic debugging: from a wrong or missing answer
436
+ to the rule at fault
437
+ mutation.py mutation testing for rules, with equivalent mutants
438
+ proved by containment
386
439
  *.py three-line launchers, so `python3 datalog.py ...` works
387
440
  straight from a checkout with nothing installed
388
441
  programs/ teaching programs, named for what they model; each
389
442
  lesson says which ones it runs
390
- lessons/ getting started, glossary, and lessons 0–24
443
+ lessons/ getting started, glossary, and lessons 0–27
391
444
  exercises/ worked answers, verified by the test suite
392
445
  cases/ golden test cases — add one without writing Python
393
446
  skills/ an Agent Skill that teaches coding agents to use the engine
394
447
  conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
395
448
  Crepe, SPINdle), run against every evaluation strategy
396
449
  benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
397
- ontology, and the N-queens puzzle)
398
- tests.py 362 tests: every shipped program and exercise answer is
399
- executed, a conformance suite runs every query through
450
+ ontology, and the N-queens puzzle), and mutate.py,
451
+ which breaks the code one line at a time to measure
452
+ how much of it the tests would notice (91% at 0.7.0)
453
+ tests.py 487 tests: every shipped program and exercise answer is
454
+ executed, every program is held to the expectations
455
+ file beside it (programs/*.expect, lesson 27) and
456
+ mutation-tested, a conformance suite runs every query through
400
457
  every engine that handles it, and a seeded fuzzer checks
401
458
  the same property on random programs
402
459
  ```
@@ -411,8 +468,8 @@ used.
411
468
  This project started as an attempt at a tiny implementation of
412
469
  Datalog, small enough to read in an afternoon. It grew with the
413
470
  course. Each lesson that taught a new technique — magic sets, stable models,
414
- semirings, incremental maintenance, tabling, subsumption, containment,
415
- defeasible logic, the chase — brought a module to run it, and the repository is
471
+ semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
472
+ defeasible logic, the chase, rule learning, rule debugging — brought a module to run it, and the repository is
416
473
  now several thousand lines. The core idea stayed small, and the code
417
474
  is laid out so you can still read just that: the common core and the
418
475
  base engine, below, are the original tiny Datalog. Everything else is
@@ -422,23 +479,25 @@ Measured in lines, comments, docstrings and blank lines included:
422
479
 
423
480
  | Tier | Lines |
424
481
  |---|---|
425
- | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,056 |
482
+ | the common core (`core.py`: the language, evaluating nothing; about 270 of these lines arrived with comparisons, constraints, value checks and the warnings) | 1,057 |
426
483
  | the base engine's evaluator (`datalog.py` up to its CLI section: the module docstring, the import list that re-exports the core, `Program`, `Engine`, aggregation folding, `run_program`) | 423 |
427
- | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 621 |
428
- | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`), plus the `engines.py` registry (naive evaluation is a flag on the base engine) | 578 |
429
- | the eight extensions | 2,860 |
484
+ | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 669 |
485
+ | the other pluggable engines: magic sets (`magic.py`) and tabling (`tabling.py`, with `tablespace.py` and `lattice.py`, the incremental tabling, explanations and answer subsumption both tabled engines share), plus the `engines.py` registry (naive evaluation is a flag on the base engine; the fifth engine, SLG, is counted with the extensions) | 1,469 |
486
+ | the thirteen extensions, and the SAT solver two of them share (`sat.py`) | 5,052 |
430
487
 
431
488
  So the smallest complete Datalog system here — parse, check, stratify,
432
489
  evaluate semi-naively — is the core plus the evaluator, about 1,500
433
- lines. All of it is 5.5k lines of toolkit (every module but the
490
+ lines. All of it is 8.7k lines of toolkit (every module but the
434
491
  re-export list in `__init__.py`), roughly a quarter of it commentary,
435
- and 3.9k of tests.
492
+ and 6.2k of tests.
436
493
 
437
494
  "Tiny" is a claim about that core and evaluator, and about each module
438
- built on them singly: none of the eleven (`magic.py`, `tabling.py`,
439
- `engines.py` and the eight extensions) exceeds 500 lines, which a test asserts. It is not a
440
- claim about the repository, which is a dozen modules because it
441
- teaches a dozen things.
495
+ built on them singly: none of the nineteen (`magic.py`, `tabling.py`,
496
+ `tablespace.py`, `lattice.py`, `engines.py`, `sat.py` and the thirteen extensions)
497
+ exceeds 500 lines, except `slg.py`, allowed 700 because it is tabling
498
+ plus a scheduler. A test asserts the limits. It is not a
499
+ claim about the repository, which is a score of modules because it
500
+ teaches a score of things.
442
501
 
443
502
  There is no dead code to golf away (checked); shrinking further means
444
503
  deleting either a technique or an explanation.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "tiny-datalog"
7
- version = "0.6.0"
7
+ version = "0.8.0"
8
8
  description = "A Datalog engine whose core you can read in an afternoon, and a course built on it"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -14,7 +14,8 @@ authors = [{name = "Andrew Goodchild"}]
14
14
  dependencies = []
15
15
  keywords = ["datalog", "logic programming", "deductive database",
16
16
  "semi-naive evaluation", "magic sets", "provenance",
17
- "stable models", "defeasible logic", "teaching"]
17
+ "stable models", "defeasible logic", "inductive logic programming",
18
+ "teaching"]
18
19
  # No "License ::" classifier: `license` above is an SPDX expression, and
19
20
  # setuptools refuses a build that declares the licence both ways.
20
21
  classifiers = [
@@ -48,11 +49,16 @@ tiny-datalog = "tiny_datalog.datalog:main"
48
49
  tiny-datalog-prolog = "tiny_datalog.prolog:main"
49
50
  tiny-datalog-semiring = "tiny_datalog.semiring:main"
50
51
  tiny-datalog-tabling = "tiny_datalog.tabling:main"
52
+ tiny-datalog-slg = "tiny_datalog.slg:main"
51
53
  tiny-datalog-incremental = "tiny_datalog.incremental:main"
52
54
  tiny-datalog-subsumption = "tiny_datalog.subsumption:main"
53
55
  tiny-datalog-containment = "tiny_datalog.containment:main"
54
56
  tiny-datalog-defeasible = "tiny_datalog.defeasible:main"
55
57
  tiny-datalog-chase = "tiny_datalog.chase:main"
58
+ tiny-datalog-foil = "tiny_datalog.foil:main"
59
+ tiny-datalog-synthesis = "tiny_datalog.synthesis:main"
60
+ tiny-datalog-diagnose = "tiny_datalog.diagnose:main"
61
+ tiny-datalog-mutation = "tiny_datalog.mutation:main"
56
62
 
57
63
  [tool.setuptools.packages.find]
58
64
  include = ["tiny_datalog*"]
@@ -9,15 +9,19 @@ are their public surface, re-exported here so that library use reads as
9
9
 
10
10
  `tiny_datalog.engines` lists the pluggable engines, which all give the
11
11
  same answers: semi-naive and naive (`datalog`), `magic` (goal-directed
12
- rewriting) and `tabling` (top-down with memoing).
12
+ rewriting), `tabling` (top-down with memoing) and `slg` (SLG
13
+ resolution, held to stratified programs).
13
14
 
14
15
  Everything else is an extension built on the core, asking a different
15
16
  question of a program: `semantics` (stable and well-founded models),
17
+ `slg` (the well-founded model top-down, by SLG resolution),
16
18
  `semiring` (provenance-weighted evaluation), `incremental` (maintenance
17
19
  under updates), `subsumption` (KL-ONE style classification),
18
20
  `containment` (query containment), `defeasible` (rules with exceptions
19
- and priorities), `chase` (existential rules and labelled nulls), and
20
- `prolog` (a Prolog reader for the same syntax).
21
+ and priorities), `chase` (existential rules and labelled nulls),
22
+ `prolog` (a Prolog reader for the same syntax), `foil` and `synthesis`
23
+ (learning rules from examples), and `diagnose` and `mutation` (finding
24
+ the rule at fault, and testing the tests).
21
25
  Import those by name: `from tiny_datalog import semiring`.
22
26
  """
23
27
 
@@ -36,7 +40,7 @@ from tiny_datalog.datalog import (
36
40
  format_atom, format_fact,
37
41
  )
38
42
 
39
- __version__ = "0.6.0"
43
+ __version__ = "0.8.0"
40
44
 
41
45
  __all__ = [
42
46
  "Var", "Const", "Struct", "Atom", "Literal", "Rule",
@@ -10,8 +10,9 @@ The package is built in three tiers:
10
10
  what a Datalog program *is*, and evaluates nothing.
11
11
  * the **engines**: interchangeable evaluation strategies that give the
12
12
  same answers to the same stratified program — semi-naive and naive
13
- bottom-up (datalog.py, the base engine), magic sets (magic.py) and
14
- tabling (tabling.py). engines.py names them and states their shared
13
+ bottom-up (datalog.py, the base engine), magic sets (magic.py),
14
+ tabling (tabling.py) and SLG resolution (slg.py, also an
15
+ extension). engines.py names them and states their shared
15
16
  interface.
16
17
  * the **extensions**: modules that ask a *different* question of a
17
18
  program, and so give different answers on purpose — stable and