cogames-agents 0.0.0.7__cp312-cp312-macosx_11_0_arm64.whl

cogames_agents/policy/scripted_agent/planky/tests/test_aligner.py

@@ -0,0 +1,24 @@
+"""Capability tests for the Aligner role."""
+
+from cogames_agents.policy.scripted_agent.planky.tests.helpers import EpisodeResult
+
+
+def test_aligner_acquires_gear(aligner_episode: EpisodeResult):
+    gained = aligner_episode.gear_gained("aligner")
+    assert gained > 0, (
+        f"Aligner did not acquire gear (aligner.gained={gained})\nTrace:\n{aligner_episode.trace.summary()}"
+    )
+
+
+def test_aligner_acquires_hearts(aligner_episode: EpisodeResult):
+    hearts = aligner_episode.hearts_gained()
+    assert hearts > 0, (
+        f"Aligner did not acquire hearts (heart.gained={hearts})\nTrace:\n{aligner_episode.trace.summary()}"
+    )
+
+
+def test_aligner_aligns_junctions(aligner_episode: EpisodeResult):
+    aligned = aligner_episode.junctions_aligned()
+    assert aligned > 0, (
+        f"Aligner did not align any junctions (junction.gained={aligned})\nTrace:\n{aligner_episode.trace.summary()}"
+    )

cogames_agents/policy/scripted_agent/planky/tests/test_miner.py

@@ -0,0 +1,30 @@
+"""Capability tests for the Miner role."""
+
+from cogames_agents.policy.scripted_agent.planky.tests.helpers import EpisodeResult
+
+
+def test_miner_acquires_gear(miner_episode: EpisodeResult):
+    gained = miner_episode.gear_gained("miner")
+    assert gained > 0, f"Miner did not acquire gear (miner.gained={gained})\nTrace:\n{miner_episode.trace.summary()}"
+
+
+def test_miner_deposits_resources(miner_episode: EpisodeResult):
+    total = miner_episode.total_deposited()
+    assert total > 0, (
+        f"Miner did not deposit any resources (total_deposited={total})\nTrace:\n{miner_episode.trace.summary()}"
+    )
+
+
+def test_miner_mines_multiple_elements(miner_episode: EpisodeResult):
+    elements = ["carbon", "oxygen", "germanium", "silicon"]
+    deposited = {e: miner_episode.resource_deposited(e) for e in elements}
+    non_zero = [e for e, v in deposited.items() if v > 0]
+    assert len(non_zero) >= 1, f"Miner did not mine any elements: {deposited}\nTrace:\n{miner_episode.trace.summary()}"
+
+
+def test_miner_stays_productive(miner_episode: EpisodeResult):
+    """Miner should deposit a meaningful amount of resources in 500 steps."""
+    total = miner_episode.total_deposited()
+    assert total >= 10, (
+        f"Miner deposited too few resources ({total}), may be stuck or idle\nTrace:\n{miner_episode.trace.summary()}"
+    )

cogames_agents/policy/scripted_agent/planky/tests/test_scout.py

@@ -0,0 +1,15 @@
+"""Capability tests for the Scout role."""
+
+from cogames_agents.policy.scripted_agent.planky.tests.helpers import EpisodeResult
+
+
+def test_scout_acquires_gear(scout_episode: EpisodeResult):
+    gained = scout_episode.gear_gained("scout")
+    assert gained > 0, f"Scout did not acquire gear (scout.gained={gained})\nTrace:\n{scout_episode.trace.summary()}"
+
+
+def test_scout_explores(scout_episode: EpisodeResult):
+    """Scout should be actively exploring (Explore goal activated in trace)."""
+    assert scout_episode.trace.had_goal("Explore"), (
+        f"Scout never activated Explore goal\nTrace:\n{scout_episode.trace.summary()}"
+    )

cogames_agents/policy/scripted_agent/planky/tests/test_scrambler.py

@@ -0,0 +1,29 @@
+"""Capability tests for the Scrambler role."""
+
+import pytest
+
+from cogames_agents.policy.scripted_agent.planky.tests.helpers import EpisodeResult
+
+
+def test_scrambler_acquires_gear(scrambler_episode: EpisodeResult):
+    gained = scrambler_episode.gear_gained("scrambler")
+    assert gained > 0, (
+        f"Scrambler did not acquire gear (scrambler.gained={gained})\nTrace:\n{scrambler_episode.trace.summary()}"
+    )
+
+
+def test_scrambler_acquires_hearts(scrambler_episode: EpisodeResult):
+    hearts = scrambler_episode.hearts_gained()
+    assert hearts > 0, (
+        f"Scrambler did not acquire hearts (heart.gained={hearts})\nTrace:\n{scrambler_episode.trace.summary()}"
+    )
+
+
+@pytest.mark.xfail(reason="Scrambler cannot reach enemy junctions in 500 steps with limited economy")
+def test_scrambler_scrambles_junctions(scrambler_episode: EpisodeResult):
+    # Check for scrambled junctions in clips stats (enemy junctions neutralized)
+    clips_aligned = int(scrambler_episode.clips_stats.get("junction.lost", 0))
+    assert clips_aligned > 0, (
+        f"Scrambler did not scramble any enemy junctions (clips junction.lost={clips_aligned})\n"
+        f"Trace:\n{scrambler_episode.trace.summary()}"
+    )

