cogames-agents 0.0.0.7__tar.gz

cogames_agents-0.0.0.7/.gitignore

@@ -0,0 +1,2 @@
+*.egg-info/
+__pycache__/

cogames_agents-0.0.0.7/.nim-version

@@ -0,0 +1 @@
+2.2.6

cogames_agents-0.0.0.7/.nimby-version

@@ -0,0 +1 @@
+0.1.17

cogames_agents-0.0.0.7/MANIFEST.in

@@ -0,0 +1,9 @@
+# Include Nim source files for building from source distribution
+recursive-include src/cogames_agents/policy/nim_agents *.nim *.nims
+include src/cogames_agents/policy/nim_agents/nimby.lock
+include .nim-version
+include .nimby-version
+
+# Exclude build artifacts
+prune src/cogames_agents/policy/nim_agents/nimbledeps
+prune src/cogames_agents/policy/nim_agents/bindings/generated

cogames_agents-0.0.0.7/PKG-INFO

@@ -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)

cogames_agents-0.0.0.7/README.co-gas.md

@@ -0,0 +1,47 @@
+# co_gas
+
+**Mission: Get to the top of the Beta-CogsGuard leaderboard.**
+
+We build competitive CogsGuard agents — scripted baselines, trained policies, and optimized submissions — all aimed at
+ranking #1.
+
+## Approach
+
+1. **Scripted agent baselines** — hand-coded strategies in `cogames-agents/` covering guard and intruder roles
+2. **Behavioral cloning (BC)** — train neural policies from scripted agent demonstrations
+3. **PPO optimization** — fine-tune trained policies with reinforcement learning
+4. **Leaderboard submission** — evaluate and submit top-performing agents
+
+## Quick Start
+
+```bash
+# Play a scripted agent locally
+cogames play --mission CogsGuard
+
+# Train a policy via BC or PPO
+cogames train --mission CogsGuard
+
+# Run a scrimmage between agents
+cogames scrimmage --mission CogsGuard
+```
+
+## Repository Structure
+
+- `cogames-agents/` — scripted agents, evolution system, and training workflows
+- `cogames-agents/docs/` — detailed documentation (see index below)
+
+## Docs Index
+
+See [`cogames-agents/docs/`](cogames-agents/docs/) for full documentation:
+
+- [Creating Scripted Agents](cogames-agents/docs/creating-scripted-agents.md)
+- [Evolution System Architecture](cogames-agents/docs/evolution-system-architecture.md)
+- [Training & Submission Guide](cogames-agents/docs/training-and-submission-guide.md)
+- [Scripted Agent Registry](cogames-agents/docs/scripted-agent-registry.md)
+- [Nim vs Python Agents Comparison](cogames-agents/docs/nim-vs-python-agents-comparison.md)
+- [Mettaboxes](cogames-agents/docs/mettaboxes.md)
+- [W&B Analysis](cogames-agents/docs/wandb-analysis-cogsguard-training.md)
+
+## Team
+
+Rig: `co_gas/polecats/rust`

cogames_agents-0.0.0.7/README.md

@@ -0,0 +1,76 @@
+# 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)

cogames_agents-0.0.0.7/docs/0018-tribal-village-temple-roles.md

@@ -0,0 +1,130 @@
+# Tribal Village Temple Role System (Notes)
+
+This doc summarizes the role-mixing system in `tribal-village` so we can port a homologous evolution system into
+`richard-evolution`. We are not bringing the temple building itself; the focus is on the role catalog, recombination,
+and mutation mechanics. It is descriptive, not a proposal.
+
+## Where it lives (tribal-village)
+
+- `src/scripted/ai_defaults.nim`: role assignment, role pool, temple hybrid flow.
+- `src/scripted/roles.nim`: role/behavior catalog, tiers, materialization.
+- `src/scripted/evolution.nim`: sampling, recombination, mutation, scoring.
+- `src/step.nim`: temple spawn that triggers hybrid requests.
+- `src/types.nim`: `TempleHybridRequest` definition.
+
+## Core model
+
+- **BehaviorDef**: wraps an `OptionDef` plus fitness, games, uses.
+- **RoleDef**: list of tiers (`RoleTier`), origin, kind (Gatherer/Builder/Fighter/Scripted), fitness and win tracking,
+  optional name lock.
+- **RoleTier**: ordered behavior IDs with a selection mode:
+  - fixed: use given order
+  - shuffle: randomize per materialization
+  - weighted: weighted shuffle using tier weights
+- **RoleCatalog**: holds behavior and role registries and can serialize history to `data/role_history.json`.
+
+## Option execution (behavior list)
+
+Roles are materialized into `OptionDef` sequences (`materializeRoleOptions`) and executed by `runOptions` (in
+`options.nim`): the active option runs until it terminates or returns 0, otherwise higher-priority options can pre-empt
+if they are marked interruptible.
+
+## Role pool + assignment
+
+- Core roles are built from Gatherer/Builder/Fighter option lists.
+- A role pool is built from all non-core roles; if none exist, core roles are used as a fallback pool.
+- Scripted agents can either explore (generate a new role) or sample a role from the pool weighted by role fitness.
+- `ScriptedRoleExplorationChance` = 0.08, `ScriptedRoleMutationChance` = 0.25, `ScriptedGeneratedRoleCount` = 16.
+
+## Evolution and scoring
+
+- `sampleRole` builds N tiers (2-4) with 1-3 behaviors per tier, chosen with weights based on behavior fitness.
+- `recombineRoles` splices tier ranges from two parents at random cut points.
+- `mutateRole` can replace behavior IDs and flip tier selection modes.
+- `applyScriptedScoring` scores roles and behaviors using territory share at `ScriptedScoreStep` (5000), updating EMA
+  fitness and persisting history.
+- `lockRoleNameIfFit` freezes names once fitness crosses 0.7.
+
+## Temple hybrid flow
+
+1. **Spawn trigger** (`src/step.nim`): when two adjacent agents of the same team stand next to a Temple and an altar
+   heart is available, a child agent is spawned. A `TempleHybridRequest(parentA, parentB, childId, teamId, pos)` is
+   queued.
+2. **Processing** (`processTempleHybridRequests` in `ai_defaults.nim`):
+   - Lookup each parent's current role.
+   - `recombineRoles` to build a hybrid role.
+   - Optional mutation and an extra behavior injection (35% chance) into the first tier (`injectBehavior`).
+   - Mark role origin as `"temple"` and register it in the catalog.
+   - Add to role pool and mark `pendingHybridRoles[childId]`.
+   - Reset the child agent init flag so the hybrid is applied next tick.
+3. **Assignment** (`assignScriptedRole`): if a pending hybrid is set, the child is assigned the new role immediately
+   before any other selection.
+
+## Metta adaptation (no temple building)
+
+- We want the same role catalog, tier recombination, and mutation mechanics.
+- The trigger is **not** a temple spawn. It can be end-of-episode, a fixed cadence, or an external coordinator signal.
+- Hybrid roles are still generated by recombining two parent roles, then optionally mutating/injecting a behavior.
+
+## What this implies for our port
+
+- We need a **role catalog** that can compose option lists from behaviors and persist fitness history.
+- The **temple trigger** is an environment event (spawn/interaction) that queues a hybrid request, not an agent
+  decision.
+- Hybridization is **tier-based recombination** with optional mutation and behavior injection, then assignment to the
+  newborn agent.
+- The system is light-weight: it relies on option lists rather than training.
+
+## Current richard-evolution implementation
+
+- Core evolution logic: `packages/cogames-agents/src/cogames_agents/policy/evolution/cogsguard/evolution.py`.
+- Coordinator and role selection:
+  `packages/cogames-agents/src/cogames_agents/policy/evolution/cogsguard/evolutionary_coordinator.py`.
+- Trigger today is **coordinator-driven** (games per generation), not an environment event.
+- `CogsguardPolicy` can opt into evolutionary role selection via URI flags (`evolution=1`, `evolutionary=1`, or
+  `evolve=1`).
+- Behavior hooks are wired up for integration (see
+  `packages/cogames-agents/src/cogames_agents/policy/scripted_agent/cogsguard/behavior_hooks.py`): the coordinator can
+  call real role behaviors when hooks are provided, but live execution still uses vibe-based roles.
+
+## Gaps vs an across-episode evolution loop
+
+- **No episode trigger wired yet.** `record_agent_performance` and `end_game` exist but are not called from the policy,
+  so fitness stays at defaults and selection is effectively uniform.
+- **Evolved roles don’t drive behavior.** Roles are mapped back to base vibes, so recombination/mutation does not change
+  the actual action ordering or per-step decisions.
+- **No persistence.** Role/behavior history isn’t saved or loaded (no `role_history.json` analog), so evolution resets
+  per run.
+
+## Suggested wiring (future work)
+
+1. **Episode completion → scoring**
+   - Pick a stable signal (team score, win/loss, hearts/influence delta, territory control).
+   - Call `record_agent_performance(agent_id, score, won)` per agent at episode end.
+   - Call `end_game(won)` to advance generations after `games_per_generation`.
+
+2. **Role execution path**
+   - Decide whether evolved roles should execute **behavior lists** (preferred) or keep mapping to base vibes.
+   - If using lists, materialize behaviors and run them via `run_options` (interruptible, priority tiers).
+   - Map behavior names to real role actions via `behavior_hooks` (already available).
+
+3. **Persistence**
+   - Serialize `RoleCatalog` fitness + usage into a JSON file under `data/` (or run output dir).
+   - Load history at coordinator init (matching tribal-village’s `role_history.json` pattern).
+
+4. **Coordinator integration**
+   - Keep `SmartRoleCoordinator` as fallback when evolution is disabled.
+   - For `evolution=1`, use the evolutionary coordinator for **gear** decisions and optionally replace smart-role
+     reassignment logic in `_maybe_switch_smart_role`.
+
+5. **Testing additions**
+   - Add unit tests for persistence (save/load round-trip, fitness continuity).
+   - Add integration tests for scoring triggers (episode end increments generation).
+   - Add behavior-execution tests to ensure evolved tiers change option order.
+
+## Open questions to resolve
+
+- What is the authoritative “score” for a role? (team win/loss, territory share, resource throughput, alignment control)
+- Should evolution be per-team or global across teams? (fitness updates per team vs pooled)
+- What cadence should evolve roles? (fixed games, fixed steps, external evaluation)
+- How much variance is acceptable before locking names / freezing roles?