GitHub - neurosymbolica/clausal-prolog: A Neurosymbolic Prolog built on Python

GitHub

8 min read Original article ↗

Clausal Prolog

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). .clausal used to be the Python-syntax seam language. It is now Clausal Prolog, and seam source is named .seam. A seam file still named .clausal fails to load with a Prolog syntax error. To migrate, run git mv name.clausal name.seam for each one. Move it rather than copying it: a name.clausal left beside name.seam is 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_quotes is chars), and modules with module/2, use_module/1,2 and end_module/1
  • Purity by design: no cut, -> or *->; use dif/2, if_/3 from library(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 with phrase/2,3
  • Regular ISO Prolog alongside: .pl files, 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 .seam modules, and allowlisted Python bridges
  • Asyncio, not a home-grown scheduler (experimental): queries run on Python's own asyncio event loop, so they wait on models, databases, people and event streams alongside any async Python library, with timeouts, cancellation and racing straight from asyncio. 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. Use dif/2, if_/3 (its condition must be a reifiable _t closure such as memberd_t(X, Xs) or X = Y), constraints or first-argument indexing, or write the predicate so it is deterministic. once/1, \+ and forall/2 are 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 .clausal module file that does not end with :- end_module(Name). is refused at load time. The require_end_module flag is the opt-out: :- set_prolog_flag(require_end_module, false). in one file, or the same flag (or CLAUSAL_REQUIRE_END_MODULE=0) for the whole process.
  • One-way dependency on ISO Prolog. A .clausal module may not import a .pl module, which may use cut. It is refused with permission_error(access, prolog_module, M). A .pl module may import a .clausal one.
  • Python only through the seam. A .clausal file reaches Python through engine-shipped library(...) facades (for example :- use_module(library(datetime), [date_add/3]).), through Python-free .seam modules, or through .seam modules listed under [tool.clausal] python_bridges in the importing project's pyproject.toml. Anything else is refused with permission_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