071906df59
- Core engine: simulator, game mechanics, triggers (138 tests) - Fog-of-war per-player state tracking - Meeting flow: interrupt, discussion, voting, consolidation - Prompt assembler with strategy injection tiers - LLM client with fallbacks for models without JSON/system support - Prompt templates: action, discussion, voting, reflection - Full integration in main.py orchestrator - Verified working with free OpenRouter models (Gemma)
99 lines
3.0 KiB
Markdown
99 lines
3.0 KiB
Markdown
# 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
|