cogames_agents/policy/scripted_agent/planky/tests/test_stem.py

@@ -0,0 +1,36 @@
+"""Capability tests for the Stem (dynamic role selection) system."""
+
+from cogames_agents.policy.scripted_agent.planky.tests.helpers import EpisodeResult
+
+
+def test_stem_agents_select_roles(stem_episode: EpisodeResult):
+    changes = stem_episode.trace.role_changes
+    assert len(changes) > 0, f"No role changes detected in trace\nTrace:\n{stem_episode.trace.summary()}"
+
+
+def test_stem_multiple_roles_represented(stem_episode: EpisodeResult):
+    roles_seen = set()
+    for line in stem_episode.trace.role_changes:
+        # Format: "[planky][t=5 a=1] role: stem→miner"
+        if "→" in line:
+            role = line.split("→")[-1].strip()
+            roles_seen.add(role)
+    assert len(roles_seen) >= 2, (
+        f"Only {len(roles_seen)} role(s) selected: {roles_seen}. "
+        f"Expected at least 2 distinct roles.\n"
+        f"Trace:\n{stem_episode.trace.summary()}"
+    )
+
+
+def test_stem_economy_produces_resources(stem_episode: EpisodeResult):
+    total = stem_episode.total_deposited()
+    assert total > 0, (
+        f"Stem team did not deposit any resources (total_deposited={total})\nTrace:\n{stem_episode.trace.summary()}"
+    )
+
+
+def test_stem_pipeline_aligns_junctions(stem_episode: EpisodeResult):
+    aligned = stem_episode.junctions_aligned()
+    assert aligned > 0, (
+        f"Stem team did not align any junctions (junction.gained={aligned})\nTrace:\n{stem_episode.trace.summary()}"
+    )

cogames_agents/policy/scripted_agent/planky/trace.py

@@ -0,0 +1,69 @@
+"""Tracing system for Planky policy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class TraceEntry:
+    """One goal evaluation entry."""
+
+    goal_name: str
+    satisfied: bool
+    detail: str = ""
+
+
+@dataclass
+class TraceLog:
+    """Collects trace information during a single tick."""
+
+    entries: list[TraceEntry] = field(default_factory=list)
+    active_goal_chain: str = ""
+    action_name: str = ""
+    blackboard_summary: str = ""
+    nav_target: Optional[tuple[int, int]] = None
+    steps_since_useful: int = 0  # Steps since last useful action (mine/deposit/align/scramble)
+
+    def skip(self, goal_name: str, reason: str = "ok") -> None:
+        """Record a satisfied (skipped) goal."""
+        self.entries.append(TraceEntry(goal_name=goal_name, satisfied=True, detail=reason))
+
+    def activate(self, goal_name: str, detail: str = "") -> None:
+        """Record an activated (unsatisfied) goal."""
+        self.entries.append(TraceEntry(goal_name=goal_name, satisfied=False, detail=detail))
+
+    def format_line(
+        self,
+        step: int,
+        agent_id: int,
+        role: str,
+        pos: tuple[int, int],
+        hp: int,
+        level: int,
+    ) -> str:
+        """Format the trace as a single line."""
+        # Include idle indicator if agent hasn't done anything useful recently
+        idle_str = f" IDLE={self.steps_since_useful}" if self.steps_since_useful >= 20 else ""
+        prefix = f"[t={step} a={agent_id} {role} ({pos[0]},{pos[1]}) hp={hp}{idle_str}]"
+
+        if level == 1:
+            return f"{prefix} {self.active_goal_chain} → {self.action_name}"
+
+        if level == 2:
+            skips = " ".join(f"skip:{e.goal_name}({e.detail})" for e in self.entries if e.satisfied)
+            target_str = ""
+            if self.nav_target:
+                dist = abs(self.nav_target[0] - pos[0]) + abs(self.nav_target[1] - pos[1])
+                target_str = f" dist={dist}"
+            bb = f" | bb={{{self.blackboard_summary}}}" if self.blackboard_summary else ""
+            idle_detail = f" idle={self.steps_since_useful}" if self.steps_since_useful > 0 else ""
+            return f"{prefix} {skips} → {self.active_goal_chain}{target_str} → {self.action_name}{bb}{idle_detail}"
+
+        # Level 3 — full detail
+        all_entries = " ".join(f"{'skip' if e.satisfied else 'ACTIVE'}:{e.goal_name}({e.detail})" for e in self.entries)
+        target_str = f" nav_target={self.nav_target}" if self.nav_target else ""
+        bb = f" bb={{{self.blackboard_summary}}}" if self.blackboard_summary else ""
+        idle_detail = f" idle={self.steps_since_useful}"
+        return f"{prefix} {all_entries}{target_str} → {self.action_name}{bb}{idle_detail}"

cogames_agents/policy/scripted_agent/types.py

@@ -0,0 +1,239 @@
+"""
+Data types and structures for scripted agents.
+
+This module contains all the dataclasses, enums, and type definitions
+used by the baseline and unclipping agents.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+from mettagrid.simulator import Action
+from mettagrid.simulator.interface import AgentObservation
+
+
+@dataclass
+class BaselineHyperparameters:
+    """Hyperparameters controlling baseline agent behavior."""
+
+    # Energy management (recharge timing)
+    recharge_threshold_low: int = 35  # Enter RECHARGE phase when energy < this
+    recharge_threshold_high: int = 85  # Exit RECHARGE phase when energy >= this
+
+    # Stuck detection and escape
+    stuck_detection_enabled: bool = True  # Enable loop detection
+    stuck_escape_distance: int = 12  # Minimum distance for escape target
+
+    # Exploration parameters
+    position_history_size: int = 30  # Size of position history buffer
+    exploration_area_check_window: int = 30  # Steps to check for stuck area
+    exploration_area_size_threshold: int = 7  # Max area size (height/width) to trigger escape
+    exploration_escape_duration: int = 10  # Steps to navigate to hub when stuck
+    exploration_direction_persistence: int = 10  # Steps to persist in one direction
+    exploration_hub_distance_threshold: int = 10  # Min distance from hub to trigger escape
+
+
+# Hyperparameter Presets for Ensemble Creation
+BASELINE_HYPERPARAMETER_PRESETS = {
+    "default": BaselineHyperparameters(
+        recharge_threshold_low=35,  # Moderate energy management
+        recharge_threshold_high=85,
+        stuck_detection_enabled=True,
+        stuck_escape_distance=12,
+        position_history_size=40,  # Thorough exploration: longer history
+        exploration_area_check_window=35,  # Thorough exploration: longer check window
+        exploration_area_size_threshold=9,  # Thorough exploration: larger area tolerance
+        exploration_escape_duration=8,  # Thorough exploration: shorter escape duration
+        exploration_direction_persistence=18,  # Thorough exploration: longer persistence
+        exploration_hub_distance_threshold=12,  # Thorough exploration: larger distance threshold
+    ),
+    "conservative": BaselineHyperparameters(
+        recharge_threshold_low=50,  # Recharge early
+        recharge_threshold_high=95,  # Stay charged
+        stuck_detection_enabled=True,
+        stuck_escape_distance=8,  # Shorter escape distance
+        position_history_size=30,
+        exploration_area_check_window=30,
+        exploration_area_size_threshold=7,
+        exploration_escape_duration=10,
+        exploration_direction_persistence=10,
+        exploration_hub_distance_threshold=10,
+    ),
+    "aggressive": BaselineHyperparameters(
+        recharge_threshold_low=20,  # Low energy tolerance
+        recharge_threshold_high=80,  # Don't wait for full charge
+        stuck_detection_enabled=True,
+        stuck_escape_distance=15,  # Longer escape distance
+        position_history_size=30,
+        exploration_area_check_window=30,
+        exploration_area_size_threshold=7,
+        exploration_escape_duration=10,
+        exploration_direction_persistence=10,
+        exploration_hub_distance_threshold=10,
+    ),
+}
+
+
+class CellType(Enum):
+    """Occupancy map cell states."""
+
+    FREE = 1  # Passable (can walk through)
+    OBSTACLE = 2  # Impassable (walls, stations, extractors)
+
+
+class Phase(Enum):
+    """Goal-driven phases for the baseline agent."""
+
+    GATHER = "gather"  # Collect resources (explore if needed)
+    ASSEMBLE = "assemble"  # Make hearts at hub
+    DELIVER = "deliver"  # Deposit hearts to chest
+    RECHARGE = "recharge"  # Recharge energy at junction
+    CRAFT_UNCLIP = "craft_unclip"  # Craft unclip items at hub
+    UNCLIP = "unclip"  # Unclip extractors
+
+
+@dataclass
+class ExtractorInfo:
+    """Tracks a discovered extractor with full state."""
+
+    position: tuple[int, int]
+    resource_type: str  # "carbon", "oxygen", "germanium", "silicon"
+    last_seen_step: int
+    times_used: int = 0
+
+    # Extractor state from observations
+    cooldown_remaining: int = 0  # Steps until ready
+    clipped: bool = False  # Is it depleted?
+    remaining_uses: int = 999  # How many uses left
+
+
+@dataclass
+class ObjectState:
+    """State of a single object at a position."""
+
+    name: str
+    tags: list[str] = field(default_factory=list)
+
+    # Extractor/station features
+    cooldown_remaining: int = 0
+    clipped: int = 0
+    remaining_uses: int = 999
+
+    # Inventory (for chests/extractors - maps resource name to amount)
+    inventory: dict[str, int] = field(default_factory=dict)
+
+    # Protocol details (recipes for hubs/extractors)
+    protocol_inputs: dict[str, int] = field(default_factory=dict)
+    protocol_outputs: dict[str, int] = field(default_factory=dict)
+
+    # Agent features (when object is another agent)
+    agent_id: int = -1  # Which agent (-1 if not an agent) - NOT in observations, kept for API
+    agent_group: int = -1  # Team/group
+    agent_frozen: int = 0  # Is frozen?
+
+
+@dataclass
+class ParsedObservation:
+    """Parsed observation data in a clean format."""
+
+    # Agent state
+    row: int
+    col: int
+    energy: int
+
+    # Inventory
+    carbon: int
+    oxygen: int
+    germanium: int
+    silicon: int
+    hearts: int
+    decoder: int
+    modulator: int
+    resonator: int
+    scrambler: int
+
+    # Nearby objects with full state (position -> ObjectState)
+    nearby_objects: dict[tuple[int, int], ObjectState]
+
+
+@dataclass
+class SimpleAgentState:
+    """State for a single agent."""
+
+    agent_id: int
+
+    phase: Phase = Phase.GATHER  # Start gathering immediately
+    step_count: int = 0
+
+    # Current position (origin-relative, starting at (0, 0))
+    row: int = 0
+    col: int = 0
+    energy: int = 100
+
+    # Per-agent discovered extractors and stations (no shared state, each agent tracks independently)
+    extractors: dict[str, list[ExtractorInfo]] = field(
+        default_factory=lambda: {"carbon": [], "oxygen": [], "germanium": [], "silicon": []}
+    )
+    stations: dict[str, tuple[int, int] | None] = field(
+        default_factory=lambda: {"hub": None, "chest": None, "junction": None}
+    )
+
+    # Inventory
+    carbon: int = 0
+    oxygen: int = 0
+    germanium: int = 0
+    silicon: int = 0
+    hearts: int = 0
+    decoder: int = 0
+    modulator: int = 0
+    resonator: int = 0
+    scrambler: int = 0
+
+    # Current target
+    target_position: Optional[tuple[int, int]] = None
+    target_resource: Optional[str] = None
+
+    # Map knowledge
+    map_height: int = 0
+    map_width: int = 0
+    occupancy: list[list[int]] = field(default_factory=list)  # 1=free, 2=obstacle (initialized in reset)
+
+    # Track last action for position updates
+    last_action: Action = field(default_factory=lambda: Action(name="noop"))
+
+    # Current glyph (vibe) for interacting with hub
+    current_glyph: str = "default"
+
+    # Discovered hub recipe (dynamically discovered from observations)
+    heart_recipe: Optional[dict[str, int]] = None
+
+    # Extractor activation state
+    waiting_at_extractor: Optional[tuple[int, int]] = None
+    wait_steps: int = 0
+    pending_use_resource: Optional[str] = None
+    pending_use_amount: int = 0
+
+    # Directional exploration state
+    exploration_target: Optional[str] = None  # Current direction ("north", "south", "east", "west")
+    exploration_target_step: int = 0  # When we set the direction
+    exploration_escape_until_step: int = 0  # If > 0, we're in escape mode until this step
+
+    # Agent positions (for collision detection)
+    agent_occupancy: set[tuple[int, int]] = field(default_factory=set)
+
+    # Stuck detection
+    position_history: list[tuple[int, int]] = field(default_factory=list)  # Last 30 positions
+    stuck_loop_detected: bool = False
+    stuck_escape_step: int = 0
+
+    # Path caching for efficient navigation (per-agent)
+    cached_path: Optional[list[tuple[int, int]]] = None
+    cached_path_target: Optional[tuple[int, int]] = None
+    cached_path_reach_adjacent: bool = False
+    using_object_this_step: bool = False  # Flag to prevent position update when using objects
+
+    # Current observation (for collision detection and state updates)
+    current_obs: Optional[AgentObservation] = None