# finrep-algo-agent HTTP 接口说明

本文档与当前代码实现一致，描述 **finrep-algo-agent**（FastAPI）对外暴露的全部 HTTP 接口。

- **服务标题**：`finrep-algo-agent`（见 `finrep_algo_agent.main:app`）
- **版本**：`0.1.0`（见 `finrep_algo_agent.__version__`）
- **机器可读契约**：服务启动后访问 **`GET /openapi.json`**；交互式文档 **`GET /docs`**（Swagger UI）

默认本地启动示例（端口以实际为准，README 中为 `8002`）：

```text
http://127.0.0.1:8002
```

---

## 1. 环境与运行模式

### 1.1 环境变量前缀

所有配置以 **`FINREP_`** 为前缀，可由环境变量或 **`algo/.env`** 注入（见 `config/settings.py`）。

与接口行为相关的常用项：

| 变量 | 说明 |
|------|------|
| `FINREP_STUB_SKILLS` | `true` 时：`/v1/outline/*`、`/v1/section` **不调用 LLM**，返回占位数据；`false` 时走真实模型 |
| `FINREP_LLM_API_KEY` | 文本生成密钥；**Embedding 未单独配置时会回退使用该密钥** |
| `FINREP_LLM_BASE_URL` / `FINREP_LLM_MODEL` / `FINREP_LLM_TIMEOUT_SECONDS` | 文本模型网关 |
| `FINREP_EMBEDDING_API_KEY` | 向量模型密钥（可空，回退 `FINREP_LLM_API_KEY`） |
| `FINREP_EMBEDDING_BASE_URL` / `FINREP_EMBEDDING_MODEL` / `FINREP_EMBEDDING_TIMEOUT_SECONDS` | 向量模型 |
| `FINREP_OCR_API_KEY` | OCR 密钥（可空，回退 `FINREP_LLM_API_KEY`） |
| `FINREP_OCR_BASE_URL` / `FINREP_OCR_MODEL` / `FINREP_OCR_TIMEOUT_SECONDS` | OCR 模型 |
| `FINREP_RAG_CHUNK_SIZE` | RAG 分块字符数近似上限 |
| `FINREP_RAG_CHUNK_OVERLAP` | 分块重叠字符数 |
| `FINREP_RAG_DEFAULT_TOP_K` | 检索默认 `top_k`（请求未传 `top_k` 时使用） |
| `FINREP_RAG_EMBEDDING_BATCH_SIZE` | 单次向量化批大小 |

`FINREP_SERVICE_TOKEN` 已在配置中预留，**当前路由层未做统一鉴权校验**；若需服务间鉴权，由网关或后续中间件实现。

### 1.2 RAG 存储

RAG 索引使用进程内 **`InMemoryRagStore`**（按 `task_id` 隔离）。**服务重启后数据清空**；多 Worker 各进程索引不共享。

---

## 2. 统一约定

### 2.1 Content-Type

- JSON 接口：`Content-Type: application/json`
- 文件入库：`multipart/form-data`（见 `/v1/rag/ingest-files`）

### 2.2 常见 HTTP 状态码

| 状态码 | 场景 |
|--------|------|
| 200 | 成功 |
| 400 | 配置缺失（如未配置密钥） |
| 422 | 请求体验证失败，或业务侧 `ValueError`（大纲/段落技能、RAG 参数等） |
| 502 | RAG 向量化或检索过程中未捕获的下游异常，包装为业务可读 `detail` |

---

## 3. 接口总览

| 方法 | 路径 | 标签 / 说明 |
|------|------|----------------|
| GET | `/health` | 健康检查 |
| GET | `/debug/runtime` | 当前运行配置快照（非敏感） |
| GET | `/debug/llm` | 探测 LLM 连通性 |
| GET | `/debug/embedding` | 探测 Embedding 连通性 |
| GET | `/debug/ocr` | 探测 OCR（需 query `image_url`） |
| POST | `/v1/outline/l1` | 一级大纲 |
| POST | `/v1/outline/l2` | 二级 / 末级结构（单章） |
| POST | `/v1/section` | 单知识单元段落生成 |
| POST | `/v1/rag/ingest-files` | 上传文件 → 解析 → 分块 → 入库 |
| POST | `/v1/rag/ingest` | 纯文本文档入库 |
| POST | `/v1/rag/retrieve` | 向量相似度检索 |
| DELETE | `/v1/rag/{task_id}` | 删除某任务下 RAG 索引 |

---

## 4. 健康检查

### `GET /health`

**响应体**（`application/json`）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | string | 固定为 `ok` |
| `service` | string | 固定为 `finrep-algo-agent` |
| `version` | string | 包版本，如 `0.1.0` |

