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.
- 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.
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.
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.
- 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
Run this from the repository root:
# PowerShell
Copy-Item .env.example .env
# macOS/Linux
cp .env.example .envThe 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.
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 8000In a second terminal:
cd apps/web
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000Open:
| 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 |
Start the database service:
docker compose up -d dbSet these values in the root .env before starting the API:
STORAGE_BACKEND=postgres
DATABASE_URL=postgresql://qaagent:qaagent@localhost:5432/qaagentThe 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>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=1024EMBEDDING_DIMENSIONSmust match the pgvector column (vector(1024)ininfra/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_URLforqwen: leave empty (or set the DashScope host root) to use the native text-embedding endpoint; pointing it at a/v1orcompatible-modeendpoint switches to OpenAI-compatible mode.qwen3.7-text-embeddingis verified live to return 1024 dimensions, even though some vendor docs list 1536; the provider validates the configured dimension and the default schema isvector(1024).
-
Start Ollama and pull a model:
ollama pull qwen3-embedding:4b -
Configure the API:
EMBEDDING_PROVIDER=ollama EMBEDDING_MODEL=qwen3-embedding:4b EMBEDDING_DIMENSIONS=1024
-
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.
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.
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.
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
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.
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.
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
Backend checks:
cd apps/api
python -m compileall app tests
python -m pytest
ruff check app testsFrontend checks:
cd apps/web
npm run lint
npx tsc --noEmit
npm run build- 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-embeddingvia the DashScope native endpoint (verified live at 1024 dimensions). Changing the embedding model requires a full reindex, and changingEMBEDDING_DIMENSIONSrequires a pgvector schema migration (infra/migrations/002_embedding_1024.sql). deepagentsis intentionally not included.PaperChatAgentremains 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.