2PPy: tuProlog for Python¶
2PPy brings tuProlog (2P-Kt) to Python: an object-oriented, modular ecosystem for symbolic AI and logic programming. It lets Python programs represent knowledge as logic terms and clauses, reason over it with Prolog (or ProbLog) solvers, and mix logic and Python code freely in both directions.
>>> from tuprolog.solve.prolog import prolog_solver
>>> from tuprolog.theory.parsing import parse_theory
>>> solver = prolog_solver(
... static_kb=parse_theory("""
... parent(abe, homer). parent(homer, bart). parent(homer, lisa).
... ancestor(X, Y) :- parent(X, Y).
... ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).
... """)
... )
>>> [answer["D"] for answer in solver.query("ancestor(abe, D)")]
['homer', 'bart', 'lisa']
No knowledge of 2P-Kt, Kotlin or Java is needed, and no Java installation either:
pip install 2ppy (Python 3.10 or later) ships everything, Java runtime included.
What 2PPy offers¶
| Capability | What it means | Where to start |
|---|---|---|
| Logic terms | Build, parse, inspect and format atoms, numbers, variables, compound terms, lists, clauses; convert them from and to Python values | Build and parse terms |
| Unification | Compute the substitutions making two terms equal, the core operation of logic programming | Terms and variables |
| Theories | Store clauses in indexed, immutable or mutable knowledge bases | Your first logic program |
| Prolog solving | Answer queries with an ISO-compliant Prolog engine, getting answers as Python dicts and errors as Python exceptions | Query solvers |
| Probabilistic solving | Compute the probability of queries over ProbLog programs | Run probabilistic programs |
| Python extensions | Define predicates and arithmetic functions as plain Python functions | Define predicates in Python |
| Python objects from Prolog | Let Prolog code create Python objects and call their methods (OOPLib) | Use Python objects from Prolog |
| Input/output | Use Python streams (files, io.StringIO, sys.stdout) wherever logic code reads or writes |
Read and write streams |
| Interactive use | Prolog and ProbLog REPLs, and a Python shell with the whole API loaded | Use the REPL |
| Terminal IDE | Edit theories and solve queries in a terminal user interface, page by page; installed with 2PPy, or run with Docker | Use the terminal IDE, How it works |
How it works¶
2PPy is a thin, Pythonic layer over 2P-Kt, the Kotlin implementation of tuProlog, which runs on a
Java virtual machine (JVM) started, once per process, when tuprolog is first imported:
your Python code
│ Pythonic API: snake_case factories, Python protocols, value conversions
▼
tuprolog (2PPy) ── JPype bridge ──▶ 2P-Kt on the JVM (terms, unification, solvers, libraries)
Logic is implemented once, in 2P-Kt, and wrapped: 2PPy adds factories with Python defaults,
conversions between Python values and terms, Python protocols on JVM objects (iteration, indexing,
len, in, operators), Python exception classes for 2P-Kt's errors, and Python-friendly ways to
extend solvers. See Architecture for details.
The package mirrors 2P-Kt's modules:
| Package | Content |
|---|---|
tuprolog.core |
terms and clauses; parsing and operators |
tuprolog.unify |
unification and substitutions |
tuprolog.theory |
theories (knowledge bases) and their parsing |
tuprolog.solve |
the solver API, the Prolog and ProbLog solvers, primitives, libraries, flags, channels |
tuprolog.errors |
Python exception classes for 2P-Kt's errors |
tuprolog.repl |
the REPLs |
tuprolog.gui and tuprolog.tui |
the core of tuProlog's IDEs, and the terminal IDE |
The package map lists every module.
How this documentation is organized¶
Following the Divio documentation system, as 2P-Kt's documentation does:
- Tutorials: learning by doing, from installation to a first logic program;
- How-to guides: recipes for specific tasks;
- Examples: Jupyter notebooks showing 2PPy at work;
- Reference: precise descriptions, including the API reference generated from the docstrings;
- Explanation: background and design, from logic programming basics to how 2PPy wraps 2P-Kt.
Every example in this documentation, notebooks included, is run by the test suite.
Project¶
2PPy is developed by the tuProlog team, under the Apache License 2.0, on GitHub, and released on PyPI. It is in alpha: its API may still change between minor versions. Contributions are welcome: see Contribute.