simengine

SimEngine

与领域无关的蒙特卡洛模拟和决策智能系统。

零依赖。纯 Python 标准库。本地 Web 界面。凡是能运行 Python 的地方都能运行。

SimEngine 将不确定性转化为可供决策的数字。在 JSON 配置中定义变量、逻辑和风险容忍度。引擎会运行数千种模拟未来情景，为它们评分；如果你提出要求，还会在遵守安全约束的前提下，逐步优化出最佳策略。

可以把它看作一台不确定性计算器。

---

快速开始

# 1. Clone the repository
git clone <repo-url> ~/projects/simengine
cd ~/projects/simengine

# 2. Start the web UI
cd v3 && python3 server.py

# 3. Open your browser
#    http://localhost:8420

就是这样。无需 pip install、Docker、Node 或构建步骤。唯一的要求是 Python 3.8+。

安装为 MCP 服务

uvx simengine-mcp

已列入 官方 MCP 注册表。 托管的免安装端点：加入候补名单。

可选的原生加速

默认引擎仍使用纯 Python。仓库根目录现在包含一个 Rust 工作区，可用于选择性加速指标归约器、轨迹区间、风险评估、直方图，以及简单数值变量分布的原生预采样。

此功能需主动启用，不会改变上述基准工作流。

工作区布局

Cargo.toml
crates/
├── simengine-core/   # pure Rust numeric kernels
└── simengine-py/     # PyO3 extension module: simengine_native
v3/native.py          # optional loader + Python fallback glue

构建原生扩展

cd crates/simengine-py
python3 -m venv ../../.venv
source ../../.venv/bin/activate
pip install maturin
maturin develop --release

完成后，只要 simengine_native 可导入，现有 Python 引擎就会自动使用原生归约器和原生批量采样器。 如果模块缺失或加载失败，SimEngine 会回退到现有的 Python 实现。

批量采样器采用保守策略：

• 仅对普通数值变量参数启用
• 相关配置下不会启用
• 可通过 SIMENGINE_DISABLE_NATIVE_SAMPLING=1 显式禁用

这样，表达式引擎、累加器和指标仍保留在 Python 中，同时将蒙特卡洛循环中的更多部分移至 Rust。

随机表达式也有一个范围更窄的原生快速路径：

• 安装扩展后，可将 binomial(n, p) 委托给 Rust
• 可通过 SIMENGINE_DISABLE_NATIVE_EXPR_SAMPLING=1 显式禁用

这有助于 step_logic 大量依赖 binomial(...) 的领域，同时仍由 Python 负责通用表达式求值。

在 Python 端，重复表达式现在只编译一次，并在蒙特卡洛运行中重复使用。可通过 SIMENGINE_DISABLE_EXPR_CACHE=1 显式禁用此缓存，以用于基准测试或故障排查。

diagnostics 模块在其仅基于 AST 的安全求值器中采用了相同的方法： 解析后的语法树会在多次调用间重复使用；可通过 SIMENGINE_DISABLE_SAFE_EXPR_CACHE=1 禁用此缓存。

---

功能

• 蒙特卡洛模拟 -- 为任何能用 JSON 描述的领域运行 5,000 次以上并行未来情景。
• 安全约束 -- 概率约束（“破产概率最多为 15%”）和 CVaR 约束（“最坏情况下的平均损失不得超过 $X”）。
• 遗传优化器 -- 在遵守安全边界的同时，逐步优化控制参数以获得最佳结果。包括交叉、变异、精英保留和锦标赛选择。
• 贝叶斯更新 -- 将观测数据反馈到模型中。共轭先验（Beta-二项、Gamma-泊松、正态-正态）会随着证据到来而收紧分布。
• 诊断 -- 收敛分析（证明样本量足够）、敏感性分析（按影响输出的程度对输入排序）、确定性基线比较（量化模拟相对于电子表格计算的价值）。
• Web UI -- 直方图、轨迹扇形图、风险仪表、含控制变量扫描和输入差异的情景比较、领域向导、贝叶斯更新模态框，以及导出为独立 HTML 报告。
• AI Agent 集成 -- 将配置内联 POST 到 /api/simulate，即可获得结构化结果。无需文件。LLM 可以将 SimEngine 用作工具（仓库根目录中的 llms.txt 以及 GET /llms.txt 可帮助其了解用法）。
• 经过验证的校准 -- sqlite 预测台账使用恰当的评分规则（Brier / log-loss / CRPS）为预测评分；该流程已通过数十年公开 FRED 数据上的约 2,800 个月度滚动预测进行了回测。亲自运行：cd v3 && python3 backtest.py（离线运行，使用已提交的快照）。结果：docs/backtests/。

