Paper-Agent — AI Paper Research & Survey Writing Workbench
Enter a research topic and get a fully traceable literature survey: multi-source paper retrieval, full-text reading, layered analysis, and evidence-based writing.
Evidence shows backend bound to 127.0.0.1 by default, frontend local-only; external effects limited to local files, SQLite and queries/downloads from three public academic APIs — least_privilege 2. Fully automated PDF downloads and local vector-store writes lack any user-confirmation mechanism, so user_confirmation 1. SSE progress and per-stage token usage support data_flow_transparency 2. api_key_env support and model. kept out of the repo are good, but key display/storage details are undocumented — sensitive_data_handling 2. Dependencies carry only lower bounds, no lockfile or audit notes — dependency_security 1. No destructive defaults, external_effects 2. SQLite/file persistence plus documented 'save and resume' on dependency failure support rollback 2. chunkId citation system and contributor credits support source_attribution 2.
test_extraction_validation.py locks citation validation, retry, and structured failure states; gateway integration tests cover sessions, event streams, and artifact persistence — self_consistency 2. README documents resume-on-dependency-failure and fallback to default_agent — dependency_availability 2. Structured errors (status, reason, ApiError) are evidenced — failure_messages 2. Static review without execution prevents full marks.
Clear scenario table for researchers/students and concrete setup steps — audience_and_scenarios 2; PowerShell-only examples weaken cross-platform guidance, environment_fit 2. Five-agent division with documented fallback rules — trigger_precision 2. capability_boundaries only 1: EVAL_NOTES.md referenced in README/tests is absent from provided files, so claimed quality metrics cannot be verified.
Directory tree, mermaid workflow, and layered config are complete — information_architecture 3. Install notes are actionable but README inconsistently references both model.example. and settings.example., and examples are PowerShell-only — install_notes 2. pyproject name 'papers-agents', placeholder description 'Add your description here', version 0.1.0 contradicting the '2.0' narrative, and no CHANGELOG — naming_stability 1, versioning_changelog 1. known_limitations 1: limitation discussion depends on the missing EVAL_NOTES.md. No LICENSE file or license metadata at all — license 0. Contribution workflow and maintainer info present — maintenance_responsibility 2. Config examples ample but no FAQ — examples_and_faq 2.
Deliverable is a review with chunkId citations, evidence mapping, and restorable session artifacts — output_usability 2. Three-source dedup, layered analysis, and evidence-constrained writing are real increments over single-source summarizers — marginal_value 2. Multi-tier model slots with token usage display aid cost control — cost_benefit 2; no executed run to verify outcomes.
Citations must be valid chunkIds with an empty-field exemption, locked by regression tests — claim_traceability 2. Three-source retrieval with dedup/scoring supports cross_source_corroboration 2. Structured extraction fields plus verification/retry separate facts from inference — fact_inference_separation 2. Static review does not execute, so 3 is not awarded.
- The repository has no license file; usage, distribution, and contribution terms are legally undefined — confirm with the author before use.
- EVAL_NOTES.md and quality metrics referenced (e.g., the 39% coverage fix) are absent from the source files; capability claims cannot be verified.
- pyproject still has a placeholder description and version 0.1.0, contradicting the '2.0 rewrite' narrative — weak maintenance hygiene.
- API keys are viewable/editable in the web settings page and examples are PowerShell-only; watch local key storage and cross-platform deployment.
- Automated downloads and full-text parsing run without user confirmation; monitor disk usage and third-party API rate limits.
What does this agent do, and when should you use it?
Paper-Agent is an open-source research assistant built on a LangGraph multi-agent architecture, hosted at Tswoen/Paper-Agent. Five agents — SearchAgent, ReadAgent, AnalyseAgent, WritingOutlineAgent, and WritingAgent — chain retrieval, reading, analysis, outlining, and section-by-section writing into one survey pipeline. It retrieves from arXiv, OpenAlex, and Semantic Scholar, and processes full texts via pypdf-to-Markdown conversion and chunking into a ChromaDB vector store for evidence-grounded writing. The backend is a FastAPI service streaming progress via SSE, paired with a Vue 3 + TypeScript + Vite web workbench, with sessions persisted in SQLite and the filesystem. It suits researchers and students willing to self-host locally and configure their own LLM providers for literature review and survey drafting.
Given a research topic, SearchAgent generates keywords, subtopics, and search constraints; the system queries arXiv, OpenAlex, and Semantic Scholar, normalizes results into PaperDocument objects, and filters/deduplicates by year, source, count, and excluded terms. ReadAgent reads abstracts to judge relevance; qualifying papers go through download → PDF-to-Markdown → chunking → extraction → insertion into a local ChromaDB vector store, with state saved for resume when dependencies are unavailable. AnalyseAgent analyzes papers per subtopic then synthesizes global findings such as research status, consensus, disputes, gaps, and temporal evolution. WritingOutlineAgent produces an outline with evidence mappings, and WritingAgent writes each section, retrieves supplementary evidence when needed, then reviews with bounded revisions, producing a cited survey. All progress streams via SSE to the web workbench, with sessions and artifacts persisted in SQLite and local JSON/Markdown/vector files.
- A graduate student entering an unfamiliar research field who needs a quick paper list and structured overview of the area
- A PhD candidate drafting a literature survey who wants section-by-section generation with traceable evidence mappings
- Research teams running long-running investigations who rely on session persistence to pause and resume anytime
- Cost-conscious teams that assign different model tiers per stage and monitor actual token usage
- Researchers on OpenAI- or Anthropic-compatible gateways who configure and test providers visually in the browser
What are this agent's strengths and limitations?
- Five-agent pipeline covers retrieval through per-section writing, with every step visible in real time via SSE and resumable across restarts
- Three-source retrieval (arXiv/OpenAlex/Semantic Scholar) plus a local ChromaDB store; writing is constrained by evidence mappings so the survey is traceable
- Per-agent model tiers (luna_agent/solar_agent/default_agent) with OpenAI- and Anthropic-compatible protocols enable fine-grained cost control
- No license is specified, so commercial use or redistribution requires confirming terms with the author
- Requires local self-hosting with Python 3.12, uv, and Node.js plus your own model API keys; there is no hosted version
- Full-text download/parsing depends on external paper sources; when dependencies are unavailable, the pipeline only saves state until configuration is fixed
How do you install or deploy this agent?
- Install Python 3.12+, uv, and Node.js/npm.
- In the repo root run:
uv init
uv venv --python 3.12
uv sync
npm run front:install- Configure models: copy config/model.example. to config/model. (contains secrets, not committed); set at least one provider's api_base, an api_key or api_key_env, agents.default_agent, and embedding_profiles.default_embedding. See config/settings.example. for a template and config/system.yaml for system parameters. You can also configure and test connectivity from the web Settings page.
How do you use this agent?
- Start the backend: uv run python main.py — it listens on 127.0.0.1:8000 by default; API docs at http://127.0.0.1:8000/docs.
- Start the frontend: npm run front:dev, then open http://127.0.0.1:5173/.
- Test model connectivity in Model Settings, then create a research task in the session workbench and watch real-time retrieval, reading, analysis, outline, and writing progress.
- For LAN access from other devices, run npm run front:dev:network.