**示例**：`{"status":"ok","service":"finrep-algo-agent","version":"0.1.0"}`

---

## 5. 调试接口

### `GET /debug/runtime`

返回当前有效配置摘要（不含 API Key）。

| 字段 | 类型 | 说明 |
|------|------|------|
| `stub_skills` | boolean | 是否占位技能模式 |
| `llm_model` | string | 文本模型名 |
| `embedding_model` | string | 向量模型名 |
| `ocr_model` | string | OCR 模型名 |
| `rag_defaults` | object | `chunk_size`、`chunk_overlap`、`top_k`、`embedding_batch_size` |

---

### `GET /debug/llm`

调用一次短对话，验证 **`FINREP_LLM_API_KEY`** 与网关可用。

- **400**：`FINREP_LLM_API_KEY` 未配置

**响应体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `model` | string | 当前 LLM 模型名 |
| `base_url` | string | LLM base_url |
| `text_sample` | string | 模型回复截断至约 200 字符 |

---

### `GET /debug/embedding`

调用一次 Embedding，验证 **`FINREP_EMBEDDING_API_KEY` 或 `FINREP_LLM_API_KEY`**。

- **400**：上述两者均未配置

**响应体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `model` | string | 当前 embedding 模型名 |
| `base_url` | string | embedding base_url |
| `dim` | integer | 向量维度 |
| `head` | array | 向量前 8 维 |

---

### `GET /debug/ocr`

**Query 参数**（必填）：

| 参数 | 类型 | 说明 |
|------|------|------|
| `image_url` | string | 可公网或可访问的图片 URL |

验证 **`FINREP_OCR_API_KEY` 或 `FINREP_LLM_API_KEY`**。

- **400**：上述两者均未配置

**响应体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `model` | string | OCR 模型名 |
| `base_url` | string | OCR base_url |
| `text_sample` | string | 识别文本截断至约 400 字符 |

---

## 6. 一级大纲

### `POST /v1/outline/l1`

**Content-Type**：`application/json`

**请求体**：`OutlineL1Request`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `report_type` | string | 是 | 报告类型，如「项目融资」「资产管理」「并购重组」 |
| `task_id` | string | 否 | 任务 ID |
| `tenant_id` | string | 否 | 租户 ID |
| `agreement_amount` | number / string | 否 | 协议金额（`Decimal`，JSON 中可用数字或字符串） |
| `enterprise_type` | string | 否 | 企业类型 |
| `group_business_segments` | string[] | 否 | 集团板块名称列表 |
| `industry_type` | string | 否 | 行业类型 |
| `has_independent_report` | boolean | 否 | 是否存在独立调查报告 |
| `independent_report_types` | string[] | 否 | 独立报告类型列表 |
| `candidate_financing_tools` | string[] | 否 | 拟分析融资工具 |
| `recommended_financing_tools` | string[] | 否 | 拟最终推荐融资工具 |
| `other_requirements` | string | 否 | 其他要求 |
| `chapter_candidates` | object[] | 否 | 一级章节候选；**非空时覆盖模板内嵌候选**。每项至少含 `chapter_id`、`chapter_name`；**允许任意扩展字段**（原样进入提示词） |

`chapter_candidates` 每项结构（`ChapterCandidate`）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `chapter_id` | string | 章节 ID（须与模型输出一致，不可改写） |
| `chapter_name` | string | 章节名称（同上） |
| （其他键） | 任意 | 扩展属性，如重要性、适用条件等 |

**响应体**：`OutlineL1Response`

| 字段 | 类型 | 说明 |
|------|------|------|
| `chapter_results` | array | 与候选 **数量、顺序一致**（若请求传了非空 `chapter_candidates`）；每项见下表 |
| `overall_logic` | string | 全篇结构逻辑说明 |

`chapter_results` 每项（`ChapterL1Result`）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `chapter_id` | string | 须与输入候选一致 |
| `chapter_name` | string | 须与输入候选一致 |
| `presentation_enum` | string | `S1` 独立呈现 / `S2` 不呈现 |
| `paragraph_count_enum` | string | `P0`～`P4`；**`S2` 必须为 `P1`；`S1` 不可为 `P0`**（服务端校验） |
| `reason` | string | 判断理由 |

**业务校验**（非空 `chapter_candidates` 时，见 `skills/outline_l1/outline_l1.py`）：

- `len(chapter_results)` 必须等于 `len(chapter_candidates)`
- 每条 `chapter_id`、`chapter_name` 必须与对应候选完全一致  
不满足则 **422**

