paperminer-cli 0.1.0

Automated pipeline to extract model architecture building blocks from papers and GitHub

PaperMiner — 论文 → 代码提取引擎

自动从 arXiv / DBLP 抓取深度学习论文，定位其 GitHub 仓库，蒸馏出纯 PyTorch nn.Module 骨架。

---

一句话介绍：PaperMiner 把「读论文 → 找 GitHub → 下代码 → 读懂目录 → 定位主模型 → 追踪依赖 → 抠出骨架」这 7 步自动化，输出一个可直接 import 的 PyTorch 模型子树。

---

简介

搞深度学习研究的人都有过这种体验：刷 arXiv 看到一篇好论文 → 按 GitHub 链接下代码 → 几百个文件中找不到 class MyModel(nn.Module) 在哪 → 手动追 import 追了半小时。

PaperMiner 把整条链路做成流水线，划分成 5 个独立阶段：

阶段	做什么	关键技术
抓取 discover	按关键词从 arXiv / DBLP 拉论文元数据	public Atom API、DBLP conf 接口
链接 link-repos	把论文匹配到其 GitHub 仓库	GitHub Search API + plausibility 过滤 + 重试回退
富化 enrich	补全 abstract / authors / tags / publishedAt	export.arxiv.org 批量条目、5xx 退避
提取 extract	下载仓库，定位主模型类，打包成可引用的子树	libcst / ast、LLM 识别、ZIP + git clone 双通道
分拣 view / serve	CLI 查看 / REST API / React 前端浏览	FastAPI、SQLite FTS5、React 18 + Tailwind

输出的每个模型包长这样：

extracted_models/2310.12345/
├── META.json            # paper 元数据 + 文件清单 + sha256 校验
├── LICENSE              # 上游 LICENSE（自动保留）
└── model_package/       # 完整包目录，保留相对导入
    ├── __init__.py
    ├── model.py         # 主模型类（在 META.json 里打 main_model 标签）
    └── layers.py

---

核心特性

• 论文发现：arXiv 全文检索 + DBLP 会议论文回溯，12 个深度学习子领域预置关键词，可自定义
• 仓库链接：三层查询（ID-in-README、关键词、标题关键词）+ plausibility 过滤剔除假阳性（portfolio / Wikipedia / 教程仓库）
• 零负担下载：zipball 带 429/5xx 指数退避，失败自动回退到 shallow git clone
• 双后端提取：CSTExtractor（保留注释格式，libcst）和 PyTorchModelExtractor（纯 stdlib ast，更快）
• LLM 识别：OpenAI 兼容 API 从候选 nn.Module 子类中挑主模型 + 类别标签（已兼容 LongCat / DeepSeek 风格 reasoning_content 网关）
• 批量富化：enrich_papers.py 补全文稿摘要、作者、标签；link_github_repos.py 批量回填 repo
• 三种入口：一行命令的 CLI、FastAPI REST API + React 前端面板、Claude Desktop 的 MCP Server

---

快速上手

1. 安装

从 PyPI（推荐）：

pip install paperminer-cli

参与贡献（editable 源码安装）：

git clone [e-mail]:ZhangCurosr/PaperTool.git
cd PaperTool
pip install -e ".[dev]"

三个入口脚本会自动注册：

命令	用途
paperminer	CLI，一次性任务、脚本化、本地查看
paperminer-api	FastAPI 服务（默认 http://localhost:8000）
paperminer-mcp	MCP Server（stdio 传输，接 Claude Desktop）

2. 配置凭据

cp .env.example .env
# 编辑 .env，填入：
#   PM_OPENAI_API_KEY    —— 用于识别主模型（没填会走首候选 fallback）
#   PM_GITHUB_TOKEN      —— 把限流从 60/hr 提到 5,000/hr

.env 全部环境变量用 PM_ 前缀，完整列表见 docs/README.md#配置。

3. 一条链路跑完

# 抓论文 → 链接仓库 → 提取模型 → 查看结果 → 查全局状态
paperminer discover --domain time_series --max-results 10
paperminer extract  --domain time_series --limit 5
paperminer view 2310.12345
paperminer status

或者一键串起来的便捷版：

paperminer run-all --domain cv_architectures --max-results 10

4. 浏览器面板

paperminer-api            # 启动 FastAPI
open http://localhost:8000/explore

React 面板支持：全文检索、子领域 / 年份 / 标签筛选、深色模式、BibTeX 一键导出、PDF / GitHub / abs 一键跳转、论文收藏夹。

---

当前快照

PaperMiner 把 SQLite 注册表随仓库提交（83 MB），让别人不用跑管线也能浏览论文索引。

指标	值
注册表论文数	80,777
子领域数	12（时序、CV、大模型、图学习、扩散模型、多模态、RL、生成式、NLP、语音、机器人、高效 ML）
REST API 入口	20+
CLI 命令	5（discover / extract / run-all / view / status）
MCP 工具	6（discover / link-repos / extract / search / get-paper / get-model-code）
测试覆盖	129 test functions / 14 模块

