Skip to content
Back to search

PaperFlow

📚 PaperFlow: Dynamic personalized scientific-paper recommendation, reading, and reporting

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/openraiser--paperflow/badge.svg)](/listings/openraiser--paperflow)

HTML

<a href="/listings/openraiser--paperflow"><img src="/api/listings/openraiser--paperflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](#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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 641 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # PaperFlow
  3. **Dynamic personalized scientific-paper recommendation, reading, and reporting.**
  4. PaperFlow turns daily paper discovery into a closed-loop research workflow:
  5. build a profile, rank today's papers, read the useful ones, collect feedback,
  6. and adapt tomorrow's recommendations.
  7. [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org/downloads/)
  8. [![Package](https://img.shields.io/badge/package-paperflow-2E7D32.svg)](https://github.com/OpenRaiser/PaperFlow/blob/main/pyproject.toml)
  9. [![HF Dataset](https://img.shields.io/badge/HF%20Dataset-OpenRaiser%2FPaperFlow-FFD21E.svg)](https://huggingface.co/datasets/OpenRaiser/PaperFlow)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-111111.svg)](https://github.com/OpenRaiser/PaperFlow/blob/main/LICENSE)
  11. ![Personalized Recommendation](https://img.shields.io/badge/personalized-recommendation-2E7D32.svg)
  12. ![Scientific Reading](https://img.shields.io/badge/scientific-reading-1565C0.svg)
  13. ![Daily Digest](https://img.shields.io/badge/daily-paper%20digest-F9A825.svg)
  14. ![Feedback Learning](https://img.shields.io/badge/feedback-learning-6A5ACD.svg)
  15. ![Interest Drift](https://img.shields.io/badge/interest-drift-00897B.svg)
  16. ![Feishu/Lark](https://img.shields.io/badge/Feishu%2FLark-bot-00A1E9.svg)
  17. **Language**:
  18. [English](https://github.com/OpenRaiser/PaperFlow#readme) ·
  19. [简体中文](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_CN.md) ·
  20. [日本語](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_JA.md) ·
  21. [Español](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_ES.md) ·
  22. [Français](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_FR.md) ·
  23. [Português](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_PT.md) ·
  24. [한국어](https://github.com/OpenRaiser/PaperFlow/blob/main/assets/README/README_KO.md)
  25. [Quick Start](#quick-start) | [Desktop Preview](#desktop-preview) | [Local GUI](#local-gui) |
  26. [GUI Preview](https://openraiser.github.io/PaperFlow/deployments/desktop/static/index.html?demo=1) |
  27. [CLI Usage](#cli-usage) |
  28. [Feedback Loop](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feedback-loop.md) |
  29. [Feishu/Lark Bot](#feishu--lark-bot) |
  30. [PaperFlow-Bench](#paperflow-bench) | [Reproduce](https://github.com/OpenRaiser/PaperFlow/blob/main/experiments/REPRODUCE.md)
  31. <img src="https://github.com/user-attachments/assets/fd31a62b-00a4-4210-82cb-1ffd080de254" alt="PaperFlow personalized scientific reading banner" width="100%">
  32. </div>
  33. ---
  34. ## Current Release
  35. This first public release is a **CLI + local browser GUI + optional
  36. Feishu/Lark bot** version. You can run PaperFlow entirely from the terminal,
  37. open a local GUI for interactive paper selection, or keep the Feishu/Lark
  38. webhook server alive for scheduled chat pushes.
  39. <table>
  40. <tr>
  41. <td><b>Input</b></td>
  42. <td>Research profiles, papers, PDFs, homepages, Google Scholar pages</td>
  43. </tr>
  44. <tr>
  45. <td><b>Output</b></td>
  46. <td>Daily paper digests, reading reports, weekly profile reports</td>
  47. </tr>
  48. <tr>
  49. <td><b>Runtime</b></td>
  50. <td>Local Python CLI, local browser GUI, SQLite, optional Feishu/Lark webhook + ngrok</td>
  51. </tr>
  52. <tr>
  53. <td><b>Benchmark</b></td>
  54. <td>PaperFlow-Bench on HuggingFace, with public evaluation scripts</td>
  55. </tr>
  56. </table>
  57. ## Desktop Preview
  58. PaperFlow now ships with an offline-first desktop browser GUI. It uses the same
  59. local SQLite state and backend workflows as the CLI, so the UI is not a static
  60. mock: paper pulls, feedback, reading reports, Wiki graph updates, and settings
  61. all route through the local backend.
  62. The embedded workflow demo shows the offline desktop loop end to end without
  63. storing large media files in the Git repository.
  64. <table width="100%">
  65. <tr>
  66. <th><p align="center">PaperFlow Desktop Workflow</p></th>
  67. </tr>
  68. <tr>
  69. <td align="center" width="100%">
  70. <a href="https://github.com/user-attachments/assets/ebfd979a-93f2-4140-9d4c-7bd64aa86b5e">
  71. <img src="https://github.com/user-attachments/assets/c852c134-5ddb-478e-8a13-3fa313dcd812" alt="PaperFlow desktop workflow video preview" width="100%">
  72. </a>
  73. <br>
  74. <a href="https://github.com/user-attachments/assets/ebfd979a-93f2-4140-9d4c-7bd64aa86b5e"><b>Watch the desktop workflow video</b></a>
  75. </td>
  76. </tr>
  77. </table>
  78. <sub><i>Demo: daily paper pull, feedback actions, deep reading, report review, local Wiki graph, cited Q&A, and settings.</i></sub>
  79. <br>
  80. <details>
  81. <summary>View desktop screenshots</summary>
  82. <table>
  83. <tr>
  84. <td width="50%">
  85. <img src="https://github.com/user-attachments/assets/018aa646-41fa-4967-b4d4-6d6a54df51cf" alt="PaperFlow daily paper recommendation stream">
  86. <br><b>Daily paper stream</b><br>
  87. Date-aware pulls, source filters, candidate metrics, paper actions, and backend task state.
  88. </td>
  89. <td width="50%">
  90. <img src="https://github.com/user-attachments/assets/305279b3-1350-4169-887c-99c0cac29a15" alt="PaperFlow knowledge Wiki graph">
  91. <br><b>Knowledge Wiki graph</b><br>
  92. Backend-derived paper, topic, method, profile, and citation relationships.
  93. </td>
  94. </tr>
  95. <tr>
  96. <td width="50%">
  97. <img src="https://github.com/user-attachments/assets/6685dd75-e2e2-45d1-b440-1ca5325eca1d" alt="PaperFlow cited local Wiki question answering">
  98. <br><b>Cited Wiki Q&A</b><br>
  99. Streamed answers with clickable reference markers and source cards.
  100. </td>
  101. <td width="50%">
  102. <img src="https://github.com/user-attachments/assets/a629cc1e-e26e-4878-9eb3-97565153b711" alt="PaperFlow local settings and source configuration">
  103. <br><b>Local settings</b><br>
  104. Provider keys, storage paths, paper-source modes, conference access, and export controls.
  105. </td>
  106. </tr>
  107. </table>
  108. </details>
  109. ### Product Framework
  110. <img src="https://github.com/user-attachments/assets/60ff5a52-5d09-46c2-be0d-1933c19515b6" alt="PaperFlow product framework diagram" width="100%">
  111. The desktop loop is intentionally local: profile state, paper pushes, feedback,
  112. reading reports, and Wiki nodes stay on disk unless you explicitly enable
  113. external providers or Feishu/Lark export.
  114. ## Why PaperFlow
  115. Scientific-paper recommendation is not a one-shot ranking problem. Real
  116. researchers ask a moving question: **what should I read today, and how should
  117. the system adapt tomorrow?**
  118. | Traditional paper alerts | PaperFlow |
  119. | --- | --- |
  120. | Static keyword or profile matching | Structured profile with feedback updates |
  121. | Same feed every day | Date-specific candidate pools and daily digest budget |
  122. | Recommendation only | Recommendation + reading report + feedback loop |
  123. | No explicit drift handling | Short-term and long-term interest drift modeling |
  124. | Hard to reproduce longitudinally | Public PaperFlow-Bench episodes and evaluator |
  125. ## Core Capabilities
  126. | Capability | What it does |
  127. | --- | --- |
  128. | Profile bootstrapping | Builds scholarly profiles from text, PDFs, homepages, or Google Scholar pages |
  129. | Daily recommendation | Fetches arXiv, OpenReview, and journal papers, then ranks a personalized daily digest |
  130. | Reading reports | Generates personalized paper reports from metadata and PDF content |
  131. | Feedback learning | Updates the same profile from CLI, GUI, Feishu/Lark, selected, skipped, read, and natural-language feedback |
  132. | Local research Wiki | Ingests paper pushes, reports, citations, feedback, and profile signals into a queryable local graph |
  133. | Cited Wiki Q&A | Answers with local evidence when retrieval is needed, supports clickable citations and explicit `@`-style references |
  134. | Offline desktop GUI | Provides a local UI for daily pulls, feedback, report reading, Wiki graph inspection, Q&A, and settings |
  135. | Drift adaptation | Tracks short-window vs long-window interest movement across days |
  136. | Feishu/Lark bot | Sends daily pushes and weekly reports; routes chat feedback and PDF requests |
  137. | Benchmark tooling | Packages, downloads, predicts, and evaluates PaperFlow-Bench submissions |
  138. ## Quick Start
  139. PaperFlow's daily flow has five steps. Steps 1-3 only run once; steps 4-5
  140. become your daily routine.
  141. ```bash
  142. # 1. Install
  143. git clone https://github.com/OpenRaiser/PaperFlow.git
  144. cd PaperFlow
  145. pip install -e ".[all]" # full install (or `pip install -e .` for the minimal CLI)
  146. # 2. Configure providers (start with no-download settings; see below)
  147. cp .env.example .env
  148. # edit .env to set PAPERFLOW_LLM_PROVIDER and, for production, an embedding backend
  149. # 3. Initialize runtime + create your user profile (REQUIRED)
  150. paperflow init
  151. paperflow doctor
  152. paperflow profile \
  153. --user-id user_alice \
  154. --natural-language "I work on LLM agents for scientific discovery, \
  155. literature mining, and automated paper reading."
  156. # 4. Daily push (run every morning, or as often as you like)
  157. paperflow daily --user-id user_alice
  158. # 5. Read selected papers (paper IDs come from the latest daily push)
  159. paperflow read 1 3 7 --user-id user_alice
  160. # Optional: use the local browser GUI for steps 4-5
  161. paperflow gui
  162. ```
  163. > **Step 3 is mandatory.** `paperflow daily / read / feedback` all read the
  164. > profile created by `paperflow profile`. Skipping it means there's no
  165. > personalization signal to score against, so `paperflow read` has no push
  166. > to read from. See [Initialize a User Profile](#initialize-a-user-profile)
  167. > below for the four bootstrap methods (text / PDF / Google Scholar / homepage).
  168. ### Offline smoke test (no API keys)
  169. ```bash
  170. paperflow demo
  171. ```
  172. The demo uses deterministic mock/hash providers, so it does not need API keys
  173. or network access. Use it to confirm the install before configuring real
  174. providers.
  175. ## Configure Providers
  176. Copy the environment template:
  177. ```bash
  178. cp .env.example .env
  179. ```
  180. Use the `PAPERFLOW_*` variables as the canonical configuration surface. A
  181. fresh install defaults to no-download embeddings so `paperflow demo` and setup
  182. checks are quick, but real recommendation quality needs a semantic embedding
  183. backend.
  184. ### Option A: recommended production setup
  185. Use one OpenAI-compatible gateway for both generation and embeddings:
  186. ```env
  187. PAPERFLOW_LLM_PROVIDER=openai
  188. PAPERFLOW_LLM_MODEL=gpt-4o-mini
  189. PAPERFLOW_EMBED_PROVIDER=openai
  190. PAPERFLOW_EMBED_MODEL=text-embedding-3-small
  191. OPENAI_API_KEY=sk-...
  192. # OPENAI_BASE_URL=https://your-openai-compatible-gateway/v1
  193. ```
  194. OpenAI-compatible gateways are supported through `OPENAI_BASE_URL`, including
  195. OpenAI, DashScope, Azure OpenAI, vLLM, and similar services. If credentials are
  196. missing or still look like placeholders, PaperFlow falls back to mock/hash
  197. providers where possible so local workflows remain testable.
  198. ### Option B: no-download smoke test
  199. Use this for install checks, GUI demos, or classrooms where downloading model
  200. weights is not acceptable:
  201. ```env
  202. PAPERFLOW_LLM_PROVIDER=mock
  203. PAPERFLOW_EMBED_PROVIDER=hash
  204. ```
  205. This mode is deterministic and fast, but the hash vectors do not encode real
  206. semantic similarity. It is not the recommended setting for evaluating
  207. recommendation quality.
  208. ### Option C: high-quality local embeddings
  209. Use this only when the machine is allowed to download and cache local model
  210. weights:
  211. ```env
  212. PAPERFLOW_EMBED_PROVIDER=sentence_transformers
  213. PAPERFLOW_EMBED_MODEL=BAAI/bge-m3
  214. PAPERFLOW_EMBED_DIMENSIONS=1024
  215. ```
  216. This local mode needs no embedding API key, but the first run downloads the
  217. model weights. `BAAI/bge-m3` is about 2.3GB, so do not use it for quick
  218. classroom demos or first-run installation checks.
  219. After changing providers, run:
  220. ```bash
  221. paperflow doctor
  222. ```
  223. `paperflow doctor` prints the resolved provider configuration. Runtime data is
  224. stored under `data/` and is ignored by Git.
  225. ## Initialize a User Profile
  226. PaperFlow keeps **one profile per `user_id`**, and every other command
  227. (`daily`, `read`, `feedback`) reads from that profile. **You must create at
  228. least one profile before the first daily run** — otherwise `paperflow daily`
  229. has nothing to score against and `paperflow read` has no push to read from.
  230. You can bootstrap a profile from any of these four sources, or combine them:
  231. ```bash
  232. # (a) Self-description in natural language (fastest)
  233. paperflow profile \
  234. --user-id user_alice \
  235. --natural-language "I work on LLM agents for scientific discovery, \
  236. literature mining, and automated paper reading."
  237. # (b) One or more papers you have written or care about
  238. paperflow profile --user-id user_alice --pdf /path/to/my-paper.pdf
  239. # (c) A Google Scholar profile (PaperFlow scrapes the public page)
  240. paperflow profile \
  241. --user-id user_alice \
  242. --scholar-url "https://scholar.google.com/citations?user=..."
  243. # (d) A personal lab or homepage
  244. paperflow profile \
  245. --user-id user_alice \
  246. --homepage-url "https://example.edu/~alice"
  247. ```
  248. Repeated `paperflow profile` calls **merge** new signals into the existing
  249. profile by default. Use `--reset-existing` only when you want to rebuild it
  250. from scratch.
  251. Inspect the resulting profile any time with:
  252. ```bash
  253. python scripts/show_profile.py user_alice
  254. ```
  255. ## Local GUI
  256. Start the local browser GUI with:
  257. ```bash
  258. paperflow gui
  259. ```
  260. To preview the interface without installing PaperFlow, open the GitHub Pages
  261. mock-data preview:
  262. [PaperFlow GUI Preview](https://openraiser.github.io/PaperFlow/deployments/desktop/static/index.html?demo=1).
  263. The GUI uses the same local SQLite database as the CLI. It is designed for the
  264. real daily workflow, not a standalone mock:
  265. - select a user profile and inspect the profile-derived direction summary
  266. - pull papers for today's date, or intentionally fetch a previous date window
  267. - keep long-running daily pulls in backend task state while the UI polls status
  268. - mark papers as precision-read, not interested, or later
  269. - submit feedback and update the local profile/Wiki signal path
  270. - generate or reopen reading reports from paper cards
  271. - inspect the backend-derived Wiki graph and search local knowledge nodes
  272. - ask questions over the local Wiki with clickable references
  273. - configure providers, source modes, storage paths, and export behavior
  274. The desktop GUI does not run background schedules. Scheduled Feishu/Lark
  275. delivery still uses `deployments/feishu/`.
  276. Useful options:
  277. ```bash
  278. paperflow gui --port 8766
  279. paperflow gui --host 0.0.0.0 --no-browser
  280. ```
  281. Detailed GUI notes are in
  282. [deployments/desktop/README.md](https://github.com/OpenRaiser/PaperFlow/blob/main/deployments/desktop/README.md).
  283. ## CLI Usage
  284. ```bash
  285. paperflow --help
  286. ```
  287. | Command | Purpose |
  288. | --- | --- |
  289. | `paperflow init` | Create local runtime directories and SQLite tables |
  290. | `paperflow doctor` | Check dependencies, credentials, and runtime paths |
  291. | `paperflow demo` | Run an offline provider demo |
  292. | `paperflow profile` | Create or update a user profile from text, PDFs, Scholar, or homepage data |
  293. | `paperflow daily` | Generate a daily personalized paper push |
  294. | `paperflow read` | Generate a personalized reading report |
  295. | `paperflow wiki` | List, search, and inspect the local reading wiki |
  296. | `paperflow feedback` | Record feedback for a previous push |
  297. | `paperflow gui` | Start the local browser GUI |
  298. | `paperflow eval` | Evaluate PaperFlow-Bench predictions |
  299. Generate a daily recommendation card without sending it:
  300. ```bash
  301. paperflow daily \
  302. --user-id user_role1 \
  303. --days 1 \
  304. --output data/daily_push.txt \
  305. --dry-run
  306. ```
  307. Generate reading reports from paper IDs shown in a previous push:
  308. ```bash
  309. paperflow read 1 3 7 --user-id user_role1 --no-feishu
  310. ```
  311. By default, `paperflow read` uses that user's latest push in
  312. `data/paperflow.db`. To read from a specific previous push:
  313. ```bash
  314. paperflow read 1 3 7 --user-id user_role1 --push-id push_20260401_090000 --no-feishu
  315. ```
  316. Daily pushes, reading reports, feedback signals, and profile-drift snapshots
  317. are also ingested into the local PaperFlow Wiki. Inspect it:
  318. ```bash
  319. paperflow wiki backfill --user-id user_role1
  320. paperflow wiki topics --user-id user_role1
  321. paperflow wiki stats --user-id user_role1
  322. paperflow wiki search "graph rag" --user-id user_role1
  323. paperflow wiki ask "What have I read about graph RAG?" --user-id user_role1
  324. ```
  325. PDFs, reading-report Markdown, monthly reports, and Topic Index files can be
  326. saved directly into an Obsidian vault. Point all four export variables at the
  327. same upper-level folder:
  328. ```env
  329. PAPERFLOW_PDF_DIR=/Users/mario/Documents/Obsidian Vault/Daily Note/Daily Note 2026
  330. PAPERFLOW_READING_REPORTS_DIR=/Users/mario/Documents/Obsidian Vault/Daily Note/Daily Note 2026
  331. PAPERFLOW_MONTHLY_REPORT_DIR=/Users/mario/Documents/Obsidian Vault/Daily Note/Daily Note 2026
  332. PAPERFLOW_TOPIC_INDEX_DIR=/Users/mario/Documents/Obsidian Vault/Daily Note/Daily Note 2026
  333. PAPERFLOW_STORAGE_ROLE_SUBDIR=true
  334. PAPERFLOW_STORAGE_CATEGORY_SUBDIR=true
  335. PAPERFLOW_STORAGE_MONTHLY_SUBDIR=true
  336. ```
  337. Local exports are role-scoped by default. If `data/roles.json` maps `role1` to
  338. `user_role1`, then `--user-id user_role1` writes these folders:
  339. `role1/pdf/arXiv - May 2026/`, `role1/reading_reports/arXiv - May 2026/`,
  340. `role1/monthly_reports/`, and `role1/topic_index/`. Monthly report and Topic
  341. Index filenames also include the target month, for example
  342. `PaperFlow Monthly Report - role1 - 2026-05.md`.
  343. Set `PAPERFLOW_STORAGE_ROLE_SUBDIR=false` or
  344. `PAPERFLOW_STORAGE_CATEGORY_SUBDIR=false` only if you want a flatter legacy
  345. layout.
  346. Export a monthly reading summary and Topic Index for Obsidian:
  347. ```bash
  348. paperflow wiki monthly --user-id user_role1
  349. ```
  350. Without `--month`, PaperFlow exports the current calendar month. Use
  351. `--month 2026-05` only when you intentionally want to regenerate an older
  352. month.
  353. Feishu/Lark document export is optional and separate from the GUI and CLI core.
  354. Configuration is in [docs/feishu-doc-export.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feishu-doc-export.md).
  355. After configuring Feishu, CLI usage is:
  356. ```bash
  357. paperflow read 1 --user-id user_role1
  358. paperflow read 1 --user-id user_role1 --folder-id <feishu_folder_token>
  359. ```
  360. In the GUI, tick "同时尝试写入飞书文档" when generating a reading report.
  361. Record feedback:
  362. ```bash
  363. paperflow feedback \
  364. --user-id user_role1 \
  365. --push-id push_20260401_090000 \
  366. --reply "1, 3"
  367. ```
  368. Feedback from CLI, GUI, and Feishu/Lark bot replies is stored in the same
  369. SQLite database and updates the same profile for that `user_id`. See
  370. [docs/feedback-loop.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feedback-loop.md) for the full learning path.
  371. ## Feishu / Lark Bot
  372. The Feishu/Lark integration is optional. Use it when you want PaperFlow to run
  373. as a chat bot with scheduled pushes and weekly reports.
  374. If you only want reading reports exported as Feishu/Lark docs, use
  375. [docs/feishu-doc-export.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feishu-doc-export.md) instead; that path does
  376. not require ngrok or webhook callbacks.
  377. Add the Feishu/Lark and ngrok values to `.env`:
  378. ```env
  379. FEISHU_APP_ID=
  380. FEISHU_APP_SECRET=
  381. FEISHU_VERIFICATION_TOKEN=
  382. FEISHU_USER_ID=
  383. NGROK_AUTHTOKEN=
  384. NGROK_DOMAIN=
  385. ```
  386. Bind role chat IDs in `data/roles.json`, then start the local webhook server:
  387. ```bash
  388. python deployments/feishu/webhook-server/start-with-ngrok.py
  389. ```
  390. The script prints the public Request URL. Paste it into the Feishu/Lark event
  391. subscription page and enable `im.message.receive_v1`.
  392. Keep the process running if you want scheduled jobs:
  393. | Job | Default schedule |
  394. | --- | --- |
  395. | Daily paper push | 09:00, Asia/Shanghai |
  396. | Weekly report | Monday 10:00, Asia/Shanghai |
  397. Watch live logs:
  398. ```powershell
  399. Get-Content data/webhook_stderr.log -Wait
  400. ```
  401. Common chat commands:
  402. ```text
  403. profile
  404. daily push
  405. weekly report
  406. 1 3
  407. read 1
  408. ```
  409. Detailed setup:
  410. [docs/feishu-webhook-setup.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feishu-webhook-setup.md).
  411. ## PaperFlow-Bench
  412. PaperFlow-Bench is published on HuggingFace:
  413. [OpenRaiser/PaperFlow](https://huggingface.co/datasets/OpenRaiser/PaperFlow).
  414. Download:
  415. ```bash
  416. python experiments/benchmark/fetch_benchmark.py \
  417. --output-dir data/PaperFlow-Bench
  418. ```
  419. Create a simple valid prediction file from pool order:
  420. ```bash
  421. python experiments/benchmark/make_benchmark_submission.py \
  422. --benchmark-dir data/PaperFlow-Bench \
  423. --output data/PaperFlow-Bench/example_predictions.jsonl
  424. ```
  425. Evaluate:
  426. ```bash
  427. paperflow eval \
  428. --benchmark-dir data/PaperFlow-Bench \
  429. --predictions data/PaperFlow-Bench/example_predictions.jsonl \
  430. --output data/PaperFlow-Bench/example_metrics.json
  431. ```
  432. More benchmark details:
  433. - [docs/benchmark.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/benchmark.md)
  434. - [experiments/REPRODUCE.md](https://github.com/OpenRaiser/PaperFlow/blob/main/experiments/REPRODUCE.md)
  435. ## Workflow
  436. ```text
  437. research profile
  438. |
  439. v
  440. daily candidate pool -> scoring + drift adjustment -> paper digest
  441. | |
  442. v v
  443. arXiv / OpenReview / journals reading reports
  444. |
  445. v
  446. feedback + profile update
  447. |
  448. v
  449. tomorrow's recommendation
  450. ```
  451. ## Repository Layout
  452. ```text
  453. PaperFlow/
  454. paperflow/ CLI and provider abstraction
  455. agents/ Core workflow agents
  456. skills/ Fetching, parsing, profile, and storage helpers
  457. deployments/desktop/ Optional local browser GUI
  458. deployments/feishu/ Optional Feishu/Lark bot deployment
  459. experiments/ Benchmark and paper reproduction scripts
  460. scripts/ Operational utilities
  461. config/ Source, scoring, and direction configuration
  462. docs/ Setup and benchmark documentation
  463. tests/ Unit and integration tests
  464. ```
  465. ## Development Checks
  466. ```bash
  467. pytest tests -q
  468. pytest experiments/tests -q
  469. ```
  470. The GitHub Actions workflow runs the main test suite. Experiment tests are kept
  471. in `experiments/tests/` for benchmark and reproduction validation.
  472. ## Documentation
  473. For a complete guide map, see [docs/README.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/README.md). The most common
  474. follow-ups are:
  475. - [docs/quickstart.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/quickstart.md) for the first local run
  476. - [docs/configuration.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/configuration.md) for environment variables and paths
  477. - [docs/feedback-loop.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feedback-loop.md) for CLI / GUI / Feishu profile learning
  478. - [deployments/desktop/README.md](https://github.com/OpenRaiser/PaperFlow/blob/main/deployments/desktop/README.md) for local GUI behavior
  479. - [PaperFlow GUI Preview](https://openraiser.github.io/PaperFlow/deployments/desktop/static/index.html?demo=1) for a no-install UI preview
  480. - [docs/feishu-doc-export.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feishu-doc-export.md) for Feishu document export
  481. - [docs/feishu-webhook-setup.md](https://github.com/OpenRaiser/PaperFlow/blob/main/docs/feishu-webhook-setup.md) for webhook + ngrok bot deployment
  482. ## Citation
  483. If you use PaperFlow or PaperFlow-Bench in academic work, please cite:
  484. ```bibtex
  485. @article{wang2026paperflow,
  486. title={PaperFlow: Profiling, Recommending, and Adapting Across Daily Paper Streams},
  487. author={Wang, Fuqiang and Tan, Song and Guo, Zheng and Fu, Jiaohao and Xu, Xinglong and Yu, Bihui and Dong, Jie and Sun, Zheng and Li, Siyuan and Wei, Jingxuan and others},
  488. journal={arXiv preprint arXiv:2606.07454},
  489. year={2026}
  490. }
  491. ```
  492. The formal citation will be updated after the paper is published.
  493. ## License
  494. PaperFlow is released under the MIT License. See [LICENSE](https://github.com/OpenRaiser/PaperFlow/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.