cogames 0.3.49__py3-none-any.whl → 0.3.64__py3-none-any.whl

cogames/{policy/scripted_agent/README.md → docs/SCRIPTED_AGENT.md}

@@ -1,14 +1,17 @@
 # Scripted Agent Policies
 
-Three teaching-friendly scripted agent implementations for CoGames evaluation and ablation studies.
+Teaching-friendly scripted agents for CoGames evaluation and ablation studies, plus a tiny demo policy and the CogsGuard
+team-play scripted policy.
 
 ## Overview
 
-This package provides three progressively capable scripted agents:
+This package provides the CogsGuard team-play policy, two progressively capable scripted agents, and one tiny demo
+policy:
 
-1. **BaselineAgent** - Core functionality: exploration, resource gathering, heart assembly (single/multi-agent)
-2. **UnclippingAgent** - Extends BaselineAgent with extractor unclipping capability
-3. **StarterAgent** - Lightweight, tutorial-friendly flow for README and quick demos
+1. **CogsGuard** - Vibe-based multi-role policy for the CogsGuard arena
+2. **BaselineAgent** - Core functionality for legacy heart-production game: exploration, resource gathering, heart
+   assembly
+3. **UnclippingAgent** - Extends BaselineAgent with extractor unclipping capability (legacy game)
 
 ## Architecture
 
@@ -16,11 +19,11 @@ This package provides three progressively capable scripted agents:
 
 ```
 scripted_agent/
+├── cogsguard/                   # CogsGuard scripted policy (vibe-based roles)
 ├── baseline_agent.py            # Base agent + BaselinePolicy wrapper
 ├── unclipping_agent.py          # Unclipping extension + UnclippingPolicy wrapper
-├── starter_agent.py             # Minimal if/else agent for docs and demos
-├── pathfinding.py               # Pathfinding utilities (shared)
-└── README.md                    # This file
+├── demo_policy.py               # Tiny demo policy (short name: tiny_baseline)
+└── pathfinding.py               # Pathfinding utilities (shared)
 ```
 
 Each agent file contains:
@@ -38,7 +41,49 @@ These agents are designed for **ablation studies** and **baseline evaluation**:
 
 ## Agents
 
-### 1. BaselineAgent
+### 1. CogsGuard Scripted Agent
+
+CogsGuard is the team-play focus for scripted policies. Agents are controlled by **vibes** that map to roles and gear
+acquisition.
+
+**Vibes**:
+
+| Vibe        | Behavior                                 |
+| ----------- | ---------------------------------------- |
+| `default`   | Idle (noop)                              |
+| `heart`     | Idle (noop)                              |
+| `gear`      | Smart role selection                     |
+| `miner`     | Gather and deposit resources             |
+| `scout`     | Explore and discover structures          |
+| `aligner`   | Align neutral supply depots to cogs      |
+| `scrambler` | Scramble clips-aligned depots to neutral |
+
+**Gear costs** (paid from cogs commons):
+
+| Gear      | Cost                                       | Bonus                |
+| --------- | ------------------------------------------ | -------------------- |
+| Miner     | 3 carbon, 1 oxygen, 1 germanium, 1 silicon | +40 cargo            |
+| Scout     | 1 carbon, 1 oxygen, 1 germanium, 3 silicon | +100 energy, +400 HP |
+| Aligner   | 3 carbon, 1 oxygen, 1 germanium, 1 silicon | +20 influence        |
+| Scrambler | 1 carbon, 3 oxygen, 1 germanium, 1 silicon | +200 HP              |
+
+**Supply depots** start clips-aligned. Scramblers neutralize them; aligners convert neutral depots to cogs for AOE
+energy regen.
+
+**Usage**:
+
+```bash
+# Default role distribution (1 scrambler, 4 miners, rest smart-gear)
+./tools/run.py recipes.experiment.cogsguard.play policy_uri=metta://policy/role
+
+# Custom role counts
+./tools/run.py recipes.experiment.cogsguard.play \
+    policy_uri="metta://policy/role?miner=3&scout=2&aligner=2&scrambler=3"
+```
+
+**Full documentation**: `packages/cogames-agents/src/cogames_agents/policy/scripted_agent/cogsguard/README.md`
+
+### 2. BaselineAgent
 
 **Purpose**: Minimal working agent for single/multi-agent missions
 
