PaperFlow

Dynamic personalized scientific-paper recommendation, reading, and reporting.

PaperFlow turns daily paper discovery into a closed-loop research workflow: build a profile, rank today's papers, read the useful ones, collect feedback, and adapt tomorrow's recommendations.

Language: English · 简体中文 · 日本語 · Español · Français · Português · 한국어

Quick Start | Desktop Preview | Local GUI | GUI Preview | CLI Usage | Feedback Loop | Feishu/Lark Bot | PaperFlow-Bench | Reproduce

---

Current Release

This first public release is a CLI + local browser GUI + optional Feishu/Lark bot version. You can run PaperFlow entirely from the terminal, open a local GUI for interactive paper selection, or keep the Feishu/Lark webhook server alive for scheduled chat pushes.

Input	Research profiles, papers, PDFs, homepages, Google Scholar pages
Output	Daily paper digests, reading reports, weekly profile reports
Runtime	Local Python CLI, local browser GUI, SQLite, optional Feishu/Lark webhook + ngrok
Benchmark	PaperFlow-Bench on HuggingFace, with public evaluation scripts

Desktop Preview

PaperFlow now ships with an offline-first desktop browser GUI. It uses the same local SQLite state and backend workflows as the CLI, so the UI is not a static mock: paper pulls, feedback, reading reports, Wiki graph updates, and settings all route through the local backend.

The embedded workflow demo shows the offline desktop loop end to end without storing large media files in the Git repository.

PaperFlow Desktop Workflow
Watch the desktop workflow video

_{Demo: daily paper pull, feedback actions, deep reading, report review, local Wiki graph, cited Q&A, and settings.}

View desktop screenshots

Daily paper stream Date-aware pulls, source filters, candidate metrics, paper actions, and backend task state.	Knowledge Wiki graph Backend-derived paper, topic, method, profile, and citation relationships.
Cited Wiki Q&A Streamed answers with clickable reference markers and source cards.	Local settings Provider keys, storage paths, paper-source modes, conference access, and export controls.

Product Framework

The desktop loop is intentionally local: profile state, paper pushes, feedback, reading reports, and Wiki nodes stay on disk unless you explicitly enable external providers or Feishu/Lark export.

Why PaperFlow

Scientific-paper recommendation is not a one-shot ranking problem. Real researchers ask a moving question: what should I read today, and how should the system adapt tomorrow?

Traditional paper alerts	PaperFlow
Static keyword or profile matching	Structured profile with feedback updates
Same feed every day	Date-specific candidate pools and daily digest budget
Recommendation only	Recommendation + reading report + feedback loop
No explicit drift handling	Short-term and long-term interest drift modeling
Hard to reproduce longitudinally	Public PaperFlow-Bench episodes and evaluator

Core Capabilities

Capability	What it does
Profile bootstrapping	Builds scholarly profiles from text, PDFs, homepages, or Google Scholar pages
Daily recommendation	Fetches arXiv, OpenReview, and journal papers, then ranks a personalized daily digest
Reading reports	Generates personalized paper reports from metadata and PDF content
Feedback learning	Updates the same profile from CLI, GUI, Feishu/Lark, selected, skipped, read, and natural-language feedback
Local research Wiki	Ingests paper pushes, reports, citations, feedback, and profile signals into a queryable local graph
Cited Wiki Q&A	Answers with local evidence when retrieval is needed, supports clickable citations and explicit @-style references
Offline desktop GUI	Provides a local UI for daily pulls, feedback, report reading, Wiki graph inspection, Q&A, and settings
Drift adaptation	Tracks short-window vs long-window interest movement across days
Feishu/Lark bot	Sends daily pushes and weekly reports; routes chat feedback and PDF requests
Benchmark tooling	Packages, downloads, predicts, and evaluates PaperFlow-Bench submissions

Quick Start

PaperFlow's daily flow has five steps. Steps 1-3 only run once; steps 4-5 become your daily routine.

# 1. Install
git clone https://github.com/OpenRaiser/PaperFlow.git
cd PaperFlow
pip install -e ".[all]"          # full install (or `pip install -e .` for the minimal CLI)

# 2. Configure providers (start with no-download settings; see below)
cp .env.example .env
# edit .env to set PAPERFLOW_LLM_PROVIDER and, for production, an embedding backend

# 3. Initialize runtime + create your user profile (REQUIRED)
paperflow init
paperflow doctor
paperflow profile \
  --user-id user_alice \
  --natural-language "I work on LLM agents for scientific discovery, \
literature mining, and automated paper reading."

