Python

Maelys DL exposes a native Python binding for in-process use — no browser or WASM runtime. It targets research pipelines, offline analysis, and long-running services: Python exceptions represent errors, explicit objects represent policy and session lifetimes, and integer terms retain the full native int64 range.

The underlying concepts — EDB facts, predicate kinds, solving and querying — are the same as in C and WASM, documented in the Concepts pages. See Bindings overview for the cross-language map.

These topic pages preserve the progression of the historical Python V1 reference: installation, loading, domains, ownership, term encoding, queries, explanations, and the API reference. They add manifest loading, prepared sessions, Why-false and explicit execution requirements.

The ordinary sequence remains: declare the domain, load a policy, collect facts, solve, and inspect the result. The CFFI extension calls the opaque C facade, never an internal engine structure.

Public Python objects

Python exposes classes and value objects rather than C handles and free functions. The links lead directly to each class card or flag reference. The complete method index below is organized by class. Each topic page lists only the reference cards defined there.

The binding also exports Status, Capability, ExplanationKind and the PRED_* flags. Predicate roles are explained in Registries, capability and explanation masks in Solving and Querying, and native failure statuses in Errors.

Main methods by task

Explore by topic

• Registries
• Loading & manifests
• Rulesets
• Runtime EDB
• Solving
• Querying and explanations
• Errors
• Complete examples

API reference

This is the complete cross-topic method index, grouped by its Python class. Each link opens the method's single reference card. On the topic pages, the tables are local indexes rather than complete class inventories.

Edb methods

Engine methods

Predicate methods

ResultTerm methods

Ruleset methods

Session methods

SolveResult methods

Constructors

Class construction is separate from domain registration or solving.

Properties and protocols

These are read-only attributes or Python protocols, not additional engine calls. Class-card links explain their types and ownership.

Installation

Python 3.10 or later, CFFI, setuptools, a C11 compiler and CMake 3.16+ are required. The binding lives in the engine repository, not on a package registry. Install the native SDK first, then compile the CFFI extension against that same SDK prefix. From the v0.11.1 source checkout:

python3 -m venv build/python-venv
build/python-venv/bin/python -m pip install cffi setuptools pytest
cmake -S . -B build/cmake-small
cmake --build build/cmake-small --parallel 4
cmake --install build/cmake-small --prefix "$PWD/build/sdk-small"
build/python-venv/bin/python bindings/python/build_cffi.py \
  --sdk-prefix "$PWD/build/sdk-small"
MAELYS_DATALOG_SDK_PREFIX="$PWD/build/sdk-small" \
MAELYS_DATALOG_EXPECT_PROFILE=small PYTHONPATH=bindings/python \
  build/python-venv/bin/python -m pytest -q tests/python

The builder copies the installed shared library beside the Python extension. --build-dir and --engine-dir belonged to the experiment and are removed; --sdk-prefix proves that headers and library come from one installation. For LARGE, configure a separate build with -DMAELYS_DATALOG_PROFILE_LARGE=ON, install it to a separate prefix, rebuild the extension and start a fresh interpreter. Inspect engine.limits and the expected-profile check to verify which library was actually loaded.

Native library discovery

A compiled Python extension is itself a dynamic library. It depends on libmaelys_datalog_shared (the engine), not the historical libmaelys_py_bind shim. At import time, the operating system must find that dependency; PYTHONPATH alone only helps Python find its package.

The CFFI builder copies the selected engine library beside the package. On Linux the resulting layout is:

bindings/python/maelys_datalog/
├── __init__.py
├── engine.py
├── _maelys_cffi....so           ← compiled extension
└── libmaelys_datalog_shared.so  ← copied from --sdk-prefix

On macOS the native library uses .dylib; the extension still uses Python's platform-specific suffix. Python first finds maelys_datalog through its module path, then the OS resolves the extension's native dependency. $ORIGIN on Linux and @loader_path on macOS record a loader-relative search path: look beside the extension, not in the original build directory. Keep the extension and library together. No LD_LIBRARY_PATH is needed for this layout; if import fails, check their origin and profile before changing environment variables.

# check_import.py
import maelys_datalog
print("import OK")

PYTHONPATH=/path/to/maelys-datalog/bindings/python python check_import.py

Native call path

The loading choices above are separate from the library layers below. Both supported choices cross the same public C boundary:

There is no handwritten maelys_py_bind layer in this path. CFFI still generates a native extension; that extension links to libmaelys_datalog_shared. Opaque handles hide implementation details, not features: engine.limits and result.derived_fact_count() are exposed through public C getters.

