内容
金融规划实验室
[](https://github.com/jman4162/agentic-financial-planner-lab/actions/workflows/ci.yml)
[](https://pypi.org/project/planner-lab/)
[](LICENSE)
[](https://doi.org/10.5281/zenodo.213017一个实验性的、与的框架，用于构建的个人理财规划代理化的案例文件、确定性计算器、蒙特卡罗器、通过模型上下文协议研究，以及一个阻止任何溯到记录计算的备忘录的批评门。
**大型M）从数学运算。** 输出备每个美元数字都记录的计算器运行或案例文件字段，如果数字无法追记录的计算，批评者备忘录。这和教育项目：不是财务交易执行，无股票选择账户。示例仅使用合成参见[免责声明)）。
![验证、导入现金流命令的docs/assets/demo.gif)
**关键词：** 理财规划、度、蒙特卡LLM 代理、协议（MCP）、资金比率、安全提款率、个人理财、FIRE。
## LLM 仅在两个地方出现（备忘录草稿和语气审查）；其他所有内容都是确定性的、种子化的和可测试的。
```mermaid
flowchart TD
A[案例文件：类型化的家庭事实] --> B[假设门：<br/>基本 / 保守 / 乐观，<br/>由用户确认]
B --> C[确定性引擎]
C --> C1[计算器：<br/>资金比率，财务独立时间线]
C --> C2[蒙特卡罗模拟]
C --> C3[CEFR 健康指标]
C --> C4[分配诊断]
C1 --> D[(计算账本：<br/>每个结果都有一个可引)]
C2 --> D
C3 --> D
C4 --> D
E[MCP 研究来源：<br/>搜索 + 获取，已记录] --> D
D --> F[备忘录编写 LLM：<br/>草稿散文，仅引用<br/>账本菜单中的 ID]
F --> G{批评门：<br/>9 个确定性检查<br/>+ LLM 语气审查}
G -- 批准 --> H[规划备忘录<br/>+ 审计边车]
G -- 拒绝两次 --> I[硬故障：<br/>不发出备忘录]
```
## 比较
| | 电子表格 / DIY | 网络退休模拟器 | 通用 LLM 聊天 | 本项目 |
|---|---|---|---|---|
| 确定性、种子数学 | 是 | 是 | 否 | 是 |
| 用散文解释权衡 | 否 | 有限 | 是 | 是 |
| 每个数字可追溯到计算 | 手动 | 否 | 否 | 由批评者强制执行 |
| 引用的方法来源 | 手动 | 部分 | 制造风险 | 获取并验证 |
| 完全本地运行 | 是 | 否 | 罕见 | 是（Ollama） |
| 拒绝不可验证的输出 | 不适用 | 不适用 | 否 | 是 |
## 安装
需要 Python 3.11+。
```bash
pip install "planner-lab[agent]" # 从 PyPI
```
或从克隆版本开始：
```bash
uv sync --extra agent --extra dev
```
额外功能按设计是可选的。核心安装不需要任何代理框架；`agent` 添加了 Strands SDK（带有 Ollama 和 OpenTelemetry 支持），`mcp` 添加了用于研究来源的模型上下文协议客户端。
## 尝试
核心功能无需 LLM 即可离线工作：
```bash
uv run planner-lab validate examples/cases/sample_household.yaml
uv run planner-lab calc funded-ratio --portfolio 900000 --spending 50000
uv run planner-lab calc fi-timeline --portfolio 250000 --savings 50000 --spending 60000
```
在本地 [Ollama](https://ollama.com/) 服务器运行支持工具调用的模型拉取（默认 `qwen3`；使用 `OLLAMA_MODEL` 覆盖）：
# 完整流程：假设 -> 计算器 -> 录草稿 -> 批评门 -> 备忘录
uv run planner-lab memo examples/cases/sample_household.yaml -o memo.md --yes
# 添加卡罗模拟、资金度量和分配诊断
uv sync-extras
uv run planner-lab analyze examples/cases/sample --simulate --health --yes
# 将的方法论建立在服务器的引用指南ANNER_LAB_RECP_URL=https://example.com/mcp \
uv run memo examples/cases/sample_household.yaml -o memo.md --research
# 从预算应用 CSV 导出中导出年度（无需 LLM）
uv run planner-lab import-cashflow_transactions_monarch.csv \
--format monarch --case my_case.yaml --write
# 交互式问诊聊天，构建案例文件
uv run planner-lab intake -o my_case.yaml
# 代理 + 工具的最小示例
uv run python examples/hello_agent.py
```
备忘录命令写入 markdown 备忘录和 `.audit.json` 边车，持有完整的计算账本和批评者报告，因此每个数字都可以手动检查。如果批评者两次拒绝草稿，则不会写入备忘录，并且会打印失败的检查。
## 案例研究
完整的演练，附有真实生成的备忘录，原样记录：
- [一个正常的夫妇，全面的分析](docs/case-studies/on-track-couple.md)：模拟百分位，CEFR 健康指标，分配诊断和引用研究在一个运行中。
- [数据缺口和 CSV 导入](docs/case-studies/data-gaps-and-csv-import.md)：披露缺失数据，然后使用无 LLM 的交易导出部分填充。
- [被拒绝的备忘录](docs/case-studies/rejected-memo.md)：批评门抓住的内容，以及最坏的情况是没有备忘录而不是错误的内容。
## 运行过程
1. 加载并验证案例文件；记录重大缺口。
2. 显示基本、保守和乐观的假设集以供确认（`--yes` 非交互式接受）。费率是真实的，扣除通货膨胀。
3. 运行每个假设确定性计算器：资金比率、财务独立年、可持续支出。每个结果都记录在计算账本中，并附有 ID。
4. 可选地，蒙特卡罗引擎模拟每个集合（以及崩溃和序列风险压力测试），位于通用 `ScenarioSimulator` 接口后面。
5. LLM 草拟备忘录，仅引用给出的账本菜单中的数字。
6. 批评者运行八个确定性检查（可追溯性、无证券建议、免责声明、假设披露、数据披露、引用一致性、真实/名义确定性语言）以及 LLM 语气审查。尝试一次修订；然后运行失败。
## 配置
所有配置均通过环境变量完成；没有任何内容是硬编码的。
| 变量 | 目的 | 默认值 |
|---|---|---|
| `PLANNER_LAB_MODEL_PROVIDER` | `ollama` 或 `bedrock` | `ollama` |
| `OLLAMA_HOST` / `OLLAMA_MODEL` | 本地模型服务器和模型 ID | `http://localhost:11434` / `qwen |
| `PLANNER_LAB_BEDROCK_MODEL` | Bedrock 模型 ID（提供者 `bedrock`） | 提供者默认值 |
| `PLANNER_LAB_RESEARCH_MCP_URL` | 流式 HTTP MCP 服务器，暴露 和 `fetch`；启用 `--research 未设置 |
| `_EXPORTER_OTLP / `OTEL_EXPORTER_OTLP_HEADERS` | `setup_telemetry("otlp")`TLP 跟；`--trace` 将跨度打印到 未设置 |
小型本地模型偶尔会复制数字或引用；然后批评一次修订尝试后拒绝录，而不是发出备忘录。较大的模型（例如 `_MODEL=gpt-20b`）使、诊断和研究的完整运行更加可靠。
可选额外`agent`（LLM 流水线，Strands`planning`（蒙特卡罗模拟，资金`portfolio`（诊断），`mcp研究来源），`（测试，lint，核心安装没有任何额外功能 状态
有效的退休流程：案例文件模式计算器、批评备忘录渲染交互式问诊、卡罗模拟、确定性等效资金比率（CEFR）指标、生命周期分配MCP 研究引用和 CSV 现金流导入。有关架构规则，请参见 `CLA`。
## 引用
```bibtex
@software{hodge_agentic_planner_lab,
author 霍奇，约 title =entic-financial-planner一个可审计的代理框架},
year {2026},
{https://github.com/jman4162/agancial-planner-lab},
doi = {10.5281/zenodo.21301713},
version = {0.1.1},
license = {MIT}
}
```
## 许可证
MIT。教育用途；此处内容建议。
