tiny-datalog 0.7.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 (32) hide show
  1. {tiny_datalog-0.7.0/tiny_datalog.egg-info → tiny_datalog-0.8.0}/PKG-INFO +77 -34
  2. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/README.md +75 -32
  3. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/pyproject.toml +7 -2
  4. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/__init__.py +5 -3
  5. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/datalog.py +73 -37
  6. tiny_datalog-0.8.0/tiny_datalog/diagnose.py +446 -0
  7. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/engines.py +40 -9
  8. tiny_datalog-0.8.0/tiny_datalog/foil.py +352 -0
  9. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/incremental.py +2 -1
  10. tiny_datalog-0.8.0/tiny_datalog/lattice.py +206 -0
  11. tiny_datalog-0.8.0/tiny_datalog/mutation.py +252 -0
  12. tiny_datalog-0.8.0/tiny_datalog/sat.py +73 -0
  13. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/semantics.py +92 -10
  14. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/slg.py +277 -135
  15. tiny_datalog-0.8.0/tiny_datalog/synthesis.py +309 -0
  16. tiny_datalog-0.8.0/tiny_datalog/tablespace.py +430 -0
  17. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/tabling.py +179 -75
  18. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0/tiny_datalog.egg-info}/PKG-INFO +77 -34
  19. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/SOURCES.txt +7 -0
  20. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/entry_points.txt +4 -0
  21. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/LICENSE +0 -0
  22. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/setup.cfg +0 -0
  23. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/chase.py +0 -0
  24. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/containment.py +0 -0
  25. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/core.py +0 -0
  26. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/defeasible.py +0 -0
  27. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/magic.py +0 -0
  28. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/prolog.py +0 -0
  29. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/semiring.py +0 -0
  30. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/subsumption.py +0 -0
  31. {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
  32. {tiny_datalog-0.7.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.7.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 # 402 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,10 +232,14 @@ 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, aggregates included, and demands that all five
233
- engines agree; that SLG matches the well-founded model on unstratified
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
234
240
  ones, with and without subsumptive tabling; and that incremental
235
- maintenance matches recomputation under random updates. 400 programs
241
+ maintenance, bottom-up and in the tabled engines' table spaces,
242
+ matches recomputation under random updates. 400 programs
236
243
  per run;
237
244
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
238
245
 
@@ -267,6 +274,13 @@ work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/
267
274
  [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
268
275
  [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
269
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.
270
284
  And it is built to be
271
285
  inherited: `git clone`, no dependencies, no hosted anything, and every
272
286
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -305,8 +319,11 @@ regression test without writing Python.
305
319
 
306
320
  ## What this is not, and what is missing on purpose
307
321
 
308
- Not an engine to build a product on. Joins are nested-loop,
309
- 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
310
327
  workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
311
328
  Python application, with arithmetic and queries over SQL databases,
312
329
  see [pyDatalog](https://pypi.org/project/pyDatalog/).
@@ -318,9 +335,13 @@ quietly:
318
335
  a relation infinite, and the termination theorem goes with it.
319
336
  [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
320
337
  story, including what to do instead.
321
- - **Indexes and join planning.** Every join is a nested loop so the
322
- algorithms stay one-screen readable. It is also why the magic-sets
323
- 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.
324
345
  - **⊤ and role hierarchies** in the classifier — what ships is EL⊥
325
346
  (disjointness and unsatisfiability detection included). SNOMED needs
326
347
  ELH (EL plus role hierarchies) with right identities, which is what
@@ -329,7 +350,10 @@ quietly:
329
350
 
330
351
  Aggregation used to be on this list;
331
352
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
332
- 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 (`<`, `<=`, `>`, `>=`, `=`,
333
357
  `!=`) used to share arithmetic's entry. They check values and never
334
358
  make them, so they can only filter, and lesson 14's own argument lets
335
359
  them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
@@ -372,7 +396,8 @@ engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
372
396
  A rule with no head is an integrity constraint, a situation that must
373
397
  never arise. `engine.violations()` lists each broken one with its
374
398
  counterexamples, and the command line prints them and exits with
375
- status 3:
399
+ status 3, under every engine (`--engine tabling` asks each constraint
400
+ as one more query):
376
401
 
377
402
  ```python
378
403
  checked = run_program(rules + ":- exposed(S, C).", facts={
@@ -390,8 +415,8 @@ skills directory.
390
415
 
391
416
  The command-line interface installs too, as `tiny-datalog` (and
392
417
  `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
393
- `-containment`, `-defeasible`, `-prolog` for the other engines and the
394
- extensions):
418
+ `-containment`, `-defeasible`, `-prolog`, `-chase`, `-foil`, `-synthesis`,
419
+ `-diagnose`, `-mutation` for the other engines and the extensions):
395
420
 
396
421
  ```sh
397
422
  tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -412,12 +437,21 @@ tiny_datalog/ the code you read, in three tiers:
412
437
  evaluation, aggregation, integrity constraints,
413
438
  --explain / why-not, --assume, the CLI
414
439
  magic.py the magic-sets rewriting (a program-to-program pass)
415
- tabling.py tabled top-down evaluation (iterative QSQR)
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
416
447
  engines.py the registry and the interface the five share (the
417
448
  fifth is SLG, from slg.py below, held to stratified
418
449
  programs)
419
450
  extensions — other questions asked of the same programs:
420
- 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
421
455
  slg.py SLG resolution: the well-founded model, top-down
422
456
  semiring.py semiring-valued evaluation (costs, counts, provenance,
423
457
  probabilities)
@@ -428,11 +462,18 @@ tiny_datalog/ the code you read, in three tiers:
428
462
  defeasible.py defeasible logic: exceptions, priorities, defeaters
429
463
  chase.py existential rules: the chase, labelled nulls, weak
430
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
431
472
  *.py three-line launchers, so `python3 datalog.py ...` works
432
473
  straight from a checkout with nothing installed
433
474
  programs/ teaching programs, named for what they model; each
434
475
  lesson says which ones it runs
435
- lessons/ getting started, glossary, and lessons 0–24
476
+ lessons/ getting started, glossary, and lessons 0–27
436
477
  exercises/ worked answers, verified by the test suite
437
478
  cases/ golden test cases — add one without writing Python
438
479
  skills/ an Agent Skill that teaches coding agents to use the engine
@@ -442,8 +483,10 @@ benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
442
483
  ontology, and the N-queens puzzle), and mutate.py,
443
484
  which breaks the code one line at a time to measure
444
485
  how much of it the tests would notice (91% at 0.7.0)
445
- tests.py 402 tests: every shipped program and exercise answer is
446
- executed, a conformance suite runs every query through
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
447
490
  every engine that handles it, and a seeded fuzzer checks
448
491
  the same property on random programs
449
492
  ```
@@ -459,7 +502,7 @@ This project started as an attempt at a tiny implementation of
459
502
  Datalog, small enough to read in an afternoon. It grew with the
460
503
  course. Each lesson that taught a new technique — magic sets, stable models,
461
504
  semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
462
- defeasible logic, the chase — brought a module to run it, and the repository is
505
+ defeasible logic, the chase, rule learning, rule debugging — brought a module to run it, and the repository is
463
506
  now several thousand lines. The core idea stayed small, and the code
464
507
  is laid out so you can still read just that: the common core and the
465
508
  base engine, below, are the original tiny Datalog. Everything else is
@@ -471,23 +514,23 @@ Measured in lines, comments, docstrings and blank lines included:
471
514
  |---|---|
472
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 |
473
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 |
474
- | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 635 |
475
- | 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; the fifth engine, SLG, is counted with the extensions) | 700 |
476
- | the nine extensions | 3,413 |
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 |
477
520
 
478
521
  So the smallest complete Datalog system here — parse, check, stratify,
479
522
  evaluate semi-naively — is the core plus the evaluator, about 1,500
480
- lines. All of it is 6.2k lines of toolkit (every module but the
523
+ lines. All of it is 8.7k lines of toolkit (every module but the
481
524
  re-export list in `__init__.py`), roughly a quarter of it commentary,
482
- and 4.4k of tests.
525
+ and 6.2k of tests.
483
526
 
484
527
  "Tiny" is a claim about that core and evaluator, and about each module
485
- built on them singly: none of the twelve (`magic.py`, `tabling.py`,
486
- `engines.py` and the nine extensions) exceeds 500 lines, except
487
- `slg.py`, allowed 600 because it is tabling plus a scheduler, and a
488
- test asserts both limits. It is not a
489
- claim about the repository, which is a dozen modules because it
490
- 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.
491
534
 
492
535
  There is no dead code to golf away (checked); shrinking further means
493
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 # 402 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,10 +199,14 @@ 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, aggregates included, and demands that all five
200
- engines agree; that SLG matches the well-founded model on unstratified
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
201
207
  ones, with and without subsumptive tabling; and that incremental
202
- maintenance matches recomputation under random updates. 400 programs
208
+ maintenance, bottom-up and in the tabled engines' table spaces,
209
+ matches recomputation under random updates. 400 programs
203
210
  per run;
204
211
  `TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
205
212
 
@@ -234,6 +241,13 @@ work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/
234
241
  [knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
235
242
  [time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
236
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.
237
251
  And it is built to be
238
252
  inherited: `git clone`, no dependencies, no hosted anything, and every
239
253
  quoted transcript re-verified by CI — the exercises cannot rot. (For where each
@@ -272,8 +286,11 @@ regression test without writing Python.
272
286
 
273
287
  ## What this is not, and what is missing on purpose
274
288
 
275
- Not an engine to build a product on. Joins are nested-loop,
276
- 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
277
294
  workloads see Soufflé, clingo, RDFox or Feldera; for Datalog inside a
278
295
  Python application, with arithmetic and queries over SQL databases,
279
296
  see [pyDatalog](https://pypi.org/project/pyDatalog/).
@@ -285,9 +302,13 @@ quietly:
285
302
  a relation infinite, and the termination theorem goes with it.
286
303
  [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
287
304
  story, including what to do instead.
288
- - **Indexes and join planning.** Every join is a nested loop so the
289
- algorithms stay one-screen readable. It is also why the magic-sets
290
- 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.
291
312
  - **⊤ and role hierarchies** in the classifier — what ships is EL⊥
292
313
  (disjointness and unsatisfiability detection included). SNOMED needs
293
314
  ELH (EL plus role hierarchies) with right identities, which is what
@@ -296,7 +317,10 @@ quietly:
296
317
 
297
318
  Aggregation used to be on this list;
298
319
  [lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
299
- 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 (`<`, `<=`, `>`, `>=`, `=`,
300
324
  `!=`) used to share arithmetic's entry. They check values and never
301
325
  make them, so they can only filter, and lesson 14's own argument lets
302
326
  them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
@@ -339,7 +363,8 @@ engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
339
363
  A rule with no head is an integrity constraint, a situation that must
340
364
  never arise. `engine.violations()` lists each broken one with its
341
365
  counterexamples, and the command line prints them and exits with
342
- status 3:
366
+ status 3, under every engine (`--engine tabling` asks each constraint
367
+ as one more query):
343
368
 
344
369
  ```python
345
370
  checked = run_program(rules + ":- exposed(S, C).", facts={
@@ -357,8 +382,8 @@ skills directory.
357
382
 
358
383
  The command-line interface installs too, as `tiny-datalog` (and
359
384
  `tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
360
- `-containment`, `-defeasible`, `-prolog` for the other engines and the
361
- extensions):
385
+ `-containment`, `-defeasible`, `-prolog`, `-chase`, `-foil`, `-synthesis`,
386
+ `-diagnose`, `-mutation` for the other engines and the extensions):
362
387
 
363
388
  ```sh
364
389
  tiny-datalog -q 'exposed(S, C)' supply-chain.dl
@@ -379,12 +404,21 @@ tiny_datalog/ the code you read, in three tiers:
379
404
  evaluation, aggregation, integrity constraints,
380
405
  --explain / why-not, --assume, the CLI
381
406
  magic.py the magic-sets rewriting (a program-to-program pass)
382
- tabling.py tabled top-down evaluation (iterative QSQR)
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
383
414
  engines.py the registry and the interface the five share (the
384
415
  fifth is SLG, from slg.py below, held to stratified
385
416
  programs)
386
417
  extensions — other questions asked of the same programs:
387
- 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
388
422
  slg.py SLG resolution: the well-founded model, top-down
389
423
  semiring.py semiring-valued evaluation (costs, counts, provenance,
390
424
  probabilities)
@@ -395,11 +429,18 @@ tiny_datalog/ the code you read, in three tiers:
395
429
  defeasible.py defeasible logic: exceptions, priorities, defeaters
396
430
  chase.py existential rules: the chase, labelled nulls, weak
397
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
398
439
  *.py three-line launchers, so `python3 datalog.py ...` works
399
440
  straight from a checkout with nothing installed
400
441
  programs/ teaching programs, named for what they model; each
401
442
  lesson says which ones it runs
402
- lessons/ getting started, glossary, and lessons 0–24
443
+ lessons/ getting started, glossary, and lessons 0–27
403
444
  exercises/ worked answers, verified by the test suite
404
445
  cases/ golden test cases — add one without writing Python
405
446
  skills/ an Agent Skill that teaches coding agents to use the engine
@@ -409,8 +450,10 @@ benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
409
450
  ontology, and the N-queens puzzle), and mutate.py,
410
451
  which breaks the code one line at a time to measure
411
452
  how much of it the tests would notice (91% at 0.7.0)
412
- tests.py 402 tests: every shipped program and exercise answer is
413
- executed, a conformance suite runs every query through
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
414
457
  every engine that handles it, and a seeded fuzzer checks
415
458
  the same property on random programs
416
459
  ```
@@ -426,7 +469,7 @@ This project started as an attempt at a tiny implementation of
426
469
  Datalog, small enough to read in an afternoon. It grew with the
427
470
  course. Each lesson that taught a new technique — magic sets, stable models,
428
471
  semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
429
- defeasible logic, the chase — brought a module to run it, and the repository is
472
+ defeasible logic, the chase, rule learning, rule debugging — brought a module to run it, and the repository is
430
473
  now several thousand lines. The core idea stayed small, and the code
431
474
  is laid out so you can still read just that: the common core and the
432
475
  base engine, below, are the original tiny Datalog. Everything else is
@@ -438,23 +481,23 @@ Measured in lines, comments, docstrings and blank lines included:
438
481
  |---|---|
439
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 |
440
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 |
441
- | `--explain`, why-not, constraint reports, `--assume`, printing and the CLI (the rest of `datalog.py`) | 635 |
442
- | 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; the fifth engine, SLG, is counted with the extensions) | 700 |
443
- | the nine extensions | 3,413 |
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 |
444
487
 
445
488
  So the smallest complete Datalog system here — parse, check, stratify,
446
489
  evaluate semi-naively — is the core plus the evaluator, about 1,500
447
- lines. All of it is 6.2k lines of toolkit (every module but the
490
+ lines. All of it is 8.7k lines of toolkit (every module but the
448
491
  re-export list in `__init__.py`), roughly a quarter of it commentary,
449
- and 4.4k of tests.
492
+ and 6.2k of tests.
450
493
 
451
494
  "Tiny" is a claim about that core and evaluator, and about each module
452
- built on them singly: none of the twelve (`magic.py`, `tabling.py`,
453
- `engines.py` and the nine extensions) exceeds 500 lines, except
454
- `slg.py`, allowed 600 because it is tabling plus a scheduler, and a
455
- test asserts both limits. It is not a
456
- claim about the repository, which is a dozen modules because it
457
- 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.
458
501
 
459
502
  There is no dead code to golf away (checked); shrinking further means
460
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.7.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 = [
@@ -54,6 +55,10 @@ tiny-datalog-subsumption = "tiny_datalog.subsumption:main"
54
55
  tiny-datalog-containment = "tiny_datalog.containment:main"
55
56
  tiny-datalog-defeasible = "tiny_datalog.defeasible:main"
56
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"
57
62
 
58
63
  [tool.setuptools.packages.find]
59
64
  include = ["tiny_datalog*"]
@@ -18,8 +18,10 @@ question of a program: `semantics` (stable and well-founded models),
18
18
  `semiring` (provenance-weighted evaluation), `incremental` (maintenance
19
19
  under updates), `subsumption` (KL-ONE style classification),
20
20
  `containment` (query containment), `defeasible` (rules with exceptions
21
- and priorities), `chase` (existential rules and labelled nulls), and
22
- `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).
23
25
  Import those by name: `from tiny_datalog import semiring`.
24
26
  """
25
27
 
@@ -38,7 +40,7 @@ from tiny_datalog.datalog import (
38
40
  format_atom, format_fact,
39
41
  )
40
42
 
41
- __version__ = "0.7.0"
43
+ __version__ = "0.8.0"
42
44
 
43
45
  __all__ = [
44
46
  "Var", "Const", "Struct", "Atom", "Literal", "Rule",