cogames-agents 0.0.0.7__cp312-cp312-macosx_11_0_arm64.whl

cogames_agents/policy/scripted_agent/pinky/services/safety.py

@@ -0,0 +1,189 @@
+"""
+SafetyManager service for Pinky policy.
+
+Manages HP/energy awareness and risk assessment.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from cogames_agents.policy.scripted_agent.pinky.types import (
+    HP_DRAIN_NEAR_ENEMY,
+    HP_DRAIN_OUTSIDE_SAFE_ZONE,
+    HP_SAFETY_MARGIN,
+    JUNCTION_AOE_RANGE,
+    RiskTolerance,
+)
+
+if TYPE_CHECKING:
+    from cogames_agents.policy.scripted_agent.pinky.state import AgentState
+
+
+class SafetyManager:
+    """Manages risk based on HP, energy, and territory."""
+
+    # HP thresholds for retreat by risk tolerance
+    # These define the HP buffer to keep when calculating safe range
+    RETREAT_THRESHOLDS = {
+        RiskTolerance.CONSERVATIVE: 40,  # Miners keep 40 HP buffer for safety
+        RiskTolerance.MODERATE: 30,  # Aligners keep 30 HP buffer
+        RiskTolerance.AGGRESSIVE: 20,  # Scouts/Scramblers are bold, keep 20 HP
+    }
+
+    def should_retreat(self, state: AgentState, risk: RiskTolerance) -> bool:
+        """Check if agent should retreat to safety based on HP and risk tolerance.
+
+        Returns True if HP is low enough that we need to head back now.
+        """
+        # If we're already in a safe zone, no need to retreat
+        if self.is_in_safe_zone(state):
+            return False
+
+        # If no safe zones discovered yet, don't retreat - we need to explore first
+        # (unless HP is critically low)
+        safe_pos = self.nearest_safe_zone(state)
+        if safe_pos is None:
+            # Critical HP threshold - retreat even without known safe zone
+            return state.hp <= 20
+
+        # Calculate steps to nearest safe zone
+        steps_to_safety = self._steps_to_nearest_safe_zone(state)
+        drain_rate = self._get_hp_drain_rate(state)
+
+        # HP needed to survive the trip
+        hp_needed = (steps_to_safety * drain_rate) + HP_SAFETY_MARGIN
+
+        return state.hp <= hp_needed
+
+    def is_in_safe_zone(self, state: AgentState) -> bool:
+        """Check if agent is within AOE of any cogs-aligned junction or hub."""
+        # Check hub
+        hub_pos = state.map.stations.get("hub")
+        if hub_pos:
+            dist = abs(state.row - hub_pos[0]) + abs(state.col - hub_pos[1])
+            if dist <= JUNCTION_AOE_RANGE:
+                return True
+
+        # Check cogs junctions
+        for junction in state.map.get_cogs_junctions():
+            dist = abs(state.row - junction.position[0]) + abs(state.col - junction.position[1])
+            if dist <= JUNCTION_AOE_RANGE:
+                return True
+
+        return False
+
+    def is_in_danger_zone(self, state: AgentState) -> bool:
+        """Check if agent is within AOE of any clips-aligned junction."""
+        for junction in state.map.get_clips_junctions():
+            dist = abs(state.row - junction.position[0]) + abs(state.col - junction.position[1])
+            if dist <= JUNCTION_AOE_RANGE:
+                return True
+        return False
+
+    def nearest_safe_zone(self, state: AgentState) -> Optional[tuple[int, int]]:
+        """Find nearest cogs-aligned building (hub or junction)."""
+        candidates: list[tuple[int, tuple[int, int]]] = []
+
+        # Hub is always cogs-aligned
+        hub_pos = state.map.stations.get("hub")
+        if hub_pos:
+            dist = abs(hub_pos[0] - state.row) + abs(hub_pos[1] - state.col)
+            candidates.append((dist, hub_pos))
+
+        # Cogs junctions
+        for junction in state.map.get_cogs_junctions():
+            dist = abs(junction.position[0] - state.row) + abs(junction.position[1] - state.col)
+            candidates.append((dist, junction.position))
+
+        if not candidates:
+            return None
+
+        candidates.sort(key=lambda x: x[0])
+        return candidates[0][1]
+
+    def step_based_range_limit(self, step: int) -> int:
+        """Calculate exploration range limit based on current step.
+
+        - First 1000 ticks: limit range to 50
+        - After 1000 ticks: start at 100, increase by 10 every 100 ticks
+        """
+        if step < 1000:
+            return 50
+        else:
+            # Start at 100 at step 1000, increase by 10 every 100 steps
+            extra_hundreds = (step - 1000) // 100
+            return 100 + extra_hundreds * 10
+
+    def max_safe_distance(self, state: AgentState, risk: RiskTolerance) -> int:
+        """Calculate max round-trip distance based on HP, risk tolerance, and step.
+
+        Returns the maximum total distance (to target + back to healing) that's safe.
+        Also applies step-based range limits to encourage gradual expansion.
+        """
+        # Reserve HP based on risk tolerance
+        threshold = self.RETREAT_THRESHOLDS[risk]
+        available_hp = max(0, state.hp - threshold)
+
+        # Calculate drain rate
+        drain_rate = self._get_hp_drain_rate(state)
+        if drain_rate <= 0:
+            hp_based_dist = 999  # No drain, unlimited HP-based range
+        else:
+            # Max steps we can take before HP runs out
+            max_steps = available_hp // drain_rate
+            # Round trip, so divide by 2
+            hp_based_dist = max_steps // 2
+
+        # Apply step-based range limit
+        step_limit = self.step_based_range_limit(state.step)
+
+        return min(hp_based_dist, step_limit)
+
+    def can_reach_safely(self, state: AgentState, target: tuple[int, int], risk: RiskTolerance) -> bool:
+        """Check if agent can reach target AND return to safety."""
+        dist_to_target = abs(target[0] - state.row) + abs(target[1] - state.col)
+
+        # Find distance from target back to nearest safe zone
+        safe_pos = self.nearest_safe_zone(state)
+        if safe_pos is None:
+            # No known safe zone, be conservative
+            dist_back = dist_to_target
+        else:
+            dist_back = abs(target[0] - safe_pos[0]) + abs(target[1] - safe_pos[1])
+
+        total_dist = dist_to_target + max(0, dist_back - JUNCTION_AOE_RANGE)
+        max_dist = self.max_safe_distance(state, risk)
+
+        return total_dist <= max_dist
+
+    def is_position_in_enemy_aoe(self, state: AgentState, pos: tuple[int, int]) -> bool:
+        """Check if a position is within AOE of any enemy junction."""
+        for junction in state.map.get_clips_junctions():
+            dist = abs(pos[0] - junction.position[0]) + abs(pos[1] - junction.position[1])
+            if dist <= JUNCTION_AOE_RANGE:
+                return True
+        return False
+
+    def _steps_to_nearest_safe_zone(self, state: AgentState) -> int:
+        """Calculate steps to reach nearest safe zone's AOE."""
+        safe_pos = self.nearest_safe_zone(state)
+        if safe_pos is None:
+            return 100  # Unknown, be conservative
+
+        dist = abs(safe_pos[0] - state.row) + abs(safe_pos[1] - state.col)
+        return max(0, dist - JUNCTION_AOE_RANGE)
+
+    def _get_hp_drain_rate(self, state: AgentState) -> int:
+        """Calculate current HP drain rate based on position."""
+        # If in safe zone, no drain
+        if self.is_in_safe_zone(state):
+            return 0
+
+        drain = HP_DRAIN_OUTSIDE_SAFE_ZONE
+
+        # Additional drain if near enemy
+        if self.is_in_danger_zone(state):
+            drain += HP_DRAIN_NEAR_ENEMY
+
+        return drain

