Metadata-Version: 2.4
Name: i151-arena-sdk
Version: 0.2.1
Summary: SDK étudiant pour la compétition IA i151
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: i151-engine>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: ml
Requires-Dist: numpy>=1.26; extra == "ml"

# i151-arena-sdk

SDK étudiant pour la [compétition IA i151](https://i151.djamma.dev) — développez, testez et emballez votre bot **sans cloner le dépôt**.

Le moteur de jeu [`i151-engine`](https://pypi.org/project/i151-engine/) est installé automatiquement.

**Prérequis** : Python 3.11+

## Installation

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install i151-arena-sdk
```

Vérifier :

```bash
arena --help
```

Option ML local : `pip install "i151-arena-sdk[ml]"` (ajoute `numpy`).

## Démarrage rapide

```bash
arena init mon-bot
cd mon-bot
pip install -r requirements.txt
arena test bot.py
arena match bot.py --vs random --seed 42
arena pack .
```

`arena pack` produit un ZIP prêt pour le dashboard ([inscription](https://i151.djamma.dev) → upload).

## Interface bot

Votre `bot.py` doit définir :

```python
from arena_sdk import PlayerView, Action

def decide(view: PlayerView, legal_actions: list[Action], time_left_ms: int) -> Action:
    return legal_actions[0]
```

Fonctions optionnelles pour charger un modèle ML :

```python
from pathlib import Path

def setup(submission_dir: Path) -> None:
    ...

def teardown() -> None:
    ...
```

Retournez **toujours** une action de `legal_actions`, sinon forfait.

## CLI

| Commande | Description |
|----------|-------------|
| `arena init [dossier]` | Créer un projet (`bot.py`, `requirements.txt`, …) |
| `arena test bot.py` | Smoke test vs `builtin:random` |
| `arena match bot.py --vs random` | Match complet (jusqu'à 151 pts) |
| `arena match bot.py --vs basic` | Affronter l'exemple glouton |
| `arena match bot.py --replay-out replay.json` | Enregistrer le replay JSON |
| `arena pack .` | ZIP de soumission (`bot.py` + imports locaux + requirements + modèles) |
| `arena pack . --entry ml_bot.py --model champion.pt` | Entry et modèle explicites (`champion.pt` → `model.pt` dans le ZIP) |

Options utiles pour `arena match` : `--seed`, `--target-score`, `--cards-per-player`, `--json`.

## Exemples inclus dans le package

| Alias | Description |
|-------|-------------|
| `starter` | Première action légale |
| `basic` | Heuristique gloutonne |

```bash
arena test starter
arena match basic --vs random --seed 42
```

Adversaires CLI : `random`, `starter`, `basic`, `builtin:random`, ou chemin vers `bot.py`.

## ML (local)

```python
from arena_sdk.features import encode_view, action_from_index
```

Entraînement en local ; seule l'**inférence** est autorisée en match. Packages pip autorisés : voir la [whitelist](https://i151.djamma.dev/docs/whitelist).

## API réexportée

Depuis `i151-engine` : `PlayerView`, `Action`, `ActionType`, `MatchConfig`, `MatchResult`, `play_match`.

## Documentation

| Ressource | Lien |
|-----------|------|
| Plateforme (inscription, matchs, ELO) | [i151.djamma.dev](https://i151.djamma.dev) |
| Tutoriel complet | [docs/tutorial](https://i151.djamma.dev/docs/tutorial) |
| Règlement | [docs/reglement](https://i151.djamma.dev/docs/reglement) |
| Architecture (`PlayerView`, replays) | [docs/architecture](https://i151.djamma.dev/docs/architecture) |

## Classement

Les matchs contre `builtin:random` ne comptent pas au classement (calibration). Les matchs **bot vs bot** entre équipes sont notés (Elo initial 1500).
