cogames-agents 0.0.0.7__cp312-cp312-macosx_11_0_arm64.whl

cogames_agents/policy/scripted_agent/utils.py

@@ -0,0 +1,381 @@
+"""
+Utility functions for scripted agents.
+
+Pure/stateless helper functions that can be reused across different agents.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, cast
+
+from mettagrid.simulator import Action
+from mettagrid.simulator.interface import AgentObservation
+
+from .common.geometry import is_adjacent as geometry_is_adjacent
+from .common.tag_utils import select_primary_tag
+from .types import ObjectState, ParsedObservation, SimpleAgentState
+
+
+def is_adjacent(pos1: tuple[int, int], pos2: tuple[int, int]) -> bool:
+    """Check if two positions are adjacent (4-way cardinal directions)."""
+    return geometry_is_adjacent(pos1, pos2)
+
+
+def is_wall(obj_name: str) -> bool:
+    """Check if an object name represents a wall or obstacle."""
+    return "wall" in obj_name or "#" in obj_name or obj_name in {"wall", "obstacle"}
+
+
+def is_station(obj_name: str, station: str) -> bool:
+    """Check if an object name contains a specific station type."""
+    return station in obj_name
+
+
+def add_inventory_token(
+    inventory: dict[str, int],
+    feature_name: str,
+    value: int,
+    *,
+    token_value_base: int,
+) -> None:
+    """Add inventory token value, reconstructing multi-token amounts."""
+    suffix = feature_name[4:]
+    if ":p" in suffix:
+        resource_name, power_str = suffix.rsplit(":p", 1)
+        power = int(power_str)
+    else:
+        resource_name = suffix
+        power = 0
+    inventory[resource_name] = inventory.get(resource_name, 0) + value * (token_value_base**power)
+
+
+def process_feature_at_position(
+    position_features: dict[tuple[int, int], dict[str, Any]],
+    pos: tuple[int, int],
+    feature_name: str,
+    value: int,
+    *,
+    spatial_feature_names: set[str],
+    agent_feature_key_by_name: dict[str, str],
+    protocol_input_prefix: str,
+    protocol_output_prefix: str,
+) -> None:
+    """Process a single observation feature and add it to position_features."""
+    if pos not in position_features:
+        position_features[pos] = {}
+    position_entry = position_features[pos]
+
+    # Handle spatial features (tag, cooldown, etc.)
+    if feature_name in spatial_feature_names:
+        # Tag: collect all tags as a list (objects can have multiple tags)
+        if feature_name == "tag":
+            tags_value = position_entry.get("tags")
+            if not isinstance(tags_value, list):
+                tags_value = []
+                position_entry["tags"] = tags_value
+            cast(list[int], tags_value).append(value)
+            return
+        # Other spatial features are single values
+        position_entry[feature_name] = value
+        return
+
+    # Handle agent features (agent:group -> agent_group, etc.)
+    agent_feature_key = agent_feature_key_by_name.get(feature_name)
+    if agent_feature_key is not None:
+        position_entry[agent_feature_key] = value
+        return
+
+    # Handle protocol features (recipes)
+    if feature_name.startswith(protocol_input_prefix):
+        resource = feature_name[len(protocol_input_prefix) :]
+        inputs_value = position_entry.get("protocol_inputs")
+        if not isinstance(inputs_value, dict):
+            inputs_value = {}
+            position_entry["protocol_inputs"] = inputs_value
+        cast(dict[str, int], inputs_value)[resource] = value
+        return
+
+    if feature_name.startswith(protocol_output_prefix):
+        resource = feature_name[len(protocol_output_prefix) :]
+        outputs_value = position_entry.get("protocol_outputs")
+        if not isinstance(outputs_value, dict):
+            outputs_value = {}
+            position_entry["protocol_outputs"] = outputs_value
+        cast(dict[str, int], outputs_value)[resource] = value
+        return
+
+
+def has_type_tag(tags: Iterable[str], tokens: Iterable[str]) -> bool:
+    for tag in tags:
+        if not tag.startswith("type:"):
+            continue
+        type_name = tag.split(":", 1)[1]
+        if any(token in type_name for token in tokens):
+            return True
+    return False
+
+
+def create_object_state(
+    features: dict[str, Any],
+    *,
+    tag_names: dict[int, str],
+) -> ObjectState:
+    """Create an ObjectState from collected features.
+
+    Note: Objects can have multiple tags (e.g., "wall" + "green" vibe).
+    Prefer type tags over collective tags for the primary object name.
+    """
+    # Get tags list (now stored as "tags" instead of "tag")
+    tags_value = features.get("tags", [])
+    if isinstance(tags_value, list):
+        tag_ids = list(tags_value)
+    elif isinstance(tags_value, int):
+        tag_ids = [tags_value]
+    else:
+        tag_ids = []
+
+    # Pick a primary object name with tag precedence.
+    if tag_ids:
+        tags = [tag_names.get(tag_id, f"unknown_tag_{tag_id}") for tag_id in tag_ids]
+        obj_name = select_primary_tag(tags)
+    else:
+        tags = []
+        obj_name = "unknown"
+
+    # Helper to safely extract int values
+    def get_int(key: str, default: int) -> int:
+        val = features.get(key, default)
+        return int(val) if isinstance(val, int) else default
+
+    # Helper to safely extract dict values
+    def get_dict(key: str) -> dict[str, int]:
+        val = features.get(key, {})
+        return dict(val) if isinstance(val, dict) else {}
+
+    return ObjectState(
+        name=obj_name,
+        tags=tags,
+        cooldown_remaining=get_int("cooldown_remaining", 0),
+        clipped=get_int("clipped", 0),
+        remaining_uses=get_int("remaining_uses", 999),
+        inventory=get_dict("inventory"),
+        protocol_inputs=get_dict("protocol_inputs"),
+        protocol_outputs=get_dict("protocol_outputs"),
+        agent_group=get_int("agent_group", -1),
+        agent_frozen=get_int("agent_frozen", 0),
+    )
+
+
+def read_inventory_from_obs(
+    state: SimpleAgentState,
+    obs: AgentObservation,
+    *,
+    obs_hr: int,
+    obs_wr: int,
+) -> None:
+    """Read inventory from observation tokens at center cell and update state."""
+    inv = {}
+    token_value_base = None
+    center_r, center_c = obs_hr, obs_wr
+    for tok in obs.tokens:
+        if tok.location == (center_r, center_c):
+            feature_name = tok.feature.name
+            if feature_name.startswith("inv:"):
+                if token_value_base is None:
+                    token_value_base = int(tok.feature.normalization)
+                add_inventory_token(inv, feature_name, tok.value, token_value_base=token_value_base)
+
+    state.energy = inv.get("energy", 0)
+    state.carbon = inv.get("carbon", 0)
+    state.oxygen = inv.get("oxygen", 0)
+    state.germanium = inv.get("germanium", 0)
+    state.silicon = inv.get("silicon", 0)
+    state.hearts = inv.get("heart", 0)
+    state.decoder = inv.get("decoder", 0)
+    state.modulator = inv.get("modulator", 0)
+    state.resonator = inv.get("resonator", 0)
+    state.scrambler = inv.get("scrambler", 0)
+
+
+def parse_observation(
+    state: SimpleAgentState,
+    obs: AgentObservation,
+    *,
+    obs_hr: int,
+    obs_wr: int,
+    spatial_feature_names: set[str],
+    agent_feature_key_by_name: dict[str, str],
+    protocol_input_prefix: str,
+    protocol_output_prefix: str,
+    tag_names: dict[int, str],
+    debug: bool = False,
+) -> ParsedObservation:
+    """Parse token-based observation into structured format.
+
+    AgentObservation with tokens (ObservationToken list)
+    - Agent inventory is obtained via agent.inventory (not parsed here)
+    - Spatial features are parsed from observations, including object inventories
+
+    Converts egocentric spatial coordinates to world coordinates using agent position.
+    Agent position (agent_row, agent_col) comes from simulation.grid_objects().
+    """
+    # First pass: collect all spatial features by position
+    position_features: dict[tuple[int, int], dict[str, Any]] = {}
+    token_value_base = None
+
+    for tok in obs.tokens:
+        obs_r, obs_c = tok.location
+        feature_name = tok.feature.name
+        value = tok.value
+
+        # Skip center location - that's inventory/global obs, obtained via agent.inventory
+        if obs_r == obs_hr and obs_c == obs_wr:
+            continue
+
+        # Convert observation-relative coords to world coords
+        if state.row >= 0 and state.col >= 0:
+            r = obs_r - obs_hr + state.row
+            c = obs_c - obs_wr + state.col
+
+            if 0 <= r < state.map_height and 0 <= c < state.map_width:
+                if feature_name.startswith("inv:"):
+                    if token_value_base is None:
+                        token_value_base = int(tok.feature.normalization)
+                    position_entry = position_features.setdefault((r, c), {})
+                    inventory_value = position_entry.get("inventory")
+                    if not isinstance(inventory_value, dict):
+                        inventory_value = {}
+                        position_entry["inventory"] = inventory_value
+                    add_inventory_token(
+                        cast(dict[str, int], inventory_value),
+                        feature_name,
+                        value,
+                        token_value_base=token_value_base,
+                    )
+                    continue
+                process_feature_at_position(
+                    position_features,
+                    (r, c),
+                    feature_name,
+                    value,
+                    spatial_feature_names=spatial_feature_names,
+                    agent_feature_key_by_name=agent_feature_key_by_name,
+                    protocol_input_prefix=protocol_input_prefix,
+                    protocol_output_prefix=protocol_output_prefix,
+                )
+
+    # Second pass: create ObjectState for each position with tags
+    nearby_objects = {
+        pos: create_object_state(features, tag_names=tag_names)
+        for pos, features in position_features.items()
+        if "tags" in features  # Note: stored as "tags" (plural) to support multiple tags per object
+    }
+
+    return ParsedObservation(
+        row=state.row,
+        col=state.col,
+        energy=0,  # Inventory obtained via agent.inventory
+        carbon=0,
+        oxygen=0,
+        germanium=0,
+        silicon=0,
+        hearts=0,
+        decoder=0,
+        modulator=0,
+        resonator=0,
+        scrambler=0,
+        nearby_objects=nearby_objects,
+    )
+
+
+def change_vibe_action(
+    vibe_name: str,
+    *,
+    action_names: list[str],
+) -> Action:
+    """
+    Return a safe vibe-change action.
+    Guard against disabled or single-vibe configurations before issuing the action.
+    """
+    change_vibe_actions = [a for a in action_names if a.startswith("change_vibe_")]
+    if len(change_vibe_actions) <= 1:
+        return Action(name="noop")
+    action_name = f"change_vibe_{vibe_name}"
+    if action_name in action_names:
+        return Action(name=action_name)
+    available = [a[len("change_vibe_") :] for a in change_vibe_actions]
+    raise Exception(f"No valid vibe called '{vibe_name}'. Available vibes: {available}")
+
+
+def update_agent_position(
+    state: SimpleAgentState,
+    *,
+    move_deltas: dict[str, tuple[int, int]],
+) -> None:
+    """Update agent position based on last action.
+
+    Position is tracked relative to origin (starting position), using only movement deltas.
+    No dependency on simulation.grid_objects().
+
+    IMPORTANT: When using objects (extractors, stations), the agent "moves into" them but doesn't
+    actually change position. We detect this by checking the using_object_this_step flag.
+    """
+    # If last action was a move and we're not using an object, update position
+    # We assume the move succeeded unless we were using an object
+    if state.last_action and state.last_action.name.startswith("move_") and not state.using_object_this_step:
+        # Extract direction from action name (e.g., "move_north" -> "north")
+        direction = state.last_action.name[5:]  # Remove "move_" prefix
+        if direction in move_deltas:
+            dr, dc = move_deltas[direction]
+            state.row += dr
+            state.col += dc
+    # Clear the flag for next step
+    state.using_object_this_step = False
+
+
+def use_object_at(
+    state: SimpleAgentState,
+    target_pos: tuple[int, int],
+) -> Action:
+    """Use an object by moving into its cell. Sets a flag so position tracking knows not to update.
+
+    This is the generic "move into to use" action for extractors, hubs, chests, junctions, etc.
+    """
+    action = move_into_cell(state, target_pos)
+
+    # Mark that we're using an object so position tracking doesn't update
+    state.using_object_this_step = True
+
+    return action
+
+
+def move_into_cell(
+    state: SimpleAgentState,
+    target: tuple[int, int],
+) -> Action:
+    """Return the action that attempts to step into the target cell.
+
+    Checks for agent occupancy before moving to avoid collisions.
+    """
+    tr, tc = target
+    if state.row == tr and state.col == tc:
+        return Action(name="noop")
+    dr = tr - state.row
+    dc = tc - state.col
+
+    # Check if another agent is at the target position
+    if (tr, tc) in state.agent_occupancy:
+        # Another agent is blocking the target, wait or try alternative
+        # For a simple fallback, return noop (caller can handle random direction if needed)
+        return Action(name="noop")
+
+    if dr == -1:
+        return Action(name="move_north")
+    if dr == 1:
+        return Action(name="move_south")
+    if dc == 1:
+        return Action(name="move_east")
+    if dc == -1:
+        return Action(name="move_west")
+    # Fallback to noop if offsets unexpected
+    return Action(name="noop")

cogames_agents/policy/scripted_registry.py

@@ -0,0 +1,80 @@
+"""Registry of scripted policy URIs derived from policy short_names."""
+
+from __future__ import annotations
+
+import ast
+import functools
+from pathlib import Path
+from typing import Iterable, Optional
+
+_POLICY_ROOT = Path(__file__).resolve().parent
+_SCRIPTED_SCAN_DIRS = (
+    _POLICY_ROOT / "scripted_agent",
+    _POLICY_ROOT / "nim_agents",
+)
+
+
+def _iter_policy_files() -> Iterable[Path]:
+    for base_dir in _SCRIPTED_SCAN_DIRS:
+        if not base_dir.exists():
+            continue
+        for path in base_dir.rglob("*.py"):
+            if path.name.startswith("__"):
+                continue
+            yield path
+
+
+def _extract_literal_strings(node: ast.AST) -> Optional[list[str]]:
+    if isinstance(node, (ast.List, ast.Tuple)):
+        values: list[str] = []
+        for elt in node.elts:
+            if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                values.append(elt.value)
+            else:
+                return None
+        return values
+    return None
+
+
+def _extract_short_names_from_class(class_def: ast.ClassDef) -> list[str]:
+    for stmt in class_def.body:
+        if isinstance(stmt, ast.Assign):
+            for target in stmt.targets:
+                if isinstance(target, ast.Name) and target.id == "short_names":
+                    value = _extract_literal_strings(stmt.value)
+                    return value or []
+        if isinstance(stmt, ast.AnnAssign):
+            if isinstance(stmt.target, ast.Name) and stmt.target.id == "short_names":
+                if stmt.value is None:
+                    return []
+                value = _extract_literal_strings(stmt.value)
+                return value or []
+    return []
+
+
+@functools.cache
+def list_scripted_agent_names() -> tuple[str, ...]:
+    names: set[str] = set()
+    for path in _iter_policy_files():
+        try:
+            source = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        try:
+            tree = ast.parse(source, filename=str(path))
+        except SyntaxError:
+            continue
+        for node in tree.body:
+            if isinstance(node, ast.ClassDef):
+                names.update(_extract_short_names_from_class(node))
+    return tuple(sorted(names))
+
+
+SCRIPTED_AGENT_URIS: dict[str, str] = {name: f"metta://policy/{name}" for name in list_scripted_agent_names()}
+
+
+def resolve_scripted_agent_uri(name: str) -> str:
+    if name in SCRIPTED_AGENT_URIS:
+        return SCRIPTED_AGENT_URIS[name]
+    available = ", ".join(sorted(SCRIPTED_AGENT_URIS))
+    raise ValueError(f"Unknown scripted agent '{name}'. Available: {available}")

cogames_agents-0.0.0.7.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: cogames-agents
+Version: 0.0.0.7
+Summary: Optional agent policies for CoGames
+Author: Metta AI
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Metta-AI/metta/tree/main/packages/cogames-agents
+Project-URL: Repository, https://github.com/Metta-AI/metta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: cogames==0.3.64
+Requires-Dist: mettagrid==0.2.0.74
+Requires-Dist: numpy>=2.0.0
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: ruff; extra == "test"
+
+# cogames-agents
+
+Optional scripted policies for CoGames. Use them for quick baselines, play/eval smoke tests, or as teacher policies.
+
+## Scripted policy registry
+
+The registry at `cogames_agents.policy.scripted_registry` maps policy `short_names` to `metta://policy/...` URIs.
+Scripted agents and teachers share these identifiers, so the same name works for evaluation, play, and
+`TeacherConfig.policy_uri`.
+
+To list the current names:
+
+```
+python -c "from cogames_agents.policy.scripted_registry import list_scripted_agent_names; print(list_scripted_agent_names())"
+```
+
+Common scripted policy names include:
+
+- Baselines: `baseline`, `tiny_baseline`, `ladybug_py`
+- Nim baselines: `thinky`, `race_car`, `ladybug`, `nim_random`
+- CogsGuard core: `role`, `role_py`, `wombo`
+- CogsGuard variants: `alignall`, `cogsguard_control`, `cogsguard_targeted`, `cogsguard_v2`
+- CogsGuard roles: `miner`, `scout`, `aligner`, `scrambler`
+- Teacher: `teacher`
+- Pinky: `pinky`
+
+For the full registry snapshot, see `docs/scripted-agent-registry.md`.
+
+Role-specific policies are exposed via role names (miner/scout/aligner/scrambler). For the teacher policy, you can pass
+`role_vibes` as a comma-separated list:
+
+```
+metta://policy/teacher?role_vibes=miner,scout
+```
+
+Fixed-role mixes and explicit orderings are configured via `role_py` parameters:
+
+Examples:
+
+```
+metta://policy/role_py?role_cycle=aligner,miner,scrambler,scout
+metta://policy/role_py?role_order=aligner,miner,aligner,miner,scout
+```
+
+Pinky role counts are applied in a different order than CogsGuard:
+
+- Pinky order: miner -> scout -> aligner -> scrambler, and any remaining agents stay default/noop.
+- CogsGuard order: scrambler -> aligner -> miner -> scout, then fills remaining agents with gear.
+
+Examples:
+
+```
+metta://policy/pinky?miner=4&aligner=2&scrambler=4
+metta://policy/pinky?miner=2&scout=2&aligner=1&scrambler=1&debug=1
+```
+
+## Recipe usage
+
+The `recipes.experiment.scripted_agents` recipe accepts the same scripted policy names:
+
+```
+./tools/run.py recipes.experiment.scripted_agents.play agent=thinky suite=cvc_arena
+./tools/run.py recipes.experiment.scripted_agents.play agent=miner suite=cogsguard
+```
+
+## Included policies
+
+- Short names map to the fastest implementation (Nim when available, otherwise Python).
+- `_nim` aliases exist when there is a Nim implementation alongside Python.
+- See `docs/scripted-agent-registry.md` for the canonical short-name list.
+- Teacher wrapper: `teacher` (`teacher_nim`) forces an initial role/vibe, then delegates to the Nim policy.
+
+## Docs
+
+- `docs/mettaboxes.md` (mettabox usage guide)
+- `docs/aws-sso-on-mettabox.md` (AWS SSO login from inside mettabox containers)