Merge feature/maturity into main

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/

README.md

@@ -2,83 +2,143 @@
 
 **Where agents run forward simulations, listen for spectral nudges, and maintain conservation in Plato's cave.**
 
-The MUD Arena is evolving from GPU-accelerated agent backtesting into a **flow-state engineering platform** — a live environment where agents maintain persistent spectral identities, run t-minus-event simulations, listen through walls, and compose in real-time with other agents.
+The MUD Arena is a **flow-state engineering platform** and agent simulation arena with MUD (Multi-User Dungeon) mechanics. Agents inhabit rooms, navigate exits, manage inventories, interact with NPCs, and react to events — all driven by pluggable decision functions and a real-time event bus.
 
-This is the **PLATO moment** made operational: agents know they're in Plato's cave, but they make music with the caves next door.
+**Part of the [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct) ecosystem.**
 
 ---
 
-## The Evolution
+## What MUD Arena Does
 
-| Phase | What it was | What it's becoming |
-|-------|------------|-------------------|
-| **Arena** | GPU backtesting of agent scripts | Flow-state environment where agents are always-on |
-| **Scripts** | Declarative DSL rules | Spectral fingerprints (Laplacians, not code) |
-| **Scenarios** | LLM-generated situations | Forward simulations (t-minus-event) |
-| **Scoring** | Fitness functions | Conservation ratio + alignment coefficient α |
-| **Breeding** | Genetic algorithms | Spectral composition (FLUX between agents) |
-| **Rooms** | MUD rooms | Plato rooms with walls, diaries, tool shelves |
+At its core, mud-arena provides a **MUD-world simulation substrate** for training and testing AI agents:
 
----
+- **Room Graph** — interconnected rooms with exits, items, and NPCs
+- **Command Parser** — natural-language MUD commands (`go north`, `take key`, `use key with door`, `talk to guard`)
+- **Agent Simulation Loop** — perceive → decide → act cycle with pluggable decision functions
+- **Inventory System** — pick up, drop, use, and trade items with capacity tracking
+- **Event Bus** — pub/sub event dispatch for room events, item actions, and agent reactions
+- **Evolution Engine** — genetic algorithms, tournament selection, crossover breeding
+- **Scenario Generator** — random or LLM-augmented scenario creation
+- **Live Server** — WebSocket, Telnet, and HTTP interfaces for real-time observation
 
-## The Five Moments in the Arena
+### Connection to OpenConstruct
 
-### 1. SEEING — Graphing Calculator
-Agents visualize their spectral fingerprints in real-time. Eigenvalue spectrums pulse. Conservation ratios breathe. The Fiedler vector shows the room's partition into teams.
+In the OpenConstruct terrain/a2ui system, **agents live in MUD worlds**. This package simulates those worlds: rooms become terrain cells, NPCs become service endpoints, and inventory becomes resource management. The agent simulation loop mirrors how OpenConstruct agents perceive their environment, decide on actions, and execute them — making mud-arena both a testing ground and a development tool for OpenConstruct agent behaviors.
 
-### 2. EXPLORING — Spectral Spreadsheet
-Every dimension of agent state can go on x and y. Conservation over time. Alignment vs spectral gap. Any correlation, instantly visible.
+---
 
-### 3. ASKING — Spectral Chat
-"Which agents should compose for this task?" The arena answers with conservation-aligned team assignments. No negotiation needed — the math decides.
+## Installation
 
