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.
- {tiny_datalog-0.7.0/tiny_datalog.egg-info → tiny_datalog-0.8.0}/PKG-INFO +77 -34
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/README.md +75 -32
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/pyproject.toml +7 -2
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/__init__.py +5 -3
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/datalog.py +73 -37
- tiny_datalog-0.8.0/tiny_datalog/diagnose.py +446 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/engines.py +40 -9
- tiny_datalog-0.8.0/tiny_datalog/foil.py +352 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/incremental.py +2 -1
- tiny_datalog-0.8.0/tiny_datalog/lattice.py +206 -0
- tiny_datalog-0.8.0/tiny_datalog/mutation.py +252 -0
- tiny_datalog-0.8.0/tiny_datalog/sat.py +73 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/semantics.py +92 -10
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/slg.py +277 -135
- tiny_datalog-0.8.0/tiny_datalog/synthesis.py +309 -0
- tiny_datalog-0.8.0/tiny_datalog/tablespace.py +430 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/tabling.py +179 -75
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0/tiny_datalog.egg-info}/PKG-INFO +77 -34
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/SOURCES.txt +7 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/entry_points.txt +4 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/LICENSE +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/setup.cfg +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/chase.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/containment.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/core.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/defeasible.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/magic.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/prolog.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/semiring.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog/subsumption.py +0 -0
- {tiny_datalog-0.7.0 → tiny_datalog-0.8.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
- {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.
|
|
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 #
|
|
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 —
|
|
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
|
|
233
|
-
|
|
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
|
|
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.
|
|
309
|
-
|
|
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.**
|
|
322
|
-
|
|
323
|
-
|
|
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
|
|
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
|
|
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
|
|
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–
|
|
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
|
|
446
|
-
executed,
|
|
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`) |
|
|
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) |
|
|
476
|
-
| the
|
|
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
|
|
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
|
|
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
|
|
486
|
-
`engines.py` and the
|
|
487
|
-
`slg.py`, allowed
|
|
488
|
-
test asserts
|
|
489
|
-
claim about the repository, which is a
|
|
490
|
-
teaches a
|
|
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 #
|
|
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 —
|
|
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
|
|
200
|
-
|
|
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
|
|
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.
|
|
276
|
-
|
|
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.**
|
|
289
|
-
|
|
290
|
-
|
|
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
|
|
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
|
|
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
|
|
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–
|
|
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
|
|
413
|
-
executed,
|
|
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`) |
|
|
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) |
|
|
443
|
-
| the
|
|
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
|
|
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
|
|
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
|
|
453
|
-
`engines.py` and the
|
|
454
|
-
`slg.py`, allowed
|
|
455
|
-
test asserts
|
|
456
|
-
claim about the repository, which is a
|
|
457
|
-
teaches a
|
|
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
|
+
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", "
|
|
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),
|
|
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.
|
|
43
|
+
__version__ = "0.8.0"
|
|
42
44
|
|
|
43
45
|
__all__ = [
|
|
44
46
|
"Var", "Const", "Struct", "Atom", "Literal", "Rule",
|