i151-arena-sdk 0.2.0__tar.gz

i151_arena_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: i151-arena-sdk
+Version: 0.2.0
+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
+
+Package installable pour développer et tester un bot i151 en local, **sans cloner le dépôt complet**.
+
+## Installation
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install i151-arena-sdk
+```
+
+En développement (monorepo) :
+
+```bash
+cd arena/engine && pip install -e ".[dev]"
+cd ../sdk && pip install -e ".[dev]"
+```
+
+## 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
+```
+
+## Exemples publics (inclus dans le package)
+
+| Alias CLI | Description |
+|-----------|-------------|
+| `starter` | Première action légale |
+| `basic` | Heuristique gloutonne |
+
+```bash
+arena test starter
+arena match basic --vs random --seed 42
+```
+
+Les bots avancés (MinMax, MCTS, RL, PPO) restent dans le monorepo pour le développement interne et ne sont **pas** publiés sur PyPI.
+
+## Interface bot
+
+```python
+from arena_sdk import PlayerView, Action
+
+def decide(view: PlayerView, legal_actions: list[Action], time_left_ms: int) -> Action:
+    return legal_actions[0]
+```
+
+## CLI
+
+```bash
+arena init mon-bot              # créer un projet
+arena test bot.py               # smoke test vs random
+arena match bot.py --vs random  # match complet
+arena match bot.py --vs basic   # affronter l'exemple glouton
+arena match bot.py --replay-out replay.json
+```
+
+## ML (local)
+
+```python
+from arena_sdk.features import encode_view, action_from_index
+```
+
+Voir [`../docs/TUTORIAL.md`](../docs/TUTORIAL.md) pour le guide complet.
+
+## Dépendance
+
+Ce package réexporte `PlayerView`, `Action` et `play_match` depuis `i151-engine` (installé automatiquement).
+
+## Publication PyPI
+
+```bash
+cd arena/engine && python -m build && twine upload dist/*
+cd ../sdk && python -m build && twine upload dist/*
+```
+
+Publier `i151-engine` avant `i151-arena-sdk`.

i151_arena_sdk-0.2.0/README.md

@@ -0,0 +1,81 @@
+# i151-arena-sdk — SDK étudiant
+
+Package installable pour développer et tester un bot i151 en local, **sans cloner le dépôt complet**.
+
+## Installation
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install i151-arena-sdk
+```
+
+En développement (monorepo) :
+
+```bash
+cd arena/engine && pip install -e ".[dev]"
+cd ../sdk && pip install -e ".[dev]"
+```
+
+## 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
+```
+
+## Exemples publics (inclus dans le package)
+
+| Alias CLI | Description |
+|-----------|-------------|
+| `starter` | Première action légale |
+| `basic` | Heuristique gloutonne |
+
+```bash
+arena test starter
+arena match basic --vs random --seed 42
+```
+
+Les bots avancés (MinMax, MCTS, RL, PPO) restent dans le monorepo pour le développement interne et ne sont **pas** publiés sur PyPI.
+
+## Interface bot
+
+```python
+from arena_sdk import PlayerView, Action
+
+def decide(view: PlayerView, legal_actions: list[Action], time_left_ms: int) -> Action:
+    return legal_actions[0]
+```
+
+## CLI
+
+```bash
+arena init mon-bot              # créer un projet
+arena test bot.py               # smoke test vs random
+arena match bot.py --vs random  # match complet
+arena match bot.py --vs basic   # affronter l'exemple glouton
+arena match bot.py --replay-out replay.json
+```
+
+## ML (local)
+
+```python
+from arena_sdk.features import encode_view, action_from_index
+```
+
+Voir [`../docs/TUTORIAL.md`](../docs/TUTORIAL.md) pour le guide complet.
+
+## Dépendance
+
+Ce package réexporte `PlayerView`, `Action` et `play_match` depuis `i151-engine` (installé automatiquement).
+
+## Publication PyPI
+
+```bash
+cd arena/engine && python -m build && twine upload dist/*
+cd ../sdk && python -m build && twine upload dist/*
+```
+
+Publier `i151-engine` avant `i151-arena-sdk`.

i151_arena_sdk-0.2.0/arena_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""SDK étudiant — façade sur i151_engine."""
+
+from i151_engine.models.action import Action, ActionType
+from i151_engine.runner.config import MatchConfig
+from i151_engine.runner.match_runner import MatchResult, play_match
+from i151_engine.view.player_view import (
+    MatchContext,
+    OpponentState,
+    PlayerView,
+    TableState,
+    TurnState,
+    YouState,
+)
+
+__all__ = [
+    "Action",
+    "ActionType",
+    "MatchConfig",
+    "MatchContext",
+    "MatchResult",
+    "OpponentState",
+    "PlayerView",
+    "TableState",
+    "TurnState",
+    "YouState",
+    "play_match",
+]

i151_arena_sdk-0.2.0/arena_sdk/cli.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from i151_engine.runner.config import MatchConfig
+from i151_engine.runner.match_runner import play_bots_match, play_match
+
+from arena_sdk.init_project import InitProjectError, init_project
+from arena_sdk.loader import load_submission
+from arena_sdk.opponents import (
+    list_opponent_aliases,
+    resolve_opponent_arg,
+    resolve_submission_path,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="arena", description="CLI locale compétition i151")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    match_parser = sub.add_parser("match", help="Lancer un match bot vs adversaire")
+    _bot_help = f"Bot : {list_opponent_aliases()} ou chemin/bot.py"
+    match_parser.add_argument("bot", help=_bot_help)
+    match_parser.add_argument(
+        "--vs",
+        dest="opponent_id",
+        default="builtin:random",
+        help=f"Adversaire : {list_opponent_aliases()} (défaut: builtin:random)",
+    )
+    match_parser.add_argument("--seed", type=int, default=42)
+    match_parser.add_argument("--target-score", type=int, default=151)
+    match_parser.add_argument(
+        "--cards-per-player",
+        type=int,
+        default=8,
+        help="Nombre de cartes distribuées à chaque joueur en début de manche (défaut 8)",
+    )
+    match_parser.add_argument("--json", action="store_true", help="Sortie JSON (résultat + replay)")
+    match_parser.add_argument("--replay-out", type=Path, help="Écrire le replay JSON dans un fichier")
+
+    test_parser = sub.add_parser("test", help="Smoke test : bot vs builtin:random")
+    test_parser.add_argument("bot", help=_bot_help)
+    test_parser.add_argument("--seed", type=int, default=42)
+
+    init_parser = sub.add_parser("init", help="Créer un nouveau projet bot (bot.py + requirements.txt)")
+    init_parser.add_argument(
+        "directory",
+        nargs="?",
+        default="mon-bot",
+        help="Dossier cible (défaut: mon-bot)",
+    )
+    init_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Écraser les fichiers template existants",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "match":
+        return _cmd_match(args)
+    if args.command == "test":
+        return _cmd_test(args)
+    if args.command == "init":
+        return _cmd_init(args)
+    return 1
+
+
+def _cmd_match(args: argparse.Namespace) -> int:
+    bot_path = resolve_submission_path(args.bot)
+    bot = load_submission(bot_path)
+    challenger_dir = bot_path.parent
+    config = MatchConfig(
+        seed=args.seed,
+        target_score=args.target_score,
+        cards_per_player=args.cards_per_player,
+    )
+    opponent = resolve_opponent_arg(args.opponent_id)
+    result = play_bots_match(
+        bot,
+        opponent.bot,
+        config,
+        challenger_name=challenger_dir.name,
+        opponent_name=opponent.name,
+        opponent_id=opponent.opponent_id,
+        challenger_dir=challenger_dir,
+        opponent_dir=opponent.submission_dir,
+    )
+
+    if args.replay_out and result.replay is not None:
+        args.replay_out.write_text(result.replay.to_json(indent=2), encoding="utf-8")
+
+    if args.json:
+        payload = {
+            "winner_id": result.winner_id,
+            "opponent_id": result.opponent_id,
+            "reason": result.reason,
+            "final_scores": result.final_scores,
+            "rounds_played": result.rounds_played,
+            "steps_played": result.steps_played,
+            "replay": result.replay.to_dict() if result.replay else None,
+        }
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f"Winner: {result.winner_id} ({result.reason})")
+        print(f"Scores: {result.final_scores}")
+        print(f"Rounds: {result.rounds_played}, steps: {result.steps_played}")
+
+    return 0 if result.reason == "normal" else 2
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    try:
+        created = init_project(Path(args.directory), force=args.force)
+    except InitProjectError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    dest = Path(args.directory).resolve()
+    print(f"Projet créé dans {dest}")
+    for path in created:
+        print(f"  + {path.name}")
+    print()
+    print("Prochaines étapes :")
+    print(f"  cd {dest}")
+    print("  python3 -m venv .venv && source .venv/bin/activate")
+    print("  pip install -r requirements.txt")
+    print("  arena test bot.py")
+    return 0
+
+
+def _cmd_test(args: argparse.Namespace) -> int:
+    bot = load_submission(resolve_submission_path(args.bot))
+    result = play_match(
+        bot,
+        "builtin:random",
+        MatchConfig(seed=args.seed, target_score=151, max_rounds=40),
+        challenger_name="test",
+    )
+    if result.reason != "normal":
+        print(f"Échec smoke test : {result.reason}", file=sys.stderr)
+        return 1
+    print("OK — match terminé sans forfait")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

i151_arena_sdk-0.2.0/arena_sdk/features.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from i151_engine.models.action import Action
+from i151_engine.view.player_view import PlayerView
+
+
+def encode_view(view: PlayerView, legal_actions: list[Action]) -> list[float]:
+    """Encodage de référence PlayerView → vecteur (usage ML local).
+
+    Schéma minimal v0 : scores, tailles de mains, état table, one-hot actions légales.
+    """
+    features: list[float] = [
+        float(view.you.total_score),
+        float(view.you.hand_size),
+        float(view.you.hand_points),
+        float(view.you.consecutive_round_wins),
+        1.0 if view.you.is_chaining else 0.0,
+        float(view.table.bank_size),
+        float(view.table.played_pile_size),
+        1.0 if view.table.table_empty else 0.0,
+        1.0 if view.table.ace_effect_active else 0.0,
+        1.0 if view.table.must_choose_suit else 0.0,
+        float(view.match.round_number),
+        float(view.turn.step_index),
+    ]
+
+    if view.opponents:
+        opp = view.opponents[0]
+        features.extend(
+            [
+                float(opp.total_score),
+                float(opp.hand_size),
+                float(opp.consecutive_round_wins),
+            ]
+        )
+    else:
+        features.extend([0.0, 0.0, 0.0])
+
+    for action in legal_actions:
+        features.append(float(hash((action.type.value, action.card, action.chosen_suit)) % 1000) / 1000.0)
+
+    return features
+
+
+def action_index(legal_actions: list[Action], action: Action) -> int:
+    try:
+        return legal_actions.index(action)
+    except ValueError:
+        return 0
+
+
+def action_from_index(legal_actions: list[Action], index: int) -> Action:
+    if not legal_actions:
+        raise ValueError("legal_actions vide")
+    clamped = max(0, min(index, len(legal_actions) - 1))
+    return legal_actions[clamped]

i151_arena_sdk-0.2.0/arena_sdk/init_project.py

@@ -0,0 +1,47 @@
+"""Génération d'un projet bot étudiant via `arena init`."""
+
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+
+_TEMPLATE_FILES = {
+    "bot.py": "bot.py",
+    "requirements.txt": "requirements.txt",
+    "README.md": "README.md",
+    ".gitignore": "gitignore",
+}
+
+
+class InitProjectError(Exception):
+    pass
+
+
+def _template_text(filename: str) -> str:
+    package = importlib.resources.files("arena_sdk").joinpath("templates", filename)
+    return package.read_text(encoding="utf-8")
+
+
+def init_project(target: Path, *, force: bool = False) -> list[Path]:
+    """Crée un dossier de projet bot avec bot.py, requirements.txt, README.md."""
+    dest = target.resolve()
+    if dest.exists():
+        if not dest.is_dir():
+            raise InitProjectError(f"La cible existe et n'est pas un dossier : {dest}")
+        conflicts = [name for name in _TEMPLATE_FILES if (dest / name).exists()]
+        if conflicts and not force:
+            raise InitProjectError(
+                f"Fichiers déjà présents dans {dest} : {', '.join(conflicts)}. "
+                "Utilisez un autre dossier ou --force."
+            )
+    else:
+        dest.mkdir(parents=True)
+
+    created: list[Path] = []
+    for dest_name, template_name in _TEMPLATE_FILES.items():
+        out = dest / dest_name
+        if out.exists() and not force:
+            continue
+        out.write_text(_template_text(template_name), encoding="utf-8")
+        created.append(out)
+    return created

i151_arena_sdk-0.2.0/arena_sdk/loader.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import ast
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from i151_engine.bots.protocol import Bot
+from i151_engine.models.action import Action
+from i151_engine.view.player_view import PlayerView
+
+_KNOWN_PACKAGES = frozenset(
+    {
+        "arena_sdk",
+        "i151_engine",
+        "numpy",
+        "sklearn",
+        "joblib",
+        "onnxruntime",
+        "torch",
+        "pandas",
+    }
+)
+
+
+class SubmissionBot:
+    """Adapte un module bot.py étudiant (setup / decide / teardown) au protocole Bot."""
+
+    def __init__(self, module: ModuleType, submission_dir: Path) -> None:
+        self._module = module
+        self._submission_dir = submission_dir
+
+    def setup(self, submission_dir: Path) -> None:
+        del submission_dir
+        setup = getattr(self._module, "setup", None)
+        if callable(setup):
+            setup(self._submission_dir)
+
+    def decide(
+        self,
+        view: PlayerView,
+        legal_actions: list[Action],
+        time_left_ms: int,
+    ) -> Action:
+        decide = self._module.decide
+        return decide(view, legal_actions, time_left_ms)
+
+    def teardown(self) -> None:
+        teardown = getattr(self._module, "teardown", None)
+        if callable(teardown):
+            teardown()
+
+
+def _local_import_roots(source: str) -> set[str]:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as exc:
+        raise ImportError(f"Syntaxe bot.py invalide : {exc}") from exc
+
+    allowed = _KNOWN_PACKAGES | sys.stdlib_module_names
+    local: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root not in allowed:
+                    local.add(root)
+        elif isinstance(node, ast.ImportFrom):
+            if node.level and node.level > 0:
+                continue
+            if node.module:
+                root = node.module.split(".")[0]
+                if root not in allowed:
+                    local.add(root)
+    return local
+
+
+def _collect_local_module_closure(
+    submission_dir: Path,
+    extract_root: Path | None,
+    seeds: set[str],
+) -> list[str]:
+    """Modules locaux transitifs, ordre de chargement (dépendances d'abord)."""
+    order: list[str] = []
+    seen: set[str] = set()
+
+    def visit(name: str) -> None:
+        if name in seen:
+            return
+        seen.add(name)
+        py_file = _find_local_module(submission_dir, extract_root, name)
+        if py_file is not None:
+            source = py_file.read_text(encoding="utf-8")
+            for dep in sorted(_local_import_roots(source)):
+                visit(dep)
+        order.append(name)
+
+    for seed in sorted(seeds):
+        visit(seed)
+    return order
+
+
+def _find_local_module(
+    submission_dir: Path,
+    extract_root: Path | None,
+    module: str,
+) -> Path | None:
+    sibling = submission_dir / f"{module}.py"
+    if sibling.is_file():
+        return sibling
+    if extract_root is not None:
+        matches = sorted(extract_root.rglob(f"{module}.py"))
+        if matches:
+            return matches[0]
+    return None
+
+
+def _preload_local_modules(
+    *,
+    submission_dir: Path,
+    extract_root: Path | None,
+    module_names: list[str],
+) -> None:
+    for mod_name in module_names:
+        py_file = _find_local_module(submission_dir, extract_root, mod_name)
+        if py_file is None:
+            raise ModuleNotFoundError(
+                f"No module named '{mod_name}' — ajoutez {mod_name}.py "
+                f"dans le même dossier que bot.py"
+            )
+        if mod_name in sys.modules:
+            continue
+        spec = importlib.util.spec_from_file_location(mod_name, py_file)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Impossible de charger {py_file}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[mod_name] = module
+        spec.loader.exec_module(module)
+
+
+def load_submission(bot_path: Path, *, extract_root: Path | None = None) -> Bot:
+    """Charge bot.py depuis un fichier ou un dossier de soumission."""
+    path = bot_path.resolve()
+    if path.is_dir():
+        submission_dir = path
+        module_path = path / "bot.py"
+    else:
+        submission_dir = path.parent
+        module_path = path
+
+    if not module_path.is_file():
+        raise FileNotFoundError(f"bot.py introuvable : {module_path}")
+
+    resolved_extract = extract_root.resolve() if extract_root is not None else None
+    bot_source = module_path.read_text(encoding="utf-8")
+    local_modules = _collect_local_module_closure(
+        submission_dir,
+        resolved_extract,
+        _local_import_roots(bot_source),
+    )
+    _preload_local_modules(
+        submission_dir=submission_dir,
+        extract_root=resolved_extract,
+        module_names=local_modules,
+    )
+
+    spec = importlib.util.spec_from_file_location("student_bot", module_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Impossible de charger {module_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["student_bot"] = module
+    spec.loader.exec_module(module)
+
+    if not callable(getattr(module, "decide", None)):
+        raise AttributeError("bot.py doit définir une fonction decide(view, legal_actions, time_left_ms)")
+
+    return SubmissionBot(module, submission_dir)