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

Currently the main branch is broken. I will be publishing to PyPI from this branch. While the parser does recognize durations you cannot recover these tags from Python.

What this project is not?

This library doesn't include and won't include algorithms for solutions search. There are lots of projects and complete packages for planning available. This project is just a library that provides the user a simple PDDL helper API useful when she experiments with her own planning algorithms.

Examples

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

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')}
>>>

The pddl files are examples obtained from the course material.

Other Resources

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

Future development

• Implement the :requirements directive.
• Add more examples (time durataion, a simple planner maybe?).
• Add API documentation.
• More unit tests.

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 - 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 pypitest - Publish to TestPyPI
• make pypipublish - Publish to PyPI
• make help - Show all available targets

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 added time-duration support.
• Yichen Wei @waymao fixed an old bug.

I'm very thankful!

License

This project is publish under the Apache License.

Who do I talk to?

For questions or requests post an issue here or tweet me at @herchu