Run the Community edition on your own machine or server, or use PaperSeek online. Bring your preferred model API; use the Web UI, CLI, HTTP API, or MCP integration.

Contents

• Why PaperSeek
• What’s new in 1.0.0-beta2
• What’s new in 1.0.0-beta1
• How it works
• Data sources
• Quick start
• Models and ranking
• Reviews · Experimental
• Community and online
• CLI, MCP, and API
• Agent Skill
• Documentation
• Architecture and contributing
• Acknowledgements and license

Why PaperSeek

Start with a question, not a perfect query. Describe the relationship, method, population, or research gap you want to investigate. PaperSeek translates it into source-specific searches and refines them using retrieval feedback.

See how the reading list was formed. Follow query iterations, source hits, candidate retrieval, and ranking. Search budgets bound the work, while saved runs keep results and events available for later inspection.

Connect papers instead of reading a flat list. OpenAlex citation expansion follows references and citing works. The interactive map provides another route through the literature around your results.

Choose your model stack. Use OpenAI Responses, OpenAI-compatible Chat Completions, or Anthropic Messages. Start with local preliminary ranking, or configure Embedding + Rerank or the Jev decision model.

Keep the next step close. Filter and select papers, export complete results, reopen history, or turn a selected evidence set into an experimental review project.

What’s new in 1.0.0-beta2

A maintenance release that keeps research going when a model gets part of its answer wrong.

• Reviews no longer fail because a few papers lack usable evidence: those papers are left out and marked, and the review continues. Quotes that match the abstract are kept even when another quote is wrong.
• Search ranking keeps the scores a model did give and asks again only for the missing papers; long “Why it ranks” explanations are no longer cut off.
• History now shows queued and running searches, also after you reload the page.
• Docker Compose publishes PaperSeek on this machine only by default; set PAPERSEEK_HOST=0.0.0.0 to reach it from other devices.
• Documentation site: a resting finger or the end of a trackpad swipe no longer jumps to another section of the home page.

What’s new in 1.0.0-beta1

1.0.0-beta1 is a complete architectural refactor with breaking changes. The runtime, frontend, persistence, and integrations now form a modular application with durable task execution.

• Search, Bibliometrics, and Reviews in a collapsible sidebar, each with its own history; models, sources, and preferences in Settings.
• Preliminary bibliometrics over the full retrieved deduplicated candidate corpus: distributions, keyword co-occurrence, bibliographic coupling, field coverage, and independent exports. LLM scoring remains a subset.
• Separate research core, application services, and deployment adapters, shared across Community, PaperSeek online, CLI, HTTP, and MCP.
• Database-backed local runs with worker leases, checkpoint recovery, cancellation, saved history, and result artifacts.
• Versioned /api/v1 endpoints and generated frontend types.
• Query-history feedback, bounded candidate selection, and multiple preliminary-ranking paths.
• Experimental reviews with editable outlines, section writing, versions, and cited exports.
• Independent, version-matched paperseek-mcp packaging and an agent usage skill.

See workspace and history and bibliometrics.

How it works

!PaperSeek 1.0.0-beta2 research workspace

Community 1.0.0-beta2 with a demonstration record. PaperSeek online shares the same workspace and adds an account and service options.

| Step | What happens | What you can inspect | | --- | --- | --- | | 1. Understand | Interpret the question and plan source-specific queries | Research scope and search strategy | | 2. Refine | Test queries and adapt them using source feedback | Query history and source hit counts | | 3. Retrieve & rank | Collect candidates, optionally expand citations, and score relevance | Retrieval progress and ranking | | 4. Explore | Present papers, connections, and exports | Results, citation map, and saved history |

A run starts with one selected data source. Complementary retrieval paths do not mean that every database is searched at once. Source hit counts, downloaded candidates, and final results describe different sets.

PaperSeek is a discovery and organization tool. It does not guarantee an exhaustive systematic search, and a relevance score is not a study-quality assessment. Read original papers before relying on generated claims.

Data sources

| Source | Useful for | Access | | --- | --- | --- | | OpenAlex | Broad scholarly discovery and citation connections | API key recommended | | arXiv | Scientific preprints | No key required | | Crossref | DOI and publication metadata | No key required | | Semantic Scholar | Papers and scholarly graph metadata | Optional API key | | PubMed | Biomedical and life-science literature | Optional NCBI API key | | Google Scholar via Serper | Scholar results through a supported API | Serper key required | | PaperHub | Top computer-science conference collections | No key required | | Web of Science Starter | WoS collection search | Clarivate key required |

OpenAlex and Serper support multi-key rotation. Metadata coverage and field filters vary by source. See the source guide for configuration and credential links.

Quick start

Python package

Requires Python 3.12+. The release package includes the built Web UI.

python -m pip install "paperseek==1.0.0b2"
paperseek serve

Open localhost:8765, configure a model connection and source, then enter your research question. You do not need a PaperSeek account for Community.

Docker

git clone https://github.com/paperseek/paperseek.git
cd paperseek
cp .env.example .env
PAPERSEEK_VERSION=1.0.0-beta2 docker compose up -d

