tiny-datalog 0.5.0__tar.gz → 0.7.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.5.0/tiny_datalog.egg-info → tiny_datalog-0.7.0}/PKG-INFO +80 -37
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/README.md +79 -36
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/pyproject.toml +2 -1
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/__init__.py +4 -2
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/chase.py +5 -1
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/containment.py +11 -1
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/core.py +291 -20
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/datalog.py +163 -38
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/engines.py +40 -7
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/incremental.py +18 -7
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/magic.py +19 -1
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/prolog.py +4 -1
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/semantics.py +6 -3
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/semiring.py +10 -3
- tiny_datalog-0.7.0/tiny_datalog/slg.py +553 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/tabling.py +144 -45
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0/tiny_datalog.egg-info}/PKG-INFO +80 -37
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/SOURCES.txt +1 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/entry_points.txt +1 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/LICENSE +0 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/setup.cfg +0 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/defeasible.py +0 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog/subsumption.py +0 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.0}/tiny_datalog.egg-info/dependency_links.txt +0 -0
- {tiny_datalog-0.5.0 → tiny_datalog-0.7.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.7.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
|
|
@@ -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 # 402 tests, ~20s
|
|
131
131
|
```
|
|
132
132
|
|
|
133
133
|
## Why the language choice decides what you can ask later
|
|
@@ -183,7 +183,9 @@ it:
|
|
|
183
183
|
|
|
184
184
|
Every feature in this repository is a check of that kind: stratification
|
|
185
185
|
catches circularity, `--models` catches contradiction and ambiguity,
|
|
186
|
-
`containment.py` catches redundancy,
|
|
186
|
+
`containment.py` catches redundancy, integrity constraints catch a rule
|
|
187
|
+
set that breaks the policy stated another way, warnings catch the typo
|
|
188
|
+
that silently empties a relation, and `--explain` produces the
|
|
187
189
|
derivation somebody has to sign off on.
|
|
188
190
|
|
|
189
191
|
Two limits. An engine checks coherence, not intent: a rule set can pass
|
|
@@ -194,7 +196,7 @@ the better tool, and that covers most problems.
|
|
|
194
196
|
|
|
195
197
|
## What else you can ask it
|
|
196
198
|
|
|
197
|
-
The worked example above is one row of a table. The full version —
|
|
199
|
+
The worked example above is one row of a table. The full version — 32
|
|
198
200
|
questions, each with the command that answers it and the lesson that
|
|
199
201
|
builds the machinery — is in
|
|
200
202
|
[getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
|
|
@@ -227,20 +229,29 @@ is the whole relation the guards are pure overhead.
|
|
|
227
229
|
[Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
|
|
228
230
|
|
|
229
231
|
Correctness is checked by a seeded differential fuzzer that generates
|
|
230
|
-
stratified programs and demands
|
|
231
|
-
|
|
232
|
-
|
|
232
|
+
stratified programs, aggregates included, and demands that all five
|
|
233
|
+
engines agree; that SLG matches the well-founded model on unstratified
|
|
234
|
+
ones, with and without subsumptive tabling; and that incremental
|
|
235
|
+
maintenance matches recomputation under random updates. 400 programs
|
|
236
|
+
per run;
|
|
233
237
|
`TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
|
|
234
238
|
|
|
235
239
|
Answers are also checked against engines this repository did not write.
|
|
236
240
|
[`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
|
|
237
241
|
runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
|
|
238
|
-
corpus, harvested from Soufflé, Nemo and Crepe, through all
|
|
242
|
+
corpus, harvested from Soufflé, Nemo and Crepe, through all five
|
|
239
243
|
strategies, and its defeasible theories, from SPINdle and the papers,
|
|
240
244
|
through `defeasible.py`: 195 cases pass. Every skip is named with its
|
|
241
245
|
reason: arithmetic and 10⁵-fact joins, which this course omits on
|
|
242
246
|
purpose, or cases written for a different logic.
|
|
243
247
|
|
|
248
|
+
And the tests themselves are checked: `benchmarks/mutate.py` makes
|
|
249
|
+
each one-line break a bug could make (a `<` for a `<=`, a dropped
|
|
250
|
+
`not`, a deleted statement) and runs the suite against each. At 0.7.0
|
|
251
|
+
the suite caught 91% of 3,322 such mutants. Most of the rest change
|
|
252
|
+
nothing a user could observe, such as a counter's starting value or a
|
|
253
|
+
default limit raised by one; the others are mainly CLI printing.
|
|
254
|
+
|
|
244
255
|
## Learning Datalog
|
|
245
256
|
|
|
246
257
|
`lessons/` is a complete course, no prior exposure assumed, every
|
|
@@ -250,10 +261,12 @@ observe that the literature advises people building Datalog engines
|
|
|
250
261
|
better than people trying to *use* one; this course does both halves
|
|
251
262
|
on purpose — sixteen lessons where the engine is the explanation, then
|
|
252
263
|
a lesson on authoring rules that survive review, one on a logic
|
|
253
|
-
built for rules with exceptions, and
|
|
264
|
+
built for rules with exceptions, and five where the engine goes to
|
|
254
265
|
work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/20-authorization.md),
|
|
255
266
|
[program analysis](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/21-program-analysis.md),
|
|
256
|
-
|
|
267
|
+
[knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
|
|
268
|
+
[time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
|
|
269
|
+
and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
|
|
257
270
|
And it is built to be
|
|
258
271
|
inherited: `git clone`, no dependencies, no hosted anything, and every
|
|
259
272
|
quoted transcript re-verified by CI — the exercises cannot rot. (For where each
|
|
@@ -301,10 +314,9 @@ see [pyDatalog](https://pypi.org/project/pyDatalog/).
|
|
|
301
314
|
Deliberate omissions, because saying why teaches more than lacking them
|
|
302
315
|
quietly:
|
|
303
316
|
|
|
304
|
-
- **Arithmetic
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
become trees. [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
|
|
317
|
+
- **Arithmetic.** `Z = X + 1` makes values nobody stated, so it can make
|
|
318
|
+
a relation infinite, and the termination theorem goes with it.
|
|
319
|
+
[Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
|
|
308
320
|
story, including what to do instead.
|
|
309
321
|
- **Indexes and join planning.** Every join is a nested loop so the
|
|
310
322
|
algorithms stay one-screen readable. It is also why the magic-sets
|
|
@@ -317,7 +329,10 @@ quietly:
|
|
|
317
329
|
|
|
318
330
|
Aggregation used to be on this list;
|
|
319
331
|
[lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
|
|
320
|
-
into a feature looks like.
|
|
332
|
+
into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
|
|
333
|
+
`!=`) used to share arithmetic's entry. They check values and never
|
|
334
|
+
make them, so they can only filter, and lesson 14's own argument lets
|
|
335
|
+
them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
|
|
321
336
|
|
|
322
337
|
## Using it in your own project
|
|
323
338
|
|
|
@@ -354,8 +369,27 @@ engine = run_program(rules, facts={
|
|
|
354
369
|
engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
|
|
355
370
|
```
|
|
356
371
|
|
|
372
|
+
A rule with no head is an integrity constraint, a situation that must
|
|
373
|
+
never arise. `engine.violations()` lists each broken one with its
|
|
374
|
+
counterexamples, and the command line prints them and exits with
|
|
375
|
+
status 3:
|
|
376
|
+
|
|
377
|
+
```python
|
|
378
|
+
checked = run_program(rules + ":- exposed(S, C).", facts={
|
|
379
|
+
"depends": [("app", "lib"), ("lib", "core")],
|
|
380
|
+
"service": ["app"],
|
|
381
|
+
"vulnerable": [("core", "cve_2026_0001")],
|
|
382
|
+
})
|
|
383
|
+
checked.violations() # [(constraint, [{'S': 'app', 'C': 'cve_2026_0001'}])]
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
For agents, `skills/tiny-datalog/SKILL.md` is an Agent Skill that
|
|
387
|
+
teaches a coding agent the language and the habits (explain before
|
|
388
|
+
trusting, state properties as constraints); copy it into your agent's
|
|
389
|
+
skills directory.
|
|
390
|
+
|
|
357
391
|
The command-line interface installs too, as `tiny-datalog` (and
|
|
358
|
-
`tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
|
|
392
|
+
`tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
|
|
359
393
|
`-containment`, `-defeasible`, `-prolog` for the other engines and the
|
|
360
394
|
extensions):
|
|
361
395
|
|
|
@@ -371,16 +405,20 @@ installed package; clone the repository for that.
|
|
|
371
405
|
```
|
|
372
406
|
tiny_datalog/ the code you read, in three tiers:
|
|
373
407
|
core.py the common core — the language every module shares:
|
|
374
|
-
AST, parser, safety checks,
|
|
375
|
-
formatting, query helpers
|
|
376
|
-
engines —
|
|
408
|
+
AST, parser, safety checks, comparisons, stratification,
|
|
409
|
+
matching, formatting, query helpers, warnings
|
|
410
|
+
engines — five strategies, one answer (engines.py lists them):
|
|
377
411
|
datalog.py the base engine: semi-naive and naive bottom-up
|
|
378
|
-
evaluation, aggregation,
|
|
412
|
+
evaluation, aggregation, integrity constraints,
|
|
413
|
+
--explain / why-not, --assume, the CLI
|
|
379
414
|
magic.py the magic-sets rewriting (a program-to-program pass)
|
|
380
415
|
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
381
|
-
engines.py the registry and the interface the
|
|
416
|
+
engines.py the registry and the interface the five share (the
|
|
417
|
+
fifth is SLG, from slg.py below, held to stratified
|
|
418
|
+
programs)
|
|
382
419
|
extensions — other questions asked of the same programs:
|
|
383
420
|
semantics.py grounding, stable models, the well-founded model
|
|
421
|
+
slg.py SLG resolution: the well-founded model, top-down
|
|
384
422
|
semiring.py semiring-valued evaluation (costs, counts, provenance,
|
|
385
423
|
probabilities)
|
|
386
424
|
incremental.py insertions + DRed deletions over a live materialisation
|
|
@@ -392,16 +430,19 @@ tiny_datalog/ the code you read, in three tiers:
|
|
|
392
430
|
acyclicity
|
|
393
431
|
*.py three-line launchers, so `python3 datalog.py ...` works
|
|
394
432
|
straight from a checkout with nothing installed
|
|
395
|
-
programs/ teaching programs,
|
|
396
|
-
|
|
397
|
-
lessons/ getting started, glossary, and lessons 0–
|
|
433
|
+
programs/ teaching programs, named for what they model; each
|
|
434
|
+
lesson says which ones it runs
|
|
435
|
+
lessons/ getting started, glossary, and lessons 0–24
|
|
398
436
|
exercises/ worked answers, verified by the test suite
|
|
399
437
|
cases/ golden test cases — add one without writing Python
|
|
438
|
+
skills/ an Agent Skill that teaches coding agents to use the engine
|
|
400
439
|
conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
|
|
401
440
|
Crepe, SPINdle), run against every evaluation strategy
|
|
402
441
|
benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
|
|
403
|
-
ontology, and the N-queens puzzle)
|
|
404
|
-
|
|
442
|
+
ontology, and the N-queens puzzle), and mutate.py,
|
|
443
|
+
which breaks the code one line at a time to measure
|
|
444
|
+
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
|
|
405
446
|
executed, a conformance suite runs every query through
|
|
406
447
|
every engine that handles it, and a seeded fuzzer checks
|
|
407
448
|
the same property on random programs
|
|
@@ -417,7 +458,7 @@ used.
|
|
|
417
458
|
This project started as an attempt at a tiny implementation of
|
|
418
459
|
Datalog, small enough to read in an afternoon. It grew with the
|
|
419
460
|
course. Each lesson that taught a new technique — magic sets, stable models,
|
|
420
|
-
semirings, incremental maintenance, tabling, subsumption, containment,
|
|
461
|
+
semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
|
|
421
462
|
defeasible logic, the chase — brought a module to run it, and the repository is
|
|
422
463
|
now several thousand lines. The core idea stayed small, and the code
|
|
423
464
|
is laid out so you can still read just that: the common core and the
|
|
@@ -428,21 +469,23 @@ Measured in lines, comments, docstrings and blank lines included:
|
|
|
428
469
|
|
|
429
470
|
| Tier | Lines |
|
|
430
471
|
|---|---|
|
|
431
|
-
| the common core (`core.py`: the language, evaluating nothing) |
|
|
432
|
-
| 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`) |
|
|
433
|
-
| `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) |
|
|
434
|
-
| 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) |
|
|
435
|
-
| the
|
|
472
|
+
| 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
|
+
| 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 |
|
|
436
477
|
|
|
437
478
|
So the smallest complete Datalog system here — parse, check, stratify,
|
|
438
|
-
evaluate semi-naively — is the core plus the evaluator, about 1,
|
|
439
|
-
lines. All of it is
|
|
479
|
+
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
|
|
440
481
|
re-export list in `__init__.py`), roughly a quarter of it commentary,
|
|
441
|
-
and
|
|
482
|
+
and 4.4k of tests.
|
|
442
483
|
|
|
443
484
|
"Tiny" is a claim about that core and evaluator, and about each module
|
|
444
|
-
built on them singly: none of the
|
|
445
|
-
`engines.py` and the
|
|
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
|
|
446
489
|
claim about the repository, which is a dozen modules because it
|
|
447
490
|
teaches a dozen things.
|
|
448
491
|
|
|
@@ -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 # 402 tests, ~20s
|
|
98
98
|
```
|
|
99
99
|
|
|
100
100
|
## Why the language choice decides what you can ask later
|
|
@@ -150,7 +150,9 @@ it:
|
|
|
150
150
|
|
|
151
151
|
Every feature in this repository is a check of that kind: stratification
|
|
152
152
|
catches circularity, `--models` catches contradiction and ambiguity,
|
|
153
|
-
`containment.py` catches redundancy,
|
|
153
|
+
`containment.py` catches redundancy, integrity constraints catch a rule
|
|
154
|
+
set that breaks the policy stated another way, warnings catch the typo
|
|
155
|
+
that silently empties a relation, and `--explain` produces the
|
|
154
156
|
derivation somebody has to sign off on.
|
|
155
157
|
|
|
156
158
|
Two limits. An engine checks coherence, not intent: a rule set can pass
|
|
@@ -161,7 +163,7 @@ the better tool, and that covers most problems.
|
|
|
161
163
|
|
|
162
164
|
## What else you can ask it
|
|
163
165
|
|
|
164
|
-
The worked example above is one row of a table. The full version —
|
|
166
|
+
The worked example above is one row of a table. The full version — 32
|
|
165
167
|
questions, each with the command that answers it and the lesson that
|
|
166
168
|
builds the machinery — is in
|
|
167
169
|
[getting started](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/getting-started.md), beside the reading
|
|
@@ -194,20 +196,29 @@ is the whole relation the guards are pure overhead.
|
|
|
194
196
|
[Lesson 7](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/07-magic-sets.md) works through why.
|
|
195
197
|
|
|
196
198
|
Correctness is checked by a seeded differential fuzzer that generates
|
|
197
|
-
stratified programs and demands
|
|
198
|
-
|
|
199
|
-
|
|
199
|
+
stratified programs, aggregates included, and demands that all five
|
|
200
|
+
engines agree; that SLG matches the well-founded model on unstratified
|
|
201
|
+
ones, with and without subsumptive tabling; and that incremental
|
|
202
|
+
maintenance matches recomputation under random updates. 400 programs
|
|
203
|
+
per run;
|
|
200
204
|
`TINY_DATALOG_FUZZ=3000 python3 tests.py DifferentialFuzzTests` soaks.
|
|
201
205
|
|
|
202
206
|
Answers are also checked against engines this repository did not write.
|
|
203
207
|
[`conformance/`](https://github.com/andrewgoodchild/tiny-datalog/tree/main/conformance)
|
|
204
208
|
runs the [datalog-conformance](https://pypi.org/project/datalog-conformance/)
|
|
205
|
-
corpus, harvested from Soufflé, Nemo and Crepe, through all
|
|
209
|
+
corpus, harvested from Soufflé, Nemo and Crepe, through all five
|
|
206
210
|
strategies, and its defeasible theories, from SPINdle and the papers,
|
|
207
211
|
through `defeasible.py`: 195 cases pass. Every skip is named with its
|
|
208
212
|
reason: arithmetic and 10⁵-fact joins, which this course omits on
|
|
209
213
|
purpose, or cases written for a different logic.
|
|
210
214
|
|
|
215
|
+
And the tests themselves are checked: `benchmarks/mutate.py` makes
|
|
216
|
+
each one-line break a bug could make (a `<` for a `<=`, a dropped
|
|
217
|
+
`not`, a deleted statement) and runs the suite against each. At 0.7.0
|
|
218
|
+
the suite caught 91% of 3,322 such mutants. Most of the rest change
|
|
219
|
+
nothing a user could observe, such as a counter's starting value or a
|
|
220
|
+
default limit raised by one; the others are mainly CLI printing.
|
|
221
|
+
|
|
211
222
|
## Learning Datalog
|
|
212
223
|
|
|
213
224
|
`lessons/` is a complete course, no prior exposure assumed, every
|
|
@@ -217,10 +228,12 @@ observe that the literature advises people building Datalog engines
|
|
|
217
228
|
better than people trying to *use* one; this course does both halves
|
|
218
229
|
on purpose — sixteen lessons where the engine is the explanation, then
|
|
219
230
|
a lesson on authoring rules that survive review, one on a logic
|
|
220
|
-
built for rules with exceptions, and
|
|
231
|
+
built for rules with exceptions, and five where the engine goes to
|
|
221
232
|
work: [authorization](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/20-authorization.md),
|
|
222
233
|
[program analysis](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/21-program-analysis.md),
|
|
223
|
-
|
|
234
|
+
[knowledge graphs and the chase](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/22-knowledge-graphs.md),
|
|
235
|
+
[time and history](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md),
|
|
236
|
+
and [memory for a language-model agent](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/24-memory.md).
|
|
224
237
|
And it is built to be
|
|
225
238
|
inherited: `git clone`, no dependencies, no hosted anything, and every
|
|
226
239
|
quoted transcript re-verified by CI — the exercises cannot rot. (For where each
|
|
@@ -268,10 +281,9 @@ see [pyDatalog](https://pypi.org/project/pyDatalog/).
|
|
|
268
281
|
Deliberate omissions, because saying why teaches more than lacking them
|
|
269
282
|
quietly:
|
|
270
283
|
|
|
271
|
-
- **Arithmetic
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
become trees. [Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
|
|
284
|
+
- **Arithmetic.** `Z = X + 1` makes values nobody stated, so it can make
|
|
285
|
+
a relation infinite, and the termination theorem goes with it.
|
|
286
|
+
[Lesson 14](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/14-arithmetic.md) is the whole
|
|
275
287
|
story, including what to do instead.
|
|
276
288
|
- **Indexes and join planning.** Every join is a nested loop so the
|
|
277
289
|
algorithms stay one-screen readable. It is also why the magic-sets
|
|
@@ -284,7 +296,10 @@ quietly:
|
|
|
284
296
|
|
|
285
297
|
Aggregation used to be on this list;
|
|
286
298
|
[lesson 13](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/13-aggregation.md) is what promoting an omission
|
|
287
|
-
into a feature looks like.
|
|
299
|
+
into a feature looks like. Comparisons (`<`, `<=`, `>`, `>=`, `=`,
|
|
300
|
+
`!=`) used to share arithmetic's entry. They check values and never
|
|
301
|
+
make them, so they can only filter, and lesson 14's own argument lets
|
|
302
|
+
them in; [lesson 23](https://github.com/andrewgoodchild/tiny-datalog/blob/main/lessons/23-time.md) puts them to work.
|
|
288
303
|
|
|
289
304
|
## Using it in your own project
|
|
290
305
|
|
|
@@ -321,8 +336,27 @@ engine = run_program(rules, facts={
|
|
|
321
336
|
engine.query("exposed(S, C)") # [{'S': 'app', 'C': 'cve_2026_0001'}]
|
|
322
337
|
```
|
|
323
338
|
|
|
339
|
+
A rule with no head is an integrity constraint, a situation that must
|
|
340
|
+
never arise. `engine.violations()` lists each broken one with its
|
|
341
|
+
counterexamples, and the command line prints them and exits with
|
|
342
|
+
status 3:
|
|
343
|
+
|
|
344
|
+
```python
|
|
345
|
+
checked = run_program(rules + ":- exposed(S, C).", facts={
|
|
346
|
+
"depends": [("app", "lib"), ("lib", "core")],
|
|
347
|
+
"service": ["app"],
|
|
348
|
+
"vulnerable": [("core", "cve_2026_0001")],
|
|
349
|
+
})
|
|
350
|
+
checked.violations() # [(constraint, [{'S': 'app', 'C': 'cve_2026_0001'}])]
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
For agents, `skills/tiny-datalog/SKILL.md` is an Agent Skill that
|
|
354
|
+
teaches a coding agent the language and the habits (explain before
|
|
355
|
+
trusting, state properties as constraints); copy it into your agent's
|
|
356
|
+
skills directory.
|
|
357
|
+
|
|
324
358
|
The command-line interface installs too, as `tiny-datalog` (and
|
|
325
|
-
`tiny-datalog-semiring`, `-tabling`, `-incremental`, `-subsumption`,
|
|
359
|
+
`tiny-datalog-semiring`, `-tabling`, `-slg`, `-incremental`, `-subsumption`,
|
|
326
360
|
`-containment`, `-defeasible`, `-prolog` for the other engines and the
|
|
327
361
|
extensions):
|
|
328
362
|
|
|
@@ -338,16 +372,20 @@ installed package; clone the repository for that.
|
|
|
338
372
|
```
|
|
339
373
|
tiny_datalog/ the code you read, in three tiers:
|
|
340
374
|
core.py the common core — the language every module shares:
|
|
341
|
-
AST, parser, safety checks,
|
|
342
|
-
formatting, query helpers
|
|
343
|
-
engines —
|
|
375
|
+
AST, parser, safety checks, comparisons, stratification,
|
|
376
|
+
matching, formatting, query helpers, warnings
|
|
377
|
+
engines — five strategies, one answer (engines.py lists them):
|
|
344
378
|
datalog.py the base engine: semi-naive and naive bottom-up
|
|
345
|
-
evaluation, aggregation,
|
|
379
|
+
evaluation, aggregation, integrity constraints,
|
|
380
|
+
--explain / why-not, --assume, the CLI
|
|
346
381
|
magic.py the magic-sets rewriting (a program-to-program pass)
|
|
347
382
|
tabling.py tabled top-down evaluation (iterative QSQR)
|
|
348
|
-
engines.py the registry and the interface the
|
|
383
|
+
engines.py the registry and the interface the five share (the
|
|
384
|
+
fifth is SLG, from slg.py below, held to stratified
|
|
385
|
+
programs)
|
|
349
386
|
extensions — other questions asked of the same programs:
|
|
350
387
|
semantics.py grounding, stable models, the well-founded model
|
|
388
|
+
slg.py SLG resolution: the well-founded model, top-down
|
|
351
389
|
semiring.py semiring-valued evaluation (costs, counts, provenance,
|
|
352
390
|
probabilities)
|
|
353
391
|
incremental.py insertions + DRed deletions over a live materialisation
|
|
@@ -359,16 +397,19 @@ tiny_datalog/ the code you read, in three tiers:
|
|
|
359
397
|
acyclicity
|
|
360
398
|
*.py three-line launchers, so `python3 datalog.py ...` works
|
|
361
399
|
straight from a checkout with nothing installed
|
|
362
|
-
programs/ teaching programs,
|
|
363
|
-
|
|
364
|
-
lessons/ getting started, glossary, and lessons 0–
|
|
400
|
+
programs/ teaching programs, named for what they model; each
|
|
401
|
+
lesson says which ones it runs
|
|
402
|
+
lessons/ getting started, glossary, and lessons 0–24
|
|
365
403
|
exercises/ worked answers, verified by the test suite
|
|
366
404
|
cases/ golden test cases — add one without writing Python
|
|
405
|
+
skills/ an Agent Skill that teaches coding agents to use the engine
|
|
367
406
|
conformance/ the external datalog-conformance corpus (Soufflé, Nemo,
|
|
368
407
|
Crepe, SPINdle), run against every evaluation strategy
|
|
369
408
|
benchmarks/ scaled input generators (chain/tree/clique/grid, an EL
|
|
370
|
-
ontology, and the N-queens puzzle)
|
|
371
|
-
|
|
409
|
+
ontology, and the N-queens puzzle), and mutate.py,
|
|
410
|
+
which breaks the code one line at a time to measure
|
|
411
|
+
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
|
|
372
413
|
executed, a conformance suite runs every query through
|
|
373
414
|
every engine that handles it, and a seeded fuzzer checks
|
|
374
415
|
the same property on random programs
|
|
@@ -384,7 +425,7 @@ used.
|
|
|
384
425
|
This project started as an attempt at a tiny implementation of
|
|
385
426
|
Datalog, small enough to read in an afternoon. It grew with the
|
|
386
427
|
course. Each lesson that taught a new technique — magic sets, stable models,
|
|
387
|
-
semirings, incremental maintenance, tabling, subsumption, containment,
|
|
428
|
+
semirings, incremental maintenance, tabling, SLG resolution, subsumption, containment,
|
|
388
429
|
defeasible logic, the chase — brought a module to run it, and the repository is
|
|
389
430
|
now several thousand lines. The core idea stayed small, and the code
|
|
390
431
|
is laid out so you can still read just that: the common core and the
|
|
@@ -395,21 +436,23 @@ Measured in lines, comments, docstrings and blank lines included:
|
|
|
395
436
|
|
|
396
437
|
| Tier | Lines |
|
|
397
438
|
|---|---|
|
|
398
|
-
| the common core (`core.py`: the language, evaluating nothing) |
|
|
399
|
-
| 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`) |
|
|
400
|
-
| `--explain`, why-not, printing and the CLI (the rest of `datalog.py`) |
|
|
401
|
-
| 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) |
|
|
402
|
-
| the
|
|
439
|
+
| 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
|
+
| 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 |
|
|
403
444
|
|
|
404
445
|
So the smallest complete Datalog system here — parse, check, stratify,
|
|
405
|
-
evaluate semi-naively — is the core plus the evaluator, about 1,
|
|
406
|
-
lines. All of it is
|
|
446
|
+
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
|
|
407
448
|
re-export list in `__init__.py`), roughly a quarter of it commentary,
|
|
408
|
-
and
|
|
449
|
+
and 4.4k of tests.
|
|
409
450
|
|
|
410
451
|
"Tiny" is a claim about that core and evaluator, and about each module
|
|
411
|
-
built on them singly: none of the
|
|
412
|
-
`engines.py` and the
|
|
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
|
|
413
456
|
claim about the repository, which is a dozen modules because it
|
|
414
457
|
teaches a dozen things.
|
|
415
458
|
|
|
@@ -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.7.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"
|
|
@@ -48,6 +48,7 @@ tiny-datalog = "tiny_datalog.datalog:main"
|
|
|
48
48
|
tiny-datalog-prolog = "tiny_datalog.prolog:main"
|
|
49
49
|
tiny-datalog-semiring = "tiny_datalog.semiring:main"
|
|
50
50
|
tiny-datalog-tabling = "tiny_datalog.tabling:main"
|
|
51
|
+
tiny-datalog-slg = "tiny_datalog.slg:main"
|
|
51
52
|
tiny-datalog-incremental = "tiny_datalog.incremental:main"
|
|
52
53
|
tiny-datalog-subsumption = "tiny_datalog.subsumption:main"
|
|
53
54
|
tiny-datalog-containment = "tiny_datalog.containment:main"
|
|
@@ -9,10 +9,12 @@ 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)
|
|
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
|
|
@@ -36,7 +38,7 @@ from tiny_datalog.datalog import (
|
|
|
36
38
|
format_atom, format_fact,
|
|
37
39
|
)
|
|
38
40
|
|
|
39
|
-
__version__ = "0.
|
|
41
|
+
__version__ = "0.7.0"
|
|
40
42
|
|
|
41
43
|
__all__ = [
|
|
42
44
|
"Var", "Const", "Struct", "Atom", "Literal", "Rule",
|
|
@@ -73,7 +73,8 @@ from dataclasses import dataclass
|
|
|
73
73
|
|
|
74
74
|
from tiny_datalog.core import (
|
|
75
75
|
_format_value, aggregate_of, Atom, cli, Const, DatalogError, Literal,
|
|
76
|
-
match, parse, parse_query_atom, read_program, Rule, Var,
|
|
76
|
+
match, parse, parse_query_atom, read_program, refuse_extras, Rule, Var,
|
|
77
|
+
validate)
|
|
77
78
|
from tiny_datalog.datalog import Engine, Program
|
|
78
79
|
|
|
79
80
|
|
|
@@ -133,6 +134,9 @@ def check(clauses):
|
|
|
133
134
|
The core's checks apply to a *skeleton* of each rule in which the
|
|
134
135
|
existential variables are replaced by a placeholder constant: that
|
|
135
136
|
is exactly "safe, except for the variables we mean to invent"."""
|
|
137
|
+
# an invented value has no order to compare, and denial
|
|
138
|
+
# constraints over nulls are a theory of their own
|
|
139
|
+
refuse_extras(clauses, "the chase")
|
|
136
140
|
for c in clauses:
|
|
137
141
|
if c.retract:
|
|
138
142
|
raise DatalogError("a retraction is an update, not a statement:"
|
|
@@ -42,7 +42,7 @@ import sys
|
|
|
42
42
|
|
|
43
43
|
from tiny_datalog.core import (
|
|
44
44
|
aggregate_of, cli, Const, DatalogError, parse, read_program, validate,
|
|
45
|
-
Var)
|
|
45
|
+
Var, is_comparison)
|
|
46
46
|
|
|
47
47
|
|
|
48
48
|
def _extend(mapping, source_args, target_args):
|
|
@@ -93,6 +93,12 @@ def _bodies(rule):
|
|
|
93
93
|
raise DatalogError(
|
|
94
94
|
"containment by homomorphism is a conjunctive-query "
|
|
95
95
|
"result; negation needs different theory: %s" % rule)
|
|
96
|
+
if is_comparison(lit):
|
|
97
|
+
# Klug (1988): with comparisons one homomorphism no longer
|
|
98
|
+
# suffices -- every ordering of the variables must be checked
|
|
99
|
+
raise DatalogError(
|
|
100
|
+
"containment by homomorphism is a conjunctive-query "
|
|
101
|
+
"result; comparisons need different theory: %s" % rule)
|
|
96
102
|
if aggregate_of(rule.head):
|
|
97
103
|
# sum/count see duplicates; Chandra–Merlin is about sets.
|
|
98
104
|
raise DatalogError(
|
|
@@ -198,6 +204,10 @@ def main(argv=None):
|
|
|
198
204
|
print("%s\n (skipped: negation is outside the theory)"
|
|
199
205
|
% rule)
|
|
200
206
|
continue
|
|
207
|
+
if any(is_comparison(lit) for lit in rule.body):
|
|
208
|
+
print("%s\n (skipped: comparisons are outside the theory)"
|
|
209
|
+
% rule)
|
|
210
|
+
continue
|
|
201
211
|
if aggregate_of(rule.head):
|
|
202
212
|
print("%s\n (skipped: aggregation is outside the theory)"
|
|
203
213
|
% rule)
|