# finrep-algo-agent

Python 算法服务骨架：健康检查、`/v1/outline/l1|l2`、`/v1/section` 占位实现，便于与 Java `pythonagent` 联调。

## 本地运行

```bash
cd algo
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
uvicorn finrep_algo_agent.main:app --reload --host 0.0.0.0 --port 8001 --app-dir src
```

## 环境变量

复制 `env.example` 为 `.env`（可选）。主要项：

- `FINREP_LLM_BASE_URL`：OpenAI 兼容网关地址，如 `https://api.openai.com/v1`
- `FINREP_LLM_API_KEY`：密钥
- `FINREP_LLM_MODEL`：模型名
- `FINREP_STUB_SKILLS=true`：为 `true` 时 L1/L2/Section 返回固定占位数据，不调模型

## 联调

- `GET http://localhost:8001/health`
- `POST http://localhost:8001/v1/outline/l1`（JSON 见 `schemas`）

## 与《MVP 需求文档》对齐的交互字段

- **一级大纲 `POST /v1/outline/l1`**：请求体与需求文档「报告背景信息」「一级章节候选清单」一致：`report_type`、`agreement_amount`、`enterprise_type`、`group_business_segments`、`industry_type`、`has_independent_report`、`independent_report_types`、`candidate_financing_tools`、`recommended_financing_tools`、`other_requirements`、`chapter_candidates`（每项可含除 `chapter_id`/`chapter_name` 外的扩展字段，如重要性、适用条件，将原样写入清单文本供模型使用）。
- **二级大纲 `POST /v1/outline/l2`**：除 `chapter_name`、`chapter_no`、`chapter_paragraph_count_enum`、`leaf_chapter_candidates` 外，需传入与需求文档「已确定的上游约束」「整体写作逻辑说明」对齐的 **`chapter_reason`**（一级该章 `reason`）、**`overall_logic`**（一级 `overall_logic`）。**报告背景**推荐整块传入 **`l1_task_snapshot`**（与 L1 请求同结构的 `OutlineL1Request`）；若不传，则使用本请求上的扁平字段（`report_type`、`agreement_amount` 等）拼背景。
- **段落生成 `POST /v1/section`**：`template_type` 取值 `info` / `analysis` / `metric` / `judgment` 对应需求文档四类模板；`overall_logic`、`chapter_logic`、`paragraph_position`、`task_input`、`data_package`、`paragraph_logic` 对应模板中「橙/蓝」占位；`example`、`notes` 对应「示例」「其他注意事项」。

提示词正文位于 `src/finrep_algo_agent/prompts/templates/*.j2`，与需求文档摘录保持一致，后续仅以改模板版本迭代。