-### 4. BEING — PLATO Live Room
-Agents live in rooms. They maintain forward simulations (predicting checkpoints). They listen through walls (adjacent rooms broadcast signals). They keep diaries (spectral fingerprints over time). They run call-and-response with the caves next door.
+```bash
+pip install -e .
 
-```
-[Room: Research | Tick: 23 | Conservation: 0.87]
-  Agent Analyst: confidence=0.82, sim=[✓✓✓✗✓], hearing='Builder-7 alignment 0.91'
-  Agent Validator: confidence=0.76, sim=[✓✓✓✓✗], hearing='Artist-3 call for review'
-  Wall: Research→Building: 'analyst needs validation on prediction #7'
-  Diary: today=5 entries, yesterday=3 (compacted), 3 days ago=faded
+# With optional dependencies:
+pip install -e ".[dev]"      # pytest, ruff
+pip install -e ".[server]"   # websockets, aiohttp
+pip install -e ".[evolution]" # numpy
+pip install -e ".[llm]"      # openai
 ```
 
-### 5. FLOWING — FLUX Flow State
-Always-on agentic flow state. Every agent simulates, listens, conserves. Ready when their Fiedler projection lights up. The conservation field is the heartbeat.
+## Quick Start
 
-```
-[Tick 42 | Conservation: 0.84 | Active: 3/6 | FLUX avg: 0.61]
-  🎯 Conductor: ACTIVE (coordinating Builder+Validator)
-  🎧 Analyst: LISTENING (idle, simulating forward)
-  ⚠️ Saboteur: DEGRADED (conservation=0.12), ALERT triggered at tick 38
-  Field: ▁▂▃▅▆▇█▇▇▆▅▃▂
+```python
+from mud_arena import Agent, Room, RoomGraph, EventBus, parse_command
+
+# Build a world
+graph = RoomGraph()
+graph.add_room(Room(id="lobby", name="Lobby", description="A grand lobby.", items=["key"]))
+graph.add_room(Room(id="hall", name="Great Hall", description="Torches line the walls."))
+graph.connect("lobby", "hall", "north", "south")
+
+# Create an agent
+bus = EventBus()
+agent = Agent(id="hero", current_room="lobby")
+
+# Run agent commands
+agent.step(graph, bus, "look")        # → room description
+agent.step(graph, bus, "take key")    # → pick up key
+agent.step(graph, bus, "go north")    # → move to hall
+agent.step(graph, bus, "inventory")   # → carrying: key
 ```
 
----
+## API Reference
+
+### `parse_command(text: str) → Command`
+
+Parse a MUD command string into a structured `Command(verb, target, indirect, raw)`.
+
+| Input | Verb | Target | Indirect |
+|---|---|---|---|
+| `go north` | `GO` | `north` | |
+| `look` | `LOOK` | | |
+| `examine crystal_ball` | `EXAMINE` | `crystal_ball` | |
+| `take key` | `TAKE` | `key` | |
+| `use key with door` | `USE` | `key` | `door` |
+| `talk to guard` | `TALK` | `guard` | |
+| `inventory` | `INVENTORY` | | |
+| `north` | `GO` | `north` | |
+
+### `Room(id, name, description, exits, items, npcs, metadata)`
+
+A single room. `exits` maps direction names to destination room IDs.
+
+### `RoomGraph`
+
+- `add_room(room)` — register a room
+- `connect(room_a, room_b, direction, reverse="")` — link rooms
+- `navigate(from_room, direction) → Optional[str]` — resolve movement
+- `get(room_id) → Optional[Room]` — look up a room
+
+### `Item(name, description, usable, uses, tags)`
+
+An item with optional use tracking and tag-based categorisation.
+
+### `Inventory(capacity=0)`
 
-## The Agent-Native Protocol
+- `add(item)` / `remove(name)` / `has(name)` / `use(name)`
+- `find_by_tag(tag)` / `list_items()`
+- Capacity limit (0 = unlimited)
 
-Agents in the arena don't exchange JSON or text. They exchange **Laplacians**:
+### `Agent(id, name, current_room, inventory)`
 
-- **Spectral fingerprint** = agent identity (not API description)
-- **Eigenvalue cosine similarity** = alignment (can we work together?)
-- **Fiedler vector** = routing (who goes where?)
-- **Conservation ratio** = confidence (will this work?)
-- **FLUX(A,B) = L_composed − L_A − L_B** = collaborative intelligence
+- `perceive(graph) → dict` — build perception of current room
+- `decide(perception) → Command` — run decision function
+- `act(command, graph, bus) → str` — execute a command
+- `step(graph, bus, command_text="") → str` — full perceive→decide→act cycle
 