# 4. Daily push (run every morning, or as often as you like)
paperflow daily --user-id user_alice

# 5. Read selected papers (paper IDs come from the latest daily push)
paperflow read 1 3 7 --user-id user_alice

# Optional: use the local browser GUI for steps 4-5
paperflow gui

Step 3 is mandatory. paperflow daily / read / feedback all read the profile created by paperflow profile. Skipping it means there's no personalization signal to score against, so paperflow read has no push to read from. See Initialize a User Profile below for the four bootstrap methods (text / PDF / Google Scholar / homepage).

Offline smoke test (no API keys)

paperflow demo

The demo uses deterministic mock/hash providers, so it does not need API keys or network access. Use it to confirm the install before configuring real providers.

Configure Providers

Copy the environment template:

cp .env.example .env

Use the PAPERFLOW_* variables as the canonical configuration surface. A fresh install defaults to no-download embeddings so paperflow demo and setup checks are quick, but real recommendation quality needs a semantic embedding backend.

Option A: recommended production setup

Use one OpenAI-compatible gateway for both generation and embeddings:

PAPERFLOW_LLM_PROVIDER=openai
PAPERFLOW_LLM_MODEL=gpt-4o-mini

PAPERFLOW_EMBED_PROVIDER=openai
PAPERFLOW_EMBED_MODEL=text-embedding-3-small

OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://your-openai-compatible-gateway/v1

OpenAI-compatible gateways are supported through OPENAI_BASE_URL, including OpenAI, DashScope, Azure OpenAI, vLLM, and similar services. If credentials are missing or still look like placeholders, PaperFlow falls back to mock/hash providers where possible so local workflows remain testable.

Option B: no-download smoke test

Use this for install checks, GUI demos, or classrooms where downloading model weights is not acceptable:

PAPERFLOW_LLM_PROVIDER=mock
PAPERFLOW_EMBED_PROVIDER=hash

This mode is deterministic and fast, but the hash vectors do not encode real semantic similarity. It is not the recommended setting for evaluating recommendation quality.

Option C: high-quality local embeddings

Use this only when the machine is allowed to download and cache local model weights:

PAPERFLOW_EMBED_PROVIDER=sentence_transformers
PAPERFLOW_EMBED_MODEL=BAAI/bge-m3
PAPERFLOW_EMBED_DIMENSIONS=1024

This local mode needs no embedding API key, but the first run downloads the model weights. BAAI/bge-m3 is about 2.3GB, so do not use it for quick classroom demos or first-run installation checks.

After changing providers, run:

paperflow doctor

paperflow doctor prints the resolved provider configuration. Runtime data is stored under data/ and is ignored by Git.

Initialize a User Profile

PaperFlow keeps one profile per user_id, and every other command (daily, read, feedback) reads from that profile. You must create at least one profile before the first daily run — otherwise paperflow daily has nothing to score against and paperflow read has no push to read from.

You can bootstrap a profile from any of these four sources, or combine them:

# (a) Self-description in natural language (fastest)
paperflow profile \
  --user-id user_alice \
  --natural-language "I work on LLM agents for scientific discovery, \
literature mining, and automated paper reading."

# (b) One or more papers you have written or care about
paperflow profile --user-id user_alice --pdf /path/to/my-paper.pdf

# (c) A Google Scholar profile (PaperFlow scrapes the public page)
paperflow profile \
  --user-id user_alice \
  --scholar-url "https://scholar.google.com/citations?user=..."

# (d) A personal lab or homepage
paperflow profile \
  --user-id user_alice \
  --homepage-url "https://example.edu/~alice"

Repeated paperflow profile calls merge new signals into the existing profile by default. Use --reset-existing only when you want to rebuild it from scratch.

Inspect the resulting profile any time with:

python scripts/show_profile.py user_alice

Local GUI

Start the local browser GUI with:

paperflow gui

To preview the interface without installing PaperFlow, open the GitHub Pages mock-data preview: PaperFlow GUI Preview.

The GUI uses the same local SQLite database as the CLI. It is designed for the real daily workflow, not a standalone mock:

• select a user profile and inspect the profile-derived direction summary
• pull papers for today's date, or intentionally fetch a previous date window
• keep long-running daily pulls in backend task state while the UI polls status
• mark papers as precision-read, not interested, or later
• submit feedback and update the local profile/Wiki signal path
• generate or reopen reading reports from paper cards
• inspect the backend-derived Wiki graph and search local knowledge nodes
• ask questions over the local Wiki with clickable references
• configure providers