cogames-agents 0.0.0.7__cp312-cp312-macosx_11_0_arm64.whl

cogames_agents/policy/nim_agents/thinky_eval.py

@@ -0,0 +1,230 @@
+# much simpler evaluator for thinky agents.
+
+from __future__ import annotations
+
+import time
+from typing import Dict, List, Tuple
+
+import cogames_agents.policy.nim_agents.agents as na
+from cogames.cli.utils import suppress_noisy_logs
+from cogames.cogs_vs_clips.evals.diagnostic_evals import DIAGNOSTIC_EVALS
+from cogames.cogs_vs_clips.mission import Mission, NumCogsVariant
+from mettagrid.policy.loader import initialize_or_load_policy
+from mettagrid.policy.policy import PolicySpec
+from mettagrid.policy.policy_env_interface import PolicyEnvInterface
+from mettagrid.simulator.rollout import Rollout
+
+# Agent to evaluate
+AGENT_PATH = "cogames_agents.policy.nim_agents.agents.ThinkyAgentsMultiPolicy"
+
+# Defaults (keep simple)
+NUM_COGS = 4
+MAX_STEPS = 10000
+SEED = 42
+
+# Add/modify your evals here over time
+EVALS: List[Tuple[str, str, int]] = [
+    # Regular evals
+    (
+        "energy_starved",
+        "buggy",
+        NUM_COGS,
+    ),  # E is very hard, max E is 256, but agents think its 100.
+    ("oxygen_bottleneck", "", NUM_COGS),
+    ("collect_resources_classic", "", NUM_COGS),
+    ("collect_resources_spread", "", NUM_COGS),
+    ("collect_far", "", NUM_COGS),
+    ("divide_and_conquer", "", NUM_COGS),
+    ("go_together", "", NUM_COGS),
+    ("single_use_swarm", "flakey", NUM_COGS),
+    # Diagnostic evals
+    ("diagnostic_chest_navigation1", "", 1),
+    ("diagnostic_chest_navigation2", "", 1),
+    ("diagnostic_chest_navigation3", "", 1),
+    ("diagnostic_chest_deposit_near", "", 1),
+    ("diagnostic_chest_deposit_search", "", 1),
+    ("diagnostic_charge_up", "buggy", 1),  # The cog needs to sacrifice itself to make hart.
+    ("diagnostic_memory", "", 1),
+    ("diagnostic_assemble_seeded_near", "", 1),
+    ("diagnostic_assemble_seeded_search", "", 1),
+    ("diagnostic_extract_missing_carbon", "", 1),
+    ("diagnostic_extract_missing_oxygen", "", 1),
+    ("diagnostic_extract_missing_germanium", "", 1),
+    ("diagnostic_extract_missing_silicon", "", 1),
+    ("diagnostic_agile", "", 1),
+    ("diagnostic_radial", "", 1),
+    # Hello World evals
+    ("distant_resources", "buggy", NUM_COGS),  # Not enough time for such distances.
+    ("quadrant_buildings", "buggy", NUM_COGS),  # Not enough junction for such distances.
+    ("vibe_check", "", NUM_COGS),
+    ("oxygen_bottleneck_easy", "", NUM_COGS),
+    ("oxygen_bottleneck_standard", "", NUM_COGS),
+    ("oxygen_bottleneck_hard", "buggy", NUM_COGS),  # Not enough junction for such distances.
+    ("energy_starved_easy", "", NUM_COGS),
+    ("energy_starved_standard", "buggy", NUM_COGS),  # E drain too high.
+    ("energy_starved_hard", "buggy", NUM_COGS),  # E drain too high.
+    ("unclipping_easy", "n/a", NUM_COGS),
+    ("unclipping_standard", "n/a", NUM_COGS),
+    ("unclipping_hard", "n/a", NUM_COGS),
+    ("distant_resources_easy", "", NUM_COGS),
+    ("distant_resources_standard", "flakey", NUM_COGS),  # Not enough time for such distances.
+    ("distant_resources_hard", "buggy", NUM_COGS),  # Not enough time for such distances.
+    ("quadrant_buildings_easy", "", NUM_COGS),
+    ("quadrant_buildings_standard", "buggy", NUM_COGS),  # Not enough junction for such distances.
+    ("quadrant_buildings_hard", "buggy", NUM_COGS),  # Not enough junction for such distances.
+    ("single_use_swarm_easy", "buggy", NUM_COGS),
+    ("single_use_swarm_standard", "buggy", NUM_COGS),  # Not enough time for such distances.
+    ("single_use_swarm_hard", "buggy", NUM_COGS),  # E drain too high.
+    ("vibe_check_easy", "buggy", NUM_COGS),  # No/invalid recipes available.
+    ("vibe_check_standard", "", NUM_COGS),
+    ("vibe_check_hard", "flakey", NUM_COGS),  # Not enough time for such distances.
+    # Hearts evals
+    ("easy_large_hearts", "slow", NUM_COGS),
+    ("easy_medium_hearts", "", NUM_COGS),
+    ("easy_small_hearts", "flakey", NUM_COGS),
+    # Missions from missions.py
+    ("harvest", "", NUM_COGS),
+    ("repair", "", 2),  # repair uses 2 cogs
+    ("hello_world_unclip", "", NUM_COGS),
+]
+
+
+def _load_all_missions() -> Dict[str, Mission]:
+    # Minimal loader: merge all known mission sets
+    from importlib import import_module
+
+    missions: List[Mission] = []
+    for mod_name in (
+        "cogames.cogs_vs_clips.evals.integrated_evals",
+        "cogames.cogs_vs_clips.evals.spanning_evals",
+        "cogames.cogs_vs_clips.missions",
+    ):
+        try:
+            mod = import_module(mod_name)
+            # missions.py uses MISSIONS, others use EVAL_MISSIONS
+            eval_list = getattr(mod, "MISSIONS", getattr(mod, "EVAL_MISSIONS", []))
+            missions.extend(eval_list)
+        except Exception:
+            pass
+
+    # Diagnostic evals are a list of classes; instantiate them
+    try:
+        missions.extend([cls() for cls in DIAGNOSTIC_EVALS])  # type: ignore[misc]
+    except Exception:
+        pass
+
+    # Build name -> mission instance map
+    mission_map: Dict[str, Mission] = {}
+    for m in missions:
+        # Items in EVAL_MISSIONS may be classes or instances; normalize to instances
+        try:
+            mission: Mission = m() if isinstance(m, type) else m  # type: ignore[call-arg,assignment]
+        except Exception:
+            continue
+        mission_map[mission.name] = mission
+    return mission_map
+
+
+def _ensure_vibe_supports_gear(env_cfg) -> None:
+    # Keep minimal and silent if anything fails
+    try:
+        hub = env_cfg.game.objects.get("hub")
+        uses_gear = False
+        if hub is not None and hasattr(hub, "protocols"):
+            for proto in hub.protocols:
+                if any(v == "gear" for v in getattr(proto, "vibes", [])):
+                    uses_gear = True
+                    break
+        if uses_gear:
+            change_vibe = env_cfg.game.actions.change_vibe
+            has_gear = any(v.name == "gear" for v in change_vibe.vibes)
+            if not has_gear:
+                from mettagrid.config.vibes import VIBE_BY_NAME
+
+                change_vibe.vibes = list(change_vibe.vibes) + [VIBE_BY_NAME["gear"]]
+    except Exception:
+        pass
+
+
+def run_eval(experiment_name: str, tag: str, mission_map: Dict[str, Mission], num_cogs: int, seed: int) -> float:
+    start = time.perf_counter()
+    try:
+        if experiment_name not in mission_map:
+            print(f"{tag:<6} {experiment_name:<40} {'MISSION NOT FOUND':>6}")
+            return 0.0
+
+        base_mission = mission_map[experiment_name]
+        mission = base_mission.with_variants([NumCogsVariant(num_cogs=num_cogs)])
+
+        env_cfg = mission.make_env()
+        _ensure_vibe_supports_gear(env_cfg)
+        env_cfg.game.max_steps = MAX_STEPS
+
+        # Create policy and rollout
+        pei = PolicyEnvInterface.from_mg_cfg(env_cfg)
+        policy = initialize_or_load_policy(
+            pei,
+            PolicySpec(class_path=AGENT_PATH, data_path=None),
+        )
+        agent_policies = [policy.agent_policy(i) for i in range(num_cogs)]
+
+        rollout = Rollout(
+            env_cfg,
+            agent_policies,
+            render_mode="none",
+            seed=seed,
+        )
+        rollout.run_until_done()
+
+        total_reward = float(sum(rollout._sim.episode_rewards))
+        hearts_per_agent = total_reward / max(1, num_cogs)
+        elapsed = time.perf_counter() - start
+
+        # One simple line per eval
+        hpa = f"{hearts_per_agent:.2f}"
+        tm = f"{elapsed:.2f}"
+        print(f"{tag:<6} {experiment_name:<40} {hpa:>6}h {tm:>6}s")
+        return hearts_per_agent
+    except Exception as e:
+        elapsed = time.perf_counter() - start
+        error_message = str(e)
+        print(f"{tag:<6} {experiment_name:<40} {error_message}")
+        return 0.0
+
+
+def main() -> None:
+    suppress_noisy_logs()
+    na.start_measure()
+    mission_map = _load_all_missions()
+    print(f"Loaded {len(mission_map)} missions")
+    print("tag .. map name ............................... harts/A .. time")
+    start = time.perf_counter()
+    total_hpa = 0.0
+    successful_evals = 0
+    num_evals = 0
+    for experiment_name, tag, num_cogs in EVALS:
+        num_evals += 1
+        if tag == "flakey":
+            for i in range(10):
+                hpa = run_eval(experiment_name, tag, mission_map, num_cogs, SEED + i)
+                if hpa > 0:
+                    successful_evals += 1
+                    total_hpa += hpa
+                    break
+        else:
+            hpa = run_eval(experiment_name, tag, mission_map, num_cogs, SEED)
+            if hpa > 0:
+                successful_evals += 1
+                total_hpa += hpa
+    success_rate = successful_evals / num_evals
+    elapsed = time.perf_counter() - start
+    total_evals = f"{num_evals} evals {success_rate * 100:.1f}% successful"
+    hpa = f"{total_hpa:.2f}"
+    tm = f"{elapsed:.2f}"
+    tag = "total"
+    print(f"{tag:<6} {total_evals:<40} {hpa:>6}h {tm:>6}s")
+    na.end_measure()
+
+
+if __name__ == "__main__":
+    main()

