Skip to content

About

面向论文搜索、PDF 阅读和引用溯源问答的 Chat-first 论文 Agent,支持开放论文源检索、PDF 解析、证据检索、页码引用和多 LLM Provider 问答。Chat-first paper reading Agent for academic search, PDF parsing, citation-grounded RAG, and LLM-powered question answering with page-level evidence.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

PaperQAAgent

English | 简体中文

PaperQAAgent is a local-first paper research workspace for searching papers, importing or uploading PDFs, reading page-level evidence, and asking citation-grounded questions about one paper at a time.

Status: runnable MVP for local evaluation and continued development.

Highlights

  • Search real bibliographic sources: OpenAlex, Semantic Scholar, Crossref, and arXiv.
  • Deduplicate results and report the status of each source independently.
  • Import papers by DOI, arXiv ID, Semantic Scholar ID, OpenAlex ID, or PDF URL.
  • Upload local PDFs and store them under storage/pdfs/.
  • Extract pages, text, sections, and bounding boxes with PyMuPDF.
  • Retrieve relevant chunks with configurable embeddings, hybrid vector/lexical search, and page-linked evidence.
  • Ask questions within the current paper and receive page-linked evidence cards.
  • Open citations in the PDF reader and highlight the approximate evidence region.
  • Use a local evidence-summary fallback or configure an LLM provider per request.
  • Resize or hide the paper library and PDF reader around the chat-first Agent workspace.

Current scope

The current Agent scope is current_paper. It does not yet provide multi-paper comparison, paper-library synthesis, accounts, multi-tenancy, permissions, billing, Google Scholar search, OCR for scanned PDFs, or full visual understanding of tables, formulas, and figures.

How the workflow works

Search or upload
      -> metadata normalization and deduplication
      -> PDF download/storage
      -> PyMuPDF page and text-block parsing
      -> chunks, bounding boxes, and configured embeddings
      -> hybrid retrieval for the current paper
      -> evidence packet
      -> LLM answer or local fallback
      -> page citations and PDF navigation

The answerer receives retrieved evidence excerpts, not the full PDF by default. PDF text is treated as untrusted input, and the LLM prompt instructs the model to ignore instructions embedded in paper text.

Quick start

Requirements

  • Python 3.11 or newer
  • Node.js 16 or newer for the current Next.js 13 setup
  • Docker Desktop only if PostgreSQL persistence is needed
  • Node.js 20+ and current patched frontend dependencies are recommended before production deployment

1. Create local configuration

Run this from the repository root:

# PowerShell
Copy-Item .env.example .env

# macOS/Linux
cp .env.example .env

The default STORAGE_BACKEND=memory requires no database. Paper metadata, chunks, sessions, and answers are kept in memory; files under storage/pdfs/ may remain after a restart. PDF indexing uses the configured embedding provider; the default is Alibaba Cloud qwen3.7-text-embedding (1024 dimensions), which needs EMBEDDING_API_KEY.

2. Start the API

In a terminal:

cd apps/api
python -m pip install -e ".[dev]"
python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

3. Start the web app

In a second terminal:

cd apps/web
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000

Open:

Service URL
Web workspace http://127.0.0.1:3000
API documentation http://127.0.0.1:8000/docs
Health check http://127.0.0.1:8000/health

Optional PostgreSQL storage

Start the database service:

docker compose up -d db

Set these values in the root .env before starting the API:

STORAGE_BACKEND=postgres
DATABASE_URL=postgresql://qaagent:qaagent@localhost:5432/qaagent

The schema starts in infra/init.sql, and incremental changes are applied from infra/migrations/ during API startup. Migration 002_embedding_1024.sql changes the active pgvector schema to 1024 dimensions (matching qwen3.7-text-embedding) and marks existing ready papers for reindexing. The Compose file also defines Redis for future integrations; the current application does not require Redis to run.

To rebuild one paper after an embedding model or schema migration:

cd apps/api
.\.venv\Scripts\qaagent-reindex.exe <paper-uuid>

Embedding configuration

The qwen provider uses the official DashScope native text-embedding endpoint; the other remote providers speak the OpenAI-compatible v1/embeddings interface. Switching is a .env change plus a reindex of existing papers:

