Metadata-Version: 2.4
Name: pddlpy
Version: 1.1.2
Summary: Python PDDL parser
Project-URL: Homepage, https://github.com/hfoffani/pddl-lib
Project-URL: Repository, https://github.com/hfoffani/pddl-lib
Project-URL: Issues, https://github.com/hfoffani/pddl-lib/issues
Author-email: Hernan Foffani <hfoffani@gmail.com>
License: MIT
License-File: LICENSE.txt
Keywords: parser,pddl,planning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: antlr4-python3-runtime==4.13.2
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Description-Content-Type: text/markdown

## pddl-lib ##

### Description ###

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.

### NOTICE ###

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.

### What this project is not? ###

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.

### Examples ###

In this repostory you'll find some PDDL examples files useful for testing purposes.
For instance, [domain-03.pddl](examples-pddl/domain-03.pddl)
and [problem-03.pddl](examples-pddl/problem-03.pddl)

#### Example showcase

The [`examples/`](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/`](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](examples/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](examples/02_type_hierarchy.py) | Multi-level `:types`, `types()` / `subtypes_of()`, supertype binding in grounding | Type hierarchies (#22) |
| 03 | [03_logical_operators.py](examples/03_logical_operators.py) | Top-level `and` / `or` connective and negative preconditions in the model | Logical operators (#13) |
| 04 | [04_planners.py](examples/04_planners.py) | The planner registry and BFS / A\* reference planners solving blocksworld and gripper | Planners (#1) |
| 05 | [05_numeric_and_costs.py](examples/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](examples/06_durative.py) | Durative model, `DurativeState` `at start` applicability and validation — **not** temporally solved | Durative actions (#23) |

### Using the PDDL Python library ###

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()` and `goals()` return a set of `Atom` objects, not
> tuples. Their `repr` looks like a tuple (as shown above), but use
> `atom.predicate` to get the list of symbols. By contrast, a *grounded*
> operator's `precondition_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:

```python
>>> domprob.requirements()
{':strips', ':typing'}
```

#### 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:

```python
>>> 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:

```python
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 ###

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)` and
  `state.apply(operator)` check/advance a grounded operator without any 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 a `successors(state)`
  function and `is_goal(state)`; the shared component every planner reuses.
* `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 its subset.
* `registry` — register and look up planners by name.
* Three reference planners over STRIPS: `BFSPlanner` (`"bfs"`), `AStarPlanner`
  (`"astar"`, goal-count heuristic) and `GBFSPlanner` (`"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.

```python
>>> 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:

```python
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)
```

### Command-line interface ###

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:

```bash
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).

```bash
$ pddlpy solve blocksworld-domain.pddl blocksworld-problem.pddl | jq .cost
4
```

### MCP server ###

For LLMs and agents, pddlpy ships a [Model Context Protocol](https://modelcontextprotocol.io)
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/`](skills/pddlpy/SKILL.md).

```bash
pip install "pddlpy[mcp]"    # the mcp SDK is an optional extra
pddlpy-mcp                   # runs on stdio
```

Client configuration (e.g. Claude Desktop / Claude Code):

```json
{
  "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`](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](https://arxiv.org/abs/2304.11477)),
the paper behind this pipeline, and *PlanBench*
([arXiv:2206.10498](https://arxiv.org/abs/2206.10498)) on why direct LLM
planning falls short.

### Documentation ###

* [`docs/object-model.md`](docs/object-model.md) — full reference for the
  parser object model and the planning layer.
* [`docs/llm-interaction.md`](docs/llm-interaction.md) — worked example of an
  LLM and pddlpy dividing the work: translate, solve, translate back (#99).
* [`skills/pddlpy/SKILL.md`](skills/pddlpy/SKILL.md) — an Agent Skill so coding
  agents can drive the library (parse, ground, plan).

### Other Resources ###

There are wonderful material at the the University of Edinburgh:
* [AI Planning MOOC Project Home Page](http://www.aiai.ed.ac.uk/project/plan/ooc)
* [Index to access all course materials and videos](http://media.aiai.ed.ac.uk/Project/AIPLAN)
* [Videos on YouTube](http://bit.ly/aiplanmooc)

### Future development ###

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

### Advanced ###

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.

#### Prerequisites

* Install [uv](https://docs.astral.sh/uv/) - a fast Python package installer and resolver
* Install Python 3.11 or higher
* Install Java (required for ANTLR grammar compilation)

#### Building

* Checkout the repository
* Initialize the uv environment: `uv sync`
* ANTLR JAR will be downloaded automatically when building
* Run `make` or `make all` to test grammar and run Python tests
* Run `make build` to build distribution packages

#### Available Make Targets

* `make all` - Run grammar tests and Python tests (default)
* `make init` - Initialize uv environment
* `make test` - Run Python tests only
* `make build` - Build distribution packages (wheel and source dist)
* `make clean` - Remove build artifacts
* `make demo` - Run demo scripts
* `make help` - Show all available targets

Publishing to PyPI is done exclusively by GitHub Actions when a `v*` tag is
pushed (TestPyPI first, then PyPI, via [Trusted
Publishing](https://docs.pypi.org/trusted-publishers/)) — see
[`.github/workflows/publish.yaml`](.github/workflows/publish.yaml). CI (tests,
100%-coverage gate, lint, typecheck) runs on every pull request.

### Contribution guidelines ###

I'd appreciate any feedback you send like pull requests, bug reports, etc.

Please, use the issue tracker at will.

### Acknowledgments

* Michiaki Tatsubori [@tatsubori](https://github.com/tatsubori) added time-duration support.
* Yichen Wei [@waymao](https://github.com/waymao) fixed an old bug.

I'm very thankful!

### License ###

This project is publish under the
[Apache License](http://www.apache.org/licenses/LICENSE-2.0).

### Who do I talk to? ###

For questions or requests post an issue here or tweet me at
[@herchu](http://twitter.com/herchu)