clausal 0.3.0__tar.gz

clausal-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Amy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clausal-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include clausal/logic/variables/_variables.c
+include clausal/logic/_trampoline.c
+include LICENSE
+include README.md

clausal-0.3.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: clausal
+Version: 0.3.0
+Summary: A Prolog-style logic programming DSL embedded in Python
+Author-email: Mike Amy <mikeamycoder@gmail.com>
+License: MIT
+Project-URL: Repository, https://gitlab.com/MikeAmy/clausal
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: greenlet
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: spacy
+Requires-Dist: spacy>=3.0; extra == "spacy"
+Dynamic: license-file
+
+# clausal
+
+A Prolog-style logic programming DSL embedded in Python. Write relational logic programs using `.clausal` source files or directly in Python, with full constraint solving, tabling, DCGs, and a rich standard library.
+
+## Features
+
+- **`.clausal` source files** — import logic modules with Python's standard import system
+- **Prolog-style predicates** — Horn clauses, unification, backtracking search
+- **Constraint solving** — CLP(FD) for integers, CLP(B) for booleans, `dif/2` disequality
+- **SLG tabling** — memoised subgoal calls for termination on cyclic structures
+- **DCGs** — Definite Clause Grammars with `>>` syntax and `phrase/2,3`
+- **Well-Founded Semantics** — negation-as-failure with `\+` / `tabled` predicates
+- **Module system** — `-import_from/2`, `-import_module/1`, qualified calls
+- **Meta-predicates** — `findall/3`, `bagof/3`, `setof/3`, `forall/2`, `call/N`
+- **Higher-order** — `maplist/2,3`, `foldl/4`, `include/3`, `exclude/3`
+- **Python interop** — `++expr` escape, lambda goal closures, f-string support
+- **SciPy integration** — wrappers for `scipy.special`, `scipy.linalg`, `scipy.optimize`, `scipy.interpolate`, `scipy.signal`
+- **Regex** — `match/2,3`, `search/2,3`, `replace/4`, `split/3` with auto-binding goal expansion
+- **Term expansion** — macro system for source-level term rewriting
+- **C extensions** — fast logic variables, trail-based backtracking, trampoline (no WAM)
+
+## Installation
+
+```bash
+pip install clausal
+```
+
+Requires Python ≥ 3.13 and a C compiler for the extension modules.
+
+## Quick start
+
+### Python API
+
+```python
+from clausal import query, solve, once, Var
+from clausal.import_hook import LogicModule
+
+# Load a .clausal module
+import clausal.examples.family  # if you have one
+```
+
+### Writing `.clausal` files
+
+```python
+# family.clausal
+parent(tom, bob) <-
+parent(tom, liz) <-
+parent(bob, ann) <-
+parent(bob, pat) <-
+
+grandparent(X_, Z_) <- (parent(X_, Y_), parent(Y_, Z_))
+```
+
+```python
+# Python
+import family   # .clausal files load via the import hook
+
+from clausal import query
+results = list(query(family.grandparent(Var(), Var())))
+# → [(tom, ann), (tom, pat)]
+```
+
+### Constraints (CLP(FD))
+
+```python
+# queens.clausal
+-import_from(clpfd, [in_, all_different, label])
+
+queens(N_, QS_) <- (
+    length(QS_, N_),
+    QS_ in_ 1..N_,
+    safe(QS_),
+    label(QS_)
+)
+```
+
+### Arithmetic & builtins
+
+```clausal
+fib(0, 0) <-
+fib(1, 1) <-
+fib(N_, F_) <- (
+    N_ > 1,
+    N1_ is N_ - 1,
+    N2_ is N_ - 2,
+    fib(N1_, F1_),
+    fib(N2_, F2_),
+    F_ is F1_ + F2_
+)
+```
+
+### DCGs
+
+```clausal
+sentence >> (noun_phrase, verb_phrase)
+noun_phrase >> ([the], noun)
+verb_phrase >> ([runs])
+noun >> ([cat])
+noun >> ([dog])
+```
+
+```python
+from clausal import once
+result = once(phrase(sentence, [the, cat, runs]))
+```
+
+## Testing
+
+`.clausal` files can include inline tests as `test/1` clauses:
+
+```clausal
+test("fib(5) = 5") <- fib(5, 5)
+```
+
+**Standalone runner:**
+
+```bash
+python -m clausal.testing clausal/examples/           # all .clausal files
+python -m clausal.testing clausal/examples/hanoi.clausal  # single file
+python -m clausal.testing -v clausal/examples/        # verbose
+```
+
+**Via pytest** (`.clausal` tests collected automatically):
+
+```bash
+python -m pytest tests/ clausal/examples/ -q
+```
+
+## Logic variables and backtracking
+
+The C extension `clausal.logic.variables` provides Prolog-style logic variables and trail-based backtracking without a Warren Abstract Machine.
+
+```python
+from clausal.logic.variables import Var, Trail, unify, is_var
+
+trail = Trail()
+X = Var()
+Y = Var()
+
+unify(X, 42, trail)
+assert X.value == 42
+
+mark = trail.mark()
+unify(Y, "temporary", trail)
+trail.undo(mark)
+assert is_var(Y)   # Y is unbound again
+```
+
+See [docs/](docs/) for full documentation.
+
+## Requirements
+
+- Python ≥ 3.13
+- [greenlet](https://pypi.org/project/greenlet/)
+- [pyyaml](https://pypi.org/project/PyYAML/) ≥ 6.0
+- C compiler (for building from source)
+
+## License
+
+MIT

clausal-0.3.0/README.md

@@ -0,0 +1,160 @@
+# clausal
+
+A Prolog-style logic programming DSL embedded in Python. Write relational logic programs using `.clausal` source files or directly in Python, with full constraint solving, tabling, DCGs, and a rich standard library.
+
+## Features
+
+- **`.clausal` source files** — import logic modules with Python's standard import system
+- **Prolog-style predicates** — Horn clauses, unification, backtracking search
+- **Constraint solving** — CLP(FD) for integers, CLP(B) for booleans, `dif/2` disequality
+- **SLG tabling** — memoised subgoal calls for termination on cyclic structures
+- **DCGs** — Definite Clause Grammars with `>>` syntax and `phrase/2,3`
+- **Well-Founded Semantics** — negation-as-failure with `\+` / `tabled` predicates
+- **Module system** — `-import_from/2`, `-import_module/1`, qualified calls
+- **Meta-predicates** — `findall/3`, `bagof/3`, `setof/3`, `forall/2`, `call/N`
+- **Higher-order** — `maplist/2,3`, `foldl/4`, `include/3`, `exclude/3`
+- **Python interop** — `++expr` escape, lambda goal closures, f-string support
+- **SciPy integration** — wrappers for `scipy.special`, `scipy.linalg`, `scipy.optimize`, `scipy.interpolate`, `scipy.signal`
+- **Regex** — `match/2,3`, `search/2,3`, `replace/4`, `split/3` with auto-binding goal expansion
+- **Term expansion** — macro system for source-level term rewriting
+- **C extensions** — fast logic variables, trail-based backtracking, trampoline (no WAM)
+
+## Installation
+
+```bash
+pip install clausal
+```
+
+Requires Python ≥ 3.13 and a C compiler for the extension modules.
+
+## Quick start
+
+### Python API
+
+```python
+from clausal import query, solve, once, Var
+from clausal.import_hook import LogicModule
+
+# Load a .clausal module
+import clausal.examples.family  # if you have one
+```
+
+### Writing `.clausal` files
+
+```python
+# family.clausal
+parent(tom, bob) <-
+parent(tom, liz) <-
+parent(bob, ann) <-
+parent(bob, pat) <-
+
+grandparent(X_, Z_) <- (parent(X_, Y_), parent(Y_, Z_))
+```
+
+```python
+# Python
+import family   # .clausal files load via the import hook
+
+from clausal import query
+results = list(query(family.grandparent(Var(), Var())))
+# → [(tom, ann), (tom, pat)]
+```
+
+### Constraints (CLP(FD))
+
+```python
+# queens.clausal
+-import_from(clpfd, [in_, all_different, label])
+
+queens(N_, QS_) <- (
+    length(QS_, N_),
+    QS_ in_ 1..N_,
+    safe(QS_),
+    label(QS_)
+)
+```
+
+### Arithmetic & builtins
+
+```clausal
+fib(0, 0) <-
+fib(1, 1) <-
+fib(N_, F_) <- (
+    N_ > 1,
+    N1_ is N_ - 1,
+    N2_ is N_ - 2,
+    fib(N1_, F1_),
+    fib(N2_, F2_),
+    F_ is F1_ + F2_
+)
+```
+
+### DCGs
+
+```clausal
+sentence >> (noun_phrase, verb_phrase)
+noun_phrase >> ([the], noun)
+verb_phrase >> ([runs])
+noun >> ([cat])
+noun >> ([dog])
+```
+
+```python
+from clausal import once
+result = once(phrase(sentence, [the, cat, runs]))
+```
+
+## Testing
+
+`.clausal` files can include inline tests as `test/1` clauses:
+
+```clausal
+test("fib(5) = 5") <- fib(5, 5)
+```
+
+**Standalone runner:**
+
+```bash
+python -m clausal.testing clausal/examples/           # all .clausal files
+python -m clausal.testing clausal/examples/hanoi.clausal  # single file
+python -m clausal.testing -v clausal/examples/        # verbose
+```
+
+**Via pytest** (`.clausal` tests collected automatically):
+
+```bash
+python -m pytest tests/ clausal/examples/ -q
+```
+
+## Logic variables and backtracking
+
+The C extension `clausal.logic.variables` provides Prolog-style logic variables and trail-based backtracking without a Warren Abstract Machine.
+
+```python
+from clausal.logic.variables import Var, Trail, unify, is_var
+
+trail = Trail()
+X = Var()
+Y = Var()
+
+unify(X, 42, trail)
+assert X.value == 42
+
+mark = trail.mark()
+unify(Y, "temporary", trail)
+trail.undo(mark)
+assert is_var(Y)   # Y is unbound again
+```
+
+See [docs/](docs/) for full documentation.
+
+## Requirements
+
+- Python ≥ 3.13
+- [greenlet](https://pypi.org/project/greenlet/)
+- [pyyaml](https://pypi.org/project/PyYAML/) ≥ 6.0
+- C compiler (for building from source)
+
+## License
+
+MIT

clausal-0.3.0/clausal/__init__.py

@@ -0,0 +1,63 @@
+"""clausal — logic programming for Python.
+
+Top-level public API (Step 7 and later).
+"""
+
+from clausal.logic.solve import call, solve, query, once, _deref_walk
+from clausal.logic.database import Module, Database, Clause
+from clausal.logic.variables import Var, Trail, deref, unify
+from clausal.terms import Compound, KWTerm, Quantity, UnitsMismatch
+from clausal.logic.builtins import (
+    structural_unify,
+    get_builtin_class,
+    _BUILTIN_CLASSES,
+)
+from clausal.logic.predicate import PredicateMeta, make_predicate
+from clausal.logic.exceptions import LogicException
+from clausal.repl import Solutions
+import clausal.import_hook as _import_hook  # registers .clausal finder on sys.meta_path
+
+
+# ── Export all builtin predicate classes as top-level names ────────────────────
+# This lets users write: from clausal import Append, Between, In, Length, ...
+
+def _export_builtin_classes():
+    """Inject all builtin PredicateMeta classes into this module's namespace."""
+    import sys
+    mod = sys.modules[__name__]
+    names = []
+    for name, cls in _BUILTIN_CLASSES.items():
+        setattr(mod, name, cls)
+        names.append(name)
+    return names
+
+_builtin_names = _export_builtin_classes()
+
+
+__all__ = [
+    # Query API
+    "call",
+    "solve",
+    "query",
+    "once",
+    # Runtime objects
+    "Module",
+    "Database",
+    "Clause",
+    "Var",
+    "Trail",
+    "Compound",
+    "KWTerm",
+    "Quantity",
+    "UnitsMismatch",
+    "deref",
+    "unify",
+    "structural_unify",
+    "PredicateMeta",
+    "make_predicate",
+    "LogicException",
+    "get_builtin_class",
+    "Solutions",
+    # All builtin predicate classes
+    *_builtin_names,
+]

clausal-0.3.0/clausal/codegen.py

@@ -0,0 +1,166 @@
+"""
+codegen.py — Compile Python AST nodes into callable functions.
+"""
+
+import ast
+import builtins as _builtins
+
+__all__ = [
+    "functiondef_to_function",
+    "stmts_to_function",
+]
+
+_BUILTIN_NAMES = frozenset(vars(_builtins))
+
+
+def _infer_args(stmts: list[ast.stmt], globals_: dict | None = None) -> ast.arguments:
+    """Infer positional parameters by scanning name loads before assignments.
+
+    A name becomes a parameter if it is loaded before it is assigned anywhere
+    in ``stmts`` (at the top-level scope only — nested functions, classes,
+    lambdas, and comprehensions introduce their own scopes and are not
+    descended into, except that the outermost iterable of a comprehension IS
+    evaluated in the enclosing scope).  Built-in names and names present in
+    ``globals_`` are excluded (they are already available, not arguments).
+
+    Order is the order of first qualifying load.
+    """
+    assigned: set[str] = set()
+    params: list[str] = []
+    seen: set[str] = set()
+    excluded = _BUILTIN_NAMES if not globals_ else _BUILTIN_NAMES | globals_.keys()
+
+    class _Scanner(ast.NodeVisitor):
+        # ── nested scopes: record the name being bound, but do not descend ─────
+        def visit_FunctionDef(self, node):
+            assigned.add(node.name)
+        visit_AsyncFunctionDef = visit_FunctionDef
+        def visit_ClassDef(self, node):
+            assigned.add(node.name)
+        def visit_Lambda(self, node): pass
+
+        # Only the outermost iterable of a comprehension is in the enclosing scope.
+        def _comp(self, node):
+            self.visit(node.generators[0].iter)
+        visit_ListComp = _comp
+        visit_SetComp = _comp
+        visit_DictComp = _comp
+        visit_GeneratorExp = _comp
+
+        # ── name handling ─────────────────────────────────────────────────────
+        def _record_load(self, name: str):
+            if name not in assigned and name not in seen and name not in excluded:
+                params.append(name)
+                seen.add(name)
+
+        def visit_Name(self, node):
+            if isinstance(node.ctx, ast.Load):
+                self._record_load(node.id)
+            elif isinstance(node.ctx, (ast.Store, ast.Del)):
+                assigned.add(node.id)
+
+        # ── assignment ordering: value (RHS) must be visited before targets ──
+        def visit_Assign(self, node):
+            self.visit(node.value)
+            for target in node.targets:
+                self.visit(target)
+
+        def visit_AnnAssign(self, node):
+            if node.value:
+                self.visit(node.value)
+            self.visit(node.target)
+
+        def visit_AugAssign(self, node):
+            # Read-modify-write: target is implicitly loaded before being stored.
+            if isinstance(node.target, ast.Name):
+                self._record_load(node.target.id)
+                assigned.add(node.target.id)
+            else:
+                self.visit(node.target)   # Attribute/Subscript: object is Load
+            self.visit(node.value)
+
+        # ── for loop: evaluate iterable before assigning loop target ─────────
+        def visit_For(self, node):
+            self.visit(node.iter)
+            self.visit(node.target)
+            for s in node.body:
+                self.visit(s)
+            for s in node.orelse:
+                self.visit(s)
+
+        # ── global/nonlocal: treat as already available, not parameters ──────
+        def visit_Global(self, node):
+            for name in node.names:
+                assigned.add(name)
+
+        def visit_Nonlocal(self, node):
+            for name in node.names:
+                assigned.add(name)
+
+    scanner = _Scanner()
+    for stmt in stmts:
+        scanner.visit(stmt)
+
+    return ast.arguments(
+        posonlyargs=[],
+        args=[ast.arg(arg=name) for name in params],
+        vararg=None,
+        kwonlyargs=[], kw_defaults=[], kwarg=None, defaults=[],
+    )
+
+
+def functiondef_to_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+    globals_: dict | None = None,
+    filename: str = "<template>",
+):
+    """Compile an ast.FunctionDef (or AsyncFunctionDef) into a Python callable.
+
+    The function name is read from node.name.  globals_ provides names
+    visible at definition time (closures, helper functions, etc.).
+    """
+    module = ast.Module(body=[node], type_ignores=[])
+    ast.fix_missing_locations(module)
+    code = compile(module, filename, "exec")
+    ns = dict(globals_ or {})
+    exec(code, ns)
+    return ns[node.name]
+
+
+def stmts_to_function(
+    body: list[ast.stmt],
+    name: str,
+    args: ast.arguments | None = None,
+    *,
+    decorators: list[ast.expr] | None = None,
+    returns: ast.expr | None = None,
+    globals_: dict | None = None,
+    filename: str = "<template>",
+):
+    """Wrap a statement list in a function definition and return a callable.
+
+    Parameters
+    ----------
+    body:       statements forming the function body
+    name:       name to give the function
+    args:       parameter signature; if omitted, inferred from the body via
+                ``_infer_args`` (names that are loaded before being assigned
+                become positional parameters, in order of first load)
+    decorators: decorator list
+    returns:    return-annotation expression
+    globals_:   names made available in the function's defining scope
+    filename:   filename used in tracebacks
+    """
+    if args is None:
+        args = _infer_args(body, globals_)
+    extra = {'type_params': []} if 'type_params' in ast.FunctionDef._fields else {}
+    func_node = ast.FunctionDef(
+        name=name,
+        args=args,
+        body=body,
+        decorator_list=decorators or [],
+        returns=returns,
+        type_comment=None,
+        **extra,
+    )
+    return functiondef_to_function(func_node, globals_=globals_, filename=filename)