Decision OS

CLI-first Monte Carlo decision engine for comparing options under uncertainty. It samples configurable probability distributions, aggregates weighted outcomes, and produces a markdown decision memo with upside/downside clarity.

Design Highlights

• Pure Python 3.11+ with deterministic runs via numpy.random.Generator seeded per decision.
• Clean dataclasses (Decision, Option, Variable) and distribution abstractions with validation.
• Metrics include mean, median, P10/P90, VaR 5%, and CVaR 5%.
• One-at-a-time sensitivity lifts each variable's mean by 10% to show the EV delta.
• CLI prints a summary table and writes a memo to reports/.

Quick Start

python -m app.cli examples/job_offer.json

The command prints the comparison table and writes reports/<decision>_memo.md.

Sample Run

$ python -m app.cli examples/job_offer.json
Decision: Job Offer Choice
Option                       | EV        | Median    | P10       | P90       | VaR5      | CVaR5    
-----------------------------+-----------+-----------+-----------+-----------+-----------+----------
Offer A: High-Growth Startup | 110920.80 | 98766.88  | 65357.72  | 168936.38 | 50715.17  | 43060.32 
Offer B: Balanced Growth     | 117728.96 | 114524.13 | 93343.23  | 149402.16 | 85301.90  | 78877.42 
Offer C: Stability First     | 146285.15 | 146310.56 | 132621.79 | 160138.71 | 122254.41 | 117782.61

Markdown memo written to reports/job_offer_choice_memo.md

Configuration Schema

examples/job_offer.json shows the expected shape:

• name: Decision name.
• simulations (int, default 50000), seed (int, default 42).
• assumptions (list[str], optional), change_conditions (list[str], optional).
• options: list of objects with name and variables.
• variables: each has name, weight (float, default 1.0), and a distribution.
• distribution: type one of Uniform, Normal, LogNormal, Triangular plus parameters:
  • Uniform: min, max
  • Normal: mean, std
  • LogNormal: mean, sigma
  • Triangular: low, mode, high

Testing

Install dev extras and run pytest:

pip install -e ".[test]"
pytest

Extending

• Add new distributions by implementing Distribution with sample, validate, mean, and with_mean_scaled.
• Additional report formats can hook into core.metrics.summarize_outcomes and core.sensitivity.run_sensitivity.