Skip to main content

pddl-lib

codecov CodeRabbit Pull Request Reviews

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 :requirements keyword in docs/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() and goals() return a set of Atom objects, not tuples. Their repr looks like a tuple, but Atom has no value equality: use atom.predicate to get the list of symbols, or pddlpy.planning.atom_tuple to compare. A grounded operator's precondition_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) and state.apply(operator) check and advance a grounded operator without manual Atom/tuple casting; state.satisfies(goals) tests the goal.
  • Plan: an ordered sequence of grounded actions with a cost.
  • GroundedTask: grounds every operator once and exposes successors(state) and is_goal(state). Every planner reuses it.
  • Planner: the abstract solver contract, solve(domainproblem) -> Plan | None. Each planner declares capabilities (the :requirements it supports) and fails fast with UnsupportedRequirementsError when 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) and TemporalPlanner ("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

Roadmap

These are plans, not promises, and there are no dates. Roughly in order:

  1. Vendor the ANTLR runtime so pip install pddlpy has zero runtime dependencies. done
  2. An oracle test harness against Fast Downward, VAL and INVAL on the IPC corpora. done
  3. Plan validation and plan simulation with structured diagnostics. done
  4. Decide whether to keep ANTLR or replace the parser, before the grammar grows.
  5. Requirements by priority: goal-side ADL and (either ...), timed initial literals, derived predicates, preferences, concurrent durative actions, trajectory constraints.
  6. Continuous effects, object fluents.
  7. 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:

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 sync to set up the environment.
  • Run make test to run the Python tests.
  • After changing pddl.g4, run make pyparser to regenerate the parser into pddlpy/ (it downloads the ANTLR jar), and commit the regenerated files. CI fails if they don't match the grammar.
  • Run make (or make all) to test the grammar (needs Java and javac) and run the Python tests.
  • Run make build to build the wheel and sdist.

Available Make Targets

  • make all - Run grammar tests and Python tests (default)
  • make init - Initialize uv environment
  • make pyparser - Generate the Python parser from pddl.g4 (needs Java)
  • make test - Run Python tests only
  • make coverage - Run tests with a coverage report
  • make lint - Lint with ruff
  • make typecheck - Type-check with mypy
  • make build - Build distribution packages (wheel and source dist)
  • make examples - Run the example showcase
  • make clean - Remove build artifacts
  • make demo - Run demo scripts
  • make 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)

Source distribution for pddlpy 1.3.0
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)

Table of built distributions (wheels) for pddlpy 1.3.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page