Metadata-Version: 2.4
Name: poke-player
Version: 0.2.1
Summary: AI-powered Pokemon gameplay agent with headless emulation, REST API, and live dashboard.
Author-email: KevRojo <meikerrd@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/KevRojo/poke-player
Project-URL: Repository, https://github.com/KevRojo/poke-player
Project-URL: Issues, https://github.com/KevRojo/poke-player/issues
Keywords: pokemon,ai,agent,emulator,gameboy,gba,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: pyboy
Requires-Dist: pyboy>=2.0.0; extra == "pyboy"
Provides-Extra: pygba
Requires-Dist: pygba>=0.1.0; extra == "pygba"
Provides-Extra: dashboard
Requires-Dist: aiofiles>=23.0.0; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: httpx>=0.25.0; extra == "dev"
Provides-Extra: all
Requires-Dist: poke-player[dashboard,pyboy]; extra == "all"
Dynamic: license-file

# 🎮 poke-player

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

> **AI-powered Pokémon gameplay agent** with headless emulation, REST API, and live dashboard.

Control Pokémon games (Game Boy / GBA) programmatically via HTTP API, read live game state from emulator RAM, and watch the AI play through a real-time web dashboard.

---

## ✨ Features

- 🕹️ **Headless Emulation** — PyBoy (GB/GBC) and PyGBA (GBA) backends
- 🧠 **Live Memory Reading** — Extract player data, party Pokémon, battle state, bag items, map position, and story flags directly from RAM
- 🌐 **REST API + WebSocket** — Control the emulator via HTTP and receive real-time state updates
- 📊 **Live Dashboard** — Beautiful cyberpunk-themed web UI with game screen, team stats, battle info, and AI action log
- 🔍 **A* Pathfinding** — Grid-based navigation with collision map support
- 💾 **Save States** — Named save/load slots for quick experimentation
- 📸 **Screenshots** — Capture PNG frames on demand

---

## 🚀 Quick Start

### Installation

```bash
# Basic install (PyBoy for GB/GBC)
pip install poke-player

# With GBA support
pip install "poke-player[pyboy,pygba]"

# With dashboard
pip install "poke-player[dashboard]"

# Everything
pip install "poke-player[all]"
```

### Start the Server

```bash
poke-player serve --rom path/to/red.gb --port 8765
```

### View the Dashboard

Open http://localhost:8765/dashboard in your browser.

---

## 🛠️ CLI Usage

```bash
# Start server
poke-player serve --rom red.gb --data-dir ~/.poke-player

# Show ROM info
poke-player info --rom red.gb

# Get current game state
poke-player state

# Press buttons
poke-player action a
poke-player action "up,up,a,b"

# Save / load state
poke-player save before_gym
poke-player load before_gym
poke-player saves

# Screenshot
poke-player screenshot --out frame.png

# Minimap
poke-player minimap

# Stop server
poke-player stop
```

---

## 🔌 API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Server health check |
| `GET` | `/state` | Full game state JSON |
| `GET` | `/state/summary` | Human-readable state summary |
| `POST` | `/action` | Press buttons (`{"actions": ["a"]}`) |
| `POST` | `/save` | Save state (`{"name": "slot1"}`) |
| `POST` | `/load` | Load state (`{"name": "slot1"}`) |
| `GET` | `/saves` | List save slots |
| `GET` | `/screenshot` | PNG screenshot (base64 or raw) |
| `GET` | `/minimap` | Explored area minimap |
| `GET` | `/info` | ROM metadata |
| `WS` | `/ws` | WebSocket for live updates |

---

## 🏗️ Architecture

```
┌─────────────┐     HTTP/WS      ┌──────────────┐     ┌─────────────┐
│   Dashboard │ ◄──────────────► │  FastAPI     │ ◄──►│   PyBoy     │
│  (Browser)  │                  │   Server     │     │  / PyGBA    │
└─────────────┘                  └──────────────┘     └─────────────┘
                                        │
                                        ▼
                              ┌──────────────────┐
                              │  Memory Reader   │
                              │  (Red/FireRed)   │
                              └──────────────────┘
```

---

## 🧪 Development

```bash
# Clone
git clone https://github.com/KevRojo/poke-player.git
cd poke-player

# Install in editable mode
pip install -e ".[all,dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=poke_player

# Lint
ruff check .
```

---

## 🗺️ Supported Games

| Game | Platform | Status | Reader |
|------|----------|--------|--------|
| Pokémon Red/Blue | Game Boy | ✅ Complete | `memory/red.py` |
| Pokémon FireRed | GBA | 🚧 Stub | `memory/firered.py` |

---

## 📁 Project Structure

```
poke_player/
├── cli.py           # Command-line interface
├── server.py        # FastAPI HTTP/WebSocket server
├── emulator.py      # Emulator wrapper (PyBoy / PyGBA)
├── pathfinding.py   # A* tile navigation
├── memory/
│   ├── reader.py    # Abstract memory reader
│   ├── red.py       # Pokémon Red/Blue reader
│   └── firered.py   # FireRed reader (Phase 2)
├── state/
│   └── builder.py   # Game state assembly
└── dashboard/
    └── static/      # Web dashboard (HTML/CSS/JS)
```

---

## 🤝 Contributing

Contributions welcome! Please open an issue or PR.

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

---

## 📜 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- Memory addresses from [pret/pokered](https://github.com/pret/pokered)
- Emulator backends: [PyBoy](https://github.com/Baekalfen/PyBoy), [PyGBA](https://github.com/mattbruv/PyGBA)

---

<p align="center">
  <i>Made with 💜 by KevRojo</i>
</p>
