# 药研资料与法规变更助手

这是一个单机开源工具，处理两类经常需要反复核对的工作：

- 按主题查询 ClinicalTrials.gov 和 PubMed，整理成可逐条取舍的研发资料；
- 比较两版文件，并从用户上传的内部文件中找出待复核条款。

程序负责查询、去重、文字差异和原文定位。摘要、候选关联和最终报告都要经过人工确认。它不判断药物是否安全有效，也不作正式法规解释或合规认定。

![待处理页面](docs/screenshots/dashboard-projects.jpg)

## 快速启动

需要 Docker Desktop 或兼容的 Docker 环境。

```bash
docker compose up --build -d
```

打开 `http://127.0.0.1:8000`。服务只绑定本机地址，因为当前版本没有登录和多用户权限。

首页可以创建正式任务，也可以从“载入示例任务”进入一套合成资料。两者严格分开：

- 正式研发任务访问用户勾选的公开接口；
- 示例任务只读取仓库内的合成文件，不访问外部接口；
- 法规初筛任务只处理用户上传的文件。

停止服务：

```bash
docker compose down
```

## 使用流程

### 整理公开研发资料

新建任务时可填写主题、疾病、干预方式、国家、招募状态和日期范围，并选择 ClinicalTrials.gov、PubMed 或同时查询两者。高级选项会显示即将发送给公开接口的实际查询参数，但隐藏邮箱和接口密钥。

系统保存每个来源的耗时、结果数、重试次数和错误。一个来源失败时，另一个来源的结果仍可继续审核；两个来源都失败时，运行会明确标为失败。

审核页分为资料列表、可编辑摘要和原始资料。试验阶段、招募状态、申办方、发表日期等字段来自公开接口，不由模型重新判断。只有“收录”的资料才会写入报告。

![研发资料审核](docs/screenshots/research-evidence-review.jpg)

### 法规版本变化与内部文件初筛

上传旧版本、新版本和最多五份待排查的内部文件。支持 Markdown、纯文本和带文字层的 PDF；单文件不超过 10 MB，单次上传合计不超过 30 MB。

程序先按条款编号和文字相似度对齐文件，再标出增加、删除和修改的文字。第三栏显示可能相关的内部文件条款，默认不勾选。用户可以保留变化但不建立文件关联，也可以只选择已经核对过的候选。报告不会带入未勾选的文件。

![法规版本变化与内部文件初筛](docs/screenshots/regulatory-three-column.jpg)

这项功能可以作为企业内部提效原型，用来验证三件事：程序能否减少逐页比较的时间，候选条款能否缩小内部文件排查范围，统一的审核记录能否减少报告整理和返工。它目前只做初筛，法规解释、实际影响判断和文件修改仍由法规、质量及文件负责人完成。

企业试点时可选择 5 至 10 次已经结束的文件更新进行历史回放。先记录人工处理的参与人数、用时、实际修改文件和审核退回原因，再比较程序的变化检出率、候选文件召回率、误报数量、人工修改率和初筛用时。历史回放达到约定标准后，再进入影子运行；程序与现有流程并行，不影响正式审批。如果高影响变化出现漏检，或人工核对时间没有下降，应先改进解析和检索，暂不扩大使用范围。

### 导出报告

报告只读取人工收录或保留的条目，可导出 Markdown、HTML 和 PDF。每条内容保留原文位置、公开链接或本地文件标识以及 SHA-256。相同审核内容重复导出时复用原文件；再次修改审核结果会生成新文件，不覆盖旧报告。

![报告预览](docs/screenshots/evidence-report.jpg)

## 模型配置

模型不是运行两条流程的前提。未配置模型时，程序仍会完成公开接口查询、字段整理、文件差异和候选检索，并生成保守的文字草稿。

如需使用兼容 OpenAI 接口的模型，在项目目录创建 `.env`：

```dotenv
NCBI_EMAIL=your-email@example.com
NCBI_API_KEY=
LLM_BASE_URL=https://example.com/v1
LLM_API_KEY=your-key
LLM_MODEL=your-model
```

不要把 `.env` 提交到 Git。不要向未经批准的模型服务发送患者信息、企业内部资料或其他敏感数据。

## 本地开发

需要 Python 3.12。

```bash
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pharma-assistant serve
```

SQLite 数据库、原始快照和报告默认写入 `data/` 与 `reports/`，这两个目录不会提交到 Git。

## 命令行

命令行和网页调用同一个应用服务，不会绕过人工审核和报告规则。

```bash
# 明确载入合成示例
pharma-assistant demo load --type research
pharma-assistant demo load --type regulatory

# 查询公开接口
pharma-assistant research run --topic "COPD inhaled therapy" --max-results 10

# 查看、审核和导出
pharma-assistant runs show RUN_ID --json
pharma-assistant findings list RUN_ID --json
pharma-assistant review accept FINDING_ID --reason "已核对原文"
pharma-assistant report export RUN_ID --format pdf
```

法规初筛命令：

```bash
pharma-assistant regulatory run \
  --old old.md \
  --new new.md \
  --sop internal-file.md \
  --name "文件更新检查"
```

## 供其他 AI 工具调用的 MCP 服务

`pharma-assistant-mcp` 通过标准输入输出提供五个受限工具。其他 AI 工具可以创建分析、查看状态、列出条目和读取证据，但不能审核、导出、发布、删除数据、执行 Shell、读取任意本地文件或访问任意网址。

