# AGENTS.md - gene-family-mas-v2 RAG知识提取系统

## 项目定位

**提取型 Agent** - 从生物学论文中提取实体和关系，构建 PlantConnectome 兼容的知识图谱

## 核心任务

| 任务 | 说明 |
|------|------|
| 实体识别 | 基因家族、基因名、物种名、组织名、发育阶段 |
| 关系提取 | identified_in, collinear_with, involved_in, contain |
| 复合实体 | "32 SPL genes (CiSPLs)" 整体识别 |
| 列表解析 | "CiSPL3a/AtSPL3" 共线性对解析 |
| 证据溯源 | 每个关系需有证据句子和章节位置 |

## PC 关系类型 (PlantConnectome 标准)

| 关系类型 | PC数量 | V13现状 | 差距 |
|----------|:------:|:-------:|:----:|
| identified_in | 19 | 2 | 17 |
| collinear_with | 16 | 0 | 16 |
| involved_in | 15 | 0 | 15 |
| contain | 6 | 0 | 6 |

## 当前优化重点 (2026-04-14)

| 阶段 | 任务 | 目标 | 状态 |
|------|------|------|:----:|
| 阶段1 | 复合实体识别 | identified_in | ✓ |
| 阶段2 | 列表形式解析 | collinear_with +12-14 | ⏳ |
| 阶段3 | 词形还原 | contain +5-6 | ⏳ |
| 阶段4 | 被动语态识别 | involved_in +10-12 | ⏳ |
| 阶段5 | 证据句子提取 | 质量提升 | ⏳ |

## 目标指标

- **覆盖率**: 从 20.6% 提升到 >=35%
- **关系数**: 从 66 提升到 >=100
- **实体数**: 从 174 提升到 >=250

## 关键目录

| 目录 | 内容 |
|------|------|
| `src/rag/extractors/v13/` | V13提取器实现 |
| `src/rag/extractors/v13/phase3_entity_recognition.py` | 实体识别 |
| `src/rag/extractors/v13/phase4_relation_extraction.py` | 关系提取 (74个PC模式) |
| `mineru_pecan/` | MinerU提取输出 |
| `generated_pc_patterns.json` | PC模式库 |
| `mineru_pecan_v13_*.json` | 提取结果 |

## 工作原则

- **覆盖率优先**: 追踪实体数、关系数、PC覆盖率
- **模式匹配**: 74个PC关系模式 + 词形还原 + 被动语态
- **证据溯源**: 每个关系需有 evidence_sentence 和 section
- **PlantConnectome兼容**: 输出 JSON 符合 PC 标准格式

## 常用命令

```bash
# 激活环境
conda activate gfpy312

# 运行提取测试
python test_v13_1_simple.py

# 查看提取结果
cat mineru_pecan_v13_PERFECT_FINAL.json | jq '.relations | length'

# 启动 RAG API
python start_rag_api.py
```

## 提取结果文件

| 文件 | 说明 |
|------|------|
| `mineru_pecan_v13_stage1.json` | 阶段1结果 |
| `mineru_pecan_v13_final.json` | 最终结果 |
| `mineru_pecan_v13_entity_linking.json` | 实体链接结果 |
| `mineru_pecan_v13_COMPLETE_FINAL.json` | 完整最终结果 |

## 论文信息

当前主要处理:
- **PMID**: 34966577 (Pecan SPL 基因家族)
- **标题**: Genome-wide identification and expression analysis of SPL gene family in Pecan

## 上次会话状态 (2026-04-16)

**完成工作**:
- 论文框架设计：PAPER_FRAMEWORK.md（SCI论文结构）
- 实验对比方案：EXPERIMENT_DESIGN.md（V13 vs GPT-4o/Claude/BioGPT）
- 测试查询集：TEST_QUERY_EXAMPLES.md（50个查询，L1-L5难度）
- 人工标注规范：ANNOTATION_GUIDELINE.md（实体/关系标注 + Cohen's Kappa）
- 统计检验方法：STATISTICAL_TEST_METHODS.md（Wilcoxon/t检验 + 效应量）

**实验设计要点**:
- 知识提取对比：PlantAnalysisAgent vs GPT-4o/Claude/BioGPT/LangChain
- 检索对比：Agent编排 vs Naive BM25 Hybrid RAG
- 预期优势：P+20%, R+25%, F1+21%, 幻觉率<5%
- 统计检验：Wilcoxon符号秩 + Bonferroni校正
- 期刊推荐：Bioinformatics (IF 5.8)

**下一步**: 补充实验数据（人工标注Ground Truth）+ 多论文测试