cogames_agents/policy/scripted_agent/pinky/state.py

@@ -0,0 +1,299 @@
+"""
+State classes for Pinky policy.
+
+AgentState, MapKnowledge, and NavigationState dataclasses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Optional
+
+from mettagrid.simulator import Action
+
+if TYPE_CHECKING:
+    from mettagrid.simulator.interface import AgentObservation
+
+from .types import CellType, DebugInfo, Role, StructureInfo, StructureType
+
+
+@dataclass
+class NavigationState:
+    """Navigation-related state managed by Navigator service."""
+
+    # Path caching
+    cached_path: Optional[list[tuple[int, int]]] = None
+    cached_path_target: Optional[tuple[int, int]] = None
+    cached_path_reach_adjacent: bool = False
+
+    # Exploration state (expanding box pattern)
+    explore_origin: Optional[tuple[int, int]] = None
+    explore_start_step: int = 0
+    explore_radius: int = 15  # Initial exploration radius, grows by 10% when area exhausted
+    explore_last_mineral_step: int = 0  # Last step we saw a mineral
+    # Resource rotation for miners - track recently gathered resources
+    last_resource_types: list[str] = field(default_factory=list)  # Most recent first, max 4
+    # Current extractor target - track to detect stuck/empty situations
+    current_extractor_target: Optional[tuple[int, int]] = None
+    steps_at_current_extractor: int = 0  # Steps spent at/near current target without cargo gain
+    failed_extractors: set[tuple[int, int]] = field(default_factory=set)  # Extractors that gave nothing
+    # Legacy fields (kept for compatibility)
+    exploration_direction: Optional[str] = None
+    exploration_direction_step: int = 0
+
+    # Stuck detection
+    position_history: list[tuple[int, int]] = field(default_factory=list)
+
+    # Track last action for position updates
+    last_action: Action = field(default_factory=lambda: Action(name="noop"))
+    last_action_executed: Optional[str] = None
+    using_object_this_step: bool = False
+
+
+@dataclass
+class AgentSighting:
+    """Information about a sighted agent."""
+
+    position: tuple[int, int]
+    last_seen_step: int
+
+
+@dataclass
+class MapKnowledge:
+    """What the agent has discovered about the world."""
+
+    grid_size: int = 200
+
+    # Occupancy grid: CellType.FREE or CellType.OBSTACLE
+    occupancy: list[list[int]] = field(default_factory=list)
+
+    # Which cells have been observed
+    explored: list[list[bool]] = field(default_factory=list)
+
+    # All discovered structures: position -> StructureInfo
+    structures: dict[tuple[int, int], StructureInfo] = field(default_factory=dict)
+
+    # Quick lookups (station_name -> position)
+    stations: dict[str, tuple[int, int]] = field(default_factory=dict)
+
+    # Other agents' positions (for collision avoidance)
+    # Current observation: positions of agents seen this step
+    agent_occupancy: set[tuple[int, int]] = field(default_factory=set)
+
+    # Recently seen agents with last-known positions
+    # Cleared when observation window passes over their position without seeing them
+    recent_agents: dict[tuple[int, int], AgentSighting] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Initialize grids if empty."""
+        if not self.occupancy:
+            # Initialize to UNKNOWN - cells become FREE/OBSTACLE when observed
+            self.occupancy = [[CellType.UNKNOWN.value] * self.grid_size for _ in range(self.grid_size)]
+        if not self.explored:
+            self.explored = [[False] * self.grid_size for _ in range(self.grid_size)]
+
+    # === Structure query methods ===
+
+    def get_structures_by_type(self, structure_type: StructureType) -> list[StructureInfo]:
+        """Get all structures of a given type."""
+        return [s for s in self.structures.values() if s.structure_type == structure_type]
+
+    def get_junctions(self) -> list[StructureInfo]:
+        """Get all known junctions."""
+        return self.get_structures_by_type(StructureType.JUNCTION)
+
+    def get_extractors(self) -> list[StructureInfo]:
+        """Get all known extractors."""
+        return self.get_structures_by_type(StructureType.EXTRACTOR)
+
+    def get_usable_extractors(self) -> list[StructureInfo]:
+        """Get all usable extractors (not depleted)."""
+        return [s for s in self.structures.values() if s.is_usable_extractor()]
+
+    def get_cogs_junctions(self) -> list[StructureInfo]:
+        """Get all cogs-aligned junctions (safe zones)."""
+        return [j for j in self.get_junctions() if j.is_cogs_aligned()]
+
+    def get_clips_junctions(self) -> list[StructureInfo]:
+        """Get all clips-aligned junctions (enemy zones)."""
+        return [j for j in self.get_junctions() if j.is_clips_aligned()]
+
+    def get_neutral_junctions(self) -> list[StructureInfo]:
+        """Get all neutral junctions."""
+        return [j for j in self.get_junctions() if j.is_neutral()]
+
+    def get_structure_at(self, pos: tuple[int, int]) -> Optional[StructureInfo]:
+        """Get structure at a specific position."""
+        return self.structures.get(pos)
+
+    def find_nearest_unexplored(
+        self, from_pos: tuple[int, int], max_dist: int = 50, direction_bias: Optional[str] = None
+    ) -> Optional[tuple[int, int]]:
+        """Find the nearest unexplored frontier cell.
+
+        A frontier cell is an unexplored cell adjacent to an explored FREE cell.
+        This guides exploration toward the edges of known territory.
+
+        Args:
+            from_pos: Starting position (row, col)
+            max_dist: Maximum search distance
+            direction_bias: Optional bias direction ('north', 'south', 'east', 'west')
+                           to spread agents across the map
+
+        Returns:
+            Position of nearest frontier cell, or None if none found
+        """
+        from collections import deque
+
+        r, c = from_pos
+        visited = set()
+        queue: deque[tuple[int, int, int]] = deque([(r, c, 0)])  # (row, col, distance)
+        visited.add((r, c))
+
+        # Direction deltas with bias ordering
+        if direction_bias == "north":
+            deltas = [(-1, 0), (0, -1), (0, 1), (1, 0)]
+        elif direction_bias == "south":
+            deltas = [(1, 0), (0, -1), (0, 1), (-1, 0)]
+        elif direction_bias == "east":
+            deltas = [(0, 1), (-1, 0), (1, 0), (0, -1)]
+        elif direction_bias == "west":
+            deltas = [(0, -1), (-1, 0), (1, 0), (0, 1)]
+        else:
+            deltas = [(-1, 0), (1, 0), (0, -1), (0, 1)]
+
+        while queue:
+            cr, cc, dist = queue.popleft()
+
+            if dist > max_dist:
+                continue
+
+            for dr, dc in deltas:
+                nr, nc = cr + dr, cc + dc
+
+                if (nr, nc) in visited:
+                    continue
+                if not (0 <= nr < self.grid_size and 0 <= nc < self.grid_size):
+                    continue
+
+                visited.add((nr, nc))
+
+                # Check if this is a frontier cell (unexplored, adjacent to explored FREE)
+                if not self.explored[nr][nc]:
+                    # Check if any neighbor is explored and FREE
+                    for dr2, dc2 in deltas:
+                        nnr, nnc = nr + dr2, nc + dc2
+                        if 0 <= nnr < self.grid_size and 0 <= nnc < self.grid_size:
+                            if self.explored[nnr][nnc] and self.occupancy[nnr][nnc] == CellType.FREE.value:
+                                return (nr, nc)
+
+                # Only expand through explored FREE cells
+                if self.explored[cr][cc] and self.occupancy[cr][cc] == CellType.FREE.value:
+                    queue.append((nr, nc, dist + 1))
+
+        return None
+
+
+@dataclass
+class AgentState:
+    """Complete state for a Pinky agent."""
+
+    agent_id: int
+    role: Role = Role.MINER
+
+    # Current vibe (read from observation)
+    vibe: str = "default"
+
+    # Step counter
+    step: int = 0
+
+    # Position (relative to spawn, stored at grid center)
+    row: int = 100
+    col: int = 100
+
+    # Inventory
+    energy: int = 100
+    hp: int = 100
+    carbon: int = 0
+    oxygen: int = 0
+    germanium: int = 0
+    silicon: int = 0
+    heart: int = 0
+    influence: int = 0
+
+    # Collective inventory (observed from stats tokens)
+    collective_carbon: int = 0
+    collective_oxygen: int = 0
+    collective_germanium: int = 0
+    collective_silicon: int = 0
+
+    # Gear (presence = equipped)
+    miner_gear: bool = False
+    scout_gear: bool = False
+    aligner_gear: bool = False
+    scrambler_gear: bool = False
+
+    # Map knowledge
+    map: MapKnowledge = field(default_factory=MapKnowledge)
+
+    # Navigation state
+    nav: NavigationState = field(default_factory=NavigationState)
+
+    # Recently visited extractor positions (for cooldown avoidance)
+    recently_mined: list[tuple[int, int]] = field(default_factory=list)
+
+    # Track cargo changes to detect extraction failure (inventory full)
+    prev_total_cargo: int = 0
+    steps_without_cargo_gain: int = 0  # Consecutive steps where cargo didn't increase
+
+    # Gear retry tracking: when gear is lost, track retry timing
+    # If station doesn't give gear, explore/mine for 200 ticks then retry
+    last_gear_attempt_step: int = 0  # Step when we last tried to get gear from station
+    had_gear_last_step: bool = False  # Whether we had gear last step (detect gear loss)
+
+    # Stuck detection: track consecutive steps at same position
+    last_position: tuple[int, int] = (100, 100)
+    steps_at_same_position: int = 0
+
+    # Escape mode: when stuck, commit to escaping for several steps
+    escape_direction: Optional[str] = None  # Direction to escape (north/south/east/west)
+    escape_until_step: int = 0  # Keep escaping until this step
+
+    # Aligner target tracking: current junction being targeted
+    aligner_target: Optional[tuple[int, int]] = None
+
+    # Last observation (for relative direction calculations)
+    last_obs: Optional["AgentObservation"] = None
+
+    # Debug info (populated by behaviors when debug is enabled)
+    debug_info: DebugInfo = field(default_factory=DebugInfo)
+
+    # === Computed properties ===
+
+    @property
+    def pos(self) -> tuple[int, int]:
+        """Current position as tuple."""
+        return (self.row, self.col)
+
+    @property
+    def total_cargo(self) -> int:
+        """Total resources currently carried."""
+        return self.carbon + self.oxygen + self.germanium + self.silicon
+
+    @property
+    def cargo_capacity(self) -> int:
+        """Cargo capacity (base 4, +40 with miner gear)."""
+        return 4 + (40 if self.miner_gear else 0)
+
+    def has_gear(self, role: Optional[Role] = None) -> bool:
+        """Check if agent has gear for the specified role (or their own role)."""
+        check_role = role or self.role
+        if check_role == Role.MINER:
+            return self.miner_gear
+        elif check_role == Role.SCOUT:
+            return self.scout_gear
+        elif check_role == Role.ALIGNER:
+            return self.aligner_gear
+        elif check_role == Role.SCRAMBLER:
+            return self.scrambler_gear
+        return False