---

架构

所有生产代码都位于 v3/ 中。

v3/
├── kernel.py          Monte Carlo engine, distributions, safety evaluation,
│                      fitness scoring, genetic optimizer, experiment manifests
├── server.py          HTTP server (port 8420), all API endpoints, report generation
├── bayesian.py        Conjugate prior updates for calibrating parameters from data
├── diagnostics.py     Convergence, sensitivity (OAT), baseline comparison, AST evaluator
├── static/
│   └── index.html     Single-page web UI (vanilla HTML/JS/CSS, no framework)
└── domains/
    ├── _template.json              Annotated starter config
    ├── business_pipeline_v3.json   B2B sales pipeline
    ├── investment_portfolio.json   Portfolio allocation
    ├── investment_portfolio_v2.json  Fat-tailed returns (Student's t)
    ├── job_search.json             Job search decision model
    ├── project_timeline.json       Software project estimation
    ├── real_estate_rental.json     Rental property analysis
    └── saas_startup.json           SaaS MRR growth and runway

---

领域配置架构

领域配置是一个完整描述模拟的 JSON 文件。v3 架构将变量分为三个语义类别，这对贝叶斯更新和优化很重要。

**已发布的规范：**机器可读的 JSON Schema（Draft 2020-12）通过 GET /api/schema 实时提供——将其交给任意 AI，即可一次性生成有效配置。纯文本字段说明见 docs/schema-reference.md。测试套件会针对每个随附领域验证该架构。

顶层字段

字段	类型	描述
name	string	便于人阅读的领域名称
description	string	此模拟所建模的内容
n_simulations	int	蒙特卡洛运行次数（默认：5000）
n_steps	int	每次模拟的时间步数（例如，12 个月）
step_label	string	时间轴标签：“month”、“week”、“sprint”
seed	int or null	用于确保结果可复现的随机种子
parameters	object	不确定变量，可根据证据更新
controls	object	操作者的决策（定价、预算、投入）
exogenous	object	不受你控制的外部因素
initial_state	object	累加器的初始值
step_logic	array	每个时间步执行的计算
accumulators	object	每一步更新的累计总量
metrics	object	最终输出指标
safety	object	概率约束和 CVaR 约束
fitness	object	优化器的加权评分组成部分
tunable	array	优化器获准调整的参数
context	object	可选元数据：决策问题、关键杠杆
calibration	object	每个变量的数据源和更新方法

变量定义

三类变量（parameters、controls、exogenous）采用相同结构：

{
  "monthly_churn_rate": {
    "distribution": "triangular",
    "params": {"low": 0.02, "mode": 0.05, "high": 0.12},
    "calibration": {
      "source": "Baremetrics Open Benchmarks: median monthly churn 5-8%",
      "updatable": true,
      "update_method": "Beta-Binomial conjugate from observed monthly cancellations"
    }
  }
}

可用分布

分布	参数	用途
fixed	value	已知常量
uniform	low、high	范围内等概率
triangular	low、mode、high	专家估算（悲观／最可能／乐观）
normal	mean、std、min?、max?	钟形曲线，可选择截断
lognormal	median、spread、min?、max?	始终为正，右偏（价格、持续时间）
bernoulli	p	二元是／否事件
poisson	lambda	罕见事件的计数
student_t	mean、scale、df、min?、max?	厚尾收益（股票可使用 df=5）
correlated_normal	mean、std	支持相关性的正态分布（通过 step_logic）

步骤逻辑

按顺序排列的计算列表，每个时间步都会执行。每个条目都有一个 target 名称，以及 expr（表达式字符串）或 sample（内联分布）：

"step_logic": [
  {"target": "new_leads",    "expr": "binomial(round(demand), conversion_rate)"},
  {"target": "revenue",      "expr": "new_leads * price_per_unit"},
  {"target": "costs",        "expr": "fixed_cost + variable_cost * new_leads"},
  {"target": "net_income",   "expr": "revenue - costs"},
  {"target": "shock_event",  "sample": {"distribution": "bernoulli", "params": {"p": 0.02}}}
]

可用表达式函数： min、max、abs、round、sum、len、int、float、sqrt、log、exp、ceil、floor、pow、random()、gauss(mu, sigma)、binomial(n, p)、clamp(val, lo, hi)、range()。支持三元表达式：100 if x > 0 else 0。

累加器

在多个时间步之间持续保留的运行状态：

"accumulators": {
  "cumulative_revenue": "cumulative_revenue + revenue",
  "cash": "cash + net_income",
  "peak_subscribers": "max(peak_subscribers, subscribers)"
}

指标

所有步骤完成后计算的最终测量值：

"metrics": {
  "total_revenue": {"expr": "cumulative_revenue",          "format": "dollar"},
  "roi":           {"expr": "cumulative_revenue / cumulative_costs", "format": "percent"},
  "final_subs":    {"expr": "subscribers",                 "format": "number"}
}

安全约束

"safety": {
  "chance_constraints": [
    {
      "metric": "ending_cash",
      "condition": "below",
      "threshold": 0,
      "max_prob": 0.15,
      "rationale": "No more than 15% chance of running out of cash"
    }
  ],
  "cvar_constraints": [
    {
      "metric": "ending_cash",
      "alpha": 0.10,
      "min_cvar": -15000,
      "rationale": "Average of the worst 10% of outcomes must not exceed $15k loss"
    }
  ]
}

适应度与可调参数

优化器会在遵守安全约束的同时，最大化适应度组件的加权总和。每个组件都是根据指标统计数据评估的表达式（例如 total_revenue_median、ending_cash_p10）：

"fitness": {
  "components": [
    {"expr": "min(100, final_mrr_median / 100)",  "weight": 0.30, "name": "mrr_growth"},
    {"expr": "max(0, 100 - months_negative_median * 5)", "weight": 0.25, "name": "time_to_profit"}
  ]
},
"tunable": [
  {"path": "controls.price_per_seat.params.value",      "range": [9, 99]},
  {"path": "parameters.monthly_churn_rate.params.mode",  "range": [0.01, 0.10]}
]

适应度表达式可以引用任何指标统计值，格式为 {metric_name}_{stat}，其中 stat 可以是：mean、median、std、p10、p25、p75、p90。

每违反一项约束，安全违规都会导致 30% 的惩罚。优化器会学会避免违规。

---

API 参考

服务运行于 http://localhost:8420。所有 POST 端点都接受并返回 JSON。所有响应均包含 CORS 标头。

GET /api/domains

列出所有可用的领域配置。

响应：

[
  {
    "file": "saas_startup.json",
    "name": "Indie SaaS -- MRR Growth & Runway",
    "description": "Models a bootstrapped SaaS product over 24 months...",
    "n_simulations": 5000,
    "n_steps": 24,
    "step_label": "month"
  }
]

GET /api/domain/{filename}

按文件名加载特定领域配置。

响应： 完整的 JSON 领域配置对象。

POST /api/simulate

运行蒙特卡洛模拟。

请求（基于文件）：

{
  "domain": "saas_startup.json",
  "n_simulations": 5000,
  "seed": 42,
  "overrides": {
    "controls.price_per_seat.params.value": 49
  }
}

请求（内联配置 —— 适用于 AI Agent）：

{
  "config": { ... full domain config object ... },
  "n_simulations": 5000,
  "seed": 42
}

响应：

{
  "domain": "Indie SaaS -- MRR Growth & Runway",
  "n_simulations": 5000,
  "elapsed": 1.23,
  "stats": {
    "final_mrr": {
      "mean": 4250.00,
      "median": 3915.00,
      "std": 2100.50,
      "p10": 1740.00,
      "p25": 2610.00,
      "p75": 5220.00,
      "p90": 7105.00,
      "format": "dollar"
    }
  },
  "trajectories": {
    "cash": {
      "p10": [24500, 23800, ...],
      "p50": [25100, 25300, ...],
      "p90": [25800, 26900, ...]
    }
  },
  "histograms": {
    "final_mrr": {
      "bins": [0.0, 250.0, ...],
      "counts": [12, 45, ...],
      "bin_width": 250.0,
      "lo": 0.0,
      "hi": 10000.0
    }
  },
  "safety": {
    "chance": [
      {"metric": "ending_cash", "condition": "below", "threshold": 0,
       "max_prob": 0.15, "actual_prob": 0.082, "passed": true}
    ],
    "cvar": [
      {"metric": "ending_cash", "alpha": 0.10, "min_cvar": -15000,
       "actual_cvar": -8500.00, "passed": true}
    ],
    "all_passed": true
  },
  "fitness": 72.5,
  "narrative": "**Final Mrr** is most likely $3,915 (range: $1,740 to $7,105 in 80% of scenarios)...",
  "context": {"decision": "Should I go full-time on this SaaS?"}
}

POST /api/evolve

运行遗传优化器，以寻找最佳控制设置。

请求：

{
  "domain": "saas_startup.json",
  "generations": 15,
  "population": 20
}

响应：

{
  "domain": "Indie SaaS -- MRR Growth & Runway",
  "best_fitness": 85.3,
  "best_stats": { ... same format as simulate stats ... },
  "best_safety": { "all_passed": true, "chance": [...], "cvar": [...] },
  "history": [
    {"gen": 0, "best_fit": 62.1, "avg_fit": 45.3, "safe_pct": 60.0, "elapsed": 2.1},
    {"gen": 1, "best_fit": 68.5, "avg_fit": 52.1, "safe_pct": 75.0, "elapsed": 2.0}
  ],
  "elapsed": 31.5
}

POST /api/validate

验证领域配置，但不运行完整模拟。运行 10 次迭代测试，以捕获表达式错误。

请求：

{
  "config": { ... domain config object ... }
}

响应：

{
  "valid": true,
  "errors": []
}

或者在失败时：

{
  "valid": false,
  "errors": [
    "Variable 'close_rate': unknown distribution 'beta'",
    "step_logic[2]: missing 'target'"
  ]
}

POST /api/save-domain

验证领域配置，并将其保存到 domains/ 目录。

请求：

{
  "config": { ... domain config object ... },
  "filename": "my_new_domain"
}

响应：

{
  "saved": true,
  "file": "my_new_domain.json"
}

POST /api/update

贝叶斯更新：将观测数据输入领域配置，获取更新后的参数分布以及预览模拟。

请求：

{
  "domain": "saas_startup.json",
  "observations": {
    "monthly_churn_rate": [0.04, 0.06, 0.03, 0.05],
    "organic_signup_rate": [18, 22, 15, 25, 20]
  }
}

响应：

{
  "updated_config": { ... full config with tightened distributions ... },
  "update_report": {
    "monthly_churn_rate": {
      "method": "beta_binomial",
      "prior_mean": 0.05,
      "posterior_mean": 0.045,
      "posterior_std": 0.012,
      "observations_used": 4,
      "credible_interval_90": [0.025, 0.065]
    }
  },
  "preview_stats": { ... simulation results with updated params ... },
  "preview_safety": { ... }
}

POST /api/report

根据模拟结果生成独立的 HTML 报告。

请求：

{
  "results": { ... simulate response object ... },
  "config": { ... domain config ... }
}

响应： HTML 文档（Content-Type: text/html）。内容自包含，无外部依赖。可保存、通过电子邮件发送或打印。

---

CLI 用法

kernel.py

cd ~/projects/simengine/v3

# Run a Monte Carlo simulation
python3 kernel.py domains/saas_startup.json

# Set a random seed for reproducibility
python3 kernel.py domains/saas_startup.json --seed 42

# Save results to a specific file
python3 kernel.py domains/saas_startup.json --output results.json

# Run evolutionary optimization
python3 kernel.py domains/saas_startup.json --evolve

# Customize optimizer parameters
python3 kernel.py domains/saas_startup.json --evolve \
  --generations 25 \
  --population 30 \
  --workers 8 \
  --output best_strategy.json

短标志：-g（代数）、-p（种群）、-w（工作线程）、-o（输出）。

diagnostics.py

cd ~/projects/simengine/v3

# Convergence analysis -- proves sample size is sufficient
# Runs at N=100, 250, 500, ..., 20000 and measures estimator stability.
python3 diagnostics.py domains/saas_startup.json --convergence

# Sensitivity analysis -- ranks which inputs drive the output
# One-at-a-time perturbation with normalized impact scores.
python3 diagnostics.py domains/saas_startup.json --sensitivity

# Baseline comparison -- Monte Carlo vs deterministic spreadsheet
# Shows the risk that point-estimate forecasting hides.
python3 diagnostics.py domains/saas_startup.json --baseline

# Target a specific metric (default: first metric defined)
python3 diagnostics.py domains/saas_startup.json --convergence --metric ending_cash

# Save results to JSON
python3 diagnostics.py domains/saas_startup.json --convergence --output conv.json

可以组合标志：--convergence --sensitivity --baseline 会运行全部三项。

---

创建新领域

有三种方式可以创建领域配置。

1. Web UI 向导

打开 http://localhost:8420，点击领域向导并填写表单。向导会生成有效配置、验证配置，并将其保存到 domains/ 目录。

2. 复制模板

cp ~/projects/simengine/v3/domains/_template.json ~/projects/simengine/v3/domains/my_problem.json

编辑 my_problem.json。模板的 _guide 字段中包含内联文档，并提供了一个可运行的示例结构。将占位变量、逻辑和指标替换为你自己的内容。

3. 使用大模型生成

向大模型描述你的问题，并请它生成 SimEngine v3 领域配置。使用前请先验证：

# Validate from the command line via the API
curl -X POST http://localhost:8420/api/validate \
  -H 'Content-Type: application/json' \
  -d '{"config": <paste your JSON>}'

或者，将配置直接 POST 到 /api/simulate，并使用 {"config": {...}}——配置要么会运行，要么会返回错误。

最小可行配置

能够运行的最小配置：

{
  "name": "Coin Flip",
  "n_simulations": 1000,
  "n_steps": 10,
  "parameters": {
    "heads": {
      "distribution": "bernoulli",
      "params": {"p": 0.5}
    }
  },
  "step_logic": [
    {"target": "payout", "expr": "1 if heads > 0.5 else -1"}
  ],
  "accumulators": {
    "bankroll": "bankroll + payout"
  },
  "metrics": {
    "final_bankroll": {"expr": "bankroll", "format": "number"}
  },
  "initial_state": {"bankroll": 0}
}

---

贝叶斯更新

SimEngine 支持共轭贝叶斯更新。随着实际数据不断到来，参数分布会逐步收窄。

工作原理

1. 从先验开始——即你在配置中指定的分布（例如，流失率使用 triangular(0.02, 0.05, 0.12)）。
2. 观察实际数据（例如，实际月流失率：[0.04, 0.06, 0.03, 0.05]）。
3. 引擎使用相应的共轭更新方法计算后验分布。
4. 配置会被改写为更集中的分布，同时反映你的先验信念和实际证据。

支持的方法

方法	共轭对	适用场景
beta_binomial	Beta-二项分布	比率和概率：成交率、流失率、转化率
gamma_poisson	Gamma-泊松分布	计数：每月潜在客户数、每个冲刺周期的错误数、每周注册数
normal_normal	正态-正态分布	连续均值：项目价值、薪资、交易规模

方法选择

按以下顺序选择方法：

1. 变量定义中显式设置的 calibration.update_method。
2. 根据分布类型和参数范围自动推断（[0,1] 范围内的值使用 Beta-二项分布；整数值泊松分布使用 Gamma-泊松分布；其他情况使用正态-正态分布）。

通过 API 使用

curl -X POST http://localhost:8420/api/update \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "saas_startup.json",
    "observations": {
      "monthly_churn_rate": [0.04, 0.06, 0.03, 0.05]
    }
  }'