Both inline source and native manifests are supported. load_inline_ruleset() compiles one policy; load_manifest() preserves native SHA verification, query whitelists and multi-policy selection. The generated bridge includes only <maelys/datalog.h>, never backend descriptors or private engine structures.

One consumer header, a separate extension API

datalog.h supplies the opaque handles, capability constants, session configuration and execution fingerprint used by this binding. datalog_backend.h is for C developers implementing an alternative execution backend; Python does not include it.

When you call ruleset.prepare(required_capabilities=..., work_limit=...), the binding creates an opaque native configuration, sets those values, creates the session and frees the temporary configuration. Session creation copies the values, so the session does not depend on that configuration's lifetime. Python code never supplies a backend ABI version or a C structure size.

This changes the native integration, not the Python method signatures. Unsupported requirements still fail explicitly: in particular, the reference backend rejects a nonzero work budget rather than pretending to enforce it.

Session lifecycle

Ruleset owns an opaque compiled-policy handle — not Engine, which owns the Python wrappers and the build-limit snapshot. Multiple rulesets can be loaded and closed independently within a process. Unlike those handles, the domain registry remains shared and survives Engine closure.

Each successful ruleset.solve() creates its own opaque session and result. The diagram above describes this convenience path. For repeated evaluation, ruleset.prepare() returns an explicit reusable Session with one live result at a time; see prepared sessions. Several results can coexist. After success, the EDB cannot be mutated, but it can be solved again to produce another independent result. Use a new ruleset.edb() for different inputs.

result.close() frees its result and, for the convenience path, its private session. With an explicit Session, closing the result leaves the session reusable. session.close() closes its live result first. ruleset.close() closes all results, sessions and EDBs before releasing the policy. The with Engine() block closes all remaining children even on exceptions. Objects used after their parent closes raise RuntimeError; query results must be read while their owner remains open.

The Python Edb owns an opaque native input EDB handle. Its idempotent close() frees that storage; it does not invalidate an already computed result. Closing its Ruleset prevents later use. Close buffers you no longer need to release native input memory, especially in long-running processes.

Python API walkthrough

Five owner/value layers structure this walkthrough: Engine owns Python Rulesets and reads build limits; Ruleset owns a compiled policy set; Edb buffers one evaluation's inputs; Session holds prepared native execution state; SolveResult retains one solve's model. The convenience solve() creates its Session for you. The sequence is the same as the original reference, but insertion timing and symbol ownership change.

Threading model

The old binding used a process-wide registry lock plus per-Ruleset symbol locks. Those locks protected particular operations; they did not make every object safe to share. Python makes the ownership rule explicit instead: an Engine and all its handles are confined to the thread that created it. The wrapper checks this before entering native code, including on close().

Do not rely on the Python interpreter lock to serialize access to native objects, and do not move an Engine into a worker after creating it in the main thread. Create the Engine inside that worker. Independent workers can own independent Engines and rulesets, while domain registration and policy loading remain serialized by the wrapper's process-wide registry lock.

That lock covers calls made through this binding. It is not a cross-language synchronization protocol for arbitrary C code mutating the same registry. Creating another Engine also does not create or unregister a domain: the vocabulary remains process-wide, as described under Domain definition.

Within one owner thread, a prepared Session permits one live result. Close that result before solving again. Independent convenience solves create independent sessions and may keep several results open. These are lifecycle rules, not an invitation to use the handles concurrently on other threads.

Use context managers or explicit close(): the prototype has no GC finalizer. A parent closes native children in result → session → EDB → policy order, and later use of a closed child raises RuntimeError. A second close() on a wrapper is harmless on its owner thread; it is not permission to race close with use.

Engine feature coverage

The following coverage is verified against the current code, not inferred from a roadmap. This is the sole source binding shipped with the current engine; it is not a separately published Python package.

Opaque handles do not preclude extensions. However, registering native callbacks is a different API from using the engine's standard filters: this binding does not manufacture a dynamic loader or Python callback ABI.

Migration from the deprecated Python V1 binding

The deprecated binding's missing atoms parameter does not mean that its engine cannot handle constants: that Python registration method simply does not expose the vocabulary parameter. Python makes it explicit, as explained under domain definition.

The old binding is not shipped in 0.10.0. Keeping the same import is not a complete migration: review buffering, symbol ownership, method names and lifetimes.