cogames_agents/policy/scripted_agent/pinky/types.py

@@ -0,0 +1,138 @@
+"""
+Types and constants for Pinky policy.
+
+Enums, StructureInfo, and role-related definitions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+from cogames_agents.policy.scripted_agent.common import roles as common_roles
+
+Role = common_roles.Role
+ROLE_TO_STATION = common_roles.ROLE_TO_STATION
+VIBE_TO_ROLE = common_roles.VIBE_TO_ROLE
+
+
+class RiskTolerance(Enum):
+    """Risk tolerance levels for different roles."""
+
+    CONSERVATIVE = "conservative"  # Miners - stay in safe zones
+    MODERATE = "moderate"  # Aligners - venture out carefully
+    AGGRESSIVE = "aggressive"  # Scouts, Scramblers - deep territory
+
+
+# Map roles to their risk tolerance
+ROLE_RISK_TOLERANCE: dict[Role, RiskTolerance] = {
+    Role.MINER: RiskTolerance.CONSERVATIVE,
+    Role.SCOUT: RiskTolerance.AGGRESSIVE,
+    Role.ALIGNER: RiskTolerance.MODERATE,
+    Role.SCRAMBLER: RiskTolerance.AGGRESSIVE,
+}
+
+
+class CellType(Enum):
+    """Occupancy map cell states."""
+
+    UNKNOWN = 0  # Not yet explored
+    FREE = 1  # Passable (can walk through)
+    OBSTACLE = 2  # Impassable (walls, stations, extractors)
+
+
+class StructureType(Enum):
+    """Types of structures in the game."""
+
+    HUB = "hub"  # Main hub / resource deposit point (cogs nexus)
+    JUNCTION = "junction"  # Territory control point (junction/supply depot)
+    MINER_STATION = "miner_station"
+    SCOUT_STATION = "scout_station"
+    ALIGNER_STATION = "aligner_station"
+    SCRAMBLER_STATION = "scrambler_station"
+    EXTRACTOR = "extractor"  # Resource source
+    CHEST = "chest"  # Heart source
+    WALL = "wall"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class StructureInfo:
+    """Information about a discovered structure."""
+
+    position: tuple[int, int]
+    structure_type: StructureType
+    name: str  # Original object name
+
+    # When we last saw this structure
+    last_seen_step: int = 0
+
+    # Alignment: "cogs", "clips", or None (neutral)
+    alignment: Optional[str] = None
+
+    # Extractor-specific attributes
+    resource_type: Optional[str] = None  # carbon, oxygen, germanium, silicon
+    remaining_uses: int = 999
+    cooldown_remaining: int = 0
+    inventory_amount: int = -1  # -1 = unknown (protocol-based), 0+ = chest-based with that amount
+    has_inventory: bool = False  # True once we've seen inv: tokens for this extractor
+
+    def is_usable_extractor(self) -> bool:
+        """Check if this is a usable extractor (not depleted, has resources).
+
+        Protocol-based extractors: Only check remaining_uses > 0
+        Chest-based extractors: Also check inventory_amount > 0
+        """
+        if self.structure_type != StructureType.EXTRACTOR:
+            return False
+        if self.remaining_uses <= 0:
+            return False
+        # If we've never seen inventory tokens, assume protocol-based (usable if remaining_uses > 0)
+        if not self.has_inventory:
+            return True
+        # Chest-based: must have inventory > 0
+        return self.inventory_amount > 0
+
+    def is_cogs_aligned(self) -> bool:
+        """Check if this structure is aligned to cogs."""
+        return self.alignment == "cogs"
+
+    def is_clips_aligned(self) -> bool:
+        """Check if this structure is aligned to clips."""
+        return self.alignment == "clips"
+
+    def is_neutral(self) -> bool:
+        """Check if this structure is neutral (unaligned)."""
+        return self.alignment is None
+
+
+# Game constants
+JUNCTION_AOE_RANGE = 10  # AOE range of junctions
+HP_DRAIN_OUTSIDE_SAFE_ZONE = 1  # HP lost per step outside safe zone
+HP_DRAIN_NEAR_ENEMY = 1  # Additional HP lost near enemy junctions
+ENERGY_MOVE_COST = 2  # Energy cost per move
+HP_SAFETY_MARGIN = 10  # Buffer HP to keep before retreating
+
+
+# Debug flag (legacy, now controlled via URI param)
+DEBUG = False
+
+
+@dataclass
+class DebugInfo:
+    """Structured debug info about agent's current intent."""
+
+    mode: str = "idle"  # Current behavior mode (e.g., "mine", "deposit", "retreat")
+    goal: str = ""  # Current goal description
+    target_object: str = ""  # Object being targeted
+    target_pos: Optional[tuple[int, int]] = None  # Target position
+    signal: str = ""  # Event signal (e.g., "extract_failed_cargo_full", "hp_too_low")
+
+    def format(self, role: str, action_name: str) -> str:
+        """Format as role:mode:goal:target:action[:signal]."""
+        target = self.target_object or (str(self.target_pos) if self.target_pos else "-")
+        base = f"{role}:{self.mode}:{self.goal or '-'}:{target}:{action_name}"
+        if self.signal:
+            return f"{base}:{self.signal}"
+        return base