Edit .env before starting. On PowerShell, use Copy-Item instead of cp, then $env:PAPERSEEK_VERSION="1.0.0-beta2"; docker compose up -d. The included Compose service publishes 127.0.0.1:8765 and uses a persistent paperseek-data volume. These commands pin the beta image; prereleases do not update latest. The supplied Compose file and .env.example also default to 1.0.0-beta2.

ModelScope Studio

Try the PaperSeek Studio on ModelScope, or fork it to run your own copy as a Docker Studio:

Community is built for one user in a trusted environment and has no sign-in. Keep your copy private: everyone who can open a public Studio shares its settings, saved keys, and history.

From source

git clone https://github.com/paperseek/paperseek.git
cd paperseek
python -m pip install ./backend

The Python project lives in backend/. Frontend development and building a checkout without prebuilt assets are covered in Contributing.

Configuration and data

The Web UI exposes model and search configuration. For deployment defaults, see .env.example and the configuration reference.

Direct CLI execution reads process environment variables; it does not automatically load .env. Docker Compose explicitly loads that file.

Local history defaults to ~/.paperseek/paperseek.db. Keep its surrounding data directory, artifacts, and encryption key together when backing up. See self-hosting for storage and process management.

Models and ranking

The main model handles query planning and relevance evaluation. Select a protocol your provider actually supports:

| Protocol | Configuration value | | --- | --- | | OpenAI Responses | openai_responses | | OpenAI-compatible Chat Completions | openai_chat | | Anthropic Messages | anthropic_messages |

Preliminary ranking has three paths:

• Local fusion: combines local lexical and semantic signals; no separate ranking service to configure.
• Embedding + Rerank: uses external vector and reranking services.
• System One: uses a configured decision service for preliminary selection, such as TypeSafe Jev.

Preliminary ranking with Jev

PaperSeek now supports Jev for preliminary ranking: add a System One connection with the TypeSafe provider (jev-latest), then choose System One decision as the preliminary ranking. Jev assesses the locally fused candidates, up to twice the final candidate budget, before the main model scores the final subset.

Reviews · Experimental

Select papers with useful abstracts, create a review project, generate and edit an outline, then write and revise sections. The workspace supports versions, linked citations, and Markdown, Word, and BibTeX exports.

Reviews are based on available abstracts and metadata. They do not imply that the model has read full-text PDFs. Check the evidence and citations against the original research before using a draft.

Read the review guide →

Community and online

| | Community | PaperSeek online | | --- | --- | --- | | Run location | Your machine or server | Managed website | | Research data | Local SQLite and files | Account-scoped storage for signed-in work | | Models | Your configuration | PaperSeek Service or Bring Your Own Key | | Account | Not required | Required for saved history and reviews | | Anonymous use | Local workspace | Temporary BYOK search | | Local model endpoints | Supported when reachable | Non-public destinations blocked |

The online edition uses the same search implementation and pages as Community, and its user guide is part of this documentation.

Online guide →

CLI, MCP, and API

Command line

paperseek search "How does open-source funding affect maintenance?" --source openalex --search-budget medium --output json

Configure credentials in the process environment first. The six commands are serve, worker, search, doctor, migrate, and version.

Model Context Protocol

python -m pip install "paperseek-mcp==1.0.0b2"
paperseek-mcp --transport stdio

MCP tools start a run, follow its status, read results and citation graphs, cancel work, and export results. Streamable HTTP is available for compatible clients.

HTTP API

The local API is under /api/v1, with its installed schema at /openapi.json.

CLI guide · MCP setup · HTTP API

Agent Skill

Add the PaperSeek Skill to a compatible agent for local literature research. It guides installation checks, isolated Community installation when missing, configuration, searches, and saved results. CLI use does not require MCP.

Install and use the Skill →

Documentation

| Start here | Go deeper | | --- | --- | | Quick start | Models & ranking | | Search workflow | Citation maps | | Results & history | Reviews · Experimental | | Online accounts | Self-hosting & upgrades | | Configuration | Troubleshooting |

English documentation · 中文文档

Architecture and contributing

PaperSeek uses a modular monolith with a persistent task executor. Its layers separate research logic from task management and deployment:

Web / CLI / HTTP / MCP
          │
    paperseek_app ────→ paperseek_core
          │            Retrieval, ranking, source and model clients
          ▼
  Community adapters   SQLite and local artifacts

• paperseek_core implements the research workflow and source/model protocols, independently of FastAPI, authentication, SQLite, or Supabase.
• paperseek_app owns submission, execution, cancellation, checkpoints, and result access through storage ports.
• paperseek_community supplies SQLite, local artifacts, FastAPI, and CLI. A single paperseek wheel includes these three packages and the built Web UI.
• PaperSeek online builds on the same packages and Vue sources, adding its own authentication and storage adapters. Shared fixes belong in Community.

Contributions are welcome: improve docs, add a reproducible issue, test a source integration, or propose a focused change. See CONTRIBUTING.md for setup and checks, CODE_OF_CONDUCT.md for community expectations, and SECURITY.md for private vulnerability reporting.

Acknowledgements and license

PaperSeek is built with Python, FastAPI, httpx, Vue, Vite, and the work of the scholarly data providers listed above. The documentation uses VitePress; the interface takes design inspiration from shadcn/ui. See third-party notices for bundled components.

Licensed under Apache-2.0. External data and APIs remain subject to their respective providers' terms.