cogames 0.3.65__py3-none-any.whl → 0.3.69__py3-none-any.whl

cogames/cli/utils.py

@@ -11,6 +11,11 @@ def suppress_noisy_logs() -> None:
     warnings.filterwarnings("ignore", category=DeprecationWarning, module="pkg_resources")
     warnings.filterwarnings("ignore", category=DeprecationWarning, module="pygame.pkgdata")
 
+    # Pyro docstrings use LaTeX math notation (\ge for ≥) which Python 3.12+ warns about:
+    # pyro/ops/stats.py:527: SyntaxWarning: invalid escape sequence '\g'
+    # Note: module= filter doesn't work for SyntaxWarnings (emitted at parse time before module loads)
+    warnings.filterwarnings("ignore", category=SyntaxWarning, message=r".*invalid escape sequence.*")
+
     # Silence PyTorch distributed elastic warning about redirects on MacOS/Windows
     logging.getLogger("torch.distributed.elastic.multiprocessing.redirects").setLevel(logging.ERROR)
     warnings.filterwarnings(

cogames/cogs_vs_clips/clip_difficulty.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import Final, Optional
+
+from cogames.cogs_vs_clips.mission import CvCMission
+from cogames.core import CoGameMissionVariant
+
+MEDIUM_CLIPS_END: Final[int] = 300
+
+
+class CogsGuardDifficulty(CoGameMissionVariant):
+    name: str
+    description: str = ""
+    disable_clips: bool = False
+    scramble_end: Optional[int] = None
+    align_end: Optional[int] = None
+    presence_end: Optional[int] = None
+
+    def modify_mission(self, mission: CvCMission) -> None:
+        if self.disable_clips:
+            mission.clips.disabled = True
+            return
+
+        mission.clips.disabled = False
+        mission.clips.scramble_end = self.scramble_end
+        mission.clips.align_end = self.align_end
+        mission.clips.presence_end = self.presence_end
+
+
+EASY = CogsGuardDifficulty(
+    name="easy",
+    description="No clips events.",
+    disable_clips=True,
+)
+
+MEDIUM = CogsGuardDifficulty(
+    name="medium",
+    description="A few early clips events, then none.",
+    scramble_end=MEDIUM_CLIPS_END,
+    align_end=MEDIUM_CLIPS_END,
+    presence_end=MEDIUM_CLIPS_END,
+)
+
+HARD = CogsGuardDifficulty(
+    name="hard",
+    description="Standard clips event system.",
+)
+
+COGSGUARD_DIFFICULTIES: tuple[CogsGuardDifficulty, ...] = (EASY, MEDIUM, HARD)
+
+
+def get_cogsguard_difficulty(name: str) -> CogsGuardDifficulty:
+    for difficulty in COGSGUARD_DIFFICULTIES:
+        if difficulty.name == name:
+            return difficulty
+    available = ", ".join(d.name for d in COGSGUARD_DIFFICULTIES)
+    raise ValueError(f"Unknown difficulty '{name}'. Available difficulties: {available}")

cogames/cogs_vs_clips/clips.py

@@ -4,6 +4,8 @@ Clips are a non-player faction that gradually takes over neutral junctions.
 These events create the spreading/scrambling behavior that pressures players.
 """
 
+from typing import Optional
+
 from pydantic import Field
 
 from mettagrid.base_config import Config
@@ -18,6 +20,8 @@ from mettagrid.config.tag import typeTag
 class ClipsConfig(Config):
     """Configuration for clips behavior in CogsGuard game mode."""
 
+    disabled: bool = Field(default=False)
+
     # Clips Behavior - scramble cogs junctions to neutral
     initial_clips_start: int = Field(default=10)
     initial_clips_spots: int = Field(default=1)
@@ -25,11 +29,16 @@ class ClipsConfig(Config):
     scramble_start: int = Field(default=50)
     scramble_interval: int = Field(default=100)
     scramble_radius: int = Field(default=25)
+    scramble_end: Optional[int] = Field(default=None)
 
     # Clips Behavior - align neutral junctions to clips
     align_start: int = Field(default=100)
     align_interval: int = Field(default=100)
     align_radius: int = Field(default=25)
+    align_end: Optional[int] = Field(default=None)
+
+    # Clips Behavior - presence check for re-invasion
+    presence_end: Optional[int] = Field(default=None)
 
     def events(self, max_steps: int) -> dict[str, EventConfig]:
         """Create all clips events for a mission.
@@ -37,6 +46,12 @@ class ClipsConfig(Config):
         Returns:
             Dictionary of event name to EventConfig.
         """
+        if self.disabled:
+            return {}
+        scramble_end = max_steps if self.scramble_end is None else min(self.scramble_end, max_steps)
+        align_end = max_steps if self.align_end is None else min(self.align_end, max_steps)
+        presence_end = max_steps if self.presence_end is None else min(self.presence_end, max_steps)
+
         return {
             "initial_clips": EventConfig(
                 name="initial_clips",
@@ -48,7 +63,7 @@ class ClipsConfig(Config):
             "cogs_to_neutral": EventConfig(
                 name="cogs_to_neutral",
                 target_tag=typeTag("junction"),
-                timesteps=periodic(start=self.scramble_start, period=self.scramble_interval, end=max_steps),
+                timesteps=periodic(start=self.scramble_start, period=self.scramble_interval, end=scramble_end),
                 # near a clips-aligned junction
                 filters=[
                     isNear(typeTag("junction"), [isAlignedTo("clips")], radius=self.scramble_radius),
@@ -61,7 +76,7 @@ class ClipsConfig(Config):
             "neutral_to_clips": EventConfig(
                 name="neutral_to_clips",
                 target_tag=typeTag("junction"),
-                timesteps=periodic(start=self.align_start, period=self.align_interval, end=max_steps),
+                timesteps=periodic(start=self.align_start, period=self.align_interval, end=align_end),
                 # neutral junctions near a clips-aligned junction
                 filters=[
                     isNear(typeTag("junction"), [isAlignedTo("clips")], radius=self.align_radius),
@@ -74,13 +89,15 @@ class ClipsConfig(Config):
             "presence_check": EventConfig(
                 name="presence_check",
                 target_tag=typeTag("junction"),
-                timesteps=periodic(start=self.initial_clips_start, period=self.scramble_interval * 2, end=max_steps),
+                timesteps=periodic(start=self.initial_clips_start, period=self.scramble_interval * 2, end=presence_end),
                 filters=[isNear(typeTag("junction"), [isAlignedTo("clips")], radius=1000)],
                 max_targets=1,
                 fallback="initial_clips",
             ),
         }
 
-    def collective_config(self) -> CollectiveConfig:
-        """Create a CollectiveConfig for this clips configuration."""
-        return CollectiveConfig(name="clips")
+    def collectives(self) -> dict[str, CollectiveConfig]:
+        """Create collectives for clips."""
+        if self.disabled:
+            return {}
+        return {"clips": CollectiveConfig(name="clips")}

cogames/cogs_vs_clips/cog.py

@@ -4,6 +4,7 @@ from pydantic import Field
 
 from cogames.cogs_vs_clips.config import CvCConfig
 from mettagrid.base_config import Config
+from mettagrid.config.game_value import InventoryValue
 from mettagrid.config.game_value import stat as game_stat
 from mettagrid.config.handler_config import Handler
 from mettagrid.config.mettagrid_config import (
@@ -11,6 +12,8 @@ from mettagrid.config.mettagrid_config import (
     InventoryConfig,
     ResourceLimitsConfig,
 )
+from mettagrid.config.mutation.game_value_mutation import SetGameValueMutation
+from mettagrid.config.mutation.mutation import EntityTarget
 from mettagrid.config.mutation.resource_mutation import updateActor
 from mettagrid.config.reward_config import reward
 
@@ -35,12 +38,12 @@ class CogConfig(Config):
     # Initial inventory
     initial_energy: int = Field(default=100)
     initial_hp: int = Field(default=50)
+    initial_solar: int = Field(default=1)
 
     # Regen amounts
-    energy_regen: int = Field(default=1)
     hp_regen: int = Field(default=-1)
     influence_regen: int = Field(default=-1)
-    action_cost: dict[str, int] = Field(default_factory=lambda: {"energy": 3})
+    action_cost: dict[str, int] = Field(default_factory=lambda: {"energy": 4})
 
     def agent_config(self, team: str, max_steps: int) -> AgentConfig:
         """Create an AgentConfig for this cog configuration."""
@@ -62,20 +65,28 @@ class CogConfig(Config):
                         min=self.influence_limit, resources=["influence"], modifiers=self.influence_modifiers
                     ),
                 },
-                initial={"energy": self.initial_energy, "hp": self.initial_hp},
+                initial={"energy": self.initial_energy, "hp": self.initial_hp, "solar": self.initial_solar},
             ),
             on_tick={
                 "regen": Handler(
                     mutations=[
                         updateActor(
                             {
-                                "energy": self.energy_regen,
                                 "hp": self.hp_regen,
                                 "influence": self.influence_regen,
                             }
                         )
                     ]
-                )
+                ),
+                "solar_to_energy": Handler(
+                    mutations=[
+                        SetGameValueMutation(
+                            value=InventoryValue(item="energy"),
+                            source=InventoryValue(item="solar"),
+                            target=EntityTarget.ACTOR,
+                        )
+                    ]
+                ),
             },
             rewards={
                 "aligned_junction_held": reward(

cogames/cogs_vs_clips/cogsguard_curriculum.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Sequence
+
+from cogames.cogs_vs_clips.mission import CvCMission
+from cogames.cogs_vs_clips.reward_variants import AVAILABLE_REWARD_VARIANTS
+from cogames.cogs_vs_clips.variants import HIDDEN_VARIANTS, VARIANTS
+from cogames.core import CoGameMissionVariant
+
+
+@dataclass(frozen=True)
+class EventProfile:
+    name: str
+    clips_overrides: dict[str, object]
+    weather_overrides: dict[str, object]
+
+
+COGSGUARD_FIXED_MAPS: list[str] = [
+    "machina_100_stations.map",
+    "machina_200_stations.map",
+    "cave_base_50.map",
+    "vanilla_large.map",
+]
+
+DEFAULT_EVENT_PROFILE = EventProfile("events_baseline", {}, {})
+COGSGUARD_EVENT_PROFILES: list[EventProfile] = [
+    DEFAULT_EVENT_PROFILE,
+    EventProfile(
+        "events_fast_clips_short_day",
+        {
+            "initial_clips_start": 5,
+            "initial_clips_spots": 2,
+            "scramble_start": 25,
+            "scramble_interval": 50,
+            "scramble_radius": 35,
+            "align_start": 50,
+            "align_interval": 50,
+            "align_radius": 35,
+        },
+        {"day_length": 100},
+    ),
+    EventProfile(
+        "events_slow_clips_long_day",
+        {
+            "initial_clips_start": 50,
+            "initial_clips_spots": 1,
+            "scramble_start": 200,
+            "scramble_interval": 200,
+            "scramble_radius": 15,
+            "align_start": 300,
+            "align_interval": 200,
+            "align_radius": 15,
+        },
+        {"day_length": 400},
+    ),
+    EventProfile(
+        "events_no_clips",
+        {"disabled": True},
+        {"day_length": 200},
+    ),
+]
+
+
+def normalize_variant_names(variants: str | Sequence[str] | None) -> list[str]:
+    if variants is None:
+        return []
+    if isinstance(variants, str):
+        if variants.startswith("["):
+            parsed = json.loads(variants)
+            if isinstance(parsed, list):
+                return [str(name) for name in parsed]
+        return [variants]
+    return list(variants)
+
+
+def split_variants(
+    variants: str | Sequence[str] | None,
+) -> tuple[list[CoGameMissionVariant], list[str]]:
+    if variants is None:
+        names: list[str] = []
+    else:
+        names = normalize_variant_names(variants)
+    all_variants = {variant.name: variant for variant in [*VARIANTS, *HIDDEN_VARIANTS]}
+    reward_variants = set(AVAILABLE_REWARD_VARIANTS)
+
+    resolved: list[CoGameMissionVariant] = []
+    resolved_rewards: list[str] = []
+    unknown: list[str] = []
+    for name in names:
+        if name in reward_variants:
+            resolved_rewards.append(name)
+            continue
+        variant = all_variants.get(name)
+        if variant is None:
+            unknown.append(name)
+            continue
+        resolved.append(variant)
+
+    if unknown:
+        available_mission = ", ".join(v.name for v in VARIANTS)
+        available_reward = ", ".join(AVAILABLE_REWARD_VARIANTS)
+        missing = ", ".join(unknown)
+        raise ValueError(
+            f"Unknown variant(s): {missing}. Mission variants: {available_mission}. "
+            f"Reward variants: {available_reward}."
+        )
+
+    return resolved, resolved_rewards
+
+
+def resolve_event_profiles(event_profiles: Sequence[EventProfile] | None) -> list[EventProfile]:
+    if event_profiles is None:
+        return [DEFAULT_EVENT_PROFILE]
+    return list(event_profiles)
+
+
+def filter_compatible_variants(
+    mission: CvCMission, variants: Sequence[CoGameMissionVariant]
+) -> list[CoGameMissionVariant]:
+    return [variant for variant in variants if variant.compat(mission)]

cogames/cogs_vs_clips/cogsguard_tutorial.py

@@ -18,11 +18,11 @@ def make_cogsguard_tutorial_site() -> CoGameSite:
         hub_height=15,
         outer_clearance=2,
         stations=[
-            "aligner_station",
-            "scrambler_station",
-            "miner_station",
-            "scout_station",
-            "chest",
+            "c:aligner",
+            "c:scrambler",
+            "c:miner",
+            "c:scout",
+            "c:chest",
         ],
     )
     map_builder = MapGen.Config(

cogames/cogs_vs_clips/config.py

@@ -32,7 +32,7 @@ CvCConfig = SimpleNamespace(
         "miner": "⛏️",
         "scout": "🔭",
     },
-    RESOURCES=["energy", "heart", "hp", "influence", *_ELEMENTS, *_GEAR],
+    RESOURCES=["energy", "heart", "hp", "influence", "solar", *_ELEMENTS, *_GEAR],
     VIBES=_VIBES,
     VIBE_NAMES=[vibe.name for vibe in _VIBES],
 )

cogames/cogs_vs_clips/docs/cogs_vs_clips_mapgen.md

@@ -341,11 +341,10 @@ Included missions and variants:
 Usage example:
 
 ```bash
-uv run python packages/cogames/scripts/run_evaluation.py \
-  --policy thinky \
+uv run cogames diagnose thinky \
   --mission-set integrated_evals \
   --cogs 4 \
-  --repeats 2
+  --episodes 2
 ```
 
 Recommendation: When designing new scorable baselines, combine one "shaping" variant (e.g., `HeartChorusVariant`,

cogames/cogs_vs_clips/evals/README.md

@@ -193,49 +193,25 @@ uv run cogames play --mission hello_world.single_use_swarm --cogs 4 -p baseline
 
 ## Programmatic Evaluation
 
-### Using run_evaluation.py
+### Using cogames diagnose / cogames run
 
 For systematic evaluation across multiple missions and configurations:
 
 ```bash
 # Evaluate on integrated eval suite
-uv run python packages/cogames/scripts/run_evaluation.py \
-  --policy thinky \
+uv run cogames diagnose thinky \
   --mission-set integrated_evals \
   --cogs 4 \
-  --repeats 2
+  --episodes 2
 
-# Evaluate specific agent
-uv run python packages/cogames/scripts/run_evaluation.py \
+# Evaluate specific agent with structured output
+uv run cogames run \
+  --mission-set integrated_evals \
   --policy baseline \
-  --steps 1000 \
-  --output eval_baseline.json
+  --episodes 10 \
+  --format json
 ```
 
-### Using in Curriculum Training
-
-Both diagnostic and integrated missions can be used in curriculum training via `mission_variant_curriculum.py`:
-
-```python
-from recipes.experiment.cvc import mission_variant_curriculum
-
-# Train on diagnostic missions
-mission_variant_curriculum.train(
-    base_missions=["diagnostic_missions"],
-    num_cogs=4,
-    variants="all"
-)
-
-# Train on specific integrated missions
-mission_variant_curriculum.train(
-    base_missions=["oxygen_bottleneck", "energy_starved"],
-    num_cogs=4,
-    variants=["pack_rat", "energized"]
-)
-```
-
----
-
 ## Design Philosophy
 
 ### Diagnostic Missions

cogames/cogs_vs_clips/evals/diagnostic_evals.py

@@ -26,7 +26,6 @@ _GENEROUS_COG = CogConfig(
     cargo_limit=255,
     initial_energy=255,
     initial_hp=100,
-    energy_regen=255,
     hp_regen=0,
     influence_regen=0,
 )

cogames/cogs_vs_clips/evals/difficulty_variants.py

@@ -37,11 +37,8 @@ class DifficultyLevel(CoGameMissionVariant):
     name: str = Field(description="Difficulty name (easy, medium, hard, brutal, etc.)")
     description: str = Field(description="What makes this difficulty challenging", default="")
 
-    # Energy regen multiplier (relative to mission baseline)
-    energy_regen_mult: float = Field(default=1.0)
-
-    # Absolute overrides (if set, ignore multipliers)
-    energy_regen_override: int | None = Field(default=None)
+    # Solar override (if set, overrides weather day/night deltas)
+    solar_override: int | None = Field(default=None)
     move_energy_cost_override: int | None = Field(default=None)
     energy_capacity_override: int | None = Field(default=None)
     cargo_capacity_override: int | None = Field(default=None)
@@ -70,20 +67,20 @@ STANDARD = DifficultyLevel(
 HARD = DifficultyLevel(
     name="hard",
     description="Minimal passive regen and higher move cost",
-    energy_regen_override=1,  # Minimal regen prevents deadlock
+    solar_override=1,  # Minimal regen prevents deadlock
     move_energy_cost_override=2,
 )
 
 SINGLE_USE = DifficultyLevel(
     name="single_use",
     description="Minimal regen - no second chances",
-    energy_regen_override=1,
+    solar_override=1,
 )
 
 SPEED_RUN = DifficultyLevel(
     name="speed_run",
     description="Short clock, cheap movement",
-    energy_regen_override=2,
+    solar_override=2,
     move_energy_cost_override=1,
     max_steps_override=600,
 )
@@ -91,7 +88,7 @@ SPEED_RUN = DifficultyLevel(
 ENERGY_CRISIS = DifficultyLevel(
     name="energy_crisis",
     description="Minimal passive regen - plan every move",
-    energy_regen_override=1,  # Minimal regen prevents deadlock
+    solar_override=1,  # Minimal regen prevents deadlock
 )
 
 # Export variants for use with --variant CLI flag.
@@ -116,7 +113,7 @@ def list_difficulties() -> None:
     print("=" * 80)
     for diff in DIFFICULTY_VARIANTS:
         print(f"\n{diff.name.upper()}: {diff.description}")
-        print(f"  Energy regen mult: {diff.energy_regen_mult}")
+        print(f"  Solar override: {diff.solar_override}")
 
 
 if __name__ == "__main__":

cogames/cogs_vs_clips/mission.py

@@ -15,6 +15,7 @@ from cogames.cogs_vs_clips.stations import (
 )
 from cogames.cogs_vs_clips.team import CogTeam
 from cogames.cogs_vs_clips.variants import NumCogsVariant
+from cogames.cogs_vs_clips.weather import WeatherConfig
 from cogames.core import (
     MAP_MISSION_DELIMITER,
     CoGameMission,
@@ -28,7 +29,7 @@ from mettagrid.config.action_config import (
     NoopActionConfig,
 )
 from mettagrid.config.game_value import inv
-from mettagrid.config.mettagrid_config import GameConfig, MettaGridConfig
+from mettagrid.config.mettagrid_config import CollectiveConfig, GameConfig, MettaGridConfig
 from mettagrid.config.obs_config import GlobalObsConfig, ObsConfig
 from mettagrid.map_builder.map_builder import AnyMapBuilderConfig
 
@@ -46,6 +47,7 @@ class CvCMission(CoGameMission):
     """Mission configuration for CogsGuard game mode."""
 
     max_steps: int = Field(default=10000)
+    total_junctions: int = Field(default=118, description="Total junctions on the map (for curriculum scaling)")
 
     cog: CogConfig = Field(default_factory=lambda: CogConfig())
     teams: dict[str, CogTeam] = Field(
@@ -55,6 +57,7 @@ class CvCMission(CoGameMission):
     )
 
     clips: ClipsConfig = Field(default_factory=lambda: ClipsConfig())
+    weather: WeatherConfig = Field(default_factory=lambda: WeatherConfig())
 
     @property
     def num_agents(self) -> int:
@@ -74,7 +77,7 @@ class CvCMission(CoGameMission):
         Returns:
             MettaGridConfig ready for environment creation
         """
-
+        team_objs = list(self.teams.values())
         game = GameConfig(
             map_builder=self.map_builder(),
             max_steps=self.max_steps,
@@ -91,24 +94,40 @@ class CvCMission(CoGameMission):
                 noop=NoopActionConfig(),
                 change_vibe=ChangeVibeActionConfig(vibes=CvCConfig.VIBES),
             ),
-            agent=self.cog.agent_config(team="cogs", max_steps=self.max_steps),
-            agents=[self.cog.agent_config(team="cogs", max_steps=self.max_steps) for _ in range(self.num_agents)],
+            agents=[
+                self.cog.agent_config(team=t.name, max_steps=self.max_steps)
+                for t in team_objs
+                for _ in range(t.num_agents)
+            ],
             objects={
                 "wall": CvCWallConfig().station_cfg(),
-                "hub": CvCHubConfig().station_cfg(team="cogs"),
                 "junction": CvCJunctionConfig().station_cfg(),
-                "chest": CvCChestConfig().station_cfg(team="cogs"),
                 **{
                     f"{resource}_extractor": CvCExtractorConfig(resource=resource).station_cfg()
                     for resource in CvCConfig.ELEMENTS
                 },
-                **{f"{g}_station": CvCGearStationConfig(gear_type=g).station_cfg(team="cogs") for g in CvCConfig.GEAR},
+                **{
+                    f"{t.short_name}:hub": CvCHubConfig().station_cfg(team=t.short_name, collective=t.name)
+                    for t in team_objs
+                },
+                **{
+                    f"{t.short_name}:chest": CvCChestConfig().station_cfg(team=t.short_name, collective=t.name)
+                    for t in team_objs
+                },
+                **{
+                    f"{t.short_name}:{g}": CvCGearStationConfig(gear_type=g).station_cfg(
+                        team=t.short_name, collective=t.name
+                    )
+                    for t in team_objs
+                    for g in CvCConfig.GEAR
+                },
             },
             collectives={
-                **{team.name: team.collective_config() for team in self.teams.values()},
-                "clips": self.clips.collective_config(),
+                **{t.name: t.collective_config() for t in team_objs},
+                **self.clips.collectives(),
+                "neutral": CollectiveConfig(name="neutral"),
             },
-            events=self.clips.events(max_steps=self.max_steps),
+            events=self._merge_events(),
         )
 
         env = MettaGridConfig(game=game)
@@ -122,3 +141,12 @@ class CvCMission(CoGameMission):
             env.label += f".{variant.name}"
 
         return env
+
+    def _merge_events(self) -> dict:
+        """Merge clips and weather events, raising on key conflicts."""
+        clips_events = self.clips.events(max_steps=self.max_steps)
+        weather_events = self.weather.events(max_steps=self.max_steps)
+        overlap = set(clips_events) & set(weather_events)
+        if overlap:
+            raise ValueError(f"Overlapping event keys between clips and weather: {overlap}")
+        return {**clips_events, **weather_events}

cogames/cogs_vs_clips/missions.py

@@ -50,7 +50,7 @@ def get_core_missions() -> list[CvCMission]:
 
 
 def _build_eval_missions() -> list[CvCMission]:
-    from cogames.cogs_vs_clips.evals.integrated_evals import EVAL_MISSIONS as INTEGRATED_EVAL_MISSIONS
+    from cogames.cogs_vs_clips.evals.integrated_evals import EVAL_MISSIONS as INTEGRATED_EVAL_MISSIONS  # noqa: PLC0415
 
     return [
         *INTEGRATED_EVAL_MISSIONS,