Documentation: clausal.pl · start with the Tutorial.
Neural networks are good at perception, language and pattern-matching, but are slow, resource-hungry, unreliable and need to be constrained. Symbolic AI is good at rules, reasoning and guarantees but can't deal with the real world. Clausal Prolog puts both in one Python process: a neural network can call symbolic logic that in turn calls neural predicates, nested as deeply as you like, with no serialisation, IPC or second runtime in between. Combining the two gives systems that are:
- Explainable: conclusions come from rules you can read and a derivation you can trace, not only from weights.
- Reliable: hard constraints such as regulations, safety rules and business policy hold exactly, every time, rather than approximately.
- Data-efficient: knowledge you can state as a rule doesn't have to be learned from examples.
- Correctable: change a rule and the behaviour changes, with no retraining.
Clausal Prolog is a Prolog implemented in Python that aims for ISO Prolog
conformity. Logic programs go in .clausal files, written in Clausal Prolog:
ISO syntax without cut or committed choice, which guarantees properties of
programs that let you realise The Power of Prolog.
Existing ISO Prolog goes in .pl files. The seam (.seam) is a Python-syntax
surface for the adapters that give controlled access* to the whole Python
ecosystem. All three import with Python's standard import system, and the
import rules preserve each surface's guarantees. The engine includes
constraint solving, tabling, DCGs and a large standard library.
*Python seam adaptors assume the Python programmer takes full responsibility for correctness (in the Pythonic way).
The package is clausal: pip install clausal, import clausal.
Three source surfaces
| Extension | Surface | Syntax | Use it for |
|---|---|---|---|
.clausal |
Clausal Prolog | ISO Prolog, without cut | Your logic programs. The default choice. |
.pl |
ISO Prolog | Regular ISO Prolog, cut included | External Prolog code, for Prolog systems such as Scryer or Trealla |
.seam |
Seam | Python syntax | The boundary with Python: ++ escapes, hosted Python, adapters |
All three are importable modules once clausal is imported. In one
directory, name.seam beats name.clausal, which beats name.pl.
Changed in 1.0 (the extension flip).
.clausalused to be the Python-syntax seam language. It is now Clausal Prolog, and seam source is named.seam. A seam file still named.clausalfails to load with a Prolog syntax error. To migrate, rungit mv name.clausal name.seamfor each one. Move it rather than copying it: aname.clausalleft besidename.seamis a different module, written in Prolog. See CHANGELOG.md.
Features
- Clausal Prolog: ISO syntax, ISO builtin names and error terms,
"…"as a string that is also a list of characters (double_quotesischars), and modules withmodule/2,use_module/1,2andend_module/1 - Purity by design: no cut,
->or*->; usedif/2,if_/3fromlibrary(reif), constraints and first-argument indexing instead - Constraint solving: CLP(Z) for integers, CLP(B), CLP(Q), CLP(R) and
dif/2 - SLG tabling and well-founded semantics for negation over tabled predicates
- DCGs:
-->grammar rules withphrase/2,3 - Regular ISO Prolog alongside:
.plfiles, run in the Scryer or Trealla embeddings, or imported directly (experimental) - Python interop through the seam:
library(...)facades over the engine's Python modules (library(json),library(datetime), …), Python-free.seammodules, and allowlisted Python bridges - Asyncio, not a home-grown scheduler (experimental): queries run on
Python's own
asyncioevent loop, so they wait on models, databases, people and event streams alongside any async Python library, with timeouts, cancellation and racing straight fromasyncio. Backtracking still works across waits. See docs/asyncio.md - ISO direction: ISO builtin names, ISO error terms and ISO modules; where ISO is silent, Scryer Prolog's behaviour
- C extensions: logic variables, trail-based backtracking and a trampoline, with no WAM
Installation
Requires Python ≥ 3.13 and a C compiler (pip uses it automatically when building from source).
Quick start
A Clausal Prolog module
% family.clausal :- module(family, [grandparent/2, fib/2, path/2]). :- use_module(library(clpz)). parent(tom, bob). parent(tom, liz). parent(bob, ann). parent(bob, pat). grandparent(X, Z) :- parent(X, Y), parent(Y, Z). % CLP(Z) arithmetic: fib/2 runs in both directions. fib(0, 0). fib(1, 1). fib(N, F) :- N #> 1, N1 #= N - 1, N2 #= N - 2, F #>= N1, F #= F1 + F2, fib(N1, F1), fib(N2, F2). % Tabling terminates on the cycle. :- table(path/2). edge(1, 2). edge(2, 3). edge(3, 1). path(X, Y) :- edge(X, Y). path(X, Y) :- edge(X, Z), path(Z, Y). test(toms_grandchildren) :- grandparent(tom, ann), grandparent(tom, pat). test(fib_10_is_55) :- fib(10, 55). % A finite domain makes the search terminate, so no once/1 is needed. test(which_fib_is_55) :- N in 0..20, fib(N, 55), N == 10. test(path_reaches_the_whole_cycle) :- findall(Y, path(1, Y), Ys), msort(Ys, [1, 2, 3]). test(tom_has_no_grandparent, fail) :- grandparent(_, tom). :- end_module(family).
A Clausal Prolog module file must end with :- end_module(Name)..
Running it
clausal family.clausal -g "grandparent(tom, X)" # X = ann. X = pat. clausal --test family.clausal # runs the test clauses
clausal FILE on its own runs the program's main/0. See
docs/cli.md.
Querying it from Python
Python asks the questions from a .seam file, with a goal in for
position after --:
# app.seam -import_from(family, [grandparent, fib]) -private([tom]) for GRANDCHILD in --grandparent(tom, GRANDCHILD): print(GRANDCHILD) # ann, then pat for N in --fib(N, 55): print(N) # 10 break
python -c "import clausal, app" # import clausal installs the import hook
See Python Integration for more ways to query.
Constraints, DCGs and reified conditions
% puzzles.clausal :- module(puzzles, [greeting//0, send_more/1, classify/2]). :- use_module(library(clpz)). :- use_module(library(reif)). greeting --> [hello], name. name --> [world]. name --> [prolog]. send_more([S,E,N,D,M,O,R,Y]) :- Vars = [S,E,N,D,M,O,R,Y], Vars ins 0..9, all_different(Vars), S #\= 0, M #\= 0, 1000*S + 100*E + 10*N + D + 1000*M + 100*O + 10*R + E #= 10000*M + 1000*O + 100*N + 10*E + Y, label(Vars). % if_/3 instead of (Cond -> Then ; Else): it stays correct when X is unbound. classify(X, R) :- if_(X = a, R = yes, R = no). test(dcg) :- phrase(greeting, [hello, prolog]). test(send_more_money) :- send_more([9,5,6,7,1,0,8,2]). test(reified_if) :- classify(a, yes), classify(b, no). test(dif) :- dif(X, a), X = b. :- end_module(puzzles).
What Clausal Prolog restricts
Clausal Prolog is ISO Prolog with a few deliberate rules. Each one is enforced when the file loads:
- Cut-free.
!and->are refused, and*->is not an operator. Usedif/2,if_/3(its condition must be a reifiable_tclosure such asmemberd_t(X, Xs)orX = Y), constraints or first-argument indexing, or write the predicate so it is deterministic.once/1,\+andforall/2are still supported, but as transition constructs: they commit to a first solution or test by failure, which gives up monotonicity, and they are being phased out. Prefer the forms above. - Modules close. By default a
.clausalmodule file that does not end with:- end_module(Name).is refused at load time. Therequire_end_moduleflag is the opt-out::- set_prolog_flag(require_end_module, false).in one file, or the same flag (orCLAUSAL_REQUIRE_END_MODULE=0) for the whole process. - One-way dependency on ISO Prolog. A
.clausalmodule may not import a.plmodule, which may use cut. It is refused withpermission_error(access, prolog_module, M). A.plmodule may import a.clausalone. - Python only through the seam. A
.clausalfile reaches Python through engine-shippedlibrary(...)facades (for example:- use_module(library(datetime), [date_add/3]).), through Python-free.seammodules, or through.seammodules listed under[tool.clausal] python_bridgesin the importing project'spyproject.toml. Anything else is refused withpermission_error(import, python_bridge, M).
See docs/importing_prolog.md for the full rules.
ISO Prolog .pl files
A .pl file is regular, external ISO Prolog: it is not restricted to the
cut-free subset, and that is why a .clausal module may not import one.
To run full ISO Prolog, cut included, alongside Clausal Prolog, use the
Scryer or
Trealla embeddings.
Importing a .pl file straight into the engine (put it on sys.path and
import it) is
experimental and outside the 1.0 compatibility promise. That in-process
loader does not run cut yet: a .pl file that uses ! or -> fails to
load there. It reads .pl with the native ISO front end, the reader that
.clausal files always use; CLAUSAL_PL_FRONTEND=translator selects the
legacy translator instead.
The seam: .seam files
Code that must call Python lives in .seam files. These use the older
Python-syntax surface, with the ++expr escape, hosted Python statements
and adapters over Python libraries. A .clausal module imports a .seam
module like any other (subject to the
Python-bridge rules). Keep .seam
modules small and write your logic in Clausal Prolog. clausal-fmt and
clausal-rewrite work on .seam files only. See
docs/clausal_prolog.md for how the two surfaces
differ.
Testing
A module carries its tests inline as test/1 clauses, or as test/2
with the option fail for a goal that must have no solution:
test(fib_5_5) :- fib(5, 5). test(no_grandparent, fail) :- grandparent(_, tom).
Standalone runner:
python -m clausal.testing path/to/dir/ # every .seam, .clausal and .pl file python -m clausal.testing family.clausal # a single file python -m clausal.testing -v clausal/examples/ # verbose
Via pytest: test clauses in .seam, .clausal and .pl files are
collected automatically.
python -m pytest tests/ clausal/examples/ -q
Requirements
- Python ≥ 3.13 and greenlet (the only
runtime dependency; it lets queries run on
asyncio) - C compiler (for building from source)
Optional packages wrap Python libraries for use from Clausal Prolog. Each is
on PyPI and is also available as an extra of clausal:
pip install clausal-scipy # or: pip install "clausal[scipy]"| Package | Wraps |
|---|---|
clausal-acl2 |
the ACL2 theorem prover |
clausal-decide |
calibrated decision models (laya, TypeSafe's Jev) |
clausal-jax |
JAX (plus optax, equinox, flax as extras) |
clausal-opencv |
OpenCV |
clausal-scipy |
SciPy |
clausal-sklearn |
scikit-learn |
clausal-spacy |
spaCy |
clausal-sympy |
SymPy |
clausal-torch |
PyTorch |
clausal-yaml |
PyYAML |
The Scryer, Trealla and GNU Prolog embeddings live in
packages/ too, but need native builds and
are not on PyPI yet.
License
MIT