cogames_agents/policy/scripted_agent/README.md

@@ -0,0 +1,360 @@
+# Scripted Agent Policies (cogames-agents)
+
+This file mirrors the scripted-agent reference used by the `cogames` CLI docs, kept here so the package ships the full
+details alongside the implementations.
+
+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 the CogsGuard team-play policy, two progressively capable scripted agents, and one tiny demo
+policy:
+
+1. **CogsGuard** - Vibe-based multi-role policy for the CogsGuard arena
+2. **BaselineAgent** - Core functionality: exploration, resource gathering, heart assembly (single/multi-agent)
+3. **UnclippingAgent** - Extends BaselineAgent with extractor unclipping capability
+
+## Architecture
+
+### File Structure
+
+```
+scripted_agent/
+├── cogsguard/                   # CogsGuard scripted policy (vibe-based roles)
+├── baseline_agent.py            # Base agent + BaselinePolicy wrapper
+├── unclipping_agent.py          # Unclipping extension + UnclippingPolicy wrapper
+├── demo_policy.py               # Tiny demo policy (short name: tiny_baseline)
+├── pathfinding.py               # Pathfinding utilities (shared)
+└── README.md                    # This documentation
+```
+
+Each agent file contains:
+
+- Agent class with core logic and state management
+- Policy wrapper classes at the bottom for CLI integration
+
+### Design Philosophy
+
+These agents are designed for **ablation studies** and **baseline evaluation**:
+
+- Simple, readable implementations
+- Clear separation of capabilities
+- Minimal dependencies
+
+## Agents
+
+### 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**: `cogsguard/README.md`
+
+### 2. BaselineAgent
+
+**Purpose**: Minimal working agent for single/multi-agent missions
+
+**Capabilities**:
+
+- ✅ Visual discovery (explores to find stations and extractors)
+- ✅ Resource gathering (navigates to extractors, handles cooldowns)
+- ✅ Heart assembly (deposits resources at hub)
+- ✅ Heart delivery (brings hearts to chest)
+- ✅ Energy management (recharges when low)
+- ✅ Extractor tracking (remembers positions, cooldowns, remaining uses)
+- ✅ Agent occupancy avoidance (multi-agent collision avoidance via pathfinding)
+
+**Limitations**:
+
+- ❌ No unclipping support (can't handle clipped extractors)
+- ⚠️ Multi-agent coordination is basic (agents avoid each other but don't explicitly coordinate)
+
+**Usage**:
+
+```python
+from cogames_agents.policy.scripted_agent.baseline_agent import BaselinePolicy
+from mettagrid import MettaGridEnv
+
+env = MettaGridEnv(env_config)
+policy = BaselinePolicy(env)
+
+obs, info = env.reset()
+policy.reset(obs, info)
+
+agent = policy.agent_policy(0)
+action = agent.step(obs[0])
+```
+
+**CLI**:
+
+```bash
+# Single agent
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 1
+
+# Multi-agent
+uv run cogames play --mission evals.diagnostic_radial -p baseline --cogs 4
+```
+
+### 3. UnclippingAgent
+
+**Purpose**: Handle missions with clipped extractors
+
+**Extends BaselineAgent with**:
+
+- ✅ Clipped extractor detection
+- ✅ Unclip item crafting
+- ✅ Extractor restoration
+- ✅ Resource deficit management (ensures enough resources for both unclipping and hearts)
+
+**Unclip Item Mapping**: | Clipped Resource | Unclip Item | Crafted From | Glyph |
+|-----------------|-------------|--------------|-------| | Oxygen | decoder | carbon | gear | | Carbon | modulator |
+oxygen | gear | | Germanium | resonator | silicon | gear | | Silicon | scrambler | germanium | gear |
+
+**Workflow**:
+
+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 hub
+5. Navigates to clipped extractor
+6. Uses item to unclip
+7. Resumes normal gathering
+
+**Usage**:
+
+```python
+from cogames_agents.policy.scripted_agent.unclipping_agent import UnclippingPolicy
+
+policy = UnclippingPolicy(env)
+# ... same as BaselinePolicy
+```
+
+### 4. TinyBaseline (demo policy)
+
+**Purpose**: Minimal, readable demo policy used for quick experiments.
+
+**Short name**: `tiny_baseline` (defined in `demo_policy.py`).
+
+## StarterAgent
+
+**Purpose**: Intro-friendly agent that mirrors the high-level flow described in docs.
+
+**Decision tree**:
+
+1. Low energy → go recharge
+2. Carrying a heart → deliver it
+3. Have all recipe inputs → assemble
+4. Otherwise → gather missing resources in a fixed order (carbon, oxygen, germanium, silicon)
+
+**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
+
+All agents use a phase-based state machine:
+
+```python
+class Phase(Enum):
+    GATHER = "gather"          # Collecting resources
+    ASSEMBLE = "assemble"      # Crafting heart at hub
+    DELIVER = "deliver"        # Bringing heart to chest
+    RECHARGE = "recharge"      # Restoring energy
+    CRAFT_UNCLIP = "craft_unclip"  # UnclippingAgent only
+    UNCLIP = "unclip"          # UnclippingAgent only
+```
+
+### Navigation
+
+Shared `pathfinding.py` module provides:
+
+- **BFS pathfinding** with occupancy grid
+- **Greedy fallback** when path blocked
+- **Adjacent positioning** for station interactions
+- **Agent occupancy avoidance** for multi-agent scenarios
+
+### Observation Parsing
+
+Agents parse egocentric observations (11×11 grid) to detect:
+
+- Stations (hub, chest, junction, extractors)
+- Other agents
+- Walls and obstacles
+- Agent state (resources, energy, inventory)
+
+### Extractor Tracking
+
+```python
+@dataclass
+class ExtractorInfo:
+    position: tuple[int, int]
+    resource_type: str  # "carbon", "oxygen", "germanium", "silicon"
+    remaining_uses: int
+    clipped: bool       # For UnclippingAgent
+```
+
+## Testing
+
+### Quick Tests
+
+#### BaselineAgent (Diagnostic Missions)
+
+```bash
+# Basic diagnostic (single agent)
+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 baseline --cogs 1 --steps 1000
+
+# Resource extraction
+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 baseline --cogs 1 --steps 2000
+
+# Multi-agent (2, 4 agents)
+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_assemble_seeded_search -p baseline --cogs 1 --steps 1000
+```
+
+### Comprehensive Evaluation
+
+```bash
+# Run full evaluation suite
+uv run python packages/cogames/scripts/run_evaluation.py --policy ladybug
+
+# Evaluate specific agent
+uv run python packages/cogames/scripts/run_evaluation.py --policy baseline
+uv run python packages/cogames/scripts/run_evaluation.py --policy ladybug
+```
+
+## Evaluation Results
+
+**Summary**:
+
+- **BaselineAgent**: Works best for non-clipped missions with straightforward resource gathering
+- **UnclippingAgent**: Best overall performance, handles clipping scenarios well
+
+## Extending
+
+### Adding New Agent Capabilities
+
+To create a new agent variant:
+
+1. **Create new file** (e.g., `my_agent.py`)
+2. **Extend base class**:
+
+```python
+from .baseline_agent import BaselineAgent, SimpleAgentState
+
+class MyAgent(BaselineAgent):
+    def _update_phase(self, s: SimpleAgentState) -> None:
+        # Add custom phase logic
+        super()._update_phase(s)
+
+    def _execute_phase(self, s: SimpleAgentState) -> int:
+        # Add custom phase execution
+        return super()._execute_phase(s)
+```
+
+3. **Add policy wrapper** at bottom of file:
+
+```python
+class MyAgentPolicy:
+    """Per-agent policy wrapper."""
+    def __init__(self, impl: MyAgent, agent_id: int):
+        self._impl = impl
+        self._agent_id = agent_id
+
+    def step(self, obs) -> int:
+        return self._impl.step(self._agent_id, obs)
+
+class MyPolicy:
+    """Policy wrapper for MyAgent."""
+    def __init__(self, simulation=None):
+        self._simulation = simulation
+        self._impl = None
+        self._agent_policies = {}
+
+    def reset(self, obs, info):
+        # Initialize impl from simulation
+        pass
+
+    def agent_policy(self, agent_id: int):
+        # Return per-agent policy
+        pass
+```
+
+4. **Register in `__init__.py`**:
+
+```python
+from cogames_agents.policy.scripted_agent.my_agent import MyPolicy
+
+__all__ = [..., "MyPolicy"]
+```
+
+### Resource Management
+
+Agents track deficits and gather in priority order:
+
+1. Germanium (5 needed, highest priority)
+2. Silicon (50 needed)
+3. Carbon (20 needed)
+4. Oxygen (20 needed)
+
+UnclippingAgent adds special logic:
+
+- Ensures enough craft resource for both unclipping AND hearts
+- Prevents resource deficits when crafting decoders
+
+## Future Work
+
+- [ ] Dynamic heart recipe detection
+- [ ] Charger clipping strategies
+- [ ] Clip spread handling
+- [ ] Learned extractor efficiency
+- [ ] Advanced multi-agent coordination (task assignment, resource reservation)
+- [ ] Frontier-based exploration improvements