Metadata-Version: 2.4
Name: angineer-docs-core
Version: 0.1.8
Summary: AnGIneer docs engine: parse pipeline (source_prep -> MinerU -> PoPo -> structure -> FTS -> vectors -> graph), retrieval and export
Author: AnGIneer Team
License: MIT
Project-URL: Repository, https://github.com/0mao0/angineer-docs-core
Project-URL: Issues, https://github.com/0mao0/angineer-docs-core/issues
Keywords: rag,document-parsing,retrieval,knowledge-base,mineru
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: angineer-tree-core<0.2.0,>=0.1.0
Requires-Dist: angineer-ai-inference<0.3.0,>=0.2.2
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: PyMuPDF==1.28.2
Requires-Dist: numpy>=1.24
Requires-Dist: python-dateutil>=2.8
Requires-Dist: tqdm>=4.60
Requires-Dist: openai>=1.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: pillow>=10.0
Requires-Dist: qdrant-client>=1.12
Provides-Extra: pg
Requires-Dist: psycopg[binary]>=3.2; extra == "pg"
Requires-Dist: pyarrow>=15.0; extra == "pg"
Provides-Extra: chroma
Requires-Dist: chromadb>=0.5.5; extra == "chroma"
Provides-Extra: text2sql
Requires-Dist: PyYAML>=6.0; extra == "text2sql"
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn>=0.30; extra == "server"
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == "api"
Requires-Dist: uvicorn>=0.30; extra == "api"
Requires-Dist: python-multipart>=0.0.6; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: fastapi>=0.115; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: python-multipart>=0.0.6; extra == "dev"
Dynamic: license-file

# angineer-docs-core