```json
{
  "mcpServers": {
    "pharma-assistant": {
      "command": "/absolute/path/to/.venv/bin/pharma-assistant-mcp",
      "env": {
        "DATABASE_URL": "sqlite:////absolute/path/to/data/pharma-assistant.db",
        "DATA_DIR": "/absolute/path/to/data",
        "REPORT_DIR": "/absolute/path/to/reports",
        "DEMO_DATA_DIR": "/absolute/path/to/demo_data",
        "NCBI_EMAIL": "your-email@example.com"
      }
    }
  }
}
```

开放的工具名：

```text
run_research_intelligence
analyze_regulatory_documents
get_run_status
list_run_findings
get_finding_evidence
```

研发工具访问固定的官方接口。法规工具只处理调用方提交的文字，并限制单份长度、总长度和文件数量。证据响应不包含本地原始文件路径。

## 测试

```bash
.venv/bin/ruff check src tests
.venv/bin/pytest -q
.venv/bin/pytest --cov=pharma_research_regulatory_assistant --cov-report=term-missing
```

测试覆盖公开接口参数转换、来源降级、模型失败、文件解析、候选文件校验、人工审核、三种报告、命令行和 MCP 权限边界。测试中的研发资料和内部文件均为合成内容。

## 当前限制

- 只适合单机单用户试用；SQLite、本地文件和进程内后台任务不适合多实例部署。
- 研发资料只覆盖 ClinicalTrials.gov 与 PubMed，不包含商业数据库、专利和企业内部研发管线。
- PDF 必须带文字层；当前不做 OCR、复杂表格还原或电子签名验证。
- 内部文件候选采用文字相似度检索，不等于完整的法规影响评估。
- 尚未实现登录、细粒度权限、通知、备份、保留策略和计算机化系统验证。
- 示例运行只能证明技术链路可用，不能证明真实准确率、节省比例或生产可用性。

如果进入企业试点，应先确认现有信息源、流程、人员和基线，再用历史资料回放和影子运行验证。是否扩大使用范围，应由业务、法规、质量、信息安全和法务共同决定。

## 升级计划

以下项目按验证顺序排列。实际优先级应由历史回放和业务访谈决定，不以功能数量作为完成标准。

### 近期：提高初筛可靠性

- **文档处理**：增加 DOCX、扫描 PDF 的 OCR、表格和附件解析；保存页码、标题层级和版面位置；解析不完整时明确提示覆盖范围。
- **条款对齐**：识别条款改号、移动、拆分和合并；为每组对齐结果保存置信度，把低置信度结果单独交给人工核对。
- **要求提取**：从变化条款中分别提取责任主体、动作、对象、适用条件、期限、频率、记录要求和禁止事项，并逐项保留原文。
- **内部文件检索**：将关键词、术语表和语义检索组合使用；每个候选文件单独展示匹配依据，不再用一段说明概括多个候选。
- **评估**：由法规和质量人员标注历史案例，测量变化检出率、高影响变化漏检率、候选文件召回率、证据定位正确率和人工修改率。

### 试点：补齐日常工作闭环

- **法规文件库**：记录发布机构、文件编号、版本、生效日期、适用业务和原始来源，保留历次版本及内容哈希。
- **法规来源**：支持经过批准的监管网站、订阅源和人工上传入口；记录最近成功时间、失败原因和待确认的新版本。
- **研发信息源**：在确认许可和接口稳定性后接入专利、企业公告、商业数据库和企业内部研发资料。
- **信息源设置**：配置启用状态、密钥引用、限速、超时、重试、默认日期范围和结果上限；项目可以覆盖平台默认值，页面不显示密钥内容。
- **持续运行**：增加定时任务、增量查询、新变化提醒、报告模板和人工反馈记录，避免每次从头检索和整理。
- **协作处理**：为待复核项增加负责人、截止日期、状态、备注和通知；保留转交、退回和关闭记录。
- **价值核算**：保存试点前基线，持续统计初筛用时、采纳率、返工次数、漏检和单份报告成本。

### 企业接入前：治理和系统集成

- **权限与审计**：接入企业身份认证，按项目、文件和角色控制权限；审计记录覆盖查看、导出、审核、配置变更和模型调用。
- **部署与数据保护**：将 SQLite、进程内任务和本地文件替换为可备份的数据库、任务队列和对象存储；补充加密、保留期限、恢复演练和监控。
- **现有系统集成**：通过受控接口连接文档管理、质量管理和通知系统。程序不直接修改已批准文件，也不绕过现有审批。
- **模型治理**：固定模型和提示词版本，使用结构化输出和回归评估；模型升级先在历史案例上验证，再进入影子运行。
- **计算机化系统验证**：根据实际用途、数据等级和监管要求完成验证、变更控制、故障回退和供应商评估。
- **关系检索**：当法规、条款、职责、流程和内部文件已经形成稳定关系数据后，再评估 GraphRAG。是否采用以候选召回率、可解释性、维护成本和响应时间为准。

## 代码结构

```text
src/pharma_research_regulatory_assistant/
├── application.py      # 网页、CLI 和 MCP 共用的应用服务
├── workflows/          # 研发资料整理与法规初筛流程
├── sources/            # 固定公开信息源适配器
├── web/                # 中文网页
├── cli.py              # 命令行入口
├── mcp_server.py       # 受限 MCP 入口
├── database.py         # SQLite 存储
└── reports.py          # Markdown、HTML、PDF 报告
```

详细设计见[架构说明](docs/architecture.md)，权限和数据边界见[安全边界](docs/security-boundaries.md)。代码使用 [Apache License 2.0](LICENSE)。公开接口分别为 [ClinicalTrials.gov API v2](https://clinicaltrials.gov/data-api/api) 和 [NCBI E-utilities](https://www.ncbi.nlm.nih.gov/books/NBK25501/)。