Scenario Lab provides an experimental Monte Carlo simulation engine for forecasting real-life events, including regional conflicts, market dynamics, and political developments. It targets researchers and power users, enabling them to transform developing situations into structured simulations. By leveraging LLMs like Codex or Claude, the engine explores numerous branching futures, ranks them, and provides calibrated confidence labels, thereby aiding complex decision-making processes.

How It Works

The core approach involves "domain packs" that define actors, phases, and action spaces for specific event types. A "belief state" integrates approved evidence, actor behavior profiles, and domain-specific fields. The simulation engine employs Monte Carlo Tree Search (MCTS) to explore potential future paths by proposing actions and sampling transitions. Outcomes are scored based on domain rules and actor profiles, constraining actions and punishing negative consequences to differentiate plausible future branches. Reports then translate these branches into readable outcomes and scenario families.

Quick Start & Requirements

Local setup requires cloning the repository, setting up a Python 3.12 virtual environment, and installing dependencies via pip install -e 'packages/core[dev]'. A demo run can be initiated with scenario-lab demo-run --root .forecast. The system necessitates Python 3.12 and integrates with LLMs such as Codex or Claude for evidence drafting. Comprehensive setup and LLM integration guides are available at docs/quickstart.md, docs/install-codex.md, and docs/install-claude-code.md.

Highlighted Details

• Features a detailed U.S.-Iran conflict simulation example, illustrating actor interactions, evidence integration, assumption validation, and ranked scenario outcomes.
• Employs a natural-language-based interactive workflow with distinct runtime phases: intake, evidence gathering, approval, simulation, and reporting.
• Supports evidence ingestion from various local file formats (Markdown, CSV, JSON, spreadsheets, PDFs) into an SQLite corpus.
• Provides tools and guides for enriching domain packs, enabling users to customize or add knowledge for specific scenarios.

Maintenance & Community

Contributors are listed in CONTRIBUTORS.md. No specific community channels (e.g., Discord, Slack) or roadmap details are provided in the README.

Licensing & Compatibility

Released under the MIT License. The software is intended for experimental, educational, and research use only, provided "as is" without warranty, and is not a substitute for professional judgment or operational decision-making.

Limitations & Caveats

Output quality is highly dependent on the depth and quality of the provided evidence packet and domain pack. OCR-backed PDF ingestion is deferred in the current public preview. The interstate-crisis domain pack does not explicitly model full-scale war as a terminal outcome. This is a v0.1.0 public preview.