# remykarem/py2pddl architecture

> Architecture diagram of the GitHub repository remykarem/py2pddl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/remykarem/py2pddl
- Repository: https://github.com/remykarem/py2pddl

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Defined Domain & Problem
    subgraph "User Defined Domain & Problem"
        U1("AirCargo Domain & Problem"):::user
        U2("Blocksworld Domain & Problem"):::user
        U3("Logistics Domain & Problem"):::user
    end

    %% CLI Interface
    CLI("CLI Interface"):::cli

    %% py2pddl Module
    subgraph "py2pddl Module"
        P1("__init__.py"):::library
        P2("init.py"):::library
        P3("parse.py"):::library
        P4("py2pddl.py"):::library
    end

    %% PDDL Generator
    PG("PDDL Generator"):::generator

    %% Generated PDDL Files
    Gen("Generated PDDL Files"):::pddlFiles

    %% External Planner Integration
    EP("External Planner Integration"):::external

    %% Project Metadata
    subgraph "Project Metadata"
        M1("README.md"):::metadata
        M2("requirements.txt"):::metadata
        M3("setup.py"):::metadata
    end

    %% Data Flow Connections
    CLI -->|"invokes"| P2
    CLI -->|"invokes"| P3
    U1 -->|"defines"| P3
    U2 -->|"defines"| P3
    U3 -->|"defines"| P3
    P3 -->|"converts"| PG
    PG -->|"outputs to"| Gen
    Gen -->|"used by"| EP

    %% Additional Connection: py2pddl Module integration
    P1 --> P2
    P2 --> P3
    P3 --> P4

    %% Styles
    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef library fill:#bbf,stroke:#333,stroke-width:2px;
    classDef user fill:#cfc,stroke:#333,stroke-width:2px;
    classDef generator fill:#f66,stroke:#333,stroke-width:2px;
    classDef pddlFiles fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#9cf,stroke:#333,stroke-width:2px;
    classDef metadata fill:#ccc,stroke:#333,stroke-width:2px;

    %% Click Events for User Defined Domain & Problem
    click U1 "https://github.com/remykarem/py2pddl/blob/master/pddl/aircargo.py"
    click U2 "https://github.com/remykarem/py2pddl/blob/master/pddl/blocksworld.py"
    click U3 "https://github.com/remykarem/py2pddl/blob/master/pddl/logistics.py"
    
    %% Click Events for py2pddl Module
    click P1 "https://github.com/remykarem/py2pddl/blob/master/py2pddl/__init__.py"
    click P2 "https://github.com/remykarem/py2pddl/blob/master/py2pddl/init.py"
    click P3 "https://github.com/remykarem/py2pddl/blob/master/py2pddl/parse.py"
    click P4 "https://github.com/remykarem/py2pddl/blob/master/py2pddl/py2pddl.py"
    
    %% Click Events for Project Metadata
    click M1 "https://github.com/remykarem/py2pddl/blob/master/README.md"
    click M2 "https://github.com/remykarem/py2pddl/blob/master/requirements.txt"
    click M3 "https://github.com/remykarem/py2pddl/blob/master/setup.py"
```
