Metadata-Version: 2.4
Name: ahu-dts307tc-toolkit
Version: 0.1.0
Summary: Shared utilities for DTS307TC reinforcement learning coursework.
Project-URL: Homepage, https://github.com/SiriusAhu/ahu_dts307tc_toolkit
Project-URL: Repository, https://github.com/SiriusAhu/ahu_dts307tc_toolkit
Author-email: SiriusAhu <SiriusLLLUUU@gmail.com>
License-File: LICENSE
Keywords: coursework,dqn,ppo,reinforcement-learning,tensorboard
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: gymnasium[box2d]>=1.0.0
Requires-Dist: loguru>=0.7
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python>=4.8
Requires-Dist: tensorboard>=2.14
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=6.1.0; extra == 'dev'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Requires-Dist: seaborn>=0.13; extra == 'viz'
Description-Content-Type: text/markdown

# ahu-dts307tc-toolkit

Shared building blocks that are reusable across `DTS307TC` Coursework 1 and Coursework 2.

## Scope

This package only contains logic that can serve both coursework projects, such as:

- environment helpers and pixel preprocessing,
- shared neural-network building blocks,
- PPO and DQN data buffers,
- TensorBoard logging and scalar readers,
- plotting helpers,
- evaluation export utilities,
- video generation helpers,
- general utility functions such as checkpointing, config loading, device selection, and seeding.

It does **not** contain coursework-specific training orchestration or report logic.

## Install

From PyPI:

```bash
pip install ahu-dts307tc-toolkit
```

For local development:

```bash
uv sync --extra dev
```

## Package Layout

| Module | Contents |
|--------|----------|
| `env` | generic `make_pixel_env`, `make_carracing_env`, pixel wrappers, `RecordEpisodeStats` |
| `models` | `NatureCNN`, `SmallCNN`, `EnhancedCNN`, MLP blocks, policy/value and Q-network heads |
| `buffers` | `RolloutBuffer` for PPO and `ReplayBuffer` for DQN |
| `logging` | TensorBoard logger and metric helpers |
| `evaluation` | deterministic evaluation, TensorBoard scalar readers, CSV/JSON export |
| `viz` | plotting helpers for coursework experiments |
| `media` | video rendering and export helpers |
| `utils` | TOML loading, checkpoint I/O, seeding, device helpers |

## Release Workflow

This package is prepared for PyPI Trusted Publishing through GitHub Actions.

Release flow:

1. bump `version` in `pyproject.toml` and `src/ahu_dts307tc_toolkit/__init__.py`
2. commit and push
3. create a tag like `v0.1.0`
4. push the tag
5. GitHub Actions publishes the build to PyPI

The publishing workflow is defined in `.github/workflows/publish.yml`.