Lifecycle and configuration notes

Engine and domain

• Engine() / engine.limits — Create a thread-confined Python owner and read the loaded native capacities.
• Predicate(name, arity, flags) — Declare a relation; combine kinds using PRED_EDB, PRED_IDB, PRED_QUERY and PRED_POLICY_FACT.
• engine.register_domain(name, predicates, atoms=()) — Register process-wide predicate and atom vocabulary. Identical re-registration is a no-op; conflicting vocabulary raises.
• engine.load_inline_ruleset(domain, policy_id, source) — Compile source against a registered domain; return a Ruleset. No manifest query whitelist.
• engine.load_manifest(path, allow_test_only=False, allow_undeclared_policy_atoms=False) — Load a manifest file and SHA-verified policies with their query declarations. Extra admission flags are explicit opt-ins.
• engine.close() / with Engine() — Close remaining native children; safe to close again on the owner thread. Does not unregister domains.

Ruleset and EDB buffer

• ruleset.policy_count / ruleset.fingerprint — Read policy-set metadata; evaluation selects a zero-based policy_index.
• ruleset.edb() — Return a fresh owned native input buffer, tracked by this Ruleset.
• edb.add_fact(predicate, terms) — Atomically copy one fact into C-owned storage; check storage bounds immediately.
• edb.add_facts(iterable) — Stage a bounded iterable, then atomically append its facts in C. No partial append on iteration or native storage failure.
• len(edb) / edb.clear() — Count stored entries before deduplication / discard an unsolved buffer; clear is rejected after successful solve.
• edb.close() — Free native input storage and prohibit further use; existing results are unaffected. Idempotent.
• ruleset.solve(edb, policy_index=0, required_capabilities=0, work_limit=0) — Submit a complete batch with a private Session owned by the result. Native rejection publishes no partial result.
• ruleset.prepare(policy_index=0, required_capabilities=0, work_limit=0) — Create reusable prepared state using the opaque session configuration API.
• ruleset.close() / with ruleset — Close results, sessions, input EDBs and policy. All children become unusable.
• edb.reset() — Explicitly empty and unfreeze the input buffer for a new request; does not close a live result.

Prepared Session

• session.solve(edb) — Solve one full batch. Close the previous result first; this is not delta/incremental inference.
• session.fingerprint — Identity of selected policy authority.
• session.execution_fingerprint — Identity also binding backend, execution requirements/budget setting and size profile.
• Capability / required_capabilities — Add explicit required capabilities; unsupported requirements are rejected without fallback.
• work_limit — A uint64 cooperative-work request, not a deadline. Nonzero values are rejected by the current reference backend.
• session.close() / with session — Close its live result then the session; no effect on independent sessions.
• ExplanationKind — Select optional shared explanation storage when preparing a session; this is distinct from capability requirements.

SolveResult and raw terms

• result.contains_fact(predicate, terms) — Check a ground fact under query permissions; searches retained policy/EDB/IDB facts.
• result.enumerate_predicate_facts(predicate, arity) — Copy queryable derived IDB rows to plain Python tuples; copies remain usable after close.
• result.enumerate_raw(predicate, arity) — Return the same derived rows as immutable, result-owned ResultTerm views.
• term.kind / term.value — Inspect the raw kind/value. Symbol IDs are local to one result, not reusable inputs.
• term.resolve() / result.resolve_term(term) — Resolve through the owning live result only; cross-result resolution is rejected.
• result.explain_true(predicate, terms) — Native Why-true text including complete/not-derived/truncated status; raises on native errors.
• result.explain_false(predicate, terms) — Native bounded Why-false text; completeness is not a formal absence certificate.
• result.derived_fact_count() — Count all distinct derived IDB facts, including non-queryable intermediates.
• result.fingerprint / result.execution_fingerprint — The policy and execution identities of the owning Session.
• result.close() / with result — Free retained result state, plus the private Session for convenience solves. Raw resolution becomes invalid.

Exceptions

• MaelysDatalogError.status / .code — Native facade return status; code is an alias, not the diagnostic reason.
• error.message / error.hint — Human-readable detail, not a stable grammar to parse.
• error.diagnostic — Immutable source/code/phase/line/column/message/hint record. Fields are empty/zero when unavailable.
• TypeError / ValueError / OverflowError — Caller representation errors, distinct from native solve rejection.
• RuntimeError — Lifecycle misuse such as wrong thread, closed owner or reusing a Session with a live result.