Add MapAnalyst agent + spatial awareness + bootstrap playbook

[jkbennitt]

Context

ADR-002 (docs/adr/002-map-analyst-agent.md). Agents place buildings in rivers, create zones on barren soil, and build arbitrary layouts because they have no spatial awareness. Delta is consistently negative (-0.015 to -0.024) across models — this is NOT a model quality problem, it's a data problem.

Three Changes

1. MapAnalyst Agent (7th agent)

Dedicated spatial reasoning agent that runs before the other 6. Reads RIMAPI terrain/ore/plant/zone/room endpoints and produces a structured MapAnalysis with:

• Colony center position
• Fertile areas with fertility scores + crop recommendations
• Recommended build sites on solid ground
• Ore deposit locations
• Water features (don't build here)
• Natural walls (use for defense)
• Recommended coordinates for: stockpile, growing zone, shelter

Other agents consume this analysis instead of picking random coordinates.

2. Early-Game Bootstrap Playbook

Deterministic plan for ticks 1-5:

• Tick 1: Stockpile zone near drop pods, work priorities for all colonists
• Tick 2: Growing zone on fertile soil (Plant_Rice for speed)
• Tick 3: Shelter walls (5x5 room with door) on solid ground
• Tick 4: Beds inside shelter
• Tick 5: Campfire/stove for cooking
• Tick 6+: LLM takes over for adaptive strategy

3. Pre-processed Map Summary

Compact text summary shared by all agents (~500 tokens):

Colony center: (128, 133). Fertile soil: (100-120, 80-95).
River: x=130-135. Mountain: z>200. Geyser: (145, 90).
Zones: 1 growing (25 cells), 1 stockpile (16 cells).
Rooms: 1 bedroom. No kitchen. No research room.

Plus role-specific deep data for relevant agents.

Files to Create/Modify

• src/rle/agents/map_analyst.py — NEW: 7th agent
• src/rle/rimapi/map_summary.py — NEW: terrain analysis + summarization
• src/rle/orchestration/game_loop.py — Run MapAnalyst before other agents, cache results
• src/rle/agents/base_role.py — Inject map summary into all agent prompts
• src/rle/agents/__init__.py — Register 7th agent
• src/rle/rimapi/schemas.py — Add MapAnalysis model
• All 6 role agents — Consume MapAnalysis in filter_game_state()
• Scenario YAMLs — Add bootstrap playbook directives per scenario

Success Criteria

• Agents place buildings on solid ground, never in water
• Growing zones on fertile soil, not random locations
• Shelter built near colony center
• Delta flips positive on Crashlanded
• All 3 colonists visibly working in first 3 ticks

Relates to #6, #8

[jkbennitt]

Implementation Complete — MapAnalyst Agent (ADR-002)

Commit: c7fc3f3

What changed (15 files, +410/-29)

New spatial data pipeline:

• ZoneData, RoomData, OreDeposit, FarmSummary schemas added to schemas.py
• MapData extended with zones, rooms, ore_deposits, farm_summary (backward-compatible defaults)
• 4 new async fetch methods in client.py: get_zones(), get_rooms(), get_ore(), get_farm_summary() — wired into get_map()

MapAnalyst agent (map_analyst.py):

• 7th agent, ALLOWED_ACTIONS = {"no_action"} — analysis only, no executable actions
• Low temperature (0.1-0.4) for deterministic spatial output
• filter_game_state() includes all spatial data: zones, rooms, ore, farm_summary, structures, colonist positions
• Role description instructs LLM to produce spatial analysis with specific (x,z) coordinates
• Early-game bootstrap directive (day < 5): identify drop pod center, nearest soil, nearest ore, flat buildable area

Game loop orchestration (game_loop.py):

• MapAnalyst separated from role agents in __init__
• Deliberates FIRST (sequential), broadcasts via CentralPost TASK_COMPLETE
• process_all_messages() routes MapAnalyst output to role agent spokes immediately
• Then 6 role agents deliberate in parallel with MapAnalyst spatial context available

Shared prompt (base_role.py):

• Updated to "7 specialized role agents"
• All agents told: "Check your inter-agent context for MapAnalyst spatial data before choosing coordinates"

ADR-002 verification

Requirement	Status
MapAnalyst runs BEFORE other 6	✅
Reads map/ore, map/zones, map/rooms, map/buildings	✅
Reads map/terrain (full grid)	⏳ Deferred — 250x250 grid too large for context
MapAnalysis consumed by other agents	✅ Via CentralPost spoke messages
Early-game bootstrap playbook	✅ _MAP_ANALYST_BOOTSTRAP + existing _EARLY_GAME_DIRECTIVE
Pre-processed map summary	✅ Shared via GameState.map, per-role via MapAnalyst spoke

Tests

• 272 tests pass, ruff clean
• MapAnalyst tests added to test_role_agents.py: class vars, filter, registration
• All mock transports updated with 4 new endpoint routes

Next

Live test to verify MapAnalyst produces useful spatial analysis and other agents use coordinates from it instead of random positions. @CalebisGross

[jkbennitt]

Live Test Results — MapAnalyst Working

10-tick live test with Nemotron 30B (nvidia/nemotron-3-nano-30b-a3b) on OpenRouter:

Composite: 0.681 | survival: 1.000 | food_security: 0.920 | wealth: 1.000 | efficiency: 0.769

What worked

• All 3 colonists working — first time this has happened. Contreras sowing potatoes, blueprints placed, stockpiles created.
• MapAnalyst spatial analysis producing correct coordinates — colony center identified, build sites on solid ground, ore locations with (x,z) coordinates
• Other agents consuming MapAnalyst output via CentralPost — growing zones on fertile soil, stockpiles near center, blueprints on valid ground
• No-pause SSE architecture working — game runs continuously during deliberation
• 7-agent pipeline fully operational: MA deliberates first → broadcasts → 6 role agents deliberate in parallel with spatial context

Remaining issues (prompt tuning, not architecture)

• Mood 0.290 — colonists miserable (no beds, no cooked meals by day 8)
• Bootstrap too slow — need to prioritize beds + cooking before farming/mining
• Bob had a tantrum (major break risk)

These are strategy/prompt problems, not spatial awareness problems. The core architecture from ADR-002 is verified working.

[jkbennitt]

Live Test: Terrain Constraints Working — 0.808 Composite

Nemotron 30B (nvidia/nemotron-3-nano-30b-a3b) on OpenRouter, 10 ticks, no-pause mode.

Score

Metric	Score
COMPOSITE	0.808
survival	1.000
wealth	1.000
threat_response	1.000
food_security	0.950
efficiency	0.754
self_sufficiency	0.667
mood	0.441
research	0.226

What's working now

• Deterministic terrain analysis — fetches RLE-encoded terrain grid (~26KB), classifies water/fertile/rock/buildable, finds best rectangles near colony center
• SPATIAL_CONSTRAINTS injected into every agent — SHELTER_SITE, FARM_SITE, STOCKPILE_SITE, WATER_ZONES with verified coordinates
• No buildings in water — agents using terrain-verified coordinates
• Save auto-loading — run_scenario.py loads scenario save and polls until game is ready
• No-pause mode fixed — game unpauses at start of loop
• All 3 colonists alive and working — stockpiles placed, blueprints down, sowing crops

Commits this session

• c7fc3f3 — MapAnalyst 7th agent
• 809378a — Fix RIMAPI response shape adapters
• 917549b — Fix no-pause mode + save loading
• a78b037 — Deterministic terrain analysis with hard spatial constraints
• e001b59 — Wait for game to fully load after save

Remaining

• Mood 0.441 — agents not prioritizing beds/cooking fast enough
• Research 0.226 — no research bench placed
• Spatial placement still somewhat scattered (not in water, but not compact)
• Strategy prioritization needs prompt tuning

@CalebisGross check it out!

[jkbennitt]

Closing — MapAnalyst + Spatial Awareness Complete

All ADR-002 architectural requirements are implemented and verified:

Final commits

• c7fc3f3 MapAnalyst 7th agent
• 809378a Fix RIMAPI response shape adapters
• 917549b Fix no-pause mode + save loading
• a78b037 Deterministic terrain analysis with hard spatial constraints
• e001b59 Wait for game to fully load after save
• 062301a Compact map summary + tick-specific bootstrap playbook
• f939af3 Unforbid all starting items after save load (RIMAPI #65)

Success criteria

Criteria	Result
Buildings on solid ground, never in water	✅ Verified across 4 live tests
Growing zones on fertile soil	✅ FARM_SITE from terrain grid
Shelter near colony center	✅ SHELTER_SITE coordinates used
All 3 colonists working in first 3 ticks	✅ Verified in screenshots
Delta flips positive	⚠️ Borderline: +0.012 vs 0.782 baseline, best run 0.808

What's in place

1. MapAnalyst agent — runs first, produces spatial analysis via CentralPost
2. Deterministic terrain analysis — fetches RLE terrain grid, classifies water/fertile/rock, finds best rectangles
3. MAP_SUMMARY — ~500 token compact text injected into every agent's context with verified coordinates
4. Bootstrap playbook — tick-specific priorities (stockpile→shelter→beds→cooking→research)
5. Unforbid items — auto-unforbids all starting items after save load

Remaining work → #6

Delta is borderline positive. Mood (0.4) is the biggest drag — agents don't build beds/cooking fast enough. This is prompt tuning, not architecture. Tracking under #6 (agents beat baseline).