**`FINREP_STUB_SKILLS=true`**：不请求 LLM，返回固定占位结构。

---

## 7. 二级大纲（单章）

### `POST /v1/outline/l2`

**Content-Type**：`application/json`

一次请求只生成 **一个一级章** 下的末级结构；完整报告需对多个一级章分别调用并由编排方合并。

**请求体**：`OutlineL2Request`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `chapter_name` | string | 是 | 一级章名称 |
| `chapter_no` | string | 是 | 一级章编号（展示/排序用） |
| `l1_chapter_id` | string | 否 | L1 的 `chapter_id`，用于模板分支匹配内置末级清单 |
| `chapter_paragraph_count_enum` | string | 否 | L1 该章 `paragraph_count_enum` |
| `chapter_presentation_enum` | string | 否 | L1 该章 `presentation_enum`（`S1`/`S2`） |
| `chapter_reason` | string | 否 | L1 该章 `reason` |
| `overall_logic` | string | 否 | L1 返回的 `overall_logic` |
| `leaf_chapter_candidates` | object[] | 否 | 末级候选覆盖列表；空则走模板内置分支 |
| `l1_task_snapshot` | object | 否 | 与 **`OutlineL1Request` 同结构** 的快照，用于拼报告背景 |
| `report_type` | string | 否 | 可与 `l1_task_snapshot` 二选一或同时提供 |
| `agreement_amount` 等 | 同 L1 扁平字段 | 否 | 无 `l1_task_snapshot` 时可用于拼背景 |
| `l1_context` | object | 否 | 额外上下文 |

**响应体**：`OutlineL2Response`

| 字段 | 类型 | 说明 |
|------|------|------|
| `chapter_name` | string | 须与请求一致（真实模式下模型若不一致会 422） |
| `chapter_no` | string | 须与请求一致 |
| `chapter_structure` | array | 末级节点列表（`ChapterStructureNode`） |
| `structure_logic` | string | 结构逻辑说明 |

`ChapterStructureNode`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `node_id` | string | 节点 ID |
| `node_name` | string | 节点名称 |
| `node_no` | string | 编号 |
| `node_level` | integer | 层级 |
| `parent_node_id` | string / null | 父节点 ID |
| `source_type` | string / null | 来源类型 |
| `source_candidate_name` | string / null | 候选名 |
| `is_selected` | boolean | 默认 `true` |

**`chapter_presentation_enum = S2` 时的服务端约束**：

- 解析成功后若 `chapter_structure` **非空**，抛出 `ValueError` → **422**  
- **Stub 模式**下对 `S2` 会直接返回 **空** `chapter_structure`

**`FINREP_STUB_SKILLS=true`**：不请求 LLM；`S1` 返回占位节点，`S2` 返回空结构。

---

## 8. 段落生成

### `POST /v1/section`

**Content-Type**：`application/json`

**请求体**：`SectionRequest`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `knowledge_unit_id` | string | 是 | 知识单元 ID |
| `template_type` | string | 是 | `info` / `analysis` / `metric` / `judgment`（非法值 → 422） |
| `task_id` | string | 否 | RAG 召回、`task_id` 隔离用 |
| `tenant_id` | string | 否 | 租户 ID |
| `report_type` | string | 否 | 报告类型 |
| `paragraph_logic` | string | 否 | 撰写逻辑 |
| `paragraph_position` | string | 否 | 段落定位 |
| `overall_logic` | string | 否 | 全篇逻辑 |
| `chapter_logic` | string | 否 | 章逻辑 |
| `task_input` | object | 否 | 任务级输入 |
| `data_package` | object | 否 | 数据包（召回结果会合并进来） |
| `example` | string | 否 | 示例 |
| `notes` | string | 否 | 备注 |
| `rag_recall` | boolean | 否 | 默认 `false`；`true` 时需 `task_id` 且已配置 embedding/llm key |
| `rag_query` | string | 否 | 召回查询；空则拼接 `paragraph_position`、`paragraph_logic`、`knowledge_unit_id` |
| `rag_top_k` | integer | 否 | 传给 RAG；空则使用服务默认 `rag_default_top_k` |
| `rag_min_score` | number | 否 | 相似度下限，低于则过滤 |