@@ -46,7 +91,7 @@ These agents are designed for **ablation studies** and **baseline evaluation**:
 
 - ✅ Visual discovery (explores to find stations and extractors)
 - ✅ Resource gathering (navigates to extractors, handles cooldowns)
-- ✅ Heart assembly (deposits resources at assembler)
+- ✅ Heart assembly (deposits resources at hub)
 - ✅ Heart delivery (brings hearts to chest)
 - ✅ Energy management (recharges when low)
 - ✅ Extractor tracking (remembers positions, cooldowns, remaining uses)
@@ -60,7 +105,7 @@ These agents are designed for **ablation studies** and **baseline evaluation**:
 **Usage**:
 
 ```python
-from cogames.policy.scripted_agent.baseline_agent import BaselinePolicy
+from cogames_agents.policy.scripted_agent.baseline_agent import BaselinePolicy
 from mettagrid import MettaGridEnv
 
 env = MettaGridEnv(env_config)
@@ -77,13 +122,13 @@ action = agent.step(obs[0])
 
 ```bash
 # Single agent
-uv run cogames play --mission evals.diagnostic_radial -p scripted_baseline --cogs 1
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 1
 
 # Multi-agent
-uv run cogames play --mission evals.diagnostic_radial -p scripted_baseline --cogs 4
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 4
 ```
 
-### 2. UnclippingAgent
+### 3. UnclippingAgent
 
 **Purpose**: Handle missions with clipped extractors
 
@@ -103,7 +148,7 @@ oxygen | gear | | Germanium | resonator | silicon | gear | | Silicon | scrambler
 1. Detects clipped extractor blocking progress
 2. Gathers craft resource (e.g., carbon for decoder)
 3. Changes glyph to "gear"
-4. Crafts unclip item at assembler
+4. Crafts unclip item at hub
 5. Navigates to clipped extractor
 6. Uses item to unclip
 7. Resumes normal gathering
@@ -111,23 +156,19 @@ oxygen | gear | | Germanium | resonator | silicon | gear | | Silicon | scrambler
 **Usage**:
 
 ```python
-from cogames.policy.scripted_agent.unclipping_agent import UnclippingPolicy
+from cogames_agents.policy.scripted_agent.unclipping_agent import UnclippingPolicy
 
 policy = UnclippingPolicy(env)
 # ... same as BaselinePolicy
 ```
 
-**CLI**:
+### 4. TinyBaseline (demo policy)
 
-```bash
-# Test with unclipping diagnostic (single agent)
-uv run cogames play --mission evals.diagnostic_unclip_craft -p scripted_unclipping --cogs 1
+**Purpose**: Minimal, readable demo policy used for quick experiments.
 
-# Test with unclipping diagnostic (multi-agent)
-uv run cogames play --mission evals.diagnostic_unclip_craft -p scripted_unclipping --cogs 2
-```
+**Short name**: `tiny_baseline` (defined in `demo_policy.py`).
 
-### 3. StarterAgent
+## StarterAgent
 
 **Purpose**: Intro-friendly agent that mirrors the high-level flow described in docs.
 
@@ -141,6 +182,9 @@ uv run cogames play --mission evals.diagnostic_unclip_craft -p scripted_unclippi
 **Why it exists**: Shows the simplest possible if/else controller that still completes missions, ideal for external
 readers who want a tiny, readable starting point before diving into the full Baseline/Unclipping logic.
 
+**Location**: The starter policy lives in the core `cogames` package at `cogames.policy.starter_agent` so it is always
+available without installing `cogames-agents`.
+
 ## Shared Components
 
 ### Phase System
@@ -150,7 +194,7 @@ All agents use a phase-based state machine:
 ```python
 class Phase(Enum):
     GATHER = "gather"          # Collecting resources
