# The Glass Box League

> Among Us as a headless discrete event simulation. LLMs are players. Classic rules, no GUI.

## Quick Start

```bash
# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install requests

# Set API key
export OPENROUTER_API_KEY="your-key-here"

# Run tests
python3 -m unittest discover -v tests/

# Run simulation (coming soon)
python3 -m src.main
```

## Project Structure

```
among-us-agents/
├── config/
│   ├── game_settings.yaml     # Game rules & parameters
│   └── prompts/               # LLM prompt templates
├── data/
│   ├── maps/skeld.json        # The Skeld map
│   └── agents/{agent_id}/     # Per-agent scratchpads
├── docs/                      # Design docs & API reference
├── src/
│   ├── engine/
│   │   ├── simulator.py       # Discrete event simulator
│   │   ├── game.py            # Game mechanics
│   │   ├── triggers.py        # Trigger registry
│   │   ├── fog_of_war.py      # Per-player knowledge
│   │   ├── available_actions.py  # Dynamic actions
│   │   ├── trigger_messages.py   # Trigger JSON schemas
│   │   ├── meeting_flow.py    # Meeting lifecycle
│   │   ├── discussion.py      # Discussion orchestrator
│   │   └── types.py           # Core data types
│   ├── map/graph.py           # Graph-based map
│   ├── agents/
│   │   ├── agent.py           # LLM agent wrapper
│   │   ├── scratchpads.py     # File-based memory
│   │   └── prompt_assembler.py  # Prompt builder
│   ├── llm/client.py          # OpenRouter client
│   └── main.py                # Game orchestrator
└── tests/                     # 138 tests
```

## Architecture

### Engine
- **Continuous time** simulation (seconds, not discrete ticks)
- **Event-driven**: triggers fire → time freezes → agent responds → time resumes
- **Fog of war**: each agent only knows what they've observed

### Agents
- **Stateless LLM calls**: each trigger = fresh invocation
- **JSON scratchpads**: persistent memory across ticks
- **Toggleable settings**: personas, strategy injection, meta-awareness

### Discussion
- **Priority bidding**: agents bid to speak, highest priority wins
- **Vote-when-ready**: discussion ends when all vote
- **Ghost chat**: dead players observe

## Documentation

| Document | Description |
|----------|-------------|
| [design_main_game.md](docs/design_main_game.md) | Game loop, triggers, tools, state |
| [design_discussion.md](docs/design_discussion.md) | Discussion, voting, personas |
| [openrouter_api.md](docs/openrouter_api.md) | LLM integration |

## Tests

```bash
python3 -m unittest discover -v tests/
# 118 tests across map, simulator, triggers, game, discussion
```

## Status

- ✅ Phase 1: Core Engine
- ✅ Phase 2: Agent Scaffolding  
- ✅ Phase 3: Prompt Engineering Design
- 🔄 Phase 4: Implementation
- ⏳ Phase 5: Prompt Templates
- ⏳ Phase 6: Testing & Polish

## License

MIT