synth-ai 0.2.12__py3-none-any.whl → 0.2.13.dev2__py3-none-any.whl

examples/task_apps/dev/pokemon_emerald/modal_app.py

@@ -0,0 +1,114 @@
+"""Modal deployment helper for the Pokémon Emerald speedrun task app example.
+
+This reproduces the manual setup described in the README:
+
+- Clone `pokeagent-speedrun` and install its Python (and mGBA) dependencies.
+- Mount the Synth AI repository so the task app can be imported directly.
+- Mount a Modal volume that stores the ROM and savestates used by the environment.
+
+Deploy with:
+
+```
+modal deploy examples/task_apps/pokemon_emerald/modal_app.py
+```
+
+Before deploying, upload `emerald.gba` and any required savestate files to the
+`pokemon-emerald-assets` volume (see the README for `modal volume put` examples).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import modal
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+POKEAGENT_SPEEDRUN_REPO = "https://github.com/sethkarten/pokeagent-speedrun.git"
+
+app = modal.App("pokemon-emerald-task-app-example")
+
+BASE_IMAGE = (
+    modal.Image.debian_slim(python_version="3.11")
+    .apt_install(
+        "git",
+        "cmake",
+        "ninja-build",
+        "build-essential",
+        "pkg-config",
+        "libpng-dev",
+        "libzip-dev",
+        "libepoxy-dev",
+        "libavcodec-dev",
+        "libavformat-dev",
+        "libavutil-dev",
+        "libswscale-dev",
+        "zlib1g-dev",
+        "libgles2-mesa-dev",
+        "libegl1-mesa-dev",
+    )
+    .pip_install(["uvicorn[standard]", "fastapi", "httpx", "horizons-ai"])
+    .run_commands(
+        [
+            "mkdir -p /external",
+            f"if [ ! -d /external/pokeagent-speedrun ]; then git clone --depth 1 {POKEAGENT_SPEEDRUN_REPO} /external/pokeagent-speedrun; fi",
+            "pip install --no-cache-dir -r /external/pokeagent-speedrun/requirements.txt",
+        ]
+    )
+)
+
+REPO_MOUNT = modal.Mount.from_local_dir(REPO_ROOT, remote_path="/workspace/synth-ai")
+ASSET_VOLUME = modal.Volume.from_name("pokemon-emerald-assets", create_if_missing=True)
+
+
+@app.function(
+    image=BASE_IMAGE,
+    mounts=[REPO_MOUNT],
+    volumes={"/assets": ASSET_VOLUME},
+    timeout=900,
+    memory=9216,
+    cpu=4.0,
+    secrets=[modal.Secret.from_name("environment-api-key")],
+    keep_warm=1,
+)
+@modal.asgi_app()
+def fastapi_app():
+    """Serve the Synth task app via Modal."""
+
+    import os
+
+    repo_path = Path("/workspace/synth-ai").resolve()
+    if str(repo_path) not in sys.path:
+        sys.path.insert(0, str(repo_path))
+
+    marker = Path("/tmp/.synth_ai_editable")
+    if not marker.exists():
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "-e", str(repo_path)])
+        marker.touch()
+
+    os.environ.setdefault("POKEAGENT_SPEEDRUN_ROOT", "/external/pokeagent-speedrun")
+    os.environ.setdefault("POKEMON_EMERALD_ASSETS", "/assets")
+
+    rom_path = Path(os.getenv("POKEMON_EMERALD_ROM", "/assets/emerald.gba"))
+    if not rom_path.exists():
+        raise RuntimeError(
+            f"Missing ROM at {rom_path}. Upload it with "
+            "\"modal volume put pokemon-emerald-assets emerald.gba\" before deployment."
+        )
+
+    from examples.task_apps.pokemon_emerald.task_app.pokemon_emerald import build_config
+    from synth_ai.task.server import create_task_app
+
+    return create_task_app(build_config())
+
+
+@app.local_entrypoint()
+def main():
+    """Print usage hints for local operators."""
+
+    print("Pokémon Emerald task app Modal helper")
+    print("Upload assets: modal volume put pokemon-emerald-assets /path/to/emerald.gba")
+    print("Optional savestates can also be uploaded to the same volume.")
+    print("Deploy with: modal deploy examples/task_apps/pokemon_emerald/modal_app.py")
+    print("Test locally: modal serve examples/task_apps/pokemon_emerald/modal_app.py")

examples/task_apps/dev/pokemon_emerald/task_app/README.md

@@ -0,0 +1,81 @@
+# Pokemon Emerald Task App
+
+This directory contains a task app for the PokéAgent Track 2 speedrunning
+environment. It wraps the `pokeagent-speedrun` mGBA integration in the Horizons
+environment API so agents trained with Synth AI can reset, step, snapshot, and
+restore deterministically.
+
+## Local setup (Track 2)
+
+1. Clone and install the **pokeagent-speedrun** project (brings in the mGBA
+   Python bindings and emulator helpers). A snapshot of the repository is
+   vendored under `examples/task_apps/dev/pokemon_emerald/external/pokeagent-speedrun`,
+   but you can also clone a separate working copy if you prefer to track upstream:
+
+   ```bash
+   git clone https://github.com/sethkarten/pokeagent-speedrun.git
+   cd pokeagent-speedrun
+   pip install -r requirements.txt
+   ```
+
+   Installing `mgba==0.10.2` may require system packages such as `cmake`,
+   `ninja-build`, `pkg-config`, `libpng-dev`, `libzip-dev`, and the FFmpeg
+   libraries listed in the repo README.
+
+2. Provide a legal copy of the Pokémon Emerald ROM and any savestate
+   checkpoints you wish to use. Place them in a known directory.
+
+3. Export environment variables so the task app can locate both the repository
+   and the assets:
+
+   ```bash
+   export POKEAGENT_SPEEDRUN_ROOT=/path/to/pokeagent-speedrun  # or the vendored path under examples/task_apps/dev/pokemon_emerald/external
+   export POKEMON_EMERALD_ROM=/path/to/emerald.gba
+   ```
+
+4. Run a rollout to validate the wiring:
+
+   ```bash
+   uv run python -m synth_ai.task.describe pokemon_emerald
+   uv run python -m synth_ai.task.rollout pokemon_emerald --seed 4001
+   ```
+
+## Modal deployment
+
+`examples/task_apps/pokemon_emerald/modal_app.py` packages the same workflow for
+Modal. It clones `pokeagent-speedrun`, installs dependencies (including mGBA),
+and mounts a persistent volume (`pokemon-emerald-assets`) where you can upload
+the ROM and savestates:
+
+```bash
+modal volume put pokemon-emerald-assets /path/to/emerald.gba
+modal deploy examples/task_apps/pokemon_emerald/modal_app.py
+```
+
+After deployment, point Synth AI workflows at the issued `modal.run` URL.
+
+## Notes (Not Yet Ready)
+
+- The adapter currently requires manual mgba installation (`mgba==0.10.2`),
+  which is not automated for Apple Silicon—treat this example as
+  **experimental** until we land a turnkey build recipe.
+- Dataset entries report savestate availability, but some scenarios may still
+  lack assets locally; `/info` will surface this.
+- Snapshot/restore wiring is complete, yet we have not validated
+  deterministic parity across platforms pending a reliable mgba install flow.
+- Actions are exposed as macro buttons; further tuning is needed once the
+  runtime environment is stable.
+
+## Status & Next Steps
+
+- **Environment readiness (blocker)**: provide a reproducible mgba installation
+  path (possibly via prebaked wheels or containerized build) before relying on
+  this adapter.
+- **Visual observations**: once runtime is reliable, keep the base64 PNG output
+  and validate frame fidelity across platforms.
+- **Macro tuning**: calibrate macro durations and add higher-level navigation
+  macros.
+- **Reward shaping**: extend badge/location bonuses with richer event hooks.
+- **Stability checks**: add regression tests for snapshot/restore determinism.
+- **Agent integration**: publish rollout scripts after environment setup is
+  automated.

examples/task_apps/dev/pokemon_emerald/task_app/__init__.py

@@ -0,0 +1,6 @@
+"""Pokemon Emerald task app configuration."""
+
+from .pokemon_emerald import build_config
+
+__all__ = ["build_config"]
+