Model or dataset
Tswoen/Paper-Agent avatar
Tswoen/Paper-Agent

Paper-Agent's own quickstart names a config example file that the tree never lists

Paper-Agent is an intelligent paper search and research tool for researchers and students. Built on a multi-agent (LangGraph) architecture with NLP and automated search, it helps users efficiently find academic papers, analyze literature and conduct research, with multi-platform integration and keyword search. Suited to paper writing, academic research and research project management.

534 stars55 forksPythonLicense varies

At a glance

What is it?
A LangGraph pipeline that searches arXiv, OpenAlex, and Semantic Scholar, then reads, analyses, and writes a review while streaming progress to a Vue 3 workbench. Its packaging tells a different story from its documentation: a uv init placeholder manifest, a 0.1.0 version against a 2.0 headline, and no license file.
Who is it for?
Paper-Agent fits a researcher who wants one long pipeline from a topic to a cited review and is willing to tune three model tiers and a provider block before the first run. It does not fit someone who needs a licensed codebase to build on, or a headless CI job, since the only documented way to reach the workbench from another machine is a development server flag.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 58 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Tswoen/Paper-Agent534 ★ · +87
Star history
Repository2026-09-112026-11-15
Tswoen/Paper-Agent447534

87 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The example config file is named two different ways in the same document

Step two of the quickstart tells you to copy `config/model.example.json` to `config/model.json`. The directory listing and the model configuration section both name something else: `config/settings.example.json` sits next to a `config/model.json` marked as local and not committed, alongside `config/system.yaml`. So the file you are told to copy in one place is not the file the tree shows two sections later. Four things must be right in the result, according to the same step: a usable provider under `providers` with `api_base` filled in, a key supplied by either `api_key` or `api_key_env`, a configured `agents.default_agent`, and an `embedding_profiles.default_embedding` pointing at a working embedding provider. Whether that embedding profile is mandatory or only checked by the test button is not settled by the text, which leaves a configuration step that reads as a checklist of four and behaves like three.

The manifest still carries the description that uv init writes

pyproject.toml names the package `papers-agents` at version `0.1.0`, requires Python 3.12 or newer, and carries the description field `Add your description here`, which is the placeholder a project initializer writes. Eight dependencies are declared, all with lower bounds rather than pins: anthropic, chromadb, fastapi, httpx, langgraph, openai, pypdf, and uvicorn. That list is shorter than the technology table, which also names Uvicorn under the runtime, Server-Sent Events under the API, a Markdown conversion step, text chunking, SQLite with local JSON and vector files, and a Vue 3 frontend with TypeScript, Vite, Vue Router, and Lucide. The root package.json is a shim rather than a dependency manifest: it is private, carries the same `papers-agents` name, declares no dependencies, and holds five scripts that all forward to the `front/` directory.

The printed layout stops after src/ and leaves out graph.py and test/

The project directory section lists `main.py` as the FastAPI entry point, `pyproject.toml`, `package.json`, the `config/` trio, the `front/` Vue tree down to `vite.config.ts`, and then `src/`, where the listing ends. Nothing under `src/` is shown, and two files that the rest of the document depends on are absent from the printed layout: `graph.py`, which is where a LangGraph workflow would live, and `test/`, which the contribution section names as the place to add or update tests. The top level of the repository also holds `doc/`, `assets/`, `uv.lock`, `package-lock.json`, and `.python-version`, none of which appear in that listing. For a reader deciding where to put a new agent, the visible part of the layout is enough to show the front and back ends and not enough to show the workflow file.

Five agents share three model tiers, and one of the tiers is mandatory

Each agent carries a default model tier, and the mapping is not uniform. `SearchAgent` defaults to `luna_agent` and turns a topic into keywords, subtopics, and search constraints. `AnalyseAgent` defaults to `solar_agent` and does both per-subtopic and global analysis. The other three, `ReadAgent`, `WritingOutlineAgent`, and `WritingAgent`, all default to `default_agent`, which handles relevance judgements and notes, outline and evidence mapping, and section-by-section writing with review. The fallback rule is explicit: without `luna_agent` or `solar_agent` the configuration falls back to `default_agent`, and without `default_agent` it cannot work at all. So one tier is load-bearing for the whole pipeline and two are optional upgrades. The stated reason for splitting them is cost, since different stages use different tiers and the workbench shows the actual token usage per stage.

Four provider backends, and the key can come from a field or an environment variable

The provider block is small enough to read in full, and the shape matters more than the example inside it:

json
{
  "providers": {
    "my_provider": {
      "backend": "openai_compat",
      "api_key_env": "OPENAI_API_KEY",
      "api_base": "https://api.openai.com/v1",
      "extra_headers": {},
      "extra_body": {}
    }
  }
}

The `backend` field accepts four values, `openai`, `openai_compat`, `anthropic`, and `anthropic_compat`, and `api_key` and `api_key_env` are alternatives rather than a pair to fill in. A compatibility gateway normally needs the backend, the base address, and the model name together, which means a self-hosted endpoint is a supported case rather than a workaround. The same settings are editable from the 系统设置 page in the browser, with a one-click connectivity test, and the project says saved values take effect immediately, so the file and the web page are two doors onto the same configuration.

