# Paper Atlas

**长期维护、按需运行的论文元数据与公开投稿历史工具。**

Paper Atlas 将 arXiv、AI 会议论文集及公开投稿决定整理到可追溯的 SQLite 数据库中，用于查询和后续研究分析。它按批次运行，不需要常驻 Web 服务；采集标题、摘要、标识、标签及决定证据，不下载论文全文。

项目仍在建设中。候选范围包含 41 个会议，尚未完成全部历史数据和最终去重复核。实际进度以数据库、来源清单和覆盖报告为准，而不是仓库文件数量。

## 项目结构

```text
paper_atlas/
  cli.py                 统一命令入口
  collectors/            各来源采集与目录盘点
  ingestion/             导入、身份回填与单写入协调
  db/                    数据模型、身份解析与 SQL schema
  audits/                来源核验和覆盖报告
  io/                    网络、快照下载、HTML 与 Git 元数据读取
  resources/             候选会议目录
  querying.py            只读查询
tests/                  回归与集成验证
docs/                   使用、数据源、数据模型和维护说明
pyproject.toml          包元数据、依赖和命令注册
.gitea/workflows/       远程 CI 与安装验证
```

## 安装与入口

以下安装、测试及批次运行在已确认的远程服务器 / `ces-control:host` runner 上执行。已在 Python 3.14 环境验证；项目要求 Python 3.12 及以上。

```sh
python3 -m venv .venv
.venv/bin/python -m pip install .
source .venv/bin/activate
paper-atlas --help
```

从源码目录也可以使用同一命令树：`python3 -B -m paper_atlas --help`。无需执行散落的脚本文件。

## 常用流程

```sh
# 查看当前入库量；不同平台记录数不等于独立论文数
paper-atlas query --db /data/paper-index/papers.sqlite --stats

# 查询标题与摘要
paper-atlas query --db /data/paper-index/papers.sqlite --query '"language model"'

# 查看一篇论文的来源、标签和所有已知投稿历史
paper-atlas query --db /data/paper-index/papers.sqlite --paper 123

# 列出全部目标会议，包括尚未入库的项目
paper-atlas coverage --db /data/paper-index/papers.sqlite \
  --out /data/paper-index/collected/venue-coverage-current.json

# 采集与导入分开；这里只采集到独立文件
paper-atlas collect colm --cache /data/paper-index/raw/http-cache \
  --out /data/paper-index/collected
```

`paper-atlas collect --help` 查看来源；`paper-atlas import --help` 查看导入方式。完整批次步骤见[使用指南](docs/usage.md)。

## 数据如何组织

- **论文和投稿分开。** 一篇论文可以多次投稿；某次被拒、后来在其他会议录用，两段历史都保留。
- **决定必须有证据。** 评分、未出现在录用名单、没有公开决定，均不能推断为 Reject。未发现录用也不等于从未录用。
- **来源和标签保留出处。** 不同平台标签分开，自定义标签使用 `custom:*`；确认合并时保留源记录与审计。
- **覆盖范围逐届核对。** 主会、Findings、workshop 等分别记录。单个文件检查通过不能证明整个会议历年完整。
- **数据库只允许单写入。** 采集任务先写独立文件，核验后由协调器合并；原始数据和数据库均放在仓库外。

## 文档

| 内容 | 入口 |
| --- | --- |
| 安装后怎么采集、导入和查询 | [使用指南](docs/usage.md) |
| 数据范围、各采集器和来源限制 | [数据源说明](docs/data-sources.md) |
| 论文、投稿、决定、标签及去重规则 | [数据模型](docs/data-model.md) |
| 批次恢复、更新和最终核验 | [运行维护](docs/operations.md) |
| 模块职责、开发和 CI | [开发说明](docs/development.md) |

## 验证与交付

CI 在已授权的远程 runner 上运行测试、构建 wheel，并从源码目录外验证安装后的命令及随包资源。数据库全量去重和覆盖率是独立的数据验收步骤，不因代码测试通过而自动完成。

开发通过工作分支和 PR 交付，由用户手动合并。