-    ASSEMBLE = "assemble"      # Crafting heart at assembler
+    ASSEMBLE = "assemble"      # Crafting heart at hub
     DELIVER = "deliver"        # Bringing heart to chest
     RECHARGE = "recharge"      # Restoring energy
     CRAFT_UNCLIP = "craft_unclip"  # UnclippingAgent only
@@ -170,7 +214,7 @@ Shared `pathfinding.py` module provides:
 
 Agents parse egocentric observations (11×11 grid) to detect:
 
-- Stations (assembler, chest, charger, extractors)
+- Stations (hub, chest, junction, extractors)
 - Other agents
 - Walls and obstacles
 - Agent state (resources, energy, inventory)
@@ -194,40 +238,23 @@ class ExtractorInfo:
 
 ```bash
 # Basic diagnostic (single agent)
-uv run cogames play --mission evals.diagnostic_radial -p scripted_baseline --cogs 1 --steps 1000
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 1 --steps 1000
 
 # Chest navigation
-uv run cogames play --mission evals.diagnostic_chest_navigation1 -p scripted_baseline --cogs 1 --steps 1000
+uv run cogames play --mission evals.diagnostic_chest_navigation1 -p baseline --cogs 1 --steps 1000
 
 # Resource extraction
-uv run cogames play --mission evals.diagnostic_extract_missing_oxygen -p scripted_baseline --cogs 1 --steps 1000
+uv run cogames play --mission evals.diagnostic_extract_missing_oxygen -p baseline --cogs 1 --steps 1000
 
 # Hard version
-uv run cogames play --mission evals.diagnostic_radial_hard -p scripted_baseline --cogs 1 --steps 2000
+uv run cogames play --mission evals.diagnostic_radial_hard -p baseline --cogs 1 --steps 2000
 
 # Multi-agent (2, 4 agents)
-uv run cogames play --mission evals.diagnostic_radial -p scripted_baseline --cogs 2 --steps 1500
-uv run cogames play --mission evals.diagnostic_radial -p scripted_baseline --cogs 4 --steps 2000
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 2 --steps 1500
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 4 --steps 2000
 
 # Assembly test
-uv run cogames play --mission evals.diagnostic_assembler_search -p scripted_baseline --cogs 1 --steps 1000
-```
-
-#### UnclippingAgent (Unclipping Diagnostics)
-
-```bash
-# Unclipping craft diagnostic
-uv run cogames play --mission evals.diagnostic_unclip_craft -p scripted_unclipping --cogs 1 --steps 2000
-
-# Unclipping with pre-seeded inventory
-uv run cogames play --mission evals.diagnostic_unclip_preseed -p scripted_unclipping --cogs 1 --steps 2000
-
-# Multi-agent unclipping
-uv run cogames play --mission evals.diagnostic_unclip_craft -p scripted_unclipping --cogs 2 --steps 2000
-
-# Note: For testing clipping variants on procedural maps, use training_facility or hello_world sites
-# Example with variants:
-uv run cogames play --mission training_facility.harvest --variant clip_hub_stations --cogs 1 --steps 2000
+uv run cogames play --mission evals.diagnostic_assemble_seeded_search -p baseline --cogs 1 --steps 1000
 ```
 
 ### Comprehensive Evaluation
@@ -237,19 +264,16 @@ uv run cogames play --mission training_facility.harvest --variant clip_hub_stati
 uv run python packages/cogames/scripts/run_evaluation.py
 
 # Evaluate specific agent
-uv run python packages/cogames/scripts/run_evaluation.py --agent simple
-uv run python packages/cogames/scripts/run_evaluation.py --agent unclipping
+uv run python packages/cogames/scripts/run_evaluation.py --policy baseline
+uv run python packages/cogames/scripts/run_evaluation.py --policy ladybug
 ```
 
 ## Evaluation Results
 
-See `experiments/SCRIPTED_AGENT_EVALUATION.md` for comprehensive evaluation results across all missions and difficulty
-variants.
-
 **Summary**:
 
-- **BaselineAgent**: 33.8% success rate across 1-8 agents, best for non-clipped missions
-- **UnclippingAgent**: 38.6% success rate, best overall performance, handles clipping well
+- **BaselineAgent**: Works best for non-clipped missions with straightforward resource gathering
+- **UnclippingAgent**: Best overall performance, handles clipping scenarios well
 
 ## Extending
 
@@ -304,7 +328,7 @@ class MyPolicy:
 4. **Register in `__init__.py`**:
 
 ```python