响应中包含更新后的配置、显示先验与后验对比的诊断报告，以及使用更新后参数运行的预览模拟。

通过 Python 使用

from bayesian import update_parameter

updated_params, diagnostics = update_parameter(
    variable_def={
        "distribution": "triangular",
        "params": {"low": 0.02, "mode": 0.05, "high": 0.12}
    },
    observations=[0.04, 0.06, 0.03, 0.05],
    method="beta_binomial"
)

print(diagnostics["posterior_mean"])    # 0.0459
print(diagnostics["credible_interval_90"])  # [0.0312, 0.0606]

---

AI Agent 集成

SimEngine 专为大模型和 AI Agent 作为工具使用而设计。其关键特性是内联配置支持：无需保存任何文件，即可将完整的领域配置直接 POST 到 /api/simulate。

使用模式

1. Agent 将问题描述为 SimEngine 领域配置（JSON）。
2. Agent 将 {"config": {...}, "n_simulations": 5000, "seed": 42} POST 到 /api/simulate。
3. Agent 读取结构化响应：统计数据、安全评估、适应度分数和叙述文本。
4. Agent 根据结果进行推理，然后向用户汇报，或调整配置并重新运行。

示例：Agent 工具调用

import json, urllib.request

config = {
    "name": "Should I take this contract?",
    "n_simulations": 3000,
    "n_steps": 6,
    "step_label": "month",
    "parameters": {
        "hours_per_week": {
            "distribution": "triangular",
            "params": {"low": 15, "mode": 25, "high": 45}
        },
        "scope_creep": {
            "distribution": "bernoulli",
            "params": {"p": 0.3}
        }
    },
    "controls": {
        "hourly_rate": {
            "distribution": "fixed",
            "params": {"value": 150}
        }
    },
    "exogenous": {},
    "initial_state": {"total_hours": 0, "total_revenue": 0},
    "step_logic": [
        {"target": "weekly_hours", "expr": "hours_per_week * (1.4 if scope_creep > 0.5 else 1.0)"},
        {"target": "monthly_hours", "expr": "weekly_hours * 4.33"},
        {"target": "monthly_rev", "expr": "min(monthly_hours, 160) * hourly_rate"}
    ],
    "accumulators": {
        "total_hours": "total_hours + monthly_hours",
        "total_revenue": "total_revenue + monthly_rev"
    },
    "metrics": {
        "total_revenue": {"expr": "total_revenue", "format": "dollar"},
        "effective_rate": {"expr": "total_revenue / total_hours if total_hours > 0 else 0", "format": "dollar"},
        "total_hours": {"expr": "total_hours", "format": "number"}
    }
}