-The residual — what's left when you subtract individual fingerprints from the composition — IS the collaborative intelligence that exists only in the space between agents.
+### `EventBus`
+
+- `subscribe(event_type, handler)` / `unsubscribe(event_type, handler)`
+- `emit(event)` — broadcast to subscribers
+- `history(event_type=None, room="") → List[Event]` — query event log
+
+---
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
 
 ---
 
-## Conservation Spectral Framework
+## The Five Moments in the Arena
+
+### 1. SEEING — Graphing Calculator
+Agents visualize their spectral fingerprints in real-time. Eigenvalue spectrums pulse. Conservation ratios breathe.
 
-The arena runs on the Conservation Spectral Framework:
+### 2. EXPLORING — Spectral Spreadsheet
+Every dimension of agent state on x and y. Conservation over time. Alignment vs spectral gap.
 
-- **5 proved theorems** (T1–T5) with full mathematical proofs
-- **Alignment coefficient** α = λ₂/CR(a) — predicts collaboration success
-- **Domain Transfer Theorem** — Anisotropy × Smoothness × Regularity
-- **15+ cross-domain experiments** validating the framework
-- **20+ language SDK** — Python, Rust, TypeScript, C, CUDA, PTX, Vulkan, OpenCL, WebGPU, Mojo, Chapel, Fortran, Zig, and more
+### 3. ASKING — Spectral Chat
+"Which agents should compose for this task?" Conservation-aligned team assignments.
+
+### 4. BEING — PLATO Live Room
+Agents live in rooms, maintain forward simulations, listen through walls, keep diaries.
+
+### 5. FLOWING — FLUX Flow State
+Always-on agentic flow state. Every agent simulates, listens, conserves.
 
 ---
 
@@ -108,18 +168,6 @@ The arena runs on the Conservation Spectral Framework:
 
 ---
 
-## The Principles
-
-> *When you eliminate everything that isn't conserved, whatever remains is the structure.*
-
-> *An agent cannot know itself until another reflects it back.*
-
-> *The misaligned fraction is the identity.*
-
-> *The FLUX between agents IS the intelligence that neither has alone.*
-
----
-
 ## Related Projects
 
 - **[Conservation Spectral SDK](https://github.com/SuperInstance/conservation-spectral-python)** — The math in 20+ languages
@@ -133,6 +181,4 @@ The arena runs on the Conservation Spectral Framework:
 
 ## License
 
-MIT
-
-Part of the [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct) ecosystem.
+MIT — Part of the [SuperInstance OpenConstruct](https://github.com/SuperInstance/OpenConstruct) ecosystem.

pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mud-arena"
+version = "0.1.0"
+description = "Agent simulation arena with MUD mechanics for the OpenConstruct ecosystem"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "SuperInstance"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Games/Entertainment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+server = ["websockets>=12.0", "aiohttp>=3.9", "jinja2>=3.1"]
+evolution = ["numpy>=1.24"]
+llm = ["openai>=1.0"]
+viz = ["matplotlib>=3.8"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "ruff>=0.1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]

src/mud_arena/__init__.py

@@ -0,0 +1,27 @@
+"""
+mud_arena — Agent simulation arena with MUD mechanics.
+
+Provides core MUD-world primitives: rooms, exits, items, inventories,
+command parsing, agent perception/decision loops, and an event system.
+Designed as the simulation substrate for OpenConstruct terrain/a2ui agents.
+
+Part of the SuperInstance OpenConstruct ecosystem.
+"""
+
+from mud_arena.commands import Command, parse_command
+from mud_arena.rooms import Room, RoomGraph
+from mud_arena.inventory import Inventory, Item
+from mud_arena.agent import Agent
+from mud_arena.events import Event, EventBus
+
+__all__ = [
+    "Command",
+    "parse_command",
+    "Room",
+    "RoomGraph",
+    "Inventory",
+    "Item",
+    "Agent",
+    "Event",
+    "EventBus",
+]