pddl-lib
pddl-py (pip install pddlpy) is a PDDL toolkit for Python. It parses PDDL
domain and problem files with an ANTLR 4 grammar, builds an object model,
checks the files for common mistakes, and solves them with small reference
planners. You can drive it from Python, from the pddlpy command line, or
through an MCP server that LLM agents call as tools.
It runs on Python 3.11 and up.
Project direction
I started pddl-py in 2015 as a PDDL parser with a simple object model, so planning students and researchers could plug in their own search algorithms. That is still in here and it still works.
What changed is who calls it. LLMs now write well-formed PDDL, but they are unreliable at producing correct or optimal plans, at tracking state over many steps, and at proving that a problem has no plan. Those are exactly the jobs a PDDL tool does well. So the primary goal of pddl-py is now to be the conformant PDDL toolkit that agents call to fill those gaps: parse, validate, simulate and solve, through the CLI and the MCP server.
Researchers and app developers stay first-class users of the Python API. I am not dropping that audience, I am adding a new one and letting it set the priorities.
A few things follow from this:
- Conformance target. PDDL 1.2, 2.1, 2.2, 3.0 and 3.1. Support is partial
today, and I publish it per
:requirementskeyword indocs/pddl-support.md, including what does not work. - Priorities. I add requirements in the order that helps LLM use most.
- Not a Fast Downward competitor. The reference planners stay small and readable. Hard search will go to external solvers, not to a bigger planner inside this package.
Install
pip install pddlpy # library + `pddlpy` CLI
pip install "pddlpy[mcp]" # also the MCP server (`pddlpy-mcp`)
pddlpy has no runtime dependencies: the ANTLR runtime (4.13.2, BSD-3-Clause)
is vendored in pddlpy/_vendor/, so it does not clash with packages that pin
another antlr4-python3-runtime version. mcp is an optional extra. Java is
not needed to install or use the package.
Command-line interface
The pddlpy command has six subcommands. All of them print JSON on stdout,
so an agent or a shell pipeline can use them without writing 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)
pddlpy validate-plan domain.pddl problem.pddl plan.txt # does the plan reach the goal?
pddlpy simulate domain.pddl problem.pddl plan.txt # state after each step
solve defaults to astar. --planner takes any registered planner: bfs,
astar, gbfs, ucs or temporal. --max-expansions N and --timeout SECONDS bound the search. The result's status is solved, unsolvable
(the search space was exhausted, so no plan exists) or limit (a bound was
hit first, or temporal, which builds sequential schedules only, found
none; either way nothing is proven), and validated says whether the plan was
checked with validate-plan before being returned.
$ pddlpy solve tests/corpus/blocksworld-domain.pddl tests/corpus/blocksworld-problem.pddl | jq .cost
4
With --planner temporal each step also carries start, duration and
end, and the result has a top-level makespan:
$ pddlpy solve tests/corpus/temporal-weld-domain.pddl tests/corpus/temporal-weld-problem.pddl --planner temporal | jq -c .
{"planner":"temporal","solved":true,"cost":6.0,"makespan":6.0,"length":1,"steps":[{"action":"steady-weld","args":{"?p":"p1"},"start":0.0,"duration":6.0,"end":6.0}]}
Exit codes: 0 success, 1 the search proved there is no plan, validate
found issues, or the plan is invalid / a step cannot run, 2 bad input
(missing file, unreadable plan, unknown operator, unsupported
:requirements, or a plan pddlpy cannot judge), 3 solve hit
--max-expansions or --timeout before finding a plan.
validate-plan and simulate take a plan in the IPC format ((move a b)
per line, or 0.0: (move a b) [2.0] for durative actions) or as JSON, so
solve output pipes straight in (- reads stdin). The verdict follows VAL,
the reference plan validator, and a failure names the step, the unmet
conditions or goal atoms, and the state at that point:
$ pddlpy validate-plan domain.pddl problem.pddl guess.plan | jq -c '.failure | {kind, step, unmet}'
{"kind":"precondition","step":2,"unmet":["(road junction riverside)"]}
validate is the feedback step for a write PDDL, validate, fix, solve loop.
A bare parse is not enough because ANTLR recovers from syntax errors and only
prints them to stderr. validate collects those syntax errors and also reports
atoms over undeclared predicates, ground atoms that name unknown objects,
operators that ground to zero instances, and malformed durative actions. For
example, after a typo in a blocksworld problem (on-table instead of
ontable):
$ pddlpy validate domain.pddl problem.pddl
{
"valid": false,
"issues": [
{
"severity": "error",
"check": "undeclared_predicate",
"message": "predicate 'on-table' is not declared in :predicates (used in :init)"
}
]
}
MCP server
The Model Context Protocol server exposes
the same operations as tools: parse, ground, solve, validate,
validate_plan and simulate. They return the same JSON as the CLI; the
plan tools take the plan text instead of a file.
pip install "pddlpy[mcp]"
pddlpy-mcp # runs on stdio
It speaks MCP 2026-07-28 and the earlier protocol versions 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25, so older clients still connect.
Client configuration (e.g. Claude Desktop / Claude Code):
{
"mcpServers": {
"pddlpy": { "command": "pddlpy-mcp" }
}
}
The tools take filesystem paths to the domain and problem files. solve takes
an optional planner argument (bfs, astar, gbfs, ucs or temporal;
default astar). For an agent that translates natural language into PDDL,
validate gives the feedback for the fix loop.
For agents that work from files instead of MCP, there is also an Agent Skill in
skills/pddlpy/.
Supported :requirements
The state of the code today, checked against the parser and the planners, not a wish list, is in docs/pddl-support.md.
Python API
>>> import pddlpy
>>> domprob = pddlpy.DomainProblem('examples-pddl/domain-03.pddl', 'examples-pddl/problem-03.pddl')
>>> sorted(map(repr, domprob.initialstate()))
["('adjacent', 'loc1', 'loc2')", "('adjacent', 'loc2', 'loc1')", "('atl', 'robq', 'loc2')", "('atl', 'robr', 'loc1')", "('in', 'conta', 'loc1')", "('in', 'contb', 'loc2')", "('unloaded', 'robq')", "('unloaded', 'robr')"]
>>> list(domprob.operators())
['move', 'load', 'unload']
>>> moves = sorted(domprob.ground_operator('move'), key=lambda op: sorted(op.variable_list.items()))
>>> len(moves)
4
>>> moves[0].variable_list
{'?from': 'loc1', '?to': 'loc2', '?r': 'robq'}
>>> sorted(moves[0].precondition_pos)
[('adjacent', 'loc1', 'loc2'), ('atl', 'robq', 'loc1')]
>>> sorted(domprob.requirements())
[':strips', ':typing']
Note:
initialstate()andgoals()return a set ofAtomobjects, not tuples. Theirreprlooks like a tuple, butAtomhas no value equality: useatom.predicateto get the list of symbols, orpddlpy.planning.atom_tupleto compare. A grounded operator'sprecondition_pos/effect_pos/ etc. are real tuples.
The files in examples-pddl/ come from the course material
mentioned in History.
Type hierarchies and variable binding
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:
>>> dp = pddlpy.DomainProblem('tests/corpus/logistics-domain.pddl', 'tests/corpus/logistics-problem.pddl')
>>> dp.types() # subtype -> direct supertype
{'truck': 'vehicle', 'airplane': 'vehicle', 'package': 'physobj', 'vehicle': 'physobj', 'airport': 'location', 'city': 'object', 'location': 'object', 'physobj': 'object'}
>>> sorted(dp.subtypes_of('object')) # all transitive subtypes
['airplane', 'airport', 'city', 'location', 'package', 'physobj', 'truck', 'vehicle']
A pluggable variable binder does the grounding. The default
StaticPrunedBinder drops parameter bindings that can never apply, by joining
the operator's static preconditions (predicates no action changes) against
the initial state. That is sound because a static predicate's truth never
changes during search. It is why move above grounds to 4 instances instead
of the 8 of the full product. Pass binder=CartesianBinder() for the 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()
Planning API
The planning package (pddlpy.planning) sits on top of the object model. It
imports the object model but never the grammar, and the object model imports
nothing from it.
It provides:
State: an immutable, hashable set of ground atoms plus a numeric valuation.State.from_problem(dp)builds the initial state;state.applicable(operator)andstate.apply(operator)check and advance a grounded operator without manualAtom/tuple casting;state.satisfies(goals)tests the goal.Plan: an ordered sequence of grounded actions with acost.GroundedTask: grounds every operator once and exposessuccessors(state)andis_goal(state). Every planner reuses it.Planner: the abstract solver contract,solve(domainproblem) -> Plan | None. Each planner declarescapabilities(the:requirementsit supports) and fails fast withUnsupportedRequirementsErrorwhen handed a domain beyond them.registry: register and look up planners by name.- Five reference planners:
BFSPlanner("bfs", fewest actions),AStarPlanner("astar", fewest actions, admissible heuristic),GBFSPlanner("gbfs", greedy),UniformCostPlanner("ucs", cost-optimal) andTemporalPlanner("temporal", durative actions).
>>> from pddlpy.planning import get
>>> dp = pddlpy.DomainProblem('tests/corpus/blocksworld-domain.pddl', 'tests/corpus/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'})]
Numeric fluents: DomainProblem.functions() and initial_numeric() expose
them, grounded operators carry precondition_num / effect_num, and State
tracks the numeric valuation, so the planners respect constraints like
(>= (fuel ?v) 10) and effects like (decrease (fuel ?v) 5).
Action costs: DomainProblem.metric() exposes the metric and Plan.cost
reports the accumulated total-cost. bfs minimizes the number of actions;
ucs minimizes total cost.
Durative actions are parsed into a DurativeAction with time-tagged
conditions (at start / over all / at end), effects (at start /
at end) and a duration. DomainProblem.durative_operators() and
ground_durative_operator(name) expose them. The temporal planner solves
these domains. It checks at start conditions at the start point, over all
as an invariant across the duration, and at end at start + duration, under
sequential semantics: actions never overlap, and instantaneous actions run as
zero-duration steps. It returns a TemporalPlan whose steps carry start
times and durations, and whose makespan is the plan cost. See the
requirements table for its limits.
>>> dp = pddlpy.DomainProblem('tests/corpus/temporal-weld-domain.pddl', 'tests/corpus/temporal-weld-problem.pddl')
>>> plan = get('temporal').solve(dp)
>>> plan.makespan
6.0
>>> [(s.start, s.action.operator_name, s.duration) for s in plan.steps]
[(0.0, 'steady-weld', 6.0)]
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)
Examples
The examples/ directory has self-contained, runnable scripts
of increasing complexity. Each one shows 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. To solve durative domains use the temporal planner (see Planning API) |
Durative actions (#23) |
More PDDL pairs for testing live in examples-pddl/ and
tests/corpus/.
Documentation
docs/object-model.md: full reference for the object model and the planning layer.docs/pddl-support.md: what each:requirementskeyword supports today, and the known bugs.docs/llm-interaction.md: worked example of an LLM and pddlpy splitting the work: translate, solve, translate back (#99).skills/pddlpy/SKILL.md: an Agent Skill so coding agents can drive the library and the CLI.
Roadmap
These are plans, not promises, and there are no dates. Roughly in order:
Vendor the ANTLR runtime sopip install pddlpyhas zero runtime dependencies.An oracle test harness against Fast Downward, VAL and INVAL on the IPC corpora.Plan validation and plan simulation with structured diagnostics.- Decide whether to keep ANTLR or replace the parser, before the grammar grows.
- Requirements by priority: goal-side ADL and
(either ...), timed initial literals, derived predicates, preferences, concurrent durative actions, trajectory constraints. - Continuous effects, object fluents.
- HDDL / HTN.
History and acknowledgments
pddl-py started in 2015, inspired by the University of Edinburgh's Artificial Intelligence Planning MOOC by Dr. Gerhard Wickler and Prof. Austin Tate. The terms in the object model API (and the API itself) closely follow the ones the lecturers used.
The original grammar was written by Zeyn Saigol from the University of Birmingham. I cleaned it up, made it language agnostic and upgraded it to ANTLR 4.
The Edinburgh course material is still worth your time:
- AI Planning MOOC Project Home Page
- Index to access all course materials and videos
- Videos on YouTube
Contributors:
- Michiaki Tatsubori @tatsubori added time-duration support.
- Yichen Wei @waymao fixed an old bug.
I'm very thankful!
Building from source
You only need this to change the grammar, add other target languages or work on the library itself. Installing and using the package needs none of it.
Prerequisites
- uv
- Python 3.11 or higher
- Java, only to change the grammar. The generated parser files are committed, so a fresh clone runs the tests without Java.
Building
- Clone the repository.
- Run
uv syncto set up the environment. - Run
make testto run the Python tests. - After changing
pddl.g4, runmake pyparserto regenerate the parser intopddlpy/(it downloads the ANTLR jar), and commit the regenerated files. CI fails if they don't match the grammar. - Run
make(ormake all) to test the grammar (needs Java andjavac) and run the Python tests. - Run
make buildto build the wheel and sdist.
Available Make Targets
make all- Run grammar tests and Python tests (default)make init- Initialize uv environmentmake pyparser- Generate the Python parser frompddl.g4(needs Java)make test- Run Python tests onlymake coverage- Run tests with a coverage reportmake lint- Lint with ruffmake typecheck- Type-check with mypymake build- Build distribution packages (wheel and source dist)make examples- Run the example showcasemake clean- Remove build artifactsmake demo- Run demo scriptsmake help- Show all available targets
Publishing to PyPI happens only in GitHub Actions when a v* tag is pushed
(TestPyPI first, then PyPI, via Trusted
Publishing). See
.github/workflows/publish.yaml. CI (tests,
100% coverage gate, lint, typecheck) runs on every pull request.
Contribution guidelines
Feedback is really appreciated. Since code is, regrettably, free now, I prefer you contact through the issue tracker instead of PRs.
License
This project is published under the Apache License.
Who do I talk to?
For questions or requests post an issue here.
Metadata
Release files for pddlpy 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pddlpy-1.3.0.tar.gz | 222.1 kB | With provenance | Details for pddlpy-1.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pddlpy-1.3.0-py3-none-any.whl | Python 3 | none | any | Details for pddlpy-1.3.0-py3-none-any.whl |
Total release size: 489.4 kB
Release files / pddlpy-1.3.0.tar.gz
| Download URL | pddlpy-1.3.0.tar.gz |
|---|---|
| Size | 222.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6444e1e60763f746b24504f5d30b57607d12cf8a225f3cc3db22bef359903fce
|
|
BLAKE2b-256 checksum How to use checksums |
aaede4d51fb98a2dfb92cbec07304b1bbeb92f4a0ab59883134f1abb2c9ab1d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / pddlpy-1.3.0-py3-none-any.whl
| Download URL | pddlpy-1.3.0-py3-none-any.whl |
|---|---|
| Size | 267.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e893a337e2f2d95422b238d16001eef10a039a62b702689f7f3442ffa9d96e8d
|
|
BLAKE2b-256 checksum How to use checksums |
7f9e72d4a4268357de0eee0b866b24328ffd3caac3bcbd828c4bfda4ff4f33ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for pddlpy 1.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pddlpy-1.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.