[![PyPI](https://img.shields.io/pypi/v/angineer-docs-core)](https://pypi.org/project/angineer-docs-core/)

AnGIneer 的文档解析入库引擎（纯 Python 库）：把工程规范 / PDF / Office 文档跑成
「**可读、可查、可算、可引用**」的知识库数据——一条管线覆盖
**源文件准备 → 格式转换 → MinerU 解析 → PoPo 强化 → 结构化 → 图描述 → SQLite+FTS → 向量索引 → 知识图谱**，
外加五路检索、text2sql 与产物导出。

| 能力 | 说明 | 靠什么 |
| :--- | :--- | :--- |
| 📖 可读 | 高保真解析 PDF，保留结构、公式、图表 | MinerU 端点（HTTP） |
| 🔍 可查 | 语义检索 + 表格精确查询 + 条款定位（五路召回 + 重排） | canonical 七表 + qdrant |
| 🧮 可算 | 公式语义、表格插值、条款计算（供上层工具消费） | 结构化的 canonical 产物 |
| 📎 可引用 | 条文 / 表格 / 图片的块级溯源 | `citation_targets` + 块 id |

> 定位：只做**数据面**（解析 / 建索引 / 图谱 / 检索），**不含网页端与管理台**；
> 独立部署需要 HTTP 服务面时，可选装薄壳：`[server]`（只读检索面 retrieval-api，见下）、
> `[api]`（解析面上传/续跑/产物下载，0.1.7 起，见下）。默认安装不含任何壳。
> 大算力全部在外部服务：版面解析、视觉结构强化、图描述、embedding、rerank 都走 HTTP 端点（配置见下）。

## 管线（9 个阶段 + 导出）

`hard` = 失败即中止；`soft` = 失败降级继续并在 `parse_stages` 留痕。

| # | 阶段 key | 名称 | 类型 | 依赖 | 做什么 |
| :-- | :--- | :--- | :--- | :--- | :--- |
| 1 | `source_prep` | 源文件准备 | hard | — | 落地源文件、登记文档节点、准备解析输入 |
| 2 | `convert` | 格式转换 | hard | source_prep | 非 PDF（doc/docx/xls…）经 LibreOffice 转 PDF |
| 3 | `raw_parse` | MinerU 解析 | hard | convert | 调 MinerU 端点（file_parse ZIP 协议），产出 markdown / 图片 / `middle.json` |
| 4 | `popo` | PoPo 强化 | **soft** | raw_parse | PoPo 做视觉结构强化，产出 enriched blocks（需 VLM 端点） |
| 5 | `structure` | 结构化 | hard | raw_parse | **Solo 是唯一构建者**；PoPo 信号只作为增强注入（对齐 / 合并 / 层级融合 / 续表） |
| 6 | `figure_describe` | 图描述 | soft | structure | VLM 描述图表内容（可关） |
| 7 | `fts` | SQLite + FTS | hard | structure | canonical 七表 + 全文索引（检索数据面） |
| 8 | `vectors` | 向量索引 | soft | fts | qdrant（默认）/ sqlite / chroma |
| 9 | `graph` | 知识图谱 | soft | structure | 实体与关系抽取入库 |

第 10 步是产物导出（`step10_export`：按册导 markdown / 图片 / 索引 / 图谱）。

## 安装

```bash
pip install angineer-docs-core
# 或钉版本
pip install "angineer-docs-core @ git+https://github.com/0mao0/angineer-docs-core.git@v0.1.1"
```

Python 要求 `>=3.10`。运行依赖：`angineer-tree-core`（树表底座）、`angineer-ai-inference`（LLM 客户端）、
`pydantic>=2`、`PyMuPDF`、`numpy`、`python-dateutil`、`qdrant-client`、`requests`、`python-dotenv`。
可选 extras：`[chroma]`（旧向量后端）、`[text2sql]`（领域关键词 YAML）、`[server]`（独立宿主薄壳 retrieval-api，见下）、`[api]`（独立宿主薄壳解析面 docs-api，见下）。

## 另有外部依赖（不随包提供）

| 依赖 | 用途 | 怎么配 |
| :--- | :--- | :--- |
| MinerU 端点 | 版面解析（GPU 大头） | `MINERU_CONFIGS` |
| PoPo 端点 | 视觉结构强化 | `POPO_CONFIGS` |
| 图描述端点 | 图表描述 | `FIGURE_DESCRIBE_CONFIGS` |
| embedding 端点 | 向量化 | `EMBEDDING_CONFIGS` |
| rerank 端点 | 重排 | `RERANKER_CONFIGS` |
| Qdrant | 向量库（默认 provider） | `QDRANT_URL`（也可换 sqlite / chroma） |
| LibreOffice | 非 PDF → PDF | 系统安装，`LIBREOFFICE_BIN` 或 PATH |

## 快速开始

```python
import os

os.environ["KNOWLEDGE_BASE_DIR"] = "/srv/knowledge"          # 数据根（也可用 ANGINEER_DATA_ROOT）
os.environ["MINERU_CONFIGS"] = '[{"name":"dgx","url":"https://your-gateway/api/mineru","api_key":"..."}]'
os.environ["POPO_CONFIGS"]   = '[{"name":"dgx","url":"https://your-gateway/api/popo/v1","api_key":"...","model":"Popo"}]'
os.environ["DOCS_VECTORSTORE_PROVIDER"] = "qdrant"
os.environ["QDRANT_URL"] = "http://localhost:6333"

from docs_core.parse_pipeline import ParseOrchestrator

orch = ParseOrchestrator()                                             # 不注入时用包内置的解析记录表
doc_id = orch.ensure_document("default", "/abs/path/spec.pdf")         # 登记文档节点
task = orch.create_parse_task("default", doc_id, "/abs/path/spec.pdf") # 后台线程跑全链
print(task["task_id"])

orch.get_parse_task(task["task_id"])     # 查进度 / 当前阶段
orch.cancel_parse_task(task["task_id"])  # 协作式取消
orch.retry_parse_task(doc_id)            # 失败重跑
```

- 阶段级重跑与校验：`STAGE_REGISTRY` / `resolve_stage_order` / `validate_stage_retry` / `compute_resume_stages`；
- 检索侧入口：`docs_core.step09_query`（五路召回 + 重排 + text2sql）；
- 知识库与节点管理：`docs_core.get_docs_service()` / `DocsService`。

## 独立宿主壳（retrieval-api · `[server]` extra）

只读检索服务的最小形态——薄壳只保留对外验收面，数据面全参数化、无仓库树依赖：

```bash
pip install "angineer-docs-core[server]"       # 只为此加装 fastapi/uvicorn
export ANGINEER_DATA_ROOT=/srv/angineer-data    # 数据根（或 KNOWLEDGE_BASE_DIR）
export DOCS_VECTORSTORE_PROVIDER=qdrant
export QDRANT_URL=http://localhost:6333
export ANGINEER_API_TOKEN='...'                 # 可选：开启后除 /health 外要求 X-API-Key / Bearer
uvicorn docs_core.server:app --host 127.0.0.1 --port 8310
```

> 注（2026-10-13 外部消费方实踩补）：**env 必须由启动器注入子进程**——壳不读进程 cwd 的 `.env`
> （包内 `load_dotenv()` 探测起点是包的安装目录，wheel 装在 site-packages 时碰不到你项目根的 `.env`，
> 能否碰到随 venv 摆放而变、不可依赖）。漏注入可能表现为数据根 / 向量库解析失败（500）或能力静默
> 降级；启动后先核 `/health` 的 data_root / registry 两行。

| 端点 | 说明 |
| :--- | :--- |
| `POST /api/knowledge/internal/retrieve` | 五路召回融合检索（snake_case 线契约，与主仓库内部服务逐位一致） |
| `POST /api/knowledge/internal/entity-search` | 图谱实体检索 |
| `GET /api/knowledge/internal/doc-nodes` | 文档节点清单（对话侧 `load_nodes` 数据源） |
| `POST /api/knowledge/internal/normalize-query` · `/internal/rerank` · `/internal/relevant-citations` · `/internal/table-blocks` · `/internal/engtool-run` | engine 端口 HTTP 面（条款号归一化 / phrase rerank / 引用挑选 / 表格块 / 外部工具执行）——chat 壳 `http_ports` 适配器消费；与主仓库 docs-api 同挂 |
| `GET /api/knowledge/libraries` | 库清单 |
| `GET /api/knowledge/stats` | 统计聚合（`knowledge_stats` 工具数据源；与主仓库 docs-api 同一实现） |
| `GET /api/knowledge/documents/{doc_id}/download` | 原文回源（`?kind=source\|pdf`、`?disposition=inline` 内联呈示） |
| `GET /health` | 探活：数据根 / 注册表挂载状态 + 向量库配置形态 |

上传 / 解析 / 迁移 / 导出仍是库调用（`ParseOrchestrator` 等），不在检索壳内；解析走下面的解析面壳。

## 解析面壳（docs-api · `[api]` extra，0.1.7 起）

解析服务的最小形态——上传、断点续跑、状态轮询、产物下载。落盘与派生索引按 `KB_STACK`
档位（legacy=SQLite / pg=PostgreSQL+pgvector，与检索壳同一套 env）；解析面写完派生层，
同 env 启动的检索面/编排面**立即可检索引用，无需同步**。

```bash
pip install "angineer-docs-core[api]"
export ANGINEER_DATA_ROOT=/srv/angineer-data       # 数据根（文件层 + 派生索引都挂它下面）
export MINERU_CONFIGS='[{"name":"dgx","url":"https://your-gateway/api/mineru","api_key":"..."}]'
export KB_STACK=pg                                  # 可选：PostgreSQL 档（配 KNOWLEDGE_PG_DSN）
export DOCS_API_STATIC_KEYS='key1,key2'             # 静态 API Key（逗号分隔）
uvicorn docs_core.docs_api:app --host 127.0.0.1 --port 8312
```

- **鉴权**：`/api/v1/*` 强制 `X-API-Key` 头；静态键命中即放行、视作未绑定库的键
  （不注入也不限制 `library_id`，调用方显式传库，不传落 `default`）。
  未配置 `DOCS_API_STATIC_KEYS` 时所有请求 401/403（与宿主无效键行为一致）。
- **就绪判定**：`GET /health` 返回 200 + `{service, started_at, pid, status}`；
  配置漂移或向量守卫异常时 `status=degraded` 并带 `config_errors`——**消费方按 body 判就绪，不是只看状态码**。
- **env 注入**：与检索壳同口径——壳不读进程 cwd 的 `.env`，启动器必须显式注入子进程 env。
- **单实例守卫（可选）**：`python -m docs_core.docs_api` 入口 + `DOCS_API_SINGLE_INSTANCE_GUARD=1`
  启动前探 `/health` 拒绝重复启动；`uvicorn` 直起不跑守卫（进程唯一性由调用方启动器保证）。

| 端点 | 说明 |
| :--- | :--- |
| `POST /api/v1/documents/parse?stages=all` | multipart `file` 上传解析；响应 `{doc_id, task_id, status}`；`stages=all` 全链，也可传截断阶段（只产文件层，不写派生索引，属正常用法） |
| `POST /api/v1/documents/{doc_id}/resume` | 断点续跑：已完成阶段保留；进行中 409 |
| `GET /api/v1/documents/{doc_id}/status` | `{status, progress, stage, stage_message, error}`；status ∈ `queued/processing/completed/failed/cancelled/partial` |
| `GET /api/v1/documents/{doc_id}/artifacts` | `{items:[{name,url}]}`；含 `doc_blocks_graph.jsonl(+meta)`、`content.md`、`images.zip`（有图时）等 |
| `GET /api/v1/documents/{doc_id}/artifacts/{name}` | 产物字节流 |
| `GET /api/v1/documents/{doc_id}/pdf` | 原始/转换后 PDF（输入即 PDF 时 404=用户已有源文件） |
| `GET /api/v1/documents/{doc_id}/blocks` / `/content` | 块清单（页面/类型过滤）与 markdown 全文 |
| `DELETE /api/v1/documents/{doc_id}` | 幂等软删：不存在返回 404，调用方按成功处理 |
| `GET /health` | 探活（见上） |

解析面不提供：知识库管理面、用户/会话/键管理（宿主网页端诉求）；R4 两点 PG 档结论见
CHANGELOG 0.1.7（FTS 落地方式 + 首连建表 DDL 覆盖范围）。

## 配置（常用）

| 变量 | 默认 | 说明 |
| :--- | :--- | :--- |
| `KNOWLEDGE_BASE_DIR` | — | **数据根（最高优先）**：元库 / 索引 / 图谱 / 文档目录都挂它下面 |
| `ANGINEER_DATA_ROOT` | — | 数据根（次优先，取 `<root>/knowledge`） |
| `ANGINEER_REPO_ROOT` | 仓库标记探测 | 仓库树根。独立安装（wheel）里没有仓库树，需要数据根请显式给上面两个之一 |
| `MINERU_CONFIGS` / `POPO_CONFIGS` / `FIGURE_DESCRIBE_CONFIGS` / `EMBEDDING_CONFIGS` / `RERANKER_CONFIGS` | — | JSON 数组，顺序=优先级，第一项为默认；连接失败/超时自动切下一项 |
| `DOCS_VECTORSTORE_PROVIDER` | —（必填） | `qdrant` / `sqlite` / `chroma`；不设会直接报错（防静默连空库） |
| `QDRANT_URL` | — | `provider=qdrant` 时必填 |
| `LIBREOFFICE_BIN` | PATH 探测 | `soffice` 路径（非 PDF 输入必需） |
| `POPO_MAX_CONCURRENCY` | 4 | PoPo 强化的并发闸（FIFO 排队） |
| `FIGURE_DESCRIBE_ENABLED` | 见 `.env.example` | 图描述开关 |

## 包里包含什么

- **`docs_core`**：管线与数据面本体（9 阶段、canonical 存储、五路检索、图谱、导出；
  `docs_api` / `server` 薄壳随 extras）；
- **PoPo 不随包**（0.1.5 起 wheel 不再内嵌 popo fork）：PoPo 视觉强化走独立客户端
  `popo-client`（dgx-spark-popo 公开仓）或服务端文档级 API（`POPO_CONFIGS`）；
  缺失也不报错——第 4 步按「软阶段」跳过，结构由 Solo 单独构建（质量降级、链路不断）。
- 依赖 **`angineer-tree-core`** 与 **`angineer-ai-inference`**，pip 会自动带上。

## 目录结构

```text
services/docs-core/
├── src/
│   ├── docs_core/
│   │   ├── paths.py                 # 布局：数据根 + 文档目录（纯路径计算，无 IO 副作用）
│   │   ├── docs_service.py          # 门面：知识库/节点/任务落库与查询的统一入口
│   │   ├── parse_pipeline.py        # 阶段注册 / 顺序 / 状态机 / 编排器
│   │   ├── models/                  # 全管线共享契约（canonical 七表类型等）
│   │   ├── step01_source_prep/      # 源文件准备
│   │   ├── step02_convert2pdf/      # LibreOffice 转 PDF
│   │   ├── step03_mineru_parse/     # MinerU 解析 + PoPo 强化（popo_enhance）
│   │   ├── step04_structure/        # Solo 结构构建 + PoPo 信号消费（popo/ 六件套）
│   │   ├── step05_sqlite_fts/       # canonical SQLite + FTS（rebuild / store）
│   │   ├── step06_vectors/          # 向量索引（qdrant / sqlite / chroma + embedding 客户端）
│   │   ├── step07_graph/            # 知识图谱（实体 / 关系 / 证据包）
│   │   ├── step08_maintain/         # 巡检与维护
│   │   ├── step09_query/            # 检索（五路召回）、text2sql、对外协议
│   │   ├── step10_export/           # 产物导出
│   │   ├── docs_api/                # [api] 解析面薄壳（上传/续跑/产物/health，0.1.7 起）
│   │   └── library_registry.py / parse_records_store.py / kb_migrator.py …
├── tests/                           # 88 个测试文件 / 500+ 用例
└── pyproject.toml
```

## 不在本库范围

- 网页端与管理台（主仓库 docs-api 宿主实现；`[server]`/`[api]` extra 仅提供检索/解析两个薄壳）；
- MinerU / PoPo / VLM / embedding / rerank 的推理服务本身；
- 知识库数据的业务展示与权限。

## 开发与测试

```bash
pip install -e ".[dev]"
python -m pytest tests -q
```

独立环境（无仓库树、无 `.env`）也能跑：`tests/conftest.py` 会先按 dotenv 规则加载 `.env`（若有），
再补缺省 —— 向量后端用 `sqlite`、数据根指向临时目录；跨服务用例（需要 docs-api）自动跳过。
当前基线：**516 passed, 16 skipped**（无外部服务、无网络）。

## 许可

MIT
