Metadata-Version: 2.4
Name: paper-sage
Version: 1.1.9
Summary: AI-powered literature reading assistant with multi-agent orchestration and hybrid RAG
Project-URL: Homepage, https://github.com/0verL1nk/PaperSage
Project-URL: Repository, https://github.com/0verL1nk/PaperSage
Project-URL: Issues, https://github.com/0verL1nk/PaperSage/issues
Project-URL: Changelog, https://github.com/0verL1nk/PaperSage/blob/main/CHANGELOG.md
Author: 0verL1nk
License-Expression: MIT
License-File: LICENSE
Keywords: agent,langchain,langgraph,literature,multi-agent,paper,rag
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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: argon2-cffi==25.1.0
Requires-Dist: chromadb<1.0.0,>=0.5.23
Requires-Dist: deepagents<0.6.0,>=0.5.4
Requires-Dist: duckduckgo-search<6.4.0,>=6.3.7
Requires-Dist: fastapi<1.0.0,>=0.116.0
Requires-Dist: fastembed<1.0.0,>=0.7.1
Requires-Dist: flashrank<1.0.0,>=0.2.10
Requires-Dist: httpx<1.0.0,>=0.28.1
Requires-Dist: lancedb>=0.34.0
Requires-Dist: langchain-chroma<1.0.0,>=0.2.0
Requires-Dist: langchain-community<0.5.0,>=0.4.0
Requires-Dist: langchain-core<2.0.0,>=1.0.0
Requires-Dist: langchain-openai<2.0.0,>=1.0.0
Requires-Dist: langchain<2.0.0,>=1.0.0
Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=2.0.0
Requires-Dist: langgraph>=0.3.0
Requires-Dist: markitdown>=0.1.0
Requires-Dist: numpy<2.4.0,>=1.26.0
Requires-Dist: onnxruntime>=1.24.3
Requires-Dist: openai<3.0.0,>=2.20.0
Requires-Dist: pyecharts<2.1.0,>=2.0.7
Requires-Dist: pymupdf<2.0.0,>=1.24.0
Requires-Dist: python-multipart<1.0.0,>=0.0.20
Requires-Dist: redis>=5.0.0
Requires-Dist: rq>=1.15.0
Requires-Dist: striprtf>=0.0.32
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.35.0
Provides-Extra: bm25
Requires-Dist: jieba>=0.42.1; extra == 'bm25'
Requires-Dist: rank-bm25>=0.2.2; extra == 'bm25'
Provides-Extra: dev
Requires-Dist: agentevals; extra == 'dev'
Requires-Dist: autoflake<3.0.0,>=2.3.1; extra == 'dev'
Requires-Dist: jieba>=0.42.1; extra == 'dev'
Requires-Dist: langsmith; extra == 'dev'
Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: rank-bm25>=0.2.2; extra == 'dev'
Requires-Dist: ruff<0.13.0,>=0.12.0; extra == 'dev'
Requires-Dist: vulture<3.0.0,>=2.11; extra == 'dev'
Description-Content-Type: text/markdown

# PaperSage

> 面向科研阅读、可追溯证据与多 Agent 协作的项目式研究工作台。

![PaperSage 系统能力总览](images/main.jpg)

PaperSage 将文献、会话、检索证据、长期记忆与 Agent 活动统一放进研究项目。上传资料后，解析、OCR 与索引在后台进行；用户可以立即开始对话，资料就绪后自动进入后续检索范围。

普通文档和可提取文本的 PDF 在本地解析；扫描型 PDF 会使用你在“设置”中配置的支持视觉输入的模型进行逐页 OCR，以避免把本地 OCR 运行时打进所有桌面安装包。

## 核心能力

- **项目式研究空间**：项目拥有资料库、主会话与分支会话、证据、记忆和研究活动，避免跨任务混杂上下文。
- **可追溯问答**：项目级 RAG 使用 LanceDB、Dense 向量、全文检索与 RRF 混合召回；回答中的证据可回到原文片段。
- **异步资料处理**：多文件上传后依次经历提取、OCR、分块、Embedding 与发布，前端显示真实进度且不阻塞会话。
- **多 Agent 协作**：Leader 可委派 researcher、reviewer、writer 等子 Agent；委派和工具调用由持久事件流驱动，而非模拟进度。
- **持久化研究过程**：SQLite 保存项目、消息、运行事件和摄取状态，LangGraph checkpoint 保存 Agent 状态；中途离开后可恢复运行与流式答案。
- **研究产物**：支持证据引用、Markdown/KaTeX 渲染、上下文检查器，以及受限 A2UI 协议生成的思维导图。

## 使用方式

1. 新建或选择一个研究项目。
2. 在“资料库”中一次上传多份 PDF、DOCX 或文本资料；不必等待索引完成。
3. 进入主会话提问，或在需要探索不同方向时创建分支会话。
4. 在回答侧边检查器中查看引用证据、资料状态与实际执行活动。

## 架构概览