req = urllib.request.Request(
    "http://localhost:8420/api/simulate",
    data=json.dumps({"config": config, "seed": 42}).encode(),
    headers={"Content-Type": "application/json"},
    method="POST"
)
resp = json.loads(urllib.request.urlopen(req).read())

print(f"Revenue (median): ${resp['stats']['total_revenue']['median']:,.0f}")
print(f"Revenue (P10-P90): ${resp['stats']['total_revenue']['p10']:,.0f} - ${resp['stats']['total_revenue']['p90']:,.0f}")
print(f"Effective rate (median): ${resp['stats']['effective_rate']['median']:,.0f}/hr")

Agent 获取的结果

/api/simulate 响应包含 Agent 推理结果所需的全部内容：

• stats —— 每项指标的完整分布统计数据（均值、中位数、标准差、p10/p25/p75/p90）。
• safety —— 每项约束的通过/未通过结果及实际概率。
• fitness —— 用于比较场景的单一标量分数。
• narrative —— 易于理解的摘要文本。
• trajectories —— 用于趋势分析的时间序列百分位区间。
• histograms —— 用于分析分布形态的分箱数据。

场景比较

如需比较不同方案，Agent 可以 POST 多个配置（改变控制变量），并比较响应中的适应度分数、安全评估或特定指标百分位数。