**响应体**：`SectionResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `generated_text` | string | 生成正文 |
| `usage` | object | `TokenUsage`：`prompt_tokens`、`completion_tokens`（当前实现多为 0） |

**`rag_recall=true`** 时：先 `retrieve`，将结果写入 `data_package["rag_recall"]`（含 `query`、`hits`、`formatted_context`），再渲染模板并调用 LLM。

**`FINREP_STUB_SKILLS=true`**：不请求 LLM，返回占位正文。

---

## 9. RAG

基路径：`/v1/rag`（路由前缀见 `main.py`）

入库与检索均需 **`FINREP_EMBEDDING_API_KEY` 或 `FINREP_LLM_API_KEY`**；否则对应接口 **400**。

### `POST /v1/rag/ingest-files`

**Content-Type**：`multipart/form-data`

| 表单字段 | 类型 | 必填 | 说明 |
|----------|------|------|------|
| `task_id` | string | 是 | 任务 ID，索引按任务隔离 |
| `replace` | boolean | 否 | 默认 `true`；`true` 时替换该任务已有块；`false` 时在原索引上追加 |
| `files` | file[] | 是 | 至少一个文件；支持常见文本及 PDF（见 `rag/ingestion/file_extract.py`） |

**行为概要**：逐文件读 bytes → 抽取文本 → 有文本的合并为 `RagDocumentIn` → 调用与 `/ingest` 相同的分块与向量化逻辑。

- **400**：未配置密钥  
- **422**：`files` 为空；或全部文件无有效文本  
- **502**：向量化异常  

**响应体**：`RagIngestFilesResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID |
| `document_count` | integer | 成功参与入库的文档数 |
| `chunk_count` | integer | 写入的向量块数量 |
| `files` | array | 每文件处理结果 `RagFileProcessResult` |

`RagFileProcessResult`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `filename` | string | 文件名 |
| `doc_id` | string | 派生文档 ID |
| `characters` | integer | 抽取字符数 |
| `skipped` | boolean | 无有效文本时为 `true` |
| `warning` | string / null | 解析警告 |

---

### `POST /v1/rag/ingest`

**Content-Type**：`application/json`

**请求体**：`RagIngestRequest`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_id` | string | 是 | 任务 ID |
| `tenant_id` | string | 否 | 租户（预留） |
| `documents` | array | 是 | 至少 1 条 `RagDocumentIn` |
| `replace` | boolean | 否 | `true` 覆盖任务索引，`false` 追加 |

`RagDocumentIn`：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `doc_id` | string | 是 | 任务内文档唯一标识 |
| `title` | string | 否 | 标题 |
| `text` | string | 是 | 待切分全文 |
| `source_label` | string | 否 | 来源展示名 |
| `page_start` | integer | 否 | 起始页 |
| `page_end` | integer | 否 | 结束页 |

若所有文档切分后无块且 `replace=true`，仍会清空该任务索引并返回 `chunk_count=0`（见 `RagService.ingest`）。

**响应体**：`RagIngestResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 任务 ID |
| `document_count` | integer | 文档条数 |
| `chunk_count` | integer | 块数量 |

---

### `POST /v1/rag/retrieve`

**Content-Type**：`application/json`

**请求体**：`RagRetrieveRequest`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_id` | string | 是 | 任务 ID |
| `tenant_id` | string | 否 | 租户（预留） |
| `query` | string | 是 | 查询句，**最小长度 1** |
| `top_k` | integer | 否 | 返回条数上限；**未传时使用 `FINREP_RAG_DEFAULT_TOP_K`**，且服务端会将 `k` 约束为 **≥1** |
| `min_score` | number | 否 | 最小相似度；未传则不过滤 |

**响应体**：`RagRetrieveResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `hits` | array | `RagHit` 列表 |
| `formatted_context` | string | 拼接后的引用上下文文本 |

`RagHit`：

| 字段 | 类型 | 说明 |
|------|------|------|
| `chunk_id` | string | 块 ID |
| `text` | string | 块文本 |
| `score` | number | 余弦相似度 |
| `doc_id` | string | 文档 ID |
| `title` | string | 标题 |
| `source_label` | string | 来源 |
| `chunk_index` | integer | 块序号 |
| `page_start` / `page_end` | integer / null | 页码 |
| `extra` | object | 扩展 |

任务无索引时返回 **空** `hits` 与空的 `formatted_context`（不报错）。

**502**：检索或 embedding 异常。

---

### `DELETE /v1/rag/{task_id}`

**路径参数**：`task_id` — 要删除索引的任务 ID。

**响应体**：`RagDeleteResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `task_id` | string | 与路径一致 |
| `deleted` | boolean | 删除前该任务**是否已有块**；无数据时为 `false` |

---

## 10. 文档维护说明

若接口或 Schema 发生变更，请同步更新：

- 本文档：`algo/docs/API.md`
- 运行时契约：以 **`/openapi.json`** 为准（由 FastAPI 自 Pydantic 模型生成）