{"data":{"kind":"file","path":"README.md","version_id":"jyo22py6mlv90no688bewtl3","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":6973,"modified_at":"2026-02-16T13:46:34.804000","content_hash":"cd5f0413d38a554938f84d08aa7bc939a2ece16cb20de25ef69dbd317c95bcde"},"entries":[],"content":"# robotrumble-prime\n\nPrime Lab starter environment for RobotRumble-style code generation.\n\n### Overview\n- **Environment ID**: `robotrumble-prime`\n- **Python package/import name**: `robotrumble_prime`\n- **Type**: Single-turn code generation\n- **Goal**: Train/evaluate models to produce syntactically valid RobotRumble `robot.py` logic\n\nThis package now includes a second module:\n- **Environment ID**: `robotrumble-prime-canonical`\n- **Module**: `robotrumble_prime_canonical.py`\n- **Type**: Multi-turn canonical carryover ladder\n\n### `robotrumble-prime` vs `robotrumble-prime-canonical`\n| Aspect | `robotrumble-prime` | `robotrumble-prime-canonical` |\n| --- | --- | --- |\n| Interaction type | Single-turn (`SingleTurnEnv`) | Multi-turn (`MultiTurnEnv`) |\n| Code carryover | No (one-shot candidate code per rollout) | Yes (latest code persists round-to-round) |\n| Ladder progression | Fixed-ladder score from one static candidate | Canonical round-by-round progression; advancement gates move to next opponent |\n| Stop condition | One model completion | Stops on ladder failure/clear (or max turns) |\n| Main use case | Fast RL bring-up, dense/strict reward ablations | Full long-horizon CC:Ladder-style behavior |\n| Compute cost | Lower | Higher |\n\n### What It Scores\nThis environment supports four scoring modes:\n\n1. Bootstrap mode (`split=train` or `split=eval`)\n- Fast reward for code-shape bring-up:\n- correct `def robot(state, unit):` signature\n- exact return contract: `Action.move(Direction.X)` or `Action.attack(Direction.X)` on every return path\n- exact RobotRumble API shape (`Action`, `Direction`, `state`, `unit`) with no `Action`/`Direction` shadowing\n- Python syntax validity\n- avoiding unsafe constructs (`os.system`, `subprocess`, `eval`, `exec`)\n\n2. Ladder mode (`split=ladder_train` or `split=ladder_eval`)\n- Adds strict CC:Ladder advancement scoring against:\n  - `human/entropicdrifter/seven-of-nine`\n  - `human/entropicdrifter/we-are-borg`\n  - `human/entropicdrifter/gigachad`\n- Uses CC:Ladder-style advancement logic (odd rounds, majority + last-round win).\n- Reward is advancement-only (highest ladder progress), with no shaping and no partial within-opponent credit.\n\n3. Bootstrap ladder mode (`split=ladder_bootstrap_train` or `split=ladder_bootstrap_eval`)\n- Same rubric family as ladder mode, but uses a single fixed opponent (`seven-of-nine`)\n- Useful for cheaper hill-climb bring-up before full 3-opponent ladder runs\n\n4. Stratified ladder-vs-humans eval (`split=ladder_vs_humans_eval`)\n- Uses seeded stratified opponent sampling across Elo tiers:\n  - Bottom quartile: 2 opponents (`bot1`, `jippty5`)\n  - Middle: 3 or 4 opponents sampled from (`maxad`, `alpha_13`, `sivuy`, `bash-brothers`)\n  - Top quartile: 2 opponents sampled from (`we-are-borg`, `seven-of-nine`, `gigachad`)\n- Opponent sampling is stable by default for cross-run comparability (`ROBOTRUMBLE_STRATIFIED_OPPONENT_SEED=2026`).\n- Reward uses dense `ladder_strength` (includes partial progress on the first opponent where the model stalls).\n- `ladder_advancement` is logged as monitoring-only.\n- Set `ROBOTRUMBLE_STRATIFIED_MIDDLE_COUNT=4` to use 4 middle-tier opponents (default: 3).\n- Set `ROBOTRUMBLE_STRATIFIED_OPPONENT_SEED=<int>` only when intentionally rotating the stratified eval set.\n\n### Environment Arguments\n| Arg | Type | Default | Description |\n| --- | ---- | ------- | ----------- |\n| `split` | str | `\"train\"` | One of: `train`, `eval`, `ladder_train`, `ladder_eval`, `ladder_bootstrap_train`, `ladder_bootstrap_eval`, `ladder_vs_humans_eval` |\n| `max_examples` | int | `-1` | Limit number of examples |\n| `seed` | int | `42` | Shuffle seed |\n\nFor `ladder_vs_humans_eval`, metadata also records:\n- `stratified_middle_count`\n- `stratified_opponent_seed`\n- `stratified_opponents`\n\n### Reward Note\n- `ladder_train`, `ladder_eval`, and bootstrap ladder splits use strict advancement-only reward aligned to CC:Ladder.\n- `ladder_vs_humans_eval` uses dense `ladder_strength` on a stratified opponent set.\n- Gameplay scoring enforces a strict gate (exact `robot(state, unit)` signature, exact `Action.move/attack(Direction.*)` returns, no API symbol redefinition, syntax-valid, safe code).\n\n### Runtime Note\n- Ladder gameplay scoring uses the `rumblebot` binary from the RobotRumble repository.\n- It is expected to work in Linux hosted environments.\n- On non-Linux local machines, ladder runner readiness may be `0.0` and ladder score may default to `0.0`.\n\n### Local Setup\nInstall Prime CLI and log in first:\n\n```bash\nuv tool install -U prime\nprime login\n```\n\nInstall this local environment from the repo root:\n\n```bash\nprime env install robotrumble-prime -p ./environments\n```\n\nRun local evaluation:\n\n```bash\nprime eval run robotrumble-prime \\\n  -m qwen/qwen3-30b-a3b-instruct-2507 \\\n  -n 20 -r 2 \\\n  -a '{\"split\":\"eval\",\"max_examples\":20,\"seed\":1337}'\n```\n\nRun ladder-mode eval:\n\n```bash\nprime eval run robotrumble-prime \\\n  -m qwen/qwen3-30b-a3b-instruct-2507 \\\n  -n 6 -r 1 \\\n  -a '{\"split\":\"ladder_eval\",\"max_examples\":6,\"seed\":1337}'\n```\n\nRun stratified ladder-vs-humans eval:\n\n```bash\nprime eval run robotrumble-prime \\\n  -m qwen/qwen3-30b-a3b-instruct-2507 \\\n  -n 6 -r 1 \\\n  -a '{\"split\":\"ladder_vs_humans_eval\",\"max_examples\":6,\"seed\":1337}'\n```\n\nRun canonical carryover eval:\n\n```bash\nprime eval run robotrumble-prime-canonical \\\n  -m qwen/qwen3-30b-a3b-instruct-2507 \\\n  -n 3 -r 1 \\\n  -a '{\"split\":\"eval\",\"max_examples\":3,\"seed\":1337,\"rounds_per_opponent\":5,\"turns_per_match\":100}'\n```\n\nCanonical env defaults:\n- Starts from a real human branch codebase (`initial_branch`, default first ladder opponent).\n- Uses ordered opponents from weaker to stronger.\n- Plays odd `rounds_per_opponent` (default `5`) and requires majority + last-round win to advance.\n- Reward is adaptation-aware in training:\n  - Train split blends dense `canonical_ladder_strength`, strict `canonical_ladder_advancement`,\n    tie-aware `canonical_competitive_score`, `canonical_late_round_quality`, and `canonical_round_win_rate`.\n  - Contract metrics are tracked (`canonical_contract_success_rate`, `canonical_contract_failure_rate`) but\n    are monitoring-only in train shaping to avoid collapsing to a legality-only reward floor.\n  - Eval split is aligned to dense `canonical_ladder_strength` for cleaner promotion gating.\n  - `canonical_contract_failure_rate` remains logged as a monitoring metric.\n- Turn prompts enforce targeted round-to-round patches (not full rewrites) and present current code in\n  `<robot_py>...</robot_py>` blocks to reduce markdown-fence leakage.\n- Hosted RL note: when using the same Hub slug (`codeclash/robotrumble-prime`), set `args.variant=\"canonical\"` in both `[[env]]` and `[[eval.env]]` to route to canonical MultiTurn logic.\n\n### Push To Hub (for Hosted Training)\n\n```bash\nprime env push -p ./environments/robotrumble_prime -v PRIVATE\n```\n\nAfter push, replace local env id in training config with your hub id (for example `your_org/robotrumble-prime`).\n","encoding":"utf-8","truncated":false,"total_bytes":6973},"status":null}