决策关口：decide_under_uncertainty（MCP）

多步骤 Agent 会不断累积过度自信的单点答案。decide_under_uncertainty MCP 工具会将模拟结果转化为继续／升级处理的判定：运行蒙特卡洛模拟，衡量结果分布中有多少概率落在你接受的范围内，并返回判定标记、完整分布和通俗易懂的原因。

它模拟的是结果风险——在输入不确定的情况下结果的分布范围——而不是语言模型自身的 token 置信度。两者互为补充；不要混为一谈。

参数：metric（必填）、acceptable（{"min": ..., "max": ...}，至少指定一个边界）、min_confidence（继续处理所需的范围内概率质量，默认值为 0.8），以及 domain 或内联 config，还有可选的 seed／n_simulations。

{
  "metric": "annual_gross_income",
  "decision": "proceed",
  "proceed": true,
  "probability_within_bounds": 0.92,
  "min_confidence": 0.8,
  "acceptable": {"min": 40000, "max": null},
  "distribution": {"median": 68000, "p10": 44000, "p90": 95000, "format": "dollar"},
  "n_simulations": 5000,
  "reason": "92% of 5,000 simulated outcomes for 'annual_gross_income' fall within the acceptable range (>= 40,000) -- at or above the 80% confidence required to proceed."
}