-from cogames.policy.scripted_agent.my_agent import MyPolicy
+from cogames_agents.policy.scripted_agent.my_agent import MyPolicy
 
 __all__ = [..., "MyPolicy"]
 ```

cogames/evaluate.py

@@ -13,11 +13,11 @@ from pydantic import BaseModel, ConfigDict
 from rich.console import Console
 from rich.table import Table
 
+from metta_alo.rollout import run_multi_episode_rollout
+from metta_alo.scoring import allocate_counts, validate_proportions
 from mettagrid import MettaGridConfig
-from mettagrid.policy.loader import initialize_or_load_policy
-from mettagrid.policy.policy import MultiAgentPolicy, PolicySpec
-from mettagrid.policy.policy_env_interface import PolicyEnvInterface
-from mettagrid.simulator.multi_episode.rollout import MultiEpisodeRolloutResult, multi_episode_rollout
+from mettagrid.policy.policy import PolicySpec
+from mettagrid.simulator.multi_episode.rollout import MultiEpisodeRolloutResult
 from mettagrid.simulator.multi_episode.summary import MultiEpisodeRolloutSummary, build_multi_episode_rollout_summaries
 
 MissionResultsSummary: TypeAlias = list[MultiEpisodeRolloutSummary]
@@ -53,6 +53,7 @@ def evaluate(
         raise ValueError("At least one mission must be provided for evaluation.")
     if not policy_specs:
         raise ValueError("At least one policy specification must be provided for evaluation.")
+    validate_proportions(proportions, len(policy_specs))
 
     mission_names = [mission_name for mission_name, _ in missions]
     if len(missions) == 1:
@@ -68,40 +69,27 @@ def evaluate(
     mission_results: list[MultiEpisodeRolloutResult] = []
     all_replay_paths: list[str] = []
     for mission_name, env_cfg in missions:
-        env_interface = PolicyEnvInterface.from_mg_cfg(env_cfg)
-        policy_instances: list[MultiAgentPolicy] = [
-            initialize_or_load_policy(env_interface, spec) for spec in policy_specs
-        ]
+        counts = allocate_counts(env_cfg.game.num_agents, proportions)
+        assignments = np.repeat(np.arange(len(counts), dtype=int), counts)
 
         progress_label = f"Simulating ({mission_name})"
-        progress_iterable = range(episodes)
-        with typer.progressbar(progress_iterable, label=progress_label) as progress:
-            iterator = iter(progress)
-
-            def _progress_callback(_: int, progress_iter=iterator) -> None:
-                try:
-                    next(progress_iter)
-                except StopIteration:
-                    pass
-
-            rollout_payload = multi_episode_rollout(
+        with typer.progressbar(length=episodes, label=progress_label) as progress:
+            rollout, replay_paths = run_multi_episode_rollout(
+                policy_specs=policy_specs,
+                assignments=assignments,
                 env_cfg=env_cfg,
-                policies=policy_instances,
-                proportions=proportions,
                 episodes=episodes,
-                max_action_time_ms=action_timeout_ms,
                 seed=seed,
-                progress_callback=_progress_callback,
-                save_replay=save_replay,
+                max_action_time_ms=action_timeout_ms,
+                replay_dir=save_replay,
+                create_replay_dir=save_replay is not None,
+                on_progress=lambda _episode_idx, _result: progress.update(1),
             )
-        mission_results.append(rollout_payload)
-        # Collect replay paths from this mission
-        for episode in rollout_payload.episodes:
-            if episode.replay_path:
-                all_replay_paths.append(episode.replay_path)
+
+        mission_results.append(rollout)
+        all_replay_paths.extend(replay_paths)
 
     summaries = build_multi_episode_rollout_summaries(mission_results, num_policies=len(policy_specs))
-    mission_names = [mission_name for mission_name, _ in missions]
     _output_results(console, policy_specs, mission_names, summaries, output_format)
 
     # Print replay commands if replays were saved