A PDDL library that, by using an ANTLR 4 grammar to parse PDDL files, provides a very simple interface to interact with domain-problems. This library publishes one object class whose API exposes methods for obtaining:
- The initial state.
- The goals.
- The list of operators.
- The positive and negative preconditions and the positive and negative effects.
- The grounded states of a given operator (grounded variables, preconditions and effects).
This is enough for the user to focus on the implementation of state-space or plan-space search algorithms.
The development of this tool was inspired from Univerty of Edinburgh's Artificial Intelligence Planning course by Dr. Gerhard Wickler and Prof. Austin Tate. The terms used in this API (and the API itself) closely resembles the ones proposed by the lecturers.
As of today it supports Python 3.11 and up.
The orginal grammar file was authored by Zeyn Saigol from University of Birmingham. I cleaned up it, made it language agnostic and upgraded to ANTLR 4.
Durative actions are now recovered into the object model (see Planning API). The reference planners, however, are non-temporal and do not solve durative domains — that is documented as out of scope for this round.
The core of this library is a PDDL parser and object model — a simple helper API for users experimenting with their own planning algorithms. It ships a small reference planner layer (see Planning API below) whose only job is to prove a stable, pluggable solver interface; it is not intended to compete with full planning systems such as Fast Downward or LAMA. For serious solving there are lots of complete packages available.
In this repostory you'll find some PDDL examples files useful for testing purposes. For instance, domain-03.pddl and problem-03.pddl
The examples/ directory holds a set of self-contained, runnable
scripts of increasing complexity, each demonstrating one capability against a
bundled PDDL domain in examples/pddl/. Run them all with
make examples, or one at a time, e.g. uv run python examples/01_parsing_basics.py.
| # | Example | What it shows | Capability |
|---|---|---|---|
| 01 | 01_parsing_basics.py | Parse a typed domain/problem; read objects, init, goals, operators and grounded operators | Core object model |
| 02 | 02_type_hierarchy.py | Multi-level :types, types() / subtypes_of(), supertype binding in grounding |
Type hierarchies (#22) |
| 03 | 03_logical_operators.py | Top-level and / or connective and negative preconditions in the model |
Logical operators (#13) |
| 04 | 04_planners.py | The planner registry and BFS / A* reference planners solving blocksworld and gripper | Planners (#1) |
| 05 | 05_numeric_and_costs.py | Numeric fluents (fuel-aware planning) and action costs (UCS cost-optimality) | Numeric fluents (#11) + action costs (#3) |
| 06 | 06_durative.py | Durative model, DurativeState at start applicability and validation — not temporally solved |
Durative actions (#23) |
To use this library the recommended way is to install it via PIP:
pip install pddlpy
It would download pddlpy and its dependencies (antlr4-python3-runtime) from PYPI and install them.
And that's it. You are ready to go.
Using the library is easy.
~hernan$ python
Python 3.11.7 (main, Feb 10 2024, 17:01:04)
[Clang 15.0.0 (clang-1500.1.0.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> import pddlpy
>>> domprob = pddlpy.DomainProblem('domain-03.pddl', 'problem-03.pddl')
>>>
>>> domprob.initialstate()
{('unloaded', 'robr'), ('adjacent', 'loc2', 'loc1'), ('unloaded', 'robq'), ('in', 'conta', 'loc1'), ('in', 'contb', 'loc2'), ('atl', 'robr', 'loc1'), ('atl', 'robq', 'loc2'), ('adjacent', 'loc1', 'loc2')}
>>>
>>> list( domprob.operators() )
['move', 'load', 'unload']
>>>
>>> list( domprob.ground_operator('move') )
[<pddlpy.pddl.Operator object at 0x1089830a0>, <pddlpy.pddl.Operator object at 0x108983130>, <pddlpy.pddl.Operator object at 0x108983190>, <pddlpy.pddl.Operator object at 0x1089830d0>, <pddlpy.pddl.Operator object at 0x1089831c0>, <pddlpy.pddl.Operator object at 0x1089835b0>, <pddlpy.pddl.Operator object at 0x1089835e0>, <pddlpy.pddl.Operator object at 0x108983610>]
>>>
>>> list( domprob.ground_operator('move') )[0].precondition_pos
{('atl', 'robq', 'loc2'), ('adjacent', 'loc2', 'loc2')}
>>>
Note:
initialstate()andgoals()return a set ofAtomobjects, not tuples. Theirreprlooks like a tuple (as shown above), but useatom.predicateto get the list of symbols. By contrast, a grounded operator'sprecondition_pos/effect_pos/etc. are real tuples.
The pddl files are examples obtained from the course material.
You can also read the domain's declared requirements:
>>> domprob.requirements()
{':strips', ':typing'}A :types hierarchy (e.g. airport - location, location - object) is
honoured: a parameter typed with a supertype binds objects of any transitive
subtype, so multi-level domains such as logistics ground and solve. The
hierarchy is also exposed directly:
>>> domprob.types() # subtype -> direct supertype
{'airport': 'location', 'location': 'object', ...}
>>> domprob.subtypes_of('object') # all transitive subtypes
{'location', 'airport', ...}Grounding is performed by a pluggable variable binder. The default
StaticPrunedBinder prunes parameter bindings that can never be applicable by
joining the operator's static preconditions (predicates no action ever
modifies) against the initial state — sound, since a static predicate's truth
is fixed for the whole search. Pass binder=CartesianBinder() for the plain
full product, or supply your own:
from pddlpy import DomainProblem
from pddlpy.binding import CartesianBinder, VariableBinder
dp = DomainProblem('domain.pddl', 'problem.pddl', binder=CartesianBinder())
class MyBinder(VariableBinder):
def bind(self, dp, operator):
# yield {param_name: object_name} dicts; helpers: dp.candidate_objects(t),
# dp.static_predicates(), dp.initialstate(), dp.worldobjects()
...
dp.binder = MyBinder()Above the parser/object model sits an optional, strictly-layered planning
package (pddlpy.planning). It imports from the object model but never from
the grammar; the object model imports nothing from it.
It provides:
State— an immutable, hashable set of ground atoms.State.from_problem(dp)builds the initial state;state.applicable(operator)andstate.apply(operator)check/advance a grounded operator without any manualAtom/tuple casting;state.satisfies(goals)tests the goal.Plan— an ordered sequence of grounded actions with acost.GroundedTask— grounds every operator once and exposes asuccessors(state)function andis_goal(state); the shared component every planner reuses.Planner— the abstract solver contract,solve(domainproblem) -> Plan | None. Each planner declarescapabilities(the:requirementsit supports) and fails fast withUnsupportedRequirementsErrorwhen handed a domain beyond its subset.registry— register and look up planners by name.- Three reference planners over STRIPS:
BFSPlanner("bfs"),AStarPlanner("astar", goal-count heuristic) andGBFSPlanner("gbfs").
Numeric fluents (:functions, numeric preconditions/effects) are supported:
DomainProblem.functions() and initial_numeric() expose them, grounded
operators carry precondition_num / effect_num, and State tracks a numeric
valuation so the planners respect constraints like (>= (fuel ?v) 10) and
effects like (decrease (fuel ?v) 5).
Action costs (:action-costs, (increase (total-cost) ...), (:metric minimize (total-cost))) are supported too. DomainProblem.metric() exposes the metric,
Plan.cost reports the accumulated total-cost, and UniformCostPlanner
("ucs") is cost-optimal — where BFSPlanner minimizes the number of actions,
"ucs" minimizes total cost.
Durative actions (:durative-actions) are recovered into a DurativeAction
type with time-tagged conditions (at start / over all / at end) and
effects (at start / at end) plus a duration. DomainProblem.durative_operators()
and ground_durative_operator(name) expose them. The reference planners are
non-temporal, so they do not solve durative domains — this is documented as out
of scope for now.
>>> import pddlpy
>>> from pddlpy.planning import get
>>> dp = pddlpy.DomainProblem('blocksworld-domain.pddl', 'blocksworld-problem.pddl')
>>> plan = get('astar').solve(dp)
>>> plan.cost
4
>>> plan.action_names()
[('pick-up', {'?x': 'b'}), ('stack', {'?x': 'b', '?y': 'c'}),
('pick-up', {'?x': 'a'}), ('stack', {'?x': 'a', '?y': 'b'})]Registering your own planner needs no changes to the layers below:
from pddlpy.planning import Planner, registry
class MyPlanner(Planner):
capabilities = frozenset({':strips', ':typing'})
def solve(self, domainproblem):
task = self.prepare(domainproblem) # runs requirement + capability checks
...
registry.register('mine', MyPlanner)
plan = registry.get('mine').solve(dp)Installing the package also installs a pddlpy command (#85) with three
subcommands, all emitting JSON on stdout — handy for shell pipelines and
for agents that shouldn't have to write Python:
pddlpy parse domain.pddl problem.pddl # object-model summary
pddlpy ground domain.pddl problem.pddl pick-up # grounded instances of one action
pddlpy solve domain.pddl problem.pddl --planner ucs
pddlpy validate domain.pddl problem.pddl # diagnostics (see below)solve defaults to astar; --planner accepts any registered planner
(bfs, astar, gbfs, ucs). Exit codes: 0 success, 1 search
completed without finding a plan / validate found issues, 2 bad input
(missing file, unknown operator, unsupported :requirements).
validate (#94) checks a pair for the mistakes that typically slip through
a bare parse — collected syntax errors (ANTLR error-recovers, so parse
alone won't stop on them), atoms over undeclared predicates, ground atoms
naming unknown objects, operators grounding to zero instances, and malformed
durative actions. It reports {valid, issues: [{severity, check, message}]}
and is designed as the feedback step of an agentic write-PDDL → validate →
fix → solve loop (e.g. translating a natural-language problem to PDDL).
$ pddlpy solve blocksworld-domain.pddl blocksworld-problem.pddl | jq .cost
4For LLMs and agents, pddlpy ships a Model Context Protocol
server (#86) exposing the same operations as tools — parse, ground,
solve and validate — with structured JSON results. It is the runtime
counterpart of the static Agent Skill in skills/pddlpy/.
pip install "pddlpy[mcp]" # the mcp SDK is an optional extra
pddlpy-mcp # runs on stdioClient configuration (e.g. Claude Desktop / Claude Code):
{
"mcpServers": {
"pddlpy": { "command": "pddlpy-mcp" }
}
}Tools take filesystem paths to the domain/problem files; solve accepts an
optional planner argument (bfs, astar, gbfs, ucs). For agents
translating natural language to PDDL, validate provides the fix-loop
feedback (syntax, undeclared predicates, unknown objects, zero groundings).
Why pair an LLM with a solver at all? LLMs translate problems into PDDL
very well but are unreliable at producing (let alone optimal) plans;
delegating the search to a classical solver combines the strengths of both.
docs/llm-interaction.md walks through a complete
worked example — natural language → PDDL → pddlpy solve → natural language —
on a small cost-optimal routing problem where the intuitive answer is wrong.
Background reading: LLM+P (arXiv:2304.11477),
the paper behind this pipeline, and PlanBench
(arXiv:2206.10498) on why direct LLM
planning falls short.
docs/object-model.md— full reference for the parser object model and the planning layer.docs/llm-interaction.md— worked example of an LLM and pddlpy dividing the work: translate, solve, translate back (#99).skills/pddlpy/SKILL.md— an Agent Skill so coding agents can drive the library (parse, ground, plan).
There are wonderful material at the the University of Edinburgh:
- AI Planning MOOC Project Home Page
- Index to access all course materials and videos
- Videos on YouTube
- A temporal planner that solves durative-action domains.
- Heuristic improvements for the reference planners.
- ADL (conditional effects, quantifiers) and a full and/or/not precondition tree.
Done recently: case-insensitive keywords, :requirements capture/enforcement,
a planner interface with BFS/A*/GBFS/UCS reference planners, numeric fluents
(:functions, numeric preconditions/effects), action costs (total-cost +
cost-aware search), durative-action recovery into the object model, and a
measured test suite with full coverage of the object model and planning layer.
In case you want to tweak the grammar, add other target languages or modify the library you will need build this project from the repository sources.
- Install uv - a fast Python package installer and resolver
- Install Python 3.11 or higher
- Install Java (required for ANTLR grammar compilation)
- Checkout the repository
- Initialize the uv environment:
uv sync - ANTLR JAR will be downloaded automatically when building
- Run
makeormake allto test grammar and run Python tests - Run
make buildto build distribution packages
make all- Run grammar tests and Python tests (default)make init- Initialize uv environmentmake test- Run Python tests onlymake build- Build distribution packages (wheel and source dist)make clean- Remove build artifactsmake demo- Run demo scriptsmake pypitest- Publish to TestPyPImake pypipublish- Publish to PyPImake help- Show all available targets
I'd appreciate any feedback you send like pull requests, bug reports, etc.
Please, use the issue tracker at will.
- Michiaki Tatsubori @tatsubori added time-duration support.
- Yichen Wei @waymao fixed an old bug.
I'm very thankful!
This project is publish under the Apache License.
For questions or requests post an issue here or tweet me at @herchu