[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2302":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":15,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":38,"readmeContent":39,"aiSummary":40,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":41,"discoverSource":42},2302,"scenario-lab","YSLAB-ai\u002Fscenario-lab","YSLAB-ai","Experimental scenario analysis for real-life events forecasting with Codex or Claude","https:\u002F\u002Fgithub.com\u002FYSLAB-ai\u002Fscenario-lab",null,"Python",301,33,8,2,0,203,55.59,"MIT License",false,"main",[23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"agent-tools","claude","codex","decision-support","forecasting","geopolitical-risk","local-first","market-forecasting","market-simulation","mcts","monte-carlo-simulation","risk-modeling","scenario-analysis","stock-market","stock-market-prediction","2026-06-12 04:00:14","# Scenario Lab\n\n🌐 Languages: [English](README.md) | [中文](README.zh-CN.md) | [Español](README.es.md) | [Français](README.fr.md) | [한국어](README.ko.md) | [日本語](README.ja.md)\n\n> Experimental preview: Monte Carlo simulation for real-world events you can run locally with Codex or Claude.\n\nScenario Lab is a Monte Carlo simulation engine for real-world events such as regional conflict, markets, politics, and company decision-making.\n\nVersion: `v0.1.0` public preview. Contributors: [CONTRIBUTORS.md](CONTRIBUTORS.md).\n\n![Scenario Lab workflow](docs\u002Fassets\u002Fscenario-lab-workflow.png)\n\n## What Is It\n\nScenario Lab turns a developing situation into a structured simulation run. You give it the actors, the current development, and the evidence you want to approve. It then explores many branching futures with Monte Carlo tree search and ranks the branches it finds.\n\nAt a high level, the engine works like this:\n\n- A domain pack defines the actors, phases, and action space for a type of event such as an interstate crisis, a market shock, or a company decision.\n- The approved evidence packet and the case framing are compiled into a belief state with actor behavior profiles and domain-specific fields.\n- The simulation engine runs `mcts` over that state, proposing actions, sampling transitions, and scoring resulting branches.\n- Reports turn the searched branches into readable outcomes, scenario families, and calibrated confidence labels.\n\nThe same runtime can be used for regional conflict, market stress, political bargaining, and company-response cases because the domain packs carry different rules and state fields.\n\n## Quickstart\n\nThe full first-use flow is in [docs\u002Fquickstart.md](docs\u002Fquickstart.md). The shortest local setup is:\n\n```bash\ngit clone git@github.com:YSLAB-ai\u002Fscenario-lab.git\ncd scenario-lab\nPYTHON=\u002Fpath\u002Fto\u002Fpython3.12\n\"$PYTHON\" -m venv packages\u002Fcore\u002F.venv\nsource packages\u002Fcore\u002F.venv\u002Fbin\u002Factivate\npip install -e 'packages\u002Fcore[dev]'\nscenario-lab demo-run --root .forecast\n```\n\nYou should see `demo-run complete`, then artifacts under `.forecast\u002Fruns\u002Fdemo-run`.\n\nFor a repo-owned bootstrap that parses a literal scenario prompt and returns the normal next workflow turn instead of running the full simulation immediately, use:\n\n```bash\nscenario-lab scenario --root .forecast \"\u002Fscenario how would a U.S.-Iran conflict at the Strait of Hormuz develop over the next 30 days\"\n```\n\n## Evidence Corpus\n\nScenario Lab drafts evidence from a local SQLite corpus. By default, evidence commands use `.forecast\u002Fcorpus.db`, so Claude Code, Codex, or another agent does not need to invent a database path.\n\nUse this normal evidence flow:\n\n```bash\nmkdir -p .forecast\u002Fevidence-candidates\n# Save or let your agent save relevant Markdown, CSV, JSON, spreadsheet, saved web page, or text-extractable PDF files there.\nscenario-lab ingest-directory --root .forecast --path .forecast\u002Fevidence-candidates --tag domain=interstate-crisis\nscenario-lab draft-evidence-packet --root .forecast --run-id \u003Crun-id> --revision-id r1\n```\n\nFor adapter-driven runs, prefer the packaged runtime:\n\n```bash\nscenario-lab run-adapter-action --root .forecast --candidate-path .forecast\u002Fevidence-candidates --run-id \u003Crun-id> --revision-id r1 --action batch-ingest-recommended\nscenario-lab run-adapter-action --root .forecast --run-id \u003Crun-id> --revision-id r1 --action draft-evidence-packet\n```\n\nYou can still override the corpus location with `--corpus-db \u003Cpath>` when you need a separate evidence database.\n\nScenario Lab is packaged to run with:\n\n- `Codex`: [docs\u002Finstall-codex.md](docs\u002Finstall-codex.md)\n- `Claude Code`: [docs\u002Finstall-claude-code.md](docs\u002Finstall-claude-code.md)\n\nIn Claude Code specifically, this repo now also ships a native project slash command at `.claude\u002Fcommands\u002Fscenario.md`, so inside Claude you can start with:\n\n```text\n\u002Fscenario how would a U.S.-Iran conflict at the Strait of Hormuz develop over the next 30 days\n```\n\nIf you want to use another coding agent, share this repo with that agent and tell it to follow [README.md](README.md), [docs\u002Fquickstart.md](docs\u002Fquickstart.md), and the linked docs for the natural-language workflow.\n\n## Workflow And Demo\n\nScenario Lab is a natural-language-based interactive engine. A normal run moves through these actual runtime phases.\n\n![Scenario Lab runtime workflow](docs\u002Fassets\u002Fscenario-lab-runtime-workflow.png)\n\n1. `intake`\n   Runtime action: `save-intake-draft`\n   What it does: understand the problem, identify the main actors, and set the time horizon. The repo can also ask follow-up questions before this setup is locked.\n2. `evidence`\n   Runtime action: usually `draft-evidence-packet`\n   Optional runtime action: `batch-ingest-recommended` when local candidate files exist and the workflow finds recommended ingestion targets\n   What it does: review what outside actors matter, what evidence is missing, and what sources to pull in, then draft or save the evidence packet.\n3. `approval`\n   Runtime action: `approve-revision`\n   What it does: lock the setup, assumptions, and evidence before search, while surfacing any warnings that still matter.\n4. `simulation`\n   Runtime action: `simulate`\n   What it does: explore many possible paths with deterministic Monte Carlo tree search.\n5. `report`\n   Runtime action: `begin-revision-update`\n   What it does: show the top outcomes, explain the main branches, and let you continue the run if the situation changes.\n\nThe public `U.S.-Iran` example follows that exact repo workflow. A longer verified CLI transcript is in [docs\u002Fdemo-us-iran.md](docs\u002Fdemo-us-iran.md).\n\nVerified deeper `U.S.-Iran` example:\n\n- broad question:\n  - `How would a U.S.-Iran conflict at the Strait of Hormuz develop for the next 30 days?`\n- intake then locked:\n  - main actors: `United States`, `Iran`\n  - third-party actors carried into the run: `China`, `Israel`, `Gulf States`, `United Kingdom`, `France`\n  - time horizon: `30d`\n  - stage: `trigger`\n- the evidence packet approved `7` curated items covering:\n  - U.S. force posture around shipping attacks\n  - UK-France maritime security coordination\n  - Iran's negotiating posture under pressure\n  - China's oil dependence on the Strait staying open\n  - Gulf export vulnerability if Hormuz closes\n  - market stress from retaliation threats\n  - Israel's readiness to resume strikes\n- the retrieval\u002Fevidence plan still centered the same evidence categories:\n  - `force posture`\n  - `diplomatic signaling`\n  - `alliance commitments`\n  - `leader behavior`\n  - `economic constraints`\n- the approval step carried `5` explicit assumptions:\n  - China prefers negotiation and backchannel pressure to prolonged closure\n  - Israel's deterrence credibility can pull the crisis toward strikes\n  - Gulf States want protected shipping but also de-escalation\n  - the United Kingdom supports a defensive escort mission\n  - France supports a defensive escort mission\n- approved revision counts:\n  - evidence items: `7`\n  - assumptions: `5`\n- simulation facts:\n  - search mode: `mcts`\n  - iterations: `10000`\n  - node count: `133`\n  - transposition hits: `111`\n- model boundary:\n  - the current `interstate-crisis` pack models bounded crisis paths through signaling, limited response, escalation pressure, negotiation, and stalemate. It does not model full-scale war as an explicit terminal outcome.\n- top ranked scenarios:\n  1. `No major escalation; allies push talks, then a tense stalemate.` with score `0.289`\n     Engine label: `Alliance consultation (coordinated signaling)`\n     What this means: outside powers pressure both sides to keep diplomacy open; the run ends in an uneasy stalemate, not a settlement.\n  2. `Warnings increase, then a tense stalemate.` with score `0.289`\n     Engine label: `Signal resolve (managed signal)`\n     What this means: Washington and Tehran keep signaling resolve, but the branch still ends in a contained stalemate.\n  3. `Talks stay open, but the crisis remains unresolved.` with score `0.287`\n     Engine label: `Open negotiation`\n     What this means: diplomacy remains available, but it does not fully resolve the crisis in this run.\n- leading scenario families:\n  - `Allies push talks, then a tense stalemate.`\n    Engine label: `Alliance consultation -> settlement-stalemate`\n    In short: outside powers pressure both sides to keep diplomacy open; the run ends in an uneasy stalemate, not a settlement.\n  - `Warnings increase, then a tense stalemate.`\n    Engine label: `Signal resolve -> settlement-stalemate`\n    In short: Washington and Tehran keep signaling resolve, but the branch still ends in a contained stalemate.\n  - `Talks stay open, then a tense stalemate.`\n    Engine label: `Open negotiation -> settlement-stalemate`\n    In short: diplomacy remains available, but it does not fully resolve the crisis in this run.\n- inferred third-party actor pressures from the approved evidence and assumptions:\n  - `China`: `domestic_sensitivity=0.62`, `negotiation_openness=0.75`\n  - `Israel`: `domestic_sensitivity=0.73`, `reputational_sensitivity=0.55`\n  - `Gulf States`: `alliance_dependence=0.86`\n  - `United Kingdom`: `alliance_dependence=0.97`\n  - `France`: `alliance_dependence=0.97`\n- report path from the rechecked run:\n  - `\u002Ftmp\u002Fscenario-lab-us-iran-deeper-main\u002Frun\u002Fruns\u002Fus-iran-deeper\u002Freports\u002Fr1.report.md`\n\nIn that verified `U.S.-Iran` run, **no major escalation; allies push talks, then a tense stalemate** ranked first, but the top three branches were very close together. The engine slightly favored allied pressure over more warning signals or direct open negotiations; it did not find a runaway winner. Engine label: `Alliance consultation (coordinated signaling)`\n\nThe shorter phase-by-phase workflow notes are in [docs\u002Fnatural-language-workflow.md](docs\u002Fnatural-language-workflow.md).\n\n## What Makes It Effective\n\nScenario Lab does not treat every branch as equally plausible. The branch search is shaped by domain rules, actor behavior profiles, and the evidence you approve for the case.\n\n- Actor actions are constrained by domain packs. For example, the `company-action` pack tracks fields such as `cash_runway_months`, `brand_sentiment`, `operational_stability`, and `regulatory_pressure`.\n- Those fields change the action priors and branch outcomes. In the company pack, weaker operations or higher regulatory pressure make moves like `operational-pivot`, `cost-program`, or `asset-sales` more competitive, while the state scoring also raises `economic_stress` and `escalation` when sentiment or operational stability deteriorate.\n- Negative consequences are therefore punished in the ranking. A company branch that improves runway but damages brand sentiment or increases pressure can still rank worse because the downstream state becomes more fragile.\n- The same pattern applies in other domains: stronger actor evidence and stronger domain knowledge produce better branch differentiation.\n\nThe repo ships with prebuilt domain knowledge, replay-backed calibration, and protected domain-evolution tools, but users should still add or modify evidence and domain assumptions for unusual scenarios.\n\nIf you want an AI agent to improve a thin domain pack, point it to [docs\u002Fdomain-pack-enrichment.md](docs\u002Fdomain-pack-enrichment.md). That guide explains the protected path: compile knowledge from approved evidence or replay misses, inspect suggestions, run retuning, and only promote changes that pass replay checks.\n\n## Current Limits\n\nThe current limitations are documented in [docs\u002Flimitations.md](docs\u002Flimitations.md).\n\n- Output quality depends heavily on the approved evidence packet.\n- Output quality depends heavily on the depth and quality of the domain pack.\n- Community contribution is part of the design: replay coverage, evidence quality, and domain knowledge all improve the results over time.\n- OCR-backed PDF ingestion is intentionally deferred in the current public preview.\n\n## License And Disclaimer\n\nScenario Lab is released under the [MIT License](LICENSE).\n\nThis repository is provided for experimental, educational, and research use. It is not a prediction product, not a guarantee of future events, and not a substitute for professional judgment or operational decision-making.\n\nThe software is provided `as is`, without warranty, under the terms of the MIT License. See [LICENSE](LICENSE) and [docs\u002Flimitations.md](docs\u002Flimitations.md) for the current public terms and limits.\n\n## Others\n\nOther useful entry points:\n\n- public quickstart: [docs\u002Fquickstart.md](docs\u002Fquickstart.md)\n- natural-language workflow notes: [docs\u002Fnatural-language-workflow.md](docs\u002Fnatural-language-workflow.md)\n- verified `U.S.-Iran` demo: [docs\u002Fdemo-us-iran.md](docs\u002Fdemo-us-iran.md)\n- domain-pack enrichment guide: [docs\u002Fdomain-pack-enrichment.md](docs\u002Fdomain-pack-enrichment.md)\n- current limitations: [docs\u002Flimitations.md](docs\u002Flimitations.md)\n- contributors: [CONTRIBUTORS.md](CONTRIBUTORS.md)\n- license: [LICENSE](LICENSE)\n- preview summary: [docs\u002Frelease-notes\u002Fpublic-preview.md](docs\u002Frelease-notes\u002Fpublic-preview.md)\n\nIf you want the smallest runnable surface instead of the higher-level interactive workflow, use the built-in demo and inspect the generated files:\n\n```bash\nsource packages\u002Fcore\u002F.venv\u002Fbin\u002Factivate\nscenario-lab demo-run --root .forecast\nls .forecast\u002Fruns\u002Fdemo-run\ncat .forecast\u002Fruns\u002Fdemo-run\u002Freport.md\ncat .forecast\u002Fruns\u002Fdemo-run\u002Fworkbench.md\n```\n","Scenario Lab 是一个用于现实世界事件预测的蒙特卡洛模拟引擎，支持使用Codex或Claude进行本地运行。该项目通过定义参与者、当前发展状况及证据来构建结构化的模拟运行，并利用蒙特卡洛树搜索探索多种可能的未来情景及其分支排名。其核心功能包括基于不同场景（如地区冲突、市场波动等）自定义领域包的能力，以及从本地SQLite数据库中草拟证据的功能。适用于需要对地缘政治风险、市场预测、公司决策支持等领域进行复杂不确定性分析的情景。","2026-06-11 02:49:20","CREATED_QUERY"]