Metadata-Version: 2.4
Name: paperminer-cli
Version: 0.1.0
Summary: Automated pipeline to extract model architecture building blocks from papers and GitHub
Project-URL: Homepage, https://github.com/ZhangCurosr/PaperTool
Project-URL: Repository, https://github.com/ZhangCurosr/PaperTool
Project-URL: Issues, https://github.com/ZhangCurosr/PaperTool/issues
Author: ZhangCurosr
License: MIT
License-File: LICENSE
Keywords: arxiv,cli,deep-learning,mcp,model-extraction,paper,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: libcst>=1.0.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">PaperMiner — 论文 → 代码提取引擎</h1>
<p align="center">
  <strong>自动从 arXiv / DBLP 抓取深度学习论文，定位其 GitHub 仓库，蒸馏出纯 PyTorch <code>nn.Module</code> 骨架。</strong>
</p>
<p align="center">
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-brightgreen" alt="python 3.10+"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
  <img src="https://img.shields.io/badge/tests-129%20passed-brightgreen" alt="tests">
  <img src="https://img.shields.io/badge/registry-80%2C777%20papers-orange" alt="registry">
  <img src="https://img.shields.io/badge/domains-12%20DL%20subfields-blueviolet" alt="domains">
  <a href="https://pypi.org/project/paperminer-cli/"><img src="https://img.shields.io/pypi/v/paperminer-cli" alt="pypi"></a>
  <img src="https://img.shields.io/badge/frontend-React%20%2B%20Tailwind-61DAFB" alt="frontend">
</p>

---

> **一句话介绍**：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（推荐）：**

```bash
pip install paperminer-cli
```

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

```bash
git clone git@github.com: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. 配置凭据

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

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

### 3. 一条链路跑完

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

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

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

### 4. 浏览器面板

```bash
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](./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 个深度学习子领域；你可以自己加减领域，不改代码。每领域可单独配置：

```yaml
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](https://github.com/ZhangCurosr/PaperTool/issues) 讨论。

---

## 完整文档

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

---

## License

[MIT](./LICENSE) © ZhangCurosr