完整的 Agent 模式请参阅 docs/decision-gate.md。

---

校准与历史记录

蒙特卡洛引擎总会生成看起来很有把握的分布。区分*“能算出看似合理的数字的计算器”与“经过验证、命中率有据可查的预测工具”*的唯一标准，是基于真实结果评分的历史记录。v3/calibration.py 就是这套机制的核心——纯标准库、零依赖。

适当评分规则：brier_score、log_loss、crps_sample。

**预测台账：**现在记录预测，之后根据实际结果进行验证，并为长期校准表现评分。

from calibration import CalibrationLedger

ledger = CalibrationLedger("forecasts.db")
fid = ledger.record("Annual gross >= $40k?", 0.82, metric="annual_gross_income")
# ... the year resolves ...
ledger.resolve(fid, 1)
print(ledger.score())   # {"n": 1, "brier": 0.0324, "log_loss": 0.198}

Brier 分数为 0.0 表示完美；0.25 是始终猜测 50/50 时的分数；1.0 则最差。对于过度自信且错误的预测，Log-loss 的惩罚更重。两者都是越低越好。时间就是护城河：只有从现在开始记录，历史记录才会逐渐积累。

---

实时数据（可选启用）

核心引擎离线运行且仅使用标准库。v3/feeds/ 软件包是连接实时数据的可选桥接层——它是 SimEngine 中唯一会访问网络的部分，仍仅使用 urllib（不增加新依赖），且核心代码绝不会导入它。