Provider EMBEDDING_PROVIDER Default base URL Notes
Alibaba Cloud DashScope (Qwen) qwen https://dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding Default. Native DashScope API with Bearer key; qwen3.7-text-embedding (1024 dims, verified live) or text-embedding-v4
OpenAI openai https://api.openai.com/v1 Key falls back to OPENAI_API_KEY
SiliconFlow siliconflow https://api.siliconflow.cn/v1 Qwen3-Embedding-4B / BAAI/bge-m3 (Matryoshka); set EMBEDDING_DIMENSIONS to the model's supported dimension
Zhipu GLM zhipu https://open.bigmodel.cn/api/paas/v4 embedding-3 supports 256/512/1024/2048; 1024 matches the current schema
OpenRouter openrouter https://openrouter.ai/api/v1 qwen3-embedding-8b supports Matryoshka dimensions
Custom OpenAI-compatible custom_openai EMBEDDING_BASE_URL Azure, vLLM, one-api proxies, etc.
Ollama (local) ollama http://localhost:11434 No API key required

Relevant environment variables:

EMBEDDING_PROVIDER=qwen
EMBEDDING_MODEL=qwen3.7-text-embedding
EMBEDDING_BASE_URL=
EMBEDDING_API_KEY=
EMBEDDING_DIMENSIONS=1024
  • EMBEDDING_DIMENSIONS must match the pgvector column (vector(1024) in infra/migrations/002_embedding_1024.sql). Models with a different native dimension require a schema migration and full reindex.
  • DashScope requests are automatically capped at 10 texts per request to stay within the API row limit (qwen3.7-text-embedding: 20, text-embedding-v3/v4: 10).
  • EMBEDDING_BASE_URL for qwen: leave empty (or set the DashScope host root) to use the native text-embedding endpoint; pointing it at a /v1 or compatible-mode endpoint switches to OpenAI-compatible mode.
  • qwen3.7-text-embedding is verified live to return 1024 dimensions, even though some vendor docs list 1536; the provider validates the configured dimension and the default schema is vector(1024).

Local deployment with Ollama

  1. Start Ollama and pull a model:

    ollama pull qwen3-embedding:4b
  2. Configure the API:

    EMBEDDING_PROVIDER=ollama
    EMBEDDING_MODEL=qwen3-embedding:4b
    EMBEDDING_DIMENSIONS=1024
  3. Reindex existing papers with qaagent-reindex <paper-uuid>.

qwen3-embedding:4b is Matryoshka-trained and can emit exactly EMBEDDING_DIMENSIONS; the dimensions request parameter is passed automatically when the installed langchain-ollama supports it (Ollama servers from 0.11 onward). Older Ollama versions ignore the parameter, so use a model whose native dimension matches the schema (e.g. bge-m3 at 1024 with a migration) or upgrade Ollama.

LLM configuration

The web settings panel supports:

  • OpenAI and Azure OpenAI
  • Anthropic Claude and Google Gemini
  • DeepSeek, Qwen / DashScope, Moonshot / Kimi, Zhipu GLM, Doubao / Volcano Ark, Tencent Hunyuan, MiniMax, SiliconFlow, StepFun, xAI Grok, and Mistral
  • OpenRouter, Ollama / Local, and custom OpenAI-compatible endpoints

Current default models per provider (verified against vendor docs / OpenRouter as of Aug 2026):

Provider Default model
OpenAI gpt-5.6-terra
Anthropic claude-sonnet-5
Google Gemini gemini-3.1-pro
DeepSeek deepseek-v4-flash
Qwen / DashScope qwen3.7-plus
Moonshot / Kimi kimi-k3
Zhipu GLM glm-5.2
Doubao / Volcano Ark doubao-seed-2-1-pro
Tencent Hunyuan hunyuan-turbos-latest
MiniMax MiniMax-M3
SiliconFlow deepseek-ai/DeepSeek-V3
StepFun step-3.7-flash
xAI Grok grok-4.5
Mistral mistral-large-latest
OpenRouter openai/gpt-5.6-terra
Ollama / Local qwen3:8b

Browser-configured API keys are stored in localStorage and sent to the API only with the current question. The backend does not persist the key in the database or Agent run payload. For local development, OPENAI_API_KEY and OPENAI_CHAT_MODEL can also provide a server-side fallback.

For a server-side default LLM of any provider, set these in .env (they are used when the web client does not send an llm_config):

LLM_PROVIDER=qwen
LLM_MODEL=qwen3.7-plus
LLM_API_KEY=sk-...
LLM_BASE_URL=
LLM_API_VERSION=

