An experimental playground built on Microsoft’s Agent Framework where multiple users collaboratively mutate a shared timeline. Every new event can ripple backward or forward in time, creating cancellations, paradoxes, and AI-generated narration. This repo contains the Python agent, supporting tools, and contributor documentation needed to evolve the simulator.
- Append-only history – events are never deleted; statuses change to reflect new realities.
- Agent-driven consequences – the agent interprets user inputs, marks impacted events (cancelled, paradox, overridden), and generates ripple events.
- Shared chaos – all participants observe the same timeline mutate in real time.
- Narration & activity feed – short AI-written summaries explain the latest historical twists.
See planning/FEATURES.md for the full experience vision and roadmap.
.
├── src/
│ ├── timeline_agent/ # domain models, orchestration, infrastructure
│ └── llm/ # shared OpenAI client + instructions loader
├── tests/ # pytest suites mirroring src structure
├── prompts/ # agent instruction files (default chaos prompt)
├── planning/ # feature specs and design docs
└── AGENTS.md # contributor guidelines
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest
python src/llm/openai_client.py # sanity-check LLM connectivity- Set
OPENAI_API_KEY(and optionallyOPENAI_MODEL_ID) in your.env. - Default agent instructions live in
prompts/default_instructions.md; edit or add new prompt files per feature.
- Read
AGENTS.mdfor structure, coding style, and PR expectations. - When changing timeline logic or prompts, update
planning/docs and add/adjust tests undertests/.
- Persistent storage for timelines and rooms.
- Realtime transport (WebSocket) to sync timeline mutations.
- Advanced agent tools: ripple generation policies, chaos-level controls, safety guardrails.