首个适配器 feeds/polymarket.py 会将实时 Polymarket 预测市场价格转换为校准先验：市场隐含概率会成为 SimEngine 变量，可放入领域配置中，并在你自己的证据陆续出现时用 Beta-Binomial 更新器进一步收紧。价格输入 → 先验 → 后验，而不是价格输入 → 价格输出。

from feeds import polymarket
markets = polymarket.fetch_markets(query="fed rate", limit=5)
prior = polymarket.market_prior(markets[0], strength=20)   # -> a triangular variable_def

请参阅 docs/feeds.md。市场价格仅作为模拟的内部输入，不会被重新广播，也不是交易信号。

---

用自然语言向 SimEngine 提问

不想编写配置？用通俗语言描述你的决策，让大模型为你构建模型。SimEngine 会起草配置、根据引擎进行验证、修复任何错误、运行模拟并解释结果——因此，即使是较小的本地模型也能保持可靠，因为引擎会为模型生成的内容提供依据。

此功能为可选启用，且仅使用标准库。默认通过 Ollama 使用本地模型——免费、私密，无需 API 密钥。设置环境变量即可改用托管模型。

命令行

# With Ollama running (e.g. `ollama pull qwen2.5`):
python3 v3/sim_ask.py "Should I take an $8k/mo, 6-month contract if there's a 30% chance it overruns?"