```mermaid
flowchart LR
  UI[React 工作台] --> API[FastAPI /api/v1]
  API --> APP[Application 用例]
  APP --> AGENT[Leader 与 Subagents]
  APP --> RAG[LanceDB 混合检索]
  APP --> DB[(SQLite)]
  RAG --> DOC[解析 / OCR / 分块 / Embedding]
  AGENT --> SSE[持久 Run 事件流]
  SSE --> UI
```

前端是独立的 Vite + React 应用：TanStack Router 管理可导航状态，TanStack Query 管理服务端缓存与轮询，Zustand 仅保存 UI 状态，shadcn/ui 与 Radix UI 提供无障碍组件基础。后端使用 FastAPI 作为传输边界，`agent/domain`、`agent/application` 和 `agent/adapters` 保持分层；UI 不直接调用模型或数据库。

更多设计细节见：[Web 应用架构](docs/architecture/web-application.md)、[Agent 运行时](docs/architecture/agent-runtime.md)、[桌面应用](docs/architecture/desktop-application.md)。

## 快速开始

### 环境要求

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- Node.js 22+
- pnpm 11（建议通过 Corepack 使用）

```bash
corepack enable
make install-dev      # 安装 Python 开发依赖
make web-install      # 按 pnpm-lock.yaml 安装前端依赖
make run              # 同时启动 API :8000 和 Vite :5173
```

浏览器打开 `http://127.0.0.1:5173`。也可以分别启动：

```bash
make api-dev          # FastAPI，支持 reload
make web-dev          # Vite 开发服务器
```

生产构建由 FastAPI 托管前端静态文件：

```bash
make web-build
make serve            # http://127.0.0.1:8000
```

## 桌面端

桌面版将 React 前端与 FastAPI 服务一起打包为 Electron 应用，并使用应用内自定义标题栏。

```bash
make desktop-dev
make desktop-package-win    # Windows NSIS
make desktop-package-mac    # 仅 macOS 上执行，生成 DMG
make desktop-package-linux  # 仅 Linux 上执行，生成 AppImage 与 deb
```

发布 `vX.Y.Z` tag 时，GitHub Actions 会在 Windows、macOS、Linux 原生 runner 上构建安装包、生成 SHA-256 清单，并为公开 Release 生成 GitHub/Sigstore 构建证明。版本号必须同时匹配 `pyproject.toml` 与 `web/package.json`。具体的签名、公证和验证操作见[桌面发布运维说明](docs/architecture/desktop-release.md)。

## 项目结构

```text
api/                    # FastAPI 路由、schema 与 HTTP transport
web/
  src/components/       # 应用壳、领域组件与 shadcn/ui 组件
  src/pages/            # 项目、研究、资料库、设置页面
  src/lib/              # API client、Zod schema、Query hooks、平台边界
  src/stores/           # Zustand UI 状态
  electron/             # Electron main / preload / 开发启动器
agent/
  domain/               # 领域模型与契约
  application/          # 用例编排
  adapters/             # SQLite、LanceDB、文件、模型等外部适配
  subagent/             # 子 Agent 定义与协作能力
tests/                  # 单元、集成与评测
docs/architecture/      # 架构与运维文档
```

## 配置

复制 `.env.example` 为 `.env`，或在应用“设置”中保存用户级模型配置。密钥仅由后端读取，API 不会返回完整密钥。

```bash
# OpenAI-compatible 模型服务
OPENAI_COMPATIBLE_BASE_URL=https://your-provider.example/v1
OPENAI_MODEL_NAME=your-model
OPENAI_API_KEY=your-secret

# 项目级 RAG：0 表示不限制资料规模
AGENT_LANCEDB_DIR=./.cache/lancedb
LOCAL_RAG_PROJECT_MAX_CHARS=0
LOCAL_RAG_PROJECT_MAX_CHUNKS=0
RAG_INDEX_BATCH_SIZE=256

# 可选：Web 搜索与 Redis 队列
BRAVE_SEARCH_API_KEY=
REDIS_HOST=localhost
```

不要提交 `.env`、API Key、签名证书或 Apple notarization 凭据。完整配置项见 [.env.example](.env.example)。

## 开发与质量门禁

```bash
make check             # 快速本地门禁：核心 lint/typecheck、Web 检查、单测
make ci                # 完整离线 CI：锁文件、质量、前端测试/构建、全量测试
make test-unit         # Python 单元测试
make web-test          # Vitest 前端组件测试
make quality-full      # Python + 前端 lint/typecheck
make test-evals        # 离线 Agent 评测
```

变更请遵守 [AGENTS.md](AGENTS.md)：保持 `UI → application → domain` 的依赖方向，业务改动附带测试和文档，并避免把运行时编排或数据访问写入 UI。

## 贡献

提交前至少运行与改动范围对应的测试。Pull Request 请说明问题背景、变更范围、风险与回滚方式，并附上执行过的验证命令。详细工程约束与评审清单见 [AGENTS.md](AGENTS.md)。

## License

本项目采用 [MIT License](LICENSE)。
