# 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 8002 --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 返回固定占位数据，不调模型

推荐使用阿里云百炼 OpenAI 兼容模式（北京）：

- Base URL：`https://dashscope.aliyuncs.com/compatible-mode/v1`
- 文本生成模型（示例）：`qwen-plus`
- 向量模型（示例）：`text-embedding-v3`
- OCR 解析模型（示例）：`qwen-vl-ocr`

本项目已支持三类模型独立配置（均为 OpenAI 兼容 HTTP）：

- 文本生成：`FINREP_LLM_*`
- 向量 Embedding：`FINREP_EMBEDDING_*`
- OCR 解析：`FINREP_OCR_*`

如果三类模型共用同一个 API Key，可只填 `FINREP_LLM_API_KEY`；代码会在 Embedding/OCR 侧自动回退复用。

## 如何获取阿里云百炼 API Key

1. 进入阿里云百炼控制台（Model Studio）。
2. 开通并进入对应地域（建议与你部署环境一致）。
3. 在「API-KEY」或「密钥管理」页面创建 Key。
4. 复制 Key 填入 `.env` 的 `FINREP_LLM_API_KEY`（或分别填到 `FINREP_EMBEDDING_API_KEY`、`FINREP_OCR_API_KEY`）。
5. 重启服务使新环境变量生效。

参考文档：

- [OpenAI 兼容模式调用千问](https://www.alibabacloud.com/help/zh/model-studio/compatibility-of-openai-with-dashscope)
- [OpenAI 兼容方式调用千问视觉模型](https://www.alibabacloud.com/help/zh/model-studio/qwen-vl-compatible-with-openai)

## 联调

- `GET http://localhost:8002/health`
- `POST http://localhost:8002/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`，与需求文档摘录保持一致，后续仅以改模板版本迭代。