Two ports, a localhost-only frontend, and a network flag with no documented login

The backend listens on `127.0.0.1:8000` by default, reloads automatically in development mode, and serves API documentation at `http://127.0.0.1:8000/docs`. The frontend is a separate process on `http://127.0.0.1:5173/`, binds to the local machine only, and proxies `/api` and `/webui` to that backend, with the dev server, proxy, and port all living in `front/vite.config.ts`. The start sequence is two commands:

powershell
uv run python main.py
powershell
npm run front:dev

Exposing the workbench to other devices on the network takes a third, separately named script, and the prose frames it as the alternative to localhost binding:

powershell
npm run front:dev:network

That script forwards to `dev:network` inside `front/`, and the README documents no authentication on either port, so the network variant is a dev server exposed further than the one it was written for. Sessions survive a browser refresh through SQLite plus the filesystem, which is the state that has to be trusted if you run the network variant on a shared link.

The full-text stage can fail, save the scene, and resume at ReadAgent

The reading stage is the one place the pipeline admits it can stop. Abstracts come first, and papers that pass the relevance check move through download, PDF to Markdown conversion, chunking, extraction, and a write into the local vector store. When a dependency there is unavailable, the workflow saves the scene instead of failing, and a later step returns to `ReadAgent` once the configuration has been repaired. Restart handling follows the same instinct at the service level: on startup the application reconciles orphaned background tasks, releases the permanent run lock, and keeps an audit event for the interruption, so a crashed run does not block the next one. Progress for all of this arrives over Server-Sent Events, which the feature table describes as covering search, reading, analysis, outline, and section-by-section writing. Cost is made visible in the same workbench, with per-stage token counts rather than a single running total.

The headline says 2.0, the manifest says 0.1.0, and the top level has no license

The 2.0 section describes a full rewrite of the 1.x line, with a Vue 3 and TypeScript frontend, `uv` for Python dependencies, three paper sources instead of arXiv alone, SQLite plus the filesystem for sessions, the startup reconciliation described above, and SSE progress. None of that is reflected in the packaging version, which is still `0.1.0`, and the two manifests use the name `papers-agents` while the repository and every heading call the project Paper-Agent. There are no GitHub releases, so the version numbers in the README prose and in pyproject.toml are the only ones a reader gets, and they disagree. The top-level layout also carries no license file and the manifest declares no license field, with the repository's license reported as unknown. For a project whose selling point is a written review, that is the part worth raising with the maintainers first, alongside the QQ group the README points readers to for discussion.

Editorial conclusion

Paper-Agent fits a researcher who wants one long pipeline from a topic to a cited review and is willing to tune three model tiers and a provider block before the first run. It does not fit someone who needs a licensed codebase to build on, or a headless CI job, since the only documented way to reach the workbench from another machine is a development server flag. Verify three things first. Which example config file actually exists, because the quickstart and the directory listing name different ones. Whether your `default_agent` entry is set, since the configuration cannot work without it. And what license terms you will use, because the repository carries none in its top-level layout and reports an unknown license.

Frequently asked questions

What is Tswoen/Paper-Agent?

A research workbench that turns a topic into a literature review. A multi-agent pipeline on LangGraph searches arXiv, OpenAlex, and Semantic Scholar, reads and analyses what it finds, and writes the review section by section, with progress streamed to a Vue 3 workbench over Server-Sent Events.

Which Python version does Paper-Agent need?

Python 3.12 or newer. pyproject.toml sets requires-python to ">=3.12", and the quickstart creates the environment with `uv venv --python 3.12`. Its eight dependencies are declared with lower bounds, from anthropic 0.111.0 and above up to pypdf 5.0.0 and above.

How do I configure a model provider in Paper-Agent?

Through the 系统设置 page in the web workbench, or by editing `config/model.json` by hand. A provider entry needs a `backend` of openai, openai_compat, anthropic, or anthropic_compat, an `api_base`, and a key supplied through either `api_key` or `api_key_env`.

What does Paper-Agent do when a PDF dependency fails?

It saves the scene and stops rather than failing. The full-text stage hands off to a save-and-resume node, which returns to `ReadAgent` once the configuration is fixed, and session state lives in SQLite plus local files.

Can I open the Paper-Agent workbench from another machine on my network?

There is a script for it: `npm run front:dev:network`, which forwards to `npm --prefix front run dev:network`. By default the frontend listens on the local machine only and proxies `/api` and `/webui` to the backend on 127.0.0.1:8000.

What license is Paper-Agent released under?

The repository's license is reported as unknown, the top-level layout carries no license file, and pyproject.toml declares no license field. Confirm the terms with the maintainers before reusing the code.

Official sources

  1. Issues
  2. README
  3. Tswoen/Paper-Agent on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tswoen-paper-agent.svg)](https://hysenlabs.com/projects/tswoen-paper-agent)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tswoen-paper-agent.svg)](https://hysenlabs.com/projects/tswoen-paper-agent)

Was this useful?