How remykarem/py2pddl works
Project Type & Purpose
• Type: A domain-specific language (DSL) conversion tool/library.
• Purpose: Allow users to write planning problems as Python classes using decorators and type checking and then convert these definitions to standardized PDDL files used in AI planning.
• Indicators: The README explains “Python to PDDL” translation and the file tree includes a “py2pddl” module and example PDDL files alongside sample domains (aircargo, blocksworld, logistics).
High-Level Components
a. User Defined Domain & Problem Code:
• These are the classes (e.g., AirCargoDomain, AirCargoProblem) defined in user-created files (like aircargo.py in the examples).
• They embody the planning domain (with types, predicates, actions) and planning problem (with objects, init, and goal definitions) using specific decorators (@predicate, @action, @init, @goal).
b. Core py2pddl Library:
• Consists of the “py2pddl” module with key files:
• __init__.py – establishes the module.
• init.py – handles boilerplate generation (used to create template files based on user input).
• parse.py – contains the logic to parse user-defined classes and translate them.
• py2pddl.py – may contain additional helper functions relevant to the conversion process.
• This module is responsible for type checking, processing decorators, and converting the in-memory representation of the planning tasks into the textual PDDL format.
c. PDDL Generator:
• Inside the library, the conversion mechanism takes the parsed domain/problem information and formats it into two PDDL files: domain.pddl and problem.pddl.
• This generator processes attributes (e.g., types, predicates, actions, initial state, goal state) to output valid PDDL according to the PDDL 1.2 syntax.
d. Command-line Interface (CLI):
• Provides entry points such as:
• “python -m py2pddl.init aircargo.py” to generate boilerplate.
• “python -m py2pddl.parse aircargo.py” to parse the domain and problem definitions.
• The CLI acts as the user’s gateway to initialize, invoke parsing, and generate outputs.
e. Examples & Test Artifacts:
• The “pddl” folder contains examples such as aircargo, blocksworld, and logistics. These serve as validations and demonstrations of the library’s abilities.
• The generated sample files (e.g., domain.pddl, problem.pddl, and corresponding SAS plan outputs) highlight the tool’s end-to-end workflow.
Relationships & Data Flow
• The user writes planning tasks in a Python file (using the provided decorators and types).
• The CLI triggers the py2pddl module’s functions (especially the parser) which then:
– Reads the Python file.
– Recognizes the Domain and Problem definitions.
– Utilizes type checking and decorator processing to assemble the internal representation.
– Invokes methods attached to the domain (like generate_domain_pddl and generate_problem_pddl) for conversion.
• The PDDL Generator then writes out the domain.pddl and problem.pddl files.
• These outputs can be used by external planners (like Fast Downward) to compute the plan.
Architectural Patterns & Design Principles
• Modularity is a key design principle. The library separates the concerns across:
– User-defined planning definitions.
– Core parsing and conversion logic (in the py2pddl submodules).
– Example domains that prove usage.
• Decorator patterns are utilized for marking methods as predicates, actions, init, and goal definitions.
• The structure also encourages reusability as the Domain class is extended by the Problem class, ensuring consistent inheritance for method reuse (e.g., generating PDDL files).