标志：--n（模拟次数）、--seed、--save NAME（将配置保存到 domains/）、--show-config、--json、--model NAME、--backend。

Web

打开 http://localhost:8420，点击提问，输入问题并运行。你将获得通俗易懂的回答、关键数字、安全判定和生成的模型——还可以将其保存为可复用的领域配置。

API

使用 {"question": "...", "n_simulations": 3000, "seed": 42} 调用 POST /api/ask，返回 {config, results, explanation, attempts, valid}。

后端（环境变量）

变量	默认值	用途
SIMENGINE_LLM_BACKEND	ollama	ollama | openai | anthropic
SIMENGINE_LLM_MODEL	qwen2.5	模型名称
SIMENGINE_LLM_TIMEOUT	120	每次请求的秒数（本地模型运行较慢时请调高）
OPENAI_API_KEY / OPENAI_BASE_URL	—	兼容 OpenAI（也支持 llama.cpp / LM Studio / vLLM）
ANTHROPIC_API_KEY	—	Anthropic

仅用于决策支持和场景分析，不构成财务建议或交易信号。

---

数字的含义

运行模拟时，每项指标表示：

• Mean -- 所有模拟未来的平均值。
• Median -- 第 50 百分位数。一半的未来结果高于该值，另一半低于该值。
• P10 -- 悲观情形。只有 10% 的未来结果更差。
• P90 -- 乐观情形。只有 10% 的未来结果更好。
• Std -- 标准差。表示分布的宽度。
• CVaR(alpha) -- 最差 alpha% 未来结果的平均值。这是注重风险的决策者最关注的数字。

安全约束可直接转化为决策语言：

• 概率约束：“[metric] 低于／高于 [threshold] 的概率不得超过 [X]%。”
• CVaR 约束：“在最差的 [alpha]% 情景中，[metric] 的平均值必须至少为 [min_cvar]。”

---

文档

**刚开始了解 SimEngine？请从通俗易懂的指南开始。**指南介绍了 SimEngine 是什么、如何阅读结果、适用于哪些人、如何向他人解释，以及如何为自己的决策建模——无需任何背景知识。

同行评审报告和系统设计论文可按需提供。请联系维护者获取。

许可证

SimEngine 采用开放核心模式。

• 引擎、服务、内核、诊断工具、Rust 加速功能和领域库——Apache License 2.0。可免费使用、修改、可自托管、嵌入自己的产品，并依据该许可证条款重新分发。
• 托管的 SimEngine MCP 服务（由 OtrovertLabs 运营）——商业许可证。订阅层级涵盖托管服务、OAuth、持久化状态、SLA 和企业功能。

自行托管开源引擎始终免费，未来也将继续免费。商业许可证仅适用于托管服务，以及开源发行版中未包含的托管功能。

SimEngine 是 OtrovertLabs 的产品，由 Venture Horizon LLC 发布。

商业许可、企业咨询或合作事宜，请访问：https://otrovertlabs.com/contact