Metadata-Version: 2.4
Name: numeric-pddl-gym
Version: 1.2.0
Summary: Convert a Numeric PDDL domain into an Gymnasium environment
Project-URL: Homepage, https://github.com/SPL-BGU/NumericPDDLGym
Author: Yarin Benyamin
License: Apache-2.0
License-File: LICENSE
Keywords: gym,pddl,planning,reinforcement-learning
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: anytree==2.13.0
Requires-Dist: dm-tree==0.1.9
Requires-Dist: gymnasium~=1.2.1
Requires-Dist: networkx==3.5
Requires-Dist: pddl-plus-parser==3.17.0
Requires-Dist: scipy==1.16.3
Requires-Dist: sympy==1.14.0
Provides-Extra: rl-agents
Requires-Dist: lz4; extra == 'rl-agents'
Requires-Dist: ray[tune]==2.50.1; extra == 'rl-agents'
Requires-Dist: torch==2.9.0; extra == 'rl-agents'
Description-Content-Type: text/markdown

<h1 align="center">Numeric PDDLGym</h1>
<p align="center">
<a href="https://www.python.org/downloads/release/python-31212/"><img alt="Python Version" src="https://img.shields.io/badge/python-3.12-blue"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>

A framework for automatically translating Numeric PDDL domains with the [Gymnasium API](https://gymnasium.farama.org/index.html).
This allows Numeric PDDL planning problems to be solved using standard RL algorithms (e.g., PPO via RLlib).

The environment converts states, actions, and goals from Numeric PDDL into fixed-size numeric vectors, enabling direct integration with deep RL libraries.


## ✨ Features

- Supports **Numeric PDDL domains and problems**
- Automatic grounding and vectorization of:
  - Predicates
  - Numeric fluents
  - Goal conditions
- Compatible with the **Gymnasium API**
- Designed for **[RLlib (Ray)](https://docs.ray.io/en/latest/rllib/index.html)** integration
- Works with standard deep RL algorithms (e.g., PPO)

## ⚙️ Configuration

The environment is configured via a dictionary (`env_config`).

| Parameter | Type | Relevant Env | Description |
|----------|------|--------------|------------|
| `domain_path` | `Path` | All | Path to the PDDL domain file |
| `problems_list` | `List[Path]` | All | List of problem files |
| `max_steps` | `int` | All | Max steps per episode |
| `executing_algorithm` | `str` | All | Name of RL algorithm (e.g., `"PPO"`) |
| `masking_strategy` | `"pre"` or `"post"` | PDDLMaskedEnv | `"pre"`: Filters invalid actions before execution using PDDL checks.<br>`"post"`: Learns invalid actions after execution from feedback. |
| `count_inapplicable` | `bool` | PDDLMaskedEnv | Relevant when using `"post"` masking.<br>If `true`, inapplicable actions count toward the episode length; if `false`, they are ignored. |
| `map_size` | `int` | MinecraftEnv | Grid size, e.g., 6, 10, 15. |

## 🚀 Installation

```
pip install numeric_pddl_gym
```

With RL (RLlib + Torch):

```
pip install numeric_pddl_gym[rl_agents]
```

## ▶️ Run Example

### RL Agent
```
python rl_agents/ppo_pddl_rllib_agent.py
```

### Planning Agent

See example for a planning-based agent in:
```
test/test_fixed_script_agent.py
```

## ⚠️ Limitations

1. Can't encode complex goal conditions.
2. Agents must be retrained if the problem has a different number of fluents, predicates, or goal conditions.
3. Currently does not support manual interaction with the environment.
4. Designed for fixed-structure problems (no variable-sized domains).
5. Enabling action applicability checking leads to slow runtime in large-scale problems.


## 📚 Citations

Coming soon