当前快照里 github_url、abstract 回填仍极少（刚起步）。每版 Release 会持续把"已链接仓库数 / 已富化比例"同步上来。

---

三种接口

CLI 一行命令

命令	作用
paperminer discover --domain <d> -n <N>	从 arXiv / DBLP 拉 N 篇到 registry
paperminer extract --domain <d> -l <N>	从 pending 论文中提取 N 篇的主模型
paperminer run-all --domain <d>	一次完成 discover + link + extract
paperminer view <paper_id>	在终端高亮查看模型源码
paperminer status	显示每个领域 pending / success / failed 数

REST API + 浏览器前端

方法	路径	作用
POST	/api/discover	触发抓取
POST	/api/extract	触发提取
GET	/api/papers	搜索 / 筛选 / 分页（FTS5）
GET	/api/papers/{id}	单篇论文完整元数据
GET	/api/papers/{id}/files	已提取模型的文件列表
GET	/api/papers/{id}/code/{path}	高亮单文件
GET	/api/papers/export	批量导出全部论文为 JSON（{total, papers}）
GET	/api/stats	全局统计（years / domains / tags 聚合）
GET	/api/pdf/{id}	302 重定向到 arxiv PDF
另有任务队列、富化进度、作者、标签、引用等端点	详见 docs/README.md#REST-API

浏览器前端（frontend/，React 18 + Tailwind + Vite）

• Explore 全文检索页 + 年份拖拽区间选择
• Tag 浏览 + 相关标签共现分析
• 论文详情 推荐相关论文 + 一键 BibTeX + 收藏星标
• Bookmarks 本地收藏夹（localStorage）
• Pipeline 管线实时状态

MCP Server（Claude Desktop / 智能体调用）

6 个工具：discover_papers / link_repos / extract_pending_models / search_extracted_models / get_registry_status / get_paper_info / get_model_code

---

子领域配置

domains.yaml 是 PaperMiner 认识的全部研究领域，开箱即用 12 个深度学习子领域；你可以自己加减领域，不改代码。每领域可单独配置：

time_series:
  keywords:          # 传给 arXiv API 的查询词
    - time series forecasting
    - temporal convolutional network
  arxiv_categories:
    - cs.LG
    - stat.ML
  dblp_venues:       # 可选：DBLP 会议论文回溯
    - KDD
    - ICDE
  extractor_type: cst  # cst 或 pytorch
  llm_classification_tags:
    - Transformer
    - CNN
    - RNN

---

批量回填脚本

随箱的 scripts/ 目录包含维护 8 万论文规模的工具：

脚本	作用
scripts/collect_24h.py	24 小时滚动抓取 arxiv 新论文
scripts/enrich_papers.py	批量回填 abstract / authors / published_at / tags（带 429/5xx 退避）
scripts/backfill_conferences.py	DBLP 会议论文反灌
scripts/link_github_repos.py	GitHub 仓库链接回补（断点续传）
scripts/build_papers_json.py	构建 GitHub Pages 静态快照 (docs/papers.json)
scripts/dev-up.sh	一键本地 dev 环境

---

目录结构

PaperTool/
├── src/paperminer/          # 核心引擎
│   ├── cli/                 # paperminer 命令行
│   ├── web/                 # FastAPI 服务 + REST 路由
│   ├── mcp/                 # MCP Server
│   ├── discovery/           # arXiv + DBLP + GitHub 链接
│   ├── extraction/          # CST / PyTorch 提取器 + 打包器
│   ├── storage/             # SQLite Registry + FTS5
│   └── pipeline.py          # 管道编排
├── frontend/                # React 浏览器面板 (Vite + Tailwind)
├── scripts/                 # 回填 / 维护工具
├── tests/                   # 14 模块 + 129 tests
├── extracted_models/        # 输出目录（论文 ID 为子目录名）
├── docs/                    # 文档站（含 papers.json 静态快照）
├── paperminer_registry.db   # 提交的生产 SQLite 快照
├── domains.yaml             # 领域配置
└── skill/paperminer/SKILL.md  # Claude Skill 描述符

---

路线图 v0.3.0（计划）

• 支持更多 LLM 网关（DeepSeek v3、Ollama 原生工具调用）作为"识别主模型"后备
• 多仓库支持（一篇论文多个实现时并列展示）
• 论文间引用关系图（Semantic Scholar 引用图已部分接入）
• REST 端点增加按引用排序
• 多模态 / 视觉领域扩展到 20+ 子领域
• enrich_papers 速率提升 + 断点续传

参与贡献请开 Issues 讨论。

---

完整文档

详细文档在 docs/README.md，含：完整安装、所有环境变量、所有 CLI / REST / MCP 参数、架构图、Docker 指南、开发和测试说明。更新日志见 CHANGELOG.md。

---

License

MIT © ZhangCurosr