Metadata-Version: 2.4
Name: rustforge-rl
Version: 0.1.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.21
Requires-Dist: gymnasium>=0.29 ; extra == 'gym'
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: gymnasium>=0.29 ; extra == 'test'
Requires-Dist: numpy>=1.21 ; extra == 'test'
Provides-Extra: gym
Provides-Extra: test
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: Reinforcement learning environments and agents implemented in Rust, with Gymnasium-compatible Python bindings
Keywords: reinforcement-learning,rust,gymnasium,dqn,pyo3
Home-Page: https://github.com/tjunjie1408/RustForge-RL
Author: Teo Jun Jie
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/tjunjie1408/RustForge-RL/blob/master/CHANGELOG.md
Project-URL: Homepage, https://github.com/tjunjie1408/RustForge-RL
Project-URL: Issues, https://github.com/tjunjie1408/RustForge-RL/issues
Project-URL: Repository, https://github.com/tjunjie1408/RustForge-RL

# rustforge (Python bindings)

PyO3 bindings to the RustForge RL framework: native environments and a DQN agent,
plus a Gymnasium-compatible adapter.

## Install

```bash
pip install rustforge-rl            # native environments + DQN
pip install "rustforge-rl[gym]"     # plus the Gymnasium bridge
```

The distribution is named `rustforge-rl`; the import name is `rustforge`.
Wheels are abi3 (one per platform, CPython ≥ 3.9) for Linux x86_64/aarch64,
macOS universal2, and Windows x86_64.

## Install (development)

```bash
cd crates/rustforge-python
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1   |   Unix: source .venv/bin/activate
pip install "maturin>=1.9,<2.0" pytest "gymnasium>=0.29" "numpy>=1.21"
maturin develop
```

## Usage

```python
import rustforge

# Gymnasium-style env
env = rustforge.make("CartPole")
obs, info = env.reset(seed=0)
obs, reward, terminated, truncated, info = env.step(env.action_space.sample())

# Train + run a DQN
agent = rustforge.DQN.train("cartpole", episodes=200)
action = agent.predict([float(x) for x in obs])
```

Available env ids: `CartPole`, `GridWorld`, `MountainCar`, `MountainCarContinuous`, `Pendulum`.
`DQN.train` supports the discrete envs: `"cartpole"`, `"gridworld"`, `"mountaincar"`.

## Error handling

Discrete environments (`CartPole`, `GridWorld`, `MountainCar`) validate the
`action` passed to `step`:

- An **out-of-range** action (e.g. `5` when only `0`, `1` are valid) raises
  `ValueError`.
- A **negative** action (e.g. `-1`) raises `OverflowError`, *not* `ValueError`.
  The action is a Rust `usize`, so PyO3 rejects negative integers during
  argument conversion, before the range check runs.

Continuous environments (`Pendulum`, `MountainCarContinuous`) raise
`ValueError` when the action list has the wrong length (they expect length 1).