LLM_PROVIDER accepts the same ids as the settings panel (deepseek, qwen, zhipu, doubao, hunyuan, minimax, siliconflow, stepfun, xai, mistral, moonshot, openrouter, ollama, ...). LLM_MODEL defaults to the provider's default model, and LLM_PROVIDER=openai falls back to OPENAI_API_KEY/OPENAI_CHAT_MODEL. Without an available answer provider, the Agent returns a local evidence-summary answer. Real PDF indexing requires the configured embedding provider; use EMBEDDING_PROVIDER=hash only for explicit offline tests. The current answer provider calls are non-streaming: the SSE endpoint reports Agent steps and the final answer, while the token event is reserved for future token-level streaming.

Agent and retrieval behavior

The Agent pipeline is implemented in apps/api/app/services/paper_agent.py and includes planning, retrieval, evidence construction, answering, citation verification, persistence, and SSE events.

Reasoning level Default top-k Retrieval behavior
fast 5 Search with the original question
balanced 8 Add method, result, evidence, conclusion, and limitation terms
deep 12 Add broader abstract, method, experiment, analysis, limitation, and conclusion terms

balanced and deep currently use lightweight keyword expansion, not LLM query rewriting, sub-question planning, or reranking. Citation verification is currently page-level: it checks that cited pages appear in the current evidence packet, but it does not yet prove support for every individual claim.

API surface

Papers and PDFs

GET  /api/papers/search?q=&year_from=&year_to=&source=&has_pdf=&limit=
POST /api/papers/import
POST /api/papers/upload
GET  /api/papers/{paper_id}
GET  /api/papers/{paper_id}/chunks?query=&limit=
POST /api/papers/{paper_id}/ask

Agent sessions and streaming events

POST /api/agent/chat/stream
GET  /api/agent/sessions?paper_id={paper_id}
GET  /api/agent/sessions/{session_id}/messages

The Agent stream currently emits run_started, tool_started, tool_finished, final, and error. token is part of the public event model but is not emitted by the current non-streaming providers.

Settings and health

GET  /api/settings/llm/providers
POST /api/llm/test
GET  /health

FastAPI's interactive API documentation is available at http://127.0.0.1:8000/docs after the API starts.

Repository layout

PaperQAAgent/
  apps/api/                 FastAPI backend
    app/api/                HTTP routes
    app/models/             Pydantic request and response models
    app/services/           search, import, PDF, retrieval, Agent, LLM, and storage services
    tests/                  backend unit and API tests
  apps/web/                 Next.js frontend
    app/page.tsx            chat-first workspace layout
    components/             search, Agent chat, PDF reader, and settings panels
    lib/                    browser API client and TypeScript types
  infra/init.sql            PostgreSQL + pgvector schema
  infra/migrations/         versioned SQL migrations (schema_migrations)
  storage/pdfs/             local PDF object directory
  docs/USAGE.zh-CN.md       detailed Chinese usage guide
  README.md                 English project overview
  README.zh-CN.md           Chinese project overview
  Assistant.md              maintained developer handoff and project memory

Development and verification

Backend checks:

cd apps/api
python -m compileall app tests
python -m pytest
ruff check app tests

Frontend checks:

cd apps/web
npm run lint
npx tsc --noEmit
npm run build

Project documentation

Known limitations and next priorities

  • The PDF reader is canvas-first and does not yet provide a complete PDF.js text layer for selection and copying.
  • Scanned PDFs do not have an OCR fallback.
  • Tables, formulas, images, and captions are parsed only at a basic level.
  • Production indexing defaults to qwen3.7-text-embedding via the DashScope native endpoint (verified live at 1024 dimensions). Changing the embedding model requires a full reindex, and changing EMBEDDING_DIMENSIONS requires a pgvector schema migration (infra/migrations/002_embedding_1024.sql).
  • deepagents is intentionally not included. PaperChatAgent remains the explicit workflow orchestrator for the current single-paper scope.
  • The Agent supports only current_paper; paper-library and cross-paper workflows are future scope.
  • PostgreSQL migrations are applied from infra/migrations/ during API startup.
  • The current frontend remains on a Node 16-compatible Next.js/PDF.js combination with known legacy dependency risk; upgrade before production deployment.

The recommended next work is PDF.js text-layer support, stronger hybrid retrieval and claim-level citation verification, real async token streaming, run cancellation/retry/recovery, and eventually paper-library scope.

About

面向论文搜索、PDF 阅读和引用溯源问答的 Chat-first 论文 Agent,支持开放论文源检索、PDF 解析、证据检索、页码引用和多 LLM Provider 问答。Chat-first paper reading Agent for academic search, PDF parsing, citation-grounded RAG, and LLM-powered question answering with page-level evidence.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages