frondori-engine 0.4.0__tar.gz

frondori_engine-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Melvine Nargeot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frondori_engine-0.4.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: frondori-engine
+Version: 0.4.0
+Summary: Frondori research environments: the common contract (PettingZoo API), registry, rendering format and contract tests. Environments are installed separately (frondori-football, frondori-kitchen...).
+Author: Melvine Nargeot
+License-Expression: MIT
+Project-URL: Homepage, https://frondori.com
+Project-URL: Documentation, https://frondori.com/documentation/train-locally
+Project-URL: Source, https://github.com/Melvin-klein/frondori-engine
+Project-URL: Issues, https://github.com/Melvin-klein/frondori-engine/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: pettingzoo>=1.24
+Requires-Dist: msgpack>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# frondori-engine
+
+Le contrat commun des environnements de recherche de
+Frondori, au format [PettingZoo](https://pettingzoo.farama.org/).
+
+**Ce paquet ne contient aucun environnement.** Chacun est un paquet à part,
+dans son propre dépôt, qu'on installe seulement s'il nous intéresse :
+
+| Paquet | Environnement |
+|---|---|
+| `frondori-football` | `football-v0` — football 2D, duel (moteur Rust) |
+| `frondori-kitchen` | `kitchen-v0` — cuisine coopérative |
+
+## Installation
+
+```bash
+pip install frondori-engine frondori-kitchen
+```
+
+(Pas encore publiés sur PyPI : depuis un clone, `pip install -e .` dans
+chaque dépôt.)
+
+## Utilisation
+
+```python
+import frondori_engine
+
+print(frondori_engine.registered_ids())     # les environnements installés
+env = frondori_engine.make("kitchen-v0")    # un pettingzoo.ParallelEnv
+observations, infos = env.reset(seed=42)
+
+while env.agents:
+    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
+    observations, rewards, terminations, truncations, infos = env.step(actions)
+```
+
+Sans serveur, sans réseau, sans token. Compatible avec l'écosystème qui parle
+PettingZoo (RLlib, TorchRL, CleanRL, SuperSuit...). Pour jouer un match en
+local dans les conditions de la compétition, ou contre d'autres agents sur
+le serveur, voir le SDK (`frondori-sdk`) : `Agent(..., local=True)`.
+
+## Ce que contient ce paquet
+
+- `frondori_engine.make` / `registered_ids` / `register` : le registre. Les
+  environnements installés sont découverts automatiquement par leur *entry
+  point* (groupe `frondori.environments`).
+- `frondori_engine.scene` : le format de rendu commun (`render_mode="scene"`).
+- `frondori_engine.wire` : le format des spaces et des valeurs sur le réseau.
+- `frondori_engine.worker` : exécute un environnement pour le serveur de
+  compétition (un processus par match).
+- `frondori_engine.testing` : les tests du contrat, à appeler depuis les
+  tests de chaque environnement (`check_environment("mon-jeu-v0")`).
+
+## Créer un environnement
+
+Un paquet Python qui dépend de `frondori-engine` et se déclare dans son
+`pyproject.toml` :
+
+```toml
+[project.entry-points."frondori.environments"]
+"mon-jeu-v0" = "mon_paquet:MonJeuEnv"
+```
+
+Guide complet, avec un exemple vérifié : Documentation > Create an
+Environment, sur le site. L'exemple de ce guide (`tests/rps.py`) sert aussi
+d'environnement de test à ce paquet.
+
+## Développer / tester
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publier une version
+
+1. Mettre à jour `version` dans `pyproject.toml` et commiter.
+2. Pousser un tag du même numéro : `git tag v0.1.0 && git push origin v0.1.0`.
+
+La CI (`.github/workflows/ci.yml`) teste, construit et publie sur PyPI ; elle
+refuse un tag qui ne correspond pas à la version. Publication par *Trusted
+Publishing*, sans token : à configurer une fois sur PyPI (projet `frondori-engine` >
+Publishing > trusted publisher GitHub : ce dépôt, workflow `ci.yml`,
+environnement `pypi`).
+
+À publier EN PREMIER : les environnements et le SDK en dépendent.
+
+Licence : MIT.

frondori_engine-0.4.0/README.md

@@ -0,0 +1,89 @@
+# frondori-engine
+
+Le contrat commun des environnements de recherche de
+Frondori, au format [PettingZoo](https://pettingzoo.farama.org/).
+
+**Ce paquet ne contient aucun environnement.** Chacun est un paquet à part,
+dans son propre dépôt, qu'on installe seulement s'il nous intéresse :
+
+| Paquet | Environnement |
+|---|---|
+| `frondori-football` | `football-v0` — football 2D, duel (moteur Rust) |
+| `frondori-kitchen` | `kitchen-v0` — cuisine coopérative |
+
+## Installation
+
+```bash
+pip install frondori-engine frondori-kitchen
+```
+
+(Pas encore publiés sur PyPI : depuis un clone, `pip install -e .` dans
+chaque dépôt.)
+
+## Utilisation
+
+```python
+import frondori_engine
+
+print(frondori_engine.registered_ids())     # les environnements installés
+env = frondori_engine.make("kitchen-v0")    # un pettingzoo.ParallelEnv
+observations, infos = env.reset(seed=42)
+
+while env.agents:
+    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
+    observations, rewards, terminations, truncations, infos = env.step(actions)
+```
+
+Sans serveur, sans réseau, sans token. Compatible avec l'écosystème qui parle
+PettingZoo (RLlib, TorchRL, CleanRL, SuperSuit...). Pour jouer un match en
+local dans les conditions de la compétition, ou contre d'autres agents sur
+le serveur, voir le SDK (`frondori-sdk`) : `Agent(..., local=True)`.
+
+## Ce que contient ce paquet
+
+- `frondori_engine.make` / `registered_ids` / `register` : le registre. Les
+  environnements installés sont découverts automatiquement par leur *entry
+  point* (groupe `frondori.environments`).
+- `frondori_engine.scene` : le format de rendu commun (`render_mode="scene"`).
+- `frondori_engine.wire` : le format des spaces et des valeurs sur le réseau.
+- `frondori_engine.worker` : exécute un environnement pour le serveur de
+  compétition (un processus par match).
+- `frondori_engine.testing` : les tests du contrat, à appeler depuis les
+  tests de chaque environnement (`check_environment("mon-jeu-v0")`).
+
+## Créer un environnement
+
+Un paquet Python qui dépend de `frondori-engine` et se déclare dans son
+`pyproject.toml` :
+
+```toml
+[project.entry-points."frondori.environments"]
+"mon-jeu-v0" = "mon_paquet:MonJeuEnv"
+```
+
+Guide complet, avec un exemple vérifié : Documentation > Create an
+Environment, sur le site. L'exemple de ce guide (`tests/rps.py`) sert aussi
+d'environnement de test à ce paquet.
+
+## Développer / tester
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publier une version
+
+1. Mettre à jour `version` dans `pyproject.toml` et commiter.
+2. Pousser un tag du même numéro : `git tag v0.1.0 && git push origin v0.1.0`.
+
+La CI (`.github/workflows/ci.yml`) teste, construit et publie sur PyPI ; elle
+refuse un tag qui ne correspond pas à la version. Publication par *Trusted
+Publishing*, sans token : à configurer une fois sur PyPI (projet `frondori-engine` >
+Publishing > trusted publisher GitHub : ce dépôt, workflow `ci.yml`,
+environnement `pypi`).
+
+À publier EN PREMIER : les environnements et le SDK en dépendent.
+
+Licence : MIT.

frondori_engine-0.4.0/frondori_engine/__init__.py

@@ -0,0 +1,25 @@
+"""Le contrat commun des environnements de recherche Frondori.
+
+Ce paquet ne contient AUCUN environnement : chacun est un paquet à part,
+installé selon ses besoins, et découvert automatiquement :
+
+    pip install frondori-engine frondori-kitchen
+
+    import frondori_engine
+
+    print(frondori_engine.registered_ids())     # ['kitchen-v0']
+    env = frondori_engine.make("kitchen-v0")
+    observations, infos = env.reset(seed=42)
+    while env.agents:
+        actions = {agent: env.action_space(agent).sample() for agent in env.agents}
+        observations, rewards, terminations, truncations, infos = env.step(actions)
+
+Il fournit ce que tous partagent : le registre (`make`, `register`), le
+format des scènes (`scene`), celui des spaces et des valeurs sur le réseau
+(`wire`), le worker qui exécute un environnement pour le serveur de
+compétition (`worker`) et les tests du contrat (`testing`).
+"""
+
+from frondori_engine.registry import ENTRY_POINT_GROUP, EnvSpec, get_spec, make, register, registered_ids
+
+__all__ = ["ENTRY_POINT_GROUP", "EnvSpec", "get_spec", "make", "register", "registered_ids"]

frondori_engine-0.4.0/frondori_engine/registry.py

@@ -0,0 +1,104 @@
+"""Registre des environnements, sur le modèle de `gymnasium.make`.
+
+Les environnements ne vivent PAS dans ce paquet : chacun est un paquet
+Python indépendant (`frondori-football`, `frondori-kitchen`...), dans son
+propre dépôt, qu'un chercheur installe seulement s'il l'intéresse. Un
+paquet se déclare par un *entry point* du groupe `frondori.environments`,
+dans son `pyproject.toml` :
+
+    [project.entry-points."frondori.environments"]
+    "kitchen-v0" = "frondori_kitchen:KitchenEnv"
+
+Au premier appel à `make`/`registered_ids`, le registre découvre tous les
+environnements installés (`importlib.metadata.entry_points`, le mécanisme
+standard des plugins Python, celui de pytest ou de Gymnasium). Chaque classe
+n'est importée qu'au moment de créer l'environnement : lister le catalogue
+ne charge aucun moteur.
+
+`register` reste disponible pour un environnement en cours d'écriture, pas
+encore empaqueté.
+
+Tout identifiant porte une version (`nom-vN`). Changer les règles d'un
+environnement, c'est en publier une nouvelle version, jamais modifier
+l'ancienne : un résultat, un replay ou un classement obtenu sur
+`football-v0` doit rester comparable dans six mois.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from importlib.metadata import EntryPoint, entry_points
+from typing import Any, Callable
+
+from pettingzoo import ParallelEnv
+
+ENTRY_POINT_GROUP = "frondori.environments"
+
+_ID_PATTERN = re.compile(r"^[a-z][a-z0-9_]*-v\d+$")
+
+
+@dataclass(frozen=True)
+class EnvSpec:
+    id: str
+    entry_point: Callable[..., ParallelEnv]
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    # Paquet installable qui fournit l'environnement (ex. "frondori-kitchen"),
+    # `None` pour un environnement enregistré à la main. Publié avec le
+    # catalogue : le site en tire la commande d'installation.
+    package: str | None = None
+
+
+_registry: dict[str, EnvSpec] = {}
+_discovered = False
+
+
+def register(id: str, entry_point: Callable[..., ParallelEnv], package: str | None = None, **kwargs: Any) -> None:
+    """Enregistre un environnement. `kwargs` : paramètres par défaut passés à
+    `entry_point`, surchargeables au moment de `make`."""
+    if not _ID_PATTERN.match(id):
+        raise ValueError(f"identifiant invalide {id!r} : format attendu 'nom-vN' (ex. 'football-v0')")
+    if id in _registry:
+        raise ValueError(f"environnement {id!r} déjà enregistré ({_registry[id].package or 'register()'})")
+    _registry[id] = EnvSpec(id=id, entry_point=entry_point, kwargs=kwargs, package=package)
+
+
+def make(id: str, **kwargs: Any) -> ParallelEnv:
+    try:
+        spec = get_spec(id)
+    except KeyError:
+        known = ", ".join(registered_ids()) or "(aucun : installer un paquet d'environnement, ex. frondori-kitchen)"
+        raise KeyError(f"environnement inconnu {id!r} ; disponibles : {known}") from None
+    return spec.entry_point(**{**spec.kwargs, **kwargs})
+
+
+def get_spec(id: str) -> EnvSpec:
+    _discover()
+    return _registry[id]
+
+
+def registered_ids() -> list[str]:
+    _discover()
+    return sorted(_registry)
+
+
+def _discover() -> None:
+    """Enregistre les environnements des paquets installés, une seule fois.
+    Deux paquets qui déclarent le même identifiant : erreur explicite plutôt
+    qu'un choix silencieux de l'un des deux."""
+    global _discovered
+    if _discovered:
+        return
+    _discovered = True
+    for entry in entry_points(group=ENTRY_POINT_GROUP):
+        register(entry.name, _lazy(entry), package=entry.dist.name if entry.dist else None)
+
+
+def _lazy(entry: EntryPoint) -> Callable[..., ParallelEnv]:
+    # La classe n'est importée qu'à la création d'un environnement : lister
+    # les environnements disponibles ne charge aucun moteur (le football
+    # charge un module natif).
+    def create(**kwargs: Any) -> ParallelEnv:
+        return entry.load()(**kwargs)
+
+    return create

frondori_engine-0.4.0/frondori_engine/scene.py

@@ -0,0 +1,34 @@
+"""Format de rendu commun à tous les environnements (`render_mode="scene"`).
+
+Un environnement ne dessine jamais lui-même : `render()` renvoie une scène
+faite de primitives simples (rectangles, cercles, texte), sérialisable en
+JSON telle quelle. N'importe quel afficheur — un script matplotlib local, la
+page de match du site — peut ainsi dessiner n'importe quel environnement
+sans rien connaître de ses règles.
+
+Repère : origine en haut à gauche, x vers la droite, y vers le bas, dans les
+unités propres à l'environnement (mètres pour le football, cases pour la
+cuisine). `width`/`height` donnent l'étendue de la scène, pour la mise à
+l'échelle. Les couleurs sont des chaînes CSS.
+"""
+
+from __future__ import annotations
+
+
+def scene(width: float, height: float, shapes: list[dict], background: str = "#ffffff") -> dict:
+    return {"width": float(width), "height": float(height), "background": background, "shapes": shapes}
+
+
+def rect(x: float, y: float, w: float, h: float, fill: str) -> dict:
+    """Rectangle plein ; `(x, y)` est son coin haut-gauche."""
+    return {"type": "rect", "x": float(x), "y": float(y), "w": float(w), "h": float(h), "fill": fill}
+
+
+def circle(x: float, y: float, r: float, fill: str) -> dict:
+    """Disque plein ; `(x, y)` est son centre."""
+    return {"type": "circle", "x": float(x), "y": float(y), "r": float(r), "fill": fill}
+
+
+def text(x: float, y: float, value: str, fill: str = "#0f172a", size: float = 0.5) -> dict:
+    """Texte centré sur `(x, y)` ; `size` est la hauteur des caractères, dans les unités de la scène."""
+    return {"type": "text", "x": float(x), "y": float(y), "text": value, "fill": fill, "size": float(size)}

frondori_engine-0.4.0/frondori_engine/testing.py

@@ -0,0 +1,130 @@
+"""Les tests du contrat commun, réutilisables par chaque paquet
+d'environnement dans ses propres tests :
+
+    from frondori_engine.testing import check_environment
+
+    def test_contract():
+        check_environment("kitchen-v0")
+
+Chaque vérification est aussi disponible seule (`check_*`). Elles lèvent
+`AssertionError` (ou l'erreur de PettingZoo) au premier manquement, avec un
+message qui dit quoi corriger.
+"""
+
+from __future__ import annotations
+
+import json
+
+from pettingzoo.test import parallel_api_test, parallel_seed_test
+
+import frondori_engine
+from frondori_engine import wire
+
+RANKINGS = ("elo", "mean_return")
+SHAPE_TYPES = {"rect", "circle", "text"}
+
+
+def check_environment(env_id: str) -> None:
+    """Tout le contrat : à appeler depuis les tests de chaque environnement."""
+    check_pettingzoo_api(env_id)
+    check_reproducible(env_id)
+    check_observations_fit_their_space(env_id)
+    check_metadata(env_id)
+    check_spaces_can_be_sent(env_id)
+    check_neutral_action(env_id)
+    check_scene(env_id)
+
+
+def check_pettingzoo_api(env_id: str) -> None:
+    """Le test officiel de PettingZoo (API parallèle). Il exige notamment
+    que `observation_space(agent)` renvoie le MÊME objet à chaque appel :
+    créer les spaces une fois, dans `__init__`."""
+    parallel_api_test(frondori_engine.make(env_id), num_cycles=300)
+
+
+def check_reproducible(env_id: str) -> None:
+    """Même seed + mêmes actions = même épisode."""
+    parallel_seed_test(lambda: frondori_engine.make(env_id), num_cycles=100)
+
+
+def check_observations_fit_their_space(env_id: str, steps: int = 500) -> None:
+    # `parallel_api_test` ne le vérifie PAS (constaté : il laisse passer une
+    # valeur hors bornes). Or c'est sur ces spaces que le serveur et les
+    # agents s'appuient : vérifié ici explicitement.
+    env = frondori_engine.make(env_id)
+    observations, _ = env.reset(seed=0)
+    for _ in range(steps):
+        for agent, observation in observations.items():
+            assert env.observation_space(agent).contains(observation), (
+                f"{env_id} : l'observation de {agent} sort de son observation_space : {observation!r}"
+            )
+        if not env.agents:
+            break
+        observations, *_ = env.step({agent: env.action_space(agent).sample() for agent in env.agents})
+
+
+def check_metadata(env_id: str) -> None:
+    """Les métadonnées dont le serveur et le site ont besoin."""
+    env = frondori_engine.make(env_id)
+    metadata = env.metadata
+    for key in ("title", "description", "documentation"):
+        assert isinstance(metadata.get(key), str) and metadata[key].strip(), (
+            f"{env_id} : metadata[{key!r}] (texte non vide) est requis"
+        )
+    assert (metadata.get("render_fps") or 0) > 0, f"{env_id} : metadata['render_fps'] (pas par seconde) est requis"
+    assert (metadata.get("compute_budget_ms") or 0) > 0, (
+        f"{env_id} : metadata['compute_budget_ms'] (temps de calcul par action, en ms) est requis"
+    )
+    assert metadata.get("ranking") in RANKINGS, f"{env_id} : metadata['ranking'] doit valoir l'un de {RANKINGS}"
+    if metadata["ranking"] == "elo":
+        assert len(env.possible_agents) == 2, f"{env_id} : un classement ELO n'a de sens qu'en duel (2 agents)"
+    assert "scene" in metadata.get("render_modes", []), f"{env_id} : render_mode 'scene' est requis"
+
+
+def check_spaces_can_be_sent(env_id: str) -> None:
+    """Seuls Box, Discrete, MultiDiscrete et Dict passent sur le réseau."""
+    env = frondori_engine.make(env_id)
+    for agent in env.possible_agents:
+        wire.space_to_spec(env.observation_space(agent))
+        wire.space_to_spec(env.action_space(agent))
+
+
+def check_neutral_action(env_id: str) -> None:
+    """L'élément "zéro" de chaque action_space est une action valide : c'est
+    celle que le serveur joue pour un agent dont l'action est invalide, trop
+    lente ou absente (elle doit ne rien faire — ce que seul l'auteur de
+    l'environnement peut garantir)."""
+    env = frondori_engine.make(env_id)
+    env.reset(seed=0)
+    for agent in env.possible_agents:
+        space = env.action_space(agent)
+        assert space.contains(wire.neutral_action(space)), (
+            f"{env_id} : l'action neutre de {agent} sort de son action_space"
+        )
+    env.step({agent: wire.neutral_action(env.action_space(agent)) for agent in env.agents})
+
+
+def check_scene(env_id: str) -> None:
+    """Le rendu générique : sérialisable en JSON, primitives connues."""
+    env = frondori_engine.make(env_id, render_mode="scene")
+    env.reset(seed=0)
+    env.step({agent: env.action_space(agent).sample() for agent in env.agents})
+    scene = env.render()
+
+    json.dumps(scene)
+    assert scene["width"] > 0 and scene["height"] > 0, f"{env_id} : la scène doit avoir une largeur et une hauteur"
+    assert scene["shapes"], f"{env_id} : la scène est vide"
+    unknown = {shape["type"] for shape in scene["shapes"]} - SHAPE_TYPES
+    assert not unknown, f"{env_id} : primitives de scène inconnues {unknown} (attendu : {SHAPE_TYPES})"
+
+
+__all__ = [
+    "check_environment",
+    "check_metadata",
+    "check_neutral_action",
+    "check_observations_fit_their_space",
+    "check_pettingzoo_api",
+    "check_reproducible",
+    "check_scene",
+    "check_spaces_can_be_sent",
+]

frondori_engine-0.4.0/frondori_engine/wire.py

@@ -0,0 +1,89 @@
+"""Passage entre les valeurs d'un environnement (numpy, spaces Gymnasium) et
+leur forme sur le fil (types MessagePack natifs : nombres, listes, dicts).
+
+Ce format fait partie du protocole de compétition : le SDK
+(`frondori-sdk-python`) en implémente l'autre moitié (spec -> space, fil ->
+numpy). Toute modification ici doit y être reportée.
+
+Spaces supportés : Box, Discrete, MultiDiscrete, et Dict de ces spaces. Un
+environnement qui en utilise un autre est refusé explicitement à la
+description (`space_to_spec`), pas silencieusement mal transmis.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from gymnasium import spaces
+
+
+def space_to_spec(space: spaces.Space) -> dict:
+    if isinstance(space, spaces.Box):
+        return {
+            "type": "box",
+            "shape": list(space.shape),
+            "dtype": space.dtype.name,
+            "low": space.low.tolist(),
+            "high": space.high.tolist(),
+        }
+    if isinstance(space, spaces.Discrete):
+        return {"type": "discrete", "n": int(space.n), "start": int(space.start)}
+    if isinstance(space, spaces.MultiDiscrete):
+        return {
+            "type": "multi_discrete",
+            "nvec": space.nvec.tolist(),
+            "start": space.start.tolist(),
+            "dtype": space.dtype.name,
+        }
+    if isinstance(space, spaces.Dict):
+        return {"type": "dict", "spaces": {key: space_to_spec(sub) for key, sub in space.spaces.items()}}
+    raise TypeError(f"space non supporté par le protocole : {type(space).__name__}")
+
+
+def to_wire(value):
+    """numpy -> types natifs, récursivement (observations, infos)."""
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, dict):
+        return {str(key): to_wire(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [to_wire(item) for item in value]
+    return value
+
+
+def from_wire(space: spaces.Space, value):
+    """Action reçue du fil -> valeur du space. Lève `ValueError` si elle n'y
+    appartient pas : un agent n'est pas de confiance, rien n'est passé à
+    l'environnement sans vérification."""
+    if isinstance(space, spaces.Dict):
+        if not isinstance(value, dict) or set(value) != set(space.spaces):
+            raise ValueError(f"attendu un dict avec les clés {sorted(space.spaces)}")
+        return {key: from_wire(sub, value[key]) for key, sub in space.spaces.items()}
+    if isinstance(space, spaces.Discrete):
+        # `bool` est un sous-type d'`int` en Python : refusé explicitement.
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError("attendu un entier")
+        action = np.int64(value)
+    else:
+        action = np.asarray(value, dtype=space.dtype)
+    if not space.contains(action):
+        raise ValueError("valeur hors de l'action_space")
+    return action
+
+
+def neutral_action(space: spaces.Space):
+    """Action appliquée à un agent qui n'a pas répondu à temps, ou dont
+    l'action est invalide : l'élément « zéro » du space (0 ramené dans les
+    bornes, ou la plus petite valeur discrète). Un environnement doit donc
+    être conçu pour que cet élément soit une action sans effet — c'est le cas
+    du football (ne pas bouger, ne pas tirer) et de la cuisine (rester)."""
+    if isinstance(space, spaces.Dict):
+        return {key: neutral_action(sub) for key, sub in space.spaces.items()}
+    if isinstance(space, spaces.Discrete):
+        return np.int64(space.start)
+    if isinstance(space, spaces.MultiDiscrete):
+        return np.array(space.start, dtype=space.dtype)
+    if isinstance(space, spaces.Box):
+        return np.clip(np.zeros(space.shape), space.low, space.high).astype(space.dtype)
+    raise TypeError(f"space non supporté par le protocole : {type(space).__name__}")

frondori_engine-0.4.0/frondori_engine/worker.py

@@ -0,0 +1,159 @@
+"""Exécute un environnement dans un processus dédié, piloté par le serveur de
+compétition (`frondori-server`) via l'entrée et la sortie standard.
+
+Le serveur lance un worker par match (`python -m frondori_engine.worker`) :
+un environnement qui plante ou se bloque n'emporte que son propre match, et
+le serveur n'a pas à savoir en quel langage l'environnement est écrit.
+
+Chaque message est un objet MessagePack précédé de sa taille (4 octets,
+big-endian), dans les deux sens. Requêtes, selon `cmd` :
+- `describe` : catalogue des environnements (agents, cadence, budget de
+  calcul, classement, spaces) ;
+- `start` (`env_id`, `seed`) : crée l'environnement et renvoie les
+  observations initiales ;
+- `step` (`actions` : agent -> action, ou `nil` si l'agent n'a pas répondu à
+  temps) : un pas de simulation.
+Réponses : `{"ok": true, ...}` ou `{"ok": false, "error": "..."}`.
+
+Une action absente ou invalide est remplacée par l'action neutre de son
+space (`wire.neutral_action`) ; les agents dont l'action a été refusée sont
+listés dans `rejected`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import struct
+import sys
+import traceback
+
+import msgpack
+
+import frondori_engine
+from frondori_engine import wire
+
+# Comment la plateforme classe les agents d'un environnement (déclaré dans
+# `metadata["ranking"]`) : `elo` pour un duel (le vainqueur est l'agent au
+# meilleur retour), `mean_return` pour le reste (coopératif, solo) — le
+# retour moyen de l'agent par match.
+RANKINGS = ("elo", "mean_return")
+
+
+def main() -> None:
+    # La sortie standard porte le protocole : un `print` égaré dans le code
+    # d'un environnement la corromprait. On garde une copie privée du vrai
+    # stdout pour les réponses, et tout le reste part sur stderr.
+    protocol_out = os.fdopen(os.dup(1), "wb")
+    os.dup2(2, 1)
+    sys.stdout = sys.stderr
+
+    session = _Session()
+    while (request := _read_frame(sys.stdin.buffer)) is not None:
+        try:
+            reply = {"ok": True, **session.handle(request)}
+        except Exception:
+            reply = {"ok": False, "error": traceback.format_exc()}
+        _write_frame(protocol_out, reply)
+
+
+class _Session:
+    def __init__(self) -> None:
+        self._env = None
+
+    def handle(self, request: dict) -> dict:
+        command = request.get("cmd")
+        if command == "describe":
+            return {"environments": {env_id: _describe(env_id) for env_id in frondori_engine.registered_ids()}}
+        if command == "start":
+            return self._start(request["env_id"], request["seed"])
+        if command == "step":
+            return self._step(request["actions"])
+        raise ValueError(f"commande inconnue : {command!r}")
+
+    def _start(self, env_id: str, seed: int) -> dict:
+        self._env = frondori_engine.make(env_id, render_mode="scene")
+        observations, infos = self._env.reset(seed=seed)
+        return {
+            "agents": list(self._env.possible_agents),
+            "observations": wire.to_wire(observations),
+            "infos": wire.to_wire(infos),
+            "scene": self._scene(),
+        }
+
+    def _step(self, received: dict) -> dict:
+        actions, rejected = {}, []
+        for agent in self._env.agents:
+            space = self._env.action_space(agent)
+            value = received.get(agent)
+            try:
+                if value is None:
+                    raise ValueError("pas d'action")
+                actions[agent] = wire.from_wire(space, value)
+            except (ValueError, TypeError):
+                actions[agent] = wire.neutral_action(space)
+                if value is not None:
+                    rejected.append(agent)
+
+        observations, rewards, terminations, truncations, infos = self._env.step(actions)
+        return {
+            "observations": wire.to_wire(observations),
+            "rewards": {agent: float(reward) for agent, reward in rewards.items()},
+            "terminations": {agent: bool(done) for agent, done in terminations.items()},
+            "truncations": {agent: bool(done) for agent, done in truncations.items()},
+            "infos": wire.to_wire(infos),
+            "scene": self._scene(),
+            "rejected": rejected,
+        }
+
+    def _scene(self) -> str:
+        # Déjà en JSON : le serveur la relaie telle quelle aux spectateurs et
+        # la concatène dans le replay, sans jamais avoir à la décoder.
+        return json.dumps(self._env.render(), separators=(",", ":"))
+
+
+def _describe(env_id: str) -> dict:
+    env = frondori_engine.make(env_id)
+    tick_rate = env.metadata.get("render_fps")
+    if not tick_rate or tick_rate <= 0:
+        raise ValueError(f"{env_id} : metadata['render_fps'] (cadence en pas/seconde) est requis")
+    ranking = env.metadata.get("ranking")
+    if ranking not in RANKINGS:
+        raise ValueError(f"{env_id} : metadata['ranking'] doit valoir l'un de {RANKINGS}")
+    if ranking == "elo" and len(env.possible_agents) != 2:
+        raise ValueError(f"{env_id} : un classement ELO n'a de sens qu'en duel (2 agents)")
+    budget = env.metadata.get("compute_budget_ms")
+    if not budget or budget <= 0:
+        raise ValueError(f"{env_id} : metadata['compute_budget_ms'] (temps de calcul par action, en ms) est requis")
+    return {
+        "agents": list(env.possible_agents),
+        "tick_rate": float(tick_rate),
+        "ranking": ranking,
+        "compute_budget_ms": float(budget),
+        "title": env.metadata.get("title", env_id),
+        "description": env.metadata.get("description", ""),
+        "documentation": env.metadata.get("documentation", ""),
+        # Le paquet à installer pour jouer à cet environnement en local
+        # (le site affiche la commande `pip install`).
+        "package": frondori_engine.get_spec(env_id).package or "",
+        "observation_spaces": {agent: wire.space_to_spec(env.observation_space(agent)) for agent in env.possible_agents},
+        "action_spaces": {agent: wire.space_to_spec(env.action_space(agent)) for agent in env.possible_agents},
+    }
+
+
+def _read_frame(stream):
+    header = stream.read(4)
+    if len(header) < 4:
+        return None
+    (size,) = struct.unpack(">I", header)
+    return msgpack.unpackb(stream.read(size), raw=False)
+
+
+def _write_frame(stream, message: dict) -> None:
+    payload = msgpack.packb(message, use_bin_type=True)
+    stream.write(struct.pack(">I", len(payload)) + payload)
+    stream.flush()
+
+
+if __name__ == "__main__":
+    main()

frondori_engine-0.4.0/frondori_engine.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: frondori-engine
+Version: 0.4.0
+Summary: Frondori research environments: the common contract (PettingZoo API), registry, rendering format and contract tests. Environments are installed separately (frondori-football, frondori-kitchen...).
+Author: Melvine Nargeot
+License-Expression: MIT
+Project-URL: Homepage, https://frondori.com
+Project-URL: Documentation, https://frondori.com/documentation/train-locally
+Project-URL: Source, https://github.com/Melvin-klein/frondori-engine
+Project-URL: Issues, https://github.com/Melvin-klein/frondori-engine/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: pettingzoo>=1.24
+Requires-Dist: msgpack>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# frondori-engine
+
+Le contrat commun des environnements de recherche de
+Frondori, au format [PettingZoo](https://pettingzoo.farama.org/).
+
+**Ce paquet ne contient aucun environnement.** Chacun est un paquet à part,
+dans son propre dépôt, qu'on installe seulement s'il nous intéresse :
+
+| Paquet | Environnement |
+|---|---|
+| `frondori-football` | `football-v0` — football 2D, duel (moteur Rust) |
+| `frondori-kitchen` | `kitchen-v0` — cuisine coopérative |
+
+## Installation
+
+```bash
+pip install frondori-engine frondori-kitchen
+```
+
+(Pas encore publiés sur PyPI : depuis un clone, `pip install -e .` dans
+chaque dépôt.)
+
+## Utilisation
+
+```python
+import frondori_engine
+
+print(frondori_engine.registered_ids())     # les environnements installés
+env = frondori_engine.make("kitchen-v0")    # un pettingzoo.ParallelEnv
+observations, infos = env.reset(seed=42)
+
+while env.agents:
+    actions = {agent: env.action_space(agent).sample() for agent in env.agents}
+    observations, rewards, terminations, truncations, infos = env.step(actions)
+```
+
+Sans serveur, sans réseau, sans token. Compatible avec l'écosystème qui parle
+PettingZoo (RLlib, TorchRL, CleanRL, SuperSuit...). Pour jouer un match en
+local dans les conditions de la compétition, ou contre d'autres agents sur
+le serveur, voir le SDK (`frondori-sdk`) : `Agent(..., local=True)`.
+
+## Ce que contient ce paquet
+
+- `frondori_engine.make` / `registered_ids` / `register` : le registre. Les
+  environnements installés sont découverts automatiquement par leur *entry
+  point* (groupe `frondori.environments`).
+- `frondori_engine.scene` : le format de rendu commun (`render_mode="scene"`).
+- `frondori_engine.wire` : le format des spaces et des valeurs sur le réseau.
+- `frondori_engine.worker` : exécute un environnement pour le serveur de
+  compétition (un processus par match).
+- `frondori_engine.testing` : les tests du contrat, à appeler depuis les
+  tests de chaque environnement (`check_environment("mon-jeu-v0")`).
+
+## Créer un environnement
+
+Un paquet Python qui dépend de `frondori-engine` et se déclare dans son
+`pyproject.toml` :
+
+```toml
+[project.entry-points."frondori.environments"]
+"mon-jeu-v0" = "mon_paquet:MonJeuEnv"
+```
+
+Guide complet, avec un exemple vérifié : Documentation > Create an
+Environment, sur le site. L'exemple de ce guide (`tests/rps.py`) sert aussi
+d'environnement de test à ce paquet.
+
+## Développer / tester
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## Publier une version
+
+1. Mettre à jour `version` dans `pyproject.toml` et commiter.
+2. Pousser un tag du même numéro : `git tag v0.1.0 && git push origin v0.1.0`.
+
+La CI (`.github/workflows/ci.yml`) teste, construit et publie sur PyPI ; elle
+refuse un tag qui ne correspond pas à la version. Publication par *Trusted
+Publishing*, sans token : à configurer une fois sur PyPI (projet `frondori-engine` >
+Publishing > trusted publisher GitHub : ce dépôt, workflow `ci.yml`,
+environnement `pypi`).
+
+À publier EN PREMIER : les environnements et le SDK en dépendent.
+
+Licence : MIT.

frondori_engine-0.4.0/frondori_engine.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+frondori_engine/__init__.py
+frondori_engine/registry.py
+frondori_engine/scene.py
+frondori_engine/testing.py
+frondori_engine/wire.py
+frondori_engine/worker.py
+frondori_engine.egg-info/PKG-INFO
+frondori_engine.egg-info/SOURCES.txt
+frondori_engine.egg-info/dependency_links.txt
+frondori_engine.egg-info/requires.txt
+frondori_engine.egg-info/top_level.txt
+tests/test_registry.py
+tests/test_testing.py
+tests/test_worker.py

frondori_engine-0.4.0/frondori_engine.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

frondori_engine-0.4.0/frondori_engine.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy>=1.24
+gymnasium>=1.0
+pettingzoo>=1.24
+msgpack>=1.0
+
+[dev]
+pytest>=7

frondori_engine-0.4.0/frondori_engine.egg-info/top_level.txt

@@ -0,0 +1 @@
+frondori_engine

frondori_engine-0.4.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frondori-engine"
+version = "0.4.0"
+description = "Frondori research environments: the common contract (PettingZoo API), registry, rendering format and contract tests. Environments are installed separately (frondori-football, frondori-kitchen...)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Melvine Nargeot" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.24",
+    "gymnasium>=1.0",
+    "pettingzoo>=1.24",
+    "msgpack>=1.0",
+]
+
+[project.urls]
+Homepage = "https://frondori.com"
+Documentation = "https://frondori.com/documentation/train-locally"
+Source = "https://github.com/Melvin-klein/frondori-engine"
+Issues = "https://github.com/Melvin-klein/frondori-engine/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["frondori_engine"]

frondori_engine-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frondori_engine-0.4.0/tests/test_registry.py

@@ -0,0 +1,72 @@
+from importlib.metadata import EntryPoint
+
+import pytest
+
+import frondori_engine
+from frondori_engine import registry
+from rps import RockPaperScissorsEnv
+
+
+def test_make_passes_kwargs_to_the_environment():
+    env = frondori_engine.make("rps-v0", rounds=3)
+    env.reset()
+
+    for _ in range(3):
+        *_, truncations, _ = env.step({agent: 1 for agent in env.agents})
+
+    assert all(truncations.values())
+    assert env.agents == []
+
+
+def test_unknown_environment_lists_available_ones():
+    with pytest.raises(KeyError, match="rps-v0"):
+        frondori_engine.make("chess-v0")
+
+
+@pytest.mark.parametrize("bad_id", ["rps", "Rps-v0", "rps-v", "rps_v0"])
+def test_ids_must_be_versioned(bad_id):
+    with pytest.raises(ValueError, match="nom-vN"):
+        frondori_engine.register(bad_id, RockPaperScissorsEnv)
+
+
+def test_an_id_cannot_be_registered_twice():
+    with pytest.raises(ValueError, match="déjà enregistré"):
+        frondori_engine.register("rps-v0", RockPaperScissorsEnv)
+
+
+def fake_entry_points(*entries):
+    return lambda group: [EntryPoint(name, value, group) for name, value in entries if group == registry.ENTRY_POINT_GROUP]
+
+
+def test_installed_environments_are_discovered(monkeypatch):
+    monkeypatch.setattr(registry, "_registry", {})
+    monkeypatch.setattr(registry, "_discovered", False)
+    monkeypatch.setattr(registry, "entry_points", fake_entry_points(("game-v0", "rps:RockPaperScissorsEnv")))
+
+    assert frondori_engine.registered_ids() == ["game-v0"]
+    env = frondori_engine.make("game-v0", rounds=2)
+    assert isinstance(env, RockPaperScissorsEnv) and env.rounds == 2
+
+
+def test_an_environment_class_is_only_imported_when_created(monkeypatch):
+    # Lister le catalogue ne doit charger aucun moteur.
+    monkeypatch.setattr(registry, "_registry", {})
+    monkeypatch.setattr(registry, "_discovered", False)
+    monkeypatch.setattr(registry, "entry_points", fake_entry_points(("broken-v0", "no_such_module:Env")))
+
+    assert frondori_engine.registered_ids() == ["broken-v0"]
+    with pytest.raises(ModuleNotFoundError):
+        frondori_engine.make("broken-v0")
+
+
+def test_two_packages_declaring_the_same_id_is_an_error(monkeypatch):
+    monkeypatch.setattr(registry, "_registry", {})
+    monkeypatch.setattr(registry, "_discovered", False)
+    monkeypatch.setattr(
+        registry,
+        "entry_points",
+        fake_entry_points(("game-v0", "rps:RockPaperScissorsEnv"), ("game-v0", "rps:RockPaperScissorsEnv")),
+    )
+
+    with pytest.raises(ValueError, match="déjà enregistré"):
+        frondori_engine.registered_ids()

frondori_engine-0.4.0/tests/test_testing.py

@@ -0,0 +1,67 @@
+"""Les vérifications du contrat, telles que les paquets d'environnement les
+utilisent : elles passent sur un environnement conforme, et attrapent les
+erreurs courantes avec un message utile."""
+
+import numpy as np
+import pytest
+from gymnasium import spaces
+
+import frondori_engine
+from frondori_engine.testing import (
+    check_environment,
+    check_metadata,
+    check_observations_fit_their_space,
+    check_pettingzoo_api,
+)
+from rps import RockPaperScissorsEnv
+
+
+def test_a_conforming_environment_passes_the_whole_contract():
+    check_environment("rps-v0")
+
+
+class SpacesRecreatedOnEveryCall(RockPaperScissorsEnv):
+    def action_space(self, agent):
+        return spaces.Discrete(4)
+
+
+class ObservationOutOfItsSpace(RockPaperScissorsEnv):
+    def _observations(self):
+        observations = super()._observations()
+        for observation in observations.values():
+            observation["rounds_left"] = 1000
+        return observations
+
+
+class EloWithThreeAgents(RockPaperScissorsEnv):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.possible_agents = ["player_0", "player_1", "player_2"]
+
+
+class NoBudget(RockPaperScissorsEnv):
+    metadata = {**RockPaperScissorsEnv.metadata, "compute_budget_ms": None}
+
+
+@pytest.mark.parametrize(
+    ("broken", "check", "message"),
+    [
+        (SpacesRecreatedOnEveryCall, check_pettingzoo_api, "same space object"),
+        (ObservationOutOfItsSpace, check_observations_fit_their_space, "sort de son observation_space"),
+        (EloWithThreeAgents, check_metadata, "duel"),
+        (NoBudget, check_metadata, "compute_budget_ms"),
+    ],
+)
+def test_common_mistakes_are_caught(broken, check, message):
+    frondori_engine.register("broken-v0", broken)
+
+    with pytest.raises(AssertionError, match=message):
+        check("broken-v0")
+
+
+def test_the_neutral_action_is_the_zero_of_the_action_space():
+    from frondori_engine import wire
+
+    assert wire.neutral_action(spaces.Discrete(4)) == 0
+    box = wire.neutral_action(spaces.Box(-1, 1, shape=(2, 3), dtype=np.float32))
+    assert box.shape == (2, 3) and not box.any()

frondori_engine-0.4.0/tests/test_worker.py

@@ -0,0 +1,122 @@
+"""Le worker, testé comme le serveur l'utilise : un vrai sous-processus,
+piloté en MessagePack par son entrée et sa sortie standard. Il joue
+l'environnement d'exemple (`tests/rps.py`), enregistré avant de démarrer."""
+
+import json
+import struct
+import subprocess
+import sys
+import textwrap
+from pathlib import Path
+
+import msgpack
+import pytest
+
+TESTS = Path(__file__).parent
+
+BOOTSTRAP = textwrap.dedent(f"""
+    import sys
+    sys.path.insert(0, {str(TESTS)!r})
+    import frondori_engine
+    from rps import RockPaperScissorsEnv
+    frondori_engine.register("rps-v0", RockPaperScissorsEnv, package="frondori-rps")
+    {{extra}}
+    from frondori_engine.worker import main
+    main()
+""")
+
+
+class Worker:
+    def __init__(self, extra: str = ""):
+        self._process = subprocess.Popen(
+            [sys.executable, "-c", BOOTSTRAP.replace("{extra}", textwrap.dedent(extra))],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+        )
+
+    def request(self, message: dict) -> dict:
+        payload = msgpack.packb(message, use_bin_type=True)
+        self._process.stdin.write(struct.pack(">I", len(payload)) + payload)
+        self._process.stdin.flush()
+        (size,) = struct.unpack(">I", self._process.stdout.read(4))
+        return msgpack.unpackb(self._process.stdout.read(size), raw=False)
+
+    def close(self) -> None:
+        self._process.stdin.close()
+        assert self._process.wait(timeout=10) == 0
+
+
+@pytest.fixture
+def worker():
+    w = Worker()
+    yield w
+    w.close()
+
+
+def test_describe_gives_what_the_server_and_the_website_need(worker):
+    reply = worker.request({"cmd": "describe"})
+
+    assert reply["ok"]
+    rps = reply["environments"]["rps-v0"]
+    assert rps["agents"] == ["player_0", "player_1"]
+    assert rps["tick_rate"] == 10.0
+    assert rps["ranking"] == "elo"
+    assert rps["compute_budget_ms"] == 50.0
+    assert rps["title"] == "Rock Paper Scissors"
+    assert rps["documentation"]
+    assert rps["package"] == "frondori-rps"
+    assert rps["action_spaces"]["player_0"] == {"type": "discrete", "n": 4, "start": 0}
+    assert rps["observation_spaces"]["player_0"]["type"] == "dict"
+
+
+def test_an_episode_runs_through_the_worker(worker):
+    start = worker.request({"cmd": "start", "env_id": "rps-v0", "seed": 0})
+
+    assert start["ok"]
+    assert start["agents"] == ["player_0", "player_1"]
+    assert start["observations"]["player_0"] == {"opponent_last": 0, "rounds_left": 100}
+    json.loads(start["scene"])
+
+    # player_0 joue la pierre (1), player_1 n'a pas répondu à temps (nil).
+    step = worker.request({"cmd": "step", "actions": {"player_0": 1, "player_1": None}})
+
+    assert step["ok"]
+    assert step["rejected"] == []
+    assert step["rewards"] == {"player_0": 1.0, "player_1": -1.0}
+    assert step["observations"]["player_1"]["opponent_last"] == 1
+    assert step["infos"]["player_0"] == {"score": 1}
+
+
+def test_invalid_actions_are_replaced_by_the_neutral_action(worker):
+    worker.request({"cmd": "start", "env_id": "rps-v0", "seed": 0})
+
+    step = worker.request({"cmd": "step", "actions": {"player_0": 42, "player_1": "n'importe quoi"}})
+
+    assert step["ok"]
+    assert sorted(step["rejected"]) == ["player_0", "player_1"]
+    # Les deux ont "passé" (action neutre 0) : manche nulle.
+    assert step["rewards"] == {"player_0": 0.0, "player_1": 0.0}
+
+
+def test_an_error_is_reported_without_killing_the_worker(worker):
+    reply = worker.request({"cmd": "start", "env_id": "chess-v0", "seed": 0})
+
+    assert not reply["ok"]
+    assert "chess-v0" in reply["error"]
+    assert worker.request({"cmd": "describe"})["ok"]
+
+
+def test_a_stray_print_in_an_environment_does_not_corrupt_the_protocol():
+    worker = Worker("""
+        class Noisy(RockPaperScissorsEnv):
+            def reset(self, seed=None, options=None):
+                print("un print oublié dans un environnement")
+                return super().reset(seed=seed, options=options)
+
+        frondori_engine.register("noisy-v0", Noisy)
+    """)
+
+    reply = worker.request({"cmd": "start", "env_id": "noisy-v0", "seed": 0})
+
+    assert reply["ok"]
+    worker.close()