papermind-ai 0.1.0__tar.gz

papermind_ai-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# PaperMind runtime
+.papermind/
+*.faiss
+report/
+*.report.json
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Playwright MCP browser artifacts / screenshots
+.playwright-mcp/
+
+# Dev-only scratch at the repo root (preview pages, screenshots, sample renders),
+# coverage, and the local MCP config. Real assets live under papermind/assets/ and
+# examples/figures/, so ignoring root-level images/PDFs is safe.
+examples/_*.html
+/preview.html
+/*.png
+/*.svg
+/*.pdf
+.coverage
+.mcp.json

papermind_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to PaperMind are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/); versions follow [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- **Bilingual web UI** — English by default with a 中文 toggle (resolved per request
+  via `?lang=`, a cookie, or `Accept-Language`).
+- Whole-method **framework diagram** — a per-paper end-to-end architecture figure
+  (paper-style SVG that also reconstructs steps the paper only implies, marked as
+  inferred). Available on the web `/framework` page and downloadable as SVG.
+- Broader paper sources, in addition to arXiv links / PDF URLs / local & uploaded
+  PDFs: a **DOI** (bare, `doi:`, or `doi.org`), a free-text **paper title** (resolved
+  via OpenAlex, then arXiv), and any academic **landing page** (resolved via its
+  `citation_pdf_url` meta tag — OpenReview, bioRxiv, ACL, PMLR, …).
+- **Gemini** as a first-class provider (chat + embeddings), alongside OpenAI,
+  Anthropic, and DeepSeek.
+- **Qwen (Aliyun Bailian / DashScope)** as a provider — `papermind config set
+  qwen-key …`, then use any `dashscope/…` model, e.g. `figure-model
+  dashscope/qwen3-max` for higher-fidelity teaching figures.
+
+### Changed
+- **Redesigned the web UI** (landing shell + report page) into one modern, light
+  "dev-tool" design system — system sans (no serif), near-white + indigo palette,
+  sticky top bar, dark mode, mobile-friendly — replacing the previous serif/beige,
+  emoji-heavy styling.
+- Title search resolves through OpenAlex (keyless, reliable) instead of the
+  rate-limited arXiv search API.
+
+### Fixed
+- Teaching SVG figures no longer show raw LaTeX (`^{}`, `_{}`, `\frac`, …) or
+  mis-rendered sub/superscripts, and multi-line report formulas render under MathJax
+  (wrapped in `aligned`); fixed several incorrect formulas in the example gallery.
+- The offline demo report no longer renders a "Syntax error · mermaid" box — its
+  figure is now a real teaching SVG.
+- A corrupt/partial `metadata.json` no longer crashes every subsequent analysis of
+  that paper (guarded read + atomic write).
+- Uploaded PDFs are content-addressed in the cache instead of leaking one temp file
+  per upload.
+- Title search degrades (PDF → DOI → arXiv) instead of hard-failing on a dead link.
+- Live web routes refund the per-IP rate-limit slot when a request fails.
+
+### Internal
+- CI runs the FastAPI web suite and a ruff (pyflakes) lint gate across Python 3.9–3.12.
+
+## [0.1.0]
+- Initial release: 4-module structured analysis, citation-verified grounded Q&A, a
+  trained cross-encoder retrieval reranker, a reproduction guide built from the
+  paper's real code repo, teaching SVG figures, and a CLI + web UI.

papermind_ai-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+PaperMind follows the spirit of the
+[Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Be respectful and constructive. Assume good faith, keep discussion technical, and
+welcome newcomers. Harassment, personal attacks, and discrimination are not tolerated.
+
+Report unacceptable behavior privately to the maintainers (via the repository profile
+or a GitHub Security Advisory). Reports are handled confidentially and in good faith.

papermind_ai-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to PaperMind
+
+Thanks for your interest! PaperMind aims to stay small, dependency-light, and easy to read.
+
+## Development setup
+
+```bash
+git clone https://github.com/Wenhao-Hua/papermind
+cd papermind
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Running tests
+
+Tests mock the LLM and avoid network, FAISS, and PyMuPDF, so they run fast and offline:
+
+```bash
+pytest
+```
+
+Please add a test alongside any new parsing rule, schema field, or answer-layering behavior.
+
+The web demo (`test_web.py`) needs the `web` extra — `pip install -e ".[dev,web]"`.
+
+## Running against a model
+
+Every provider is routed through `litellm`, so they're config, not code. Set a key
+(env var, or `papermind config set <name>-key ...`) and pick a model:
+
+| Provider | Key | Example model |
+| --- | --- | --- |
+| OpenAI (default) | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-5-sonnet-latest` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
+| Gemini | `GEMINI_API_KEY` | `gemini/gemini-2.5-flash` |
+| Local / free | — | `--local` (Ollama) |
+
+Override the model with `--model` / `PAPERMIND_MODEL` and embeddings with
+`PAPERMIND_EMBEDDING_MODEL`. `papermind demo` runs fully offline with no key.
+
+## Architecture at a glance
+
+```
+papermind/
+├── cli.py            # typer entry point (lazy-imports heavy work)
+├── analyze.py        # orchestration: resolve → parse → modules → figures → Report
+├── config.py         # keys / model / cache resolution (env > file > default)
+├── parser/           # arxiv.py (download+meta), pdf.py (text+figures)
+├── modules/          # contributions / technical / connections / reproduction
+├── figures/          # extract.py (match originals), generate.py (teaching SVGs; legacy Mermaid), framework.py (whole-method diagram: spec + deterministic SVG renderer)
+├── qa/               # index.py (chunk+FAISS), retriever.py, chat.py (PaperChat)
+├── repro/            # repo.py (locate & verify the paper's official code repo)
+├── rerank/           # infer.py (trained cross-encoder reranker inference)
+├── llm/              # base.py (litellm wrapper), prompts.py (all prompts)
+└── output/           # schema.py (pydantic, single source of truth), markdown/json/terminal
+```
+
+## Guidelines
+
+- **Keep dependencies minimal.** No LangChain or heavyweight frameworks. Heavy imports
+  (`litellm`, `faiss`, `fitz`, `numpy`) must stay **lazy** so `papermind --help`/`config`
+  work without them.
+- **Prompts live in one place** — [`papermind/llm/prompts.py`](papermind/llm/prompts.py).
+- **`output/schema.py` is the single source of truth.** Change it first, then renderers.
+- **Parse LLM JSON defensively.** A single malformed field should never sink a whole report
+  (see [`papermind/modules/_util.py`](papermind/modules/_util.py)).
+- **Type-annotate public functions and all pydantic models.**
+- Match the existing style; keep changes surgical.
+
+## Submitting changes
+
+1. Branch from `main`.
+2. Add/update tests; run `pytest`.
+3. Open a PR describing the change and its motivation.
+
+By contributing you agree your work is licensed under the project's [MIT License](LICENSE).

papermind_ai-0.1.0/Dockerfile

@@ -0,0 +1,17 @@
+# PaperMind web service — public-safe by default (demo mode: cached reports only).
+# Build:  docker build -t papermind .
+# Run:    docker run -p 8080:8080 papermind
+# Live:   docker run -p 8080:8080 -e OPENAI_API_KEY=sk-... papermind \
+#                papermind serve --host 0.0.0.0 --port 8080 --live
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY . /app
+
+# faiss-cpu / pymupdf / litellm ship manylinux wheels, so no build toolchain needed.
+RUN pip install --no-cache-dir ".[web]"
+
+EXPOSE 8080
+# Demo mode by default: serves only already-cached reports, makes no model calls,
+# so exposing it publicly won't burn an API key. Add `--live` (and a key) for real analysis.
+CMD ["papermind", "serve", "--host", "0.0.0.0", "--port", "8080"]

papermind_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PaperMind contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

papermind_ai-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: papermind-ai
+Version: 0.1.0
+Summary: Read arXiv papers for real: structured analysis, grounded RAG Q&A, and reproduction tutoring from the command line.
+Project-URL: Homepage, https://github.com/Wenhao-Hua/papermind
+Project-URL: Repository, https://github.com/Wenhao-Hua/papermind
+Project-URL: Issues, https://github.com/Wenhao-Hua/papermind/issues
+Project-URL: Changelog, https://github.com/Wenhao-Hua/papermind/blob/main/CHANGELOG.md
+Author: PaperMind contributors
+License: MIT
+License-File: LICENSE
+Keywords: arxiv,citation,cli,cross-encoder,grounded-qa,litellm,llm,paper,paper-reading,rag,reproducibility,reproduction,reranker,research,scientific-papers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: faiss-cpu>=1.7.4
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: litellm<2.0,>=1.40.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic<3,>=2.0.0
+Requires-Dist: pymupdf>=1.23.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: local-embeddings
+Requires-Dist: sentence-transformers>=2.2.0; extra == 'local-embeddings'
+Provides-Extra: train
+Requires-Dist: rank-bm25>=0.2.2; extra == 'train'
+Requires-Dist: sentence-transformers>=2.7.0; extra == 'train'
+Provides-Extra: ui
+Requires-Dist: fastapi>=0.110.0; extra == 'ui'
+Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
+Requires-Dist: uvicorn>=0.27.0; extra == 'ui'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110.0; extra == 'web'
+Requires-Dist: python-multipart>=0.0.9; extra == 'web'
+Requires-Dist: uvicorn>=0.27.0; extra == 'web'
+Description-Content-Type: text/markdown
+
+# PaperMind
+
+**English · [简体中文](README.zh-CN.md)**
+
+> **Read any paper — from skim to reproduction — with every key claim traced back to the source.**
+> Paste an arXiv link, DOI, paper title, or any paper page / PDF URL (or upload a PDF): structured analysis, grounded & citation‑verified Q&A, a whole‑method framework diagram (downloadable SVG), and a runnable reproduction guide.
+
+[![CI](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml/badge.svg)](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![Python](https://img.shields.io/pypi/pyversions/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+<p align="center">
+  <img src="papermind/assets/hero.svg" alt="A paper-style teaching diagram PaperMind generates for a technical point" width="760">
+</p>
+<p align="center">
+  <sub>↑ A <b>paper-style teaching diagram PaperMind generates</b> for a technical point (real output) ·
+  <a href="examples/transformer.md"><b>full sample report</b></a> · <a href="examples/README.md">gallery →</a></sub>
+</p>
+
+## Why it isn't just another chat‑with‑PDF
+
+- **🔬 We trained our own retrieval reranker — +14pt Recall@5 over a strong dense baseline** (QASPER, held‑out test). Most "chat with a paper" tools wrap an API; PaperMind's evidence retrieval is a cross‑encoder we fine‑tuned and measured (see [Benchmarks](#benchmarks-the-reranker-is-trained-and-measured-not-a-black-box)).
+- **🔎 Key claims are labeled and citation‑verified.** Answers are split into **fact / inference (with confidence) / out‑of‑scope**, and each cited quote is checked against the actual paper text — if it can't be found, it's flagged ⚠️ rather than silently trusted.
+- **📐 Whole‑method framework diagram.** Beyond per‑point figures, PaperMind reconstructs the paper's end‑to‑end method as a single Figure‑1‑style architecture diagram (steps the paper only implies are marked *inferred*) — view it on the web `/framework` tab and download it as SVG.
+- **🛠️ Reproduction grounded in the real code repo.** PaperMind locates the paper's code repository and builds `setup.sh` from the repo's **actual dependency file and README run‑commands** — not a hallucinated guess.
+- **🆓 Runs fully local & free.** `papermind demo` works offline; `--local` routes everything through Ollama; with no key it auto‑falls back to local.
+
+| | **PaperMind** | Typical chat‑with‑PDF / SaaS readers |
+| --- | :---: | :---: |
+| Per‑claim citation **with verification** (flags unverifiable ⚠️) | ✅ | — |
+| Reproduction → runnable `setup.sh` from the **real** repo | ✅ | — |
+| **Self‑trained** RAG reranker, measured on QASPER | ✅ | — |
+| Runs **fully local / offline, zero cost** | ✅ | ✗ |
+| **Open‑source & self‑hostable** | ✅ | ✗ |
+
+<sub>“—” = not a documented capability we're aware of; open an issue to correct us. Open‑source/local rows are clear‑cut for closed SaaS tools.</sub>
+
+## Three ways to use it
+
+| | How | Best for |
+| --- | --- | --- |
+| 🌐 **Online** | open **[papermind.try2026.cn](https://papermind.try2026.cn)** — zero install | trying it instantly |
+| 🖥️ **GUI** | `pip install "papermind-ai[web]"` → `papermind ui` | full features, in your browser |
+| ⌨️ **CLI / API** | `pip install papermind-ai` → `papermind analyze https://arxiv.org/abs/2307.08691` | scripting, batch, integration |
+
+> 🆓 No spend: `papermind demo` shows the output offline (no key); add `--local` to any command to run fully on local Ollama at zero cost.
+
+## What you get
+
+```
+╭──────────────── Attention Is All You Need · 2017 · arXiv:1706.03762 ───────────────╮
+🎯 Contributions   A fully attention-based model (Transformer): no recurrence/convolution…
+🔬 Technical       1. Scaled Dot-Product Attention [high]  softmax(QKᵀ/√d_k)·V; scaling avoids
+                      saturated gradients   💡 analogy + 📊 paper-style teaching diagram (SVG)
+💬 Grounded Q&A    "Why divide by √d_k?" → [FACT] large d_k inflates dot-product variance…
+                      📌 source Section 3.2.1 (p.4) ✓ verified
+🛠️ Reproduction    code repo (★24k) github.com/… → setup.sh (real deps + README run commands)
+```
+
+Full rendered reports (open on GitHub — paper‑style diagrams, jump‑to‑source citations, reproduction tables):
+**[Transformer](examples/transformer.md)** · **[ViT](examples/vit.md)** · **[PPO](examples/ppo.md)** · **[the full gallery →](examples/README.md)**
+
+## Gallery — 7 papers across 5 areas
+
+PaperMind isn't NLP‑only. Real reports generated by the pipeline, grouped by area:
+
+| Area | Papers |
+| --- | --- |
+| **NLP / Attention** | [Transformer](examples/transformer.md) · [FlashAttention‑2](examples/flashattention2.md) · [Llama 2](examples/llama2.md) |
+| **Computer Vision** | [ViT](examples/vit.md) |
+| **Generative / Diffusion** | [Latent Diffusion (Stable Diffusion)](examples/latent-diffusion.md) |
+| **Reinforcement Learning** | [PPO](examples/ppo.md) |
+| **Efficient fine‑tuning** | [LoRA](examples/lora.md) |
+
+## Benchmarks — the reranker is trained and measured, not a black box
+
+We fine‑tuned a cross‑encoder reranker (`bge‑reranker‑base`) on **QASPER**. Over all‑paragraph candidates, versus a strong dense baseline:
+
+| | Recall@5 | MRR | nDCG@10 |
+| --- | --- | --- | --- |
+| Dense (`bge‑small‑en‑v1.5`) | 0.519 | 0.463 | 0.469 |
+| **+ our reranker** | **0.660** | **0.612** | **0.609** |
+
+Consistent across dev (888 q) and a held‑out test (1309 q) — no overfitting. Reproduce it: [`docs/RESEARCH_PLAN.md`](docs/RESEARCH_PLAN.md) (`trainer/` to train · `evaluation/` to evaluate).
+
+## Self‑host the online service
+
+One Docker command. Public exposure is safe by default (demo mode is read‑only cache, never spends a key):
+
+```bash
+git clone https://github.com/Wenhao-Hua/papermind && cd papermind
+docker build -t papermind . && docker run -p 8080:8080 papermind            # demo mode
+
+docker run -p 8080:8080 -e OPENAI_API_KEY=sk-... -e PAPERMIND_TRUST_PROXY=1 papermind \
+       papermind serve --host 0.0.0.0 --port 8080 --live                    # live (your key, billed)
+```
+
+> **`--live` is rate‑limited by default** (8/IP/day, 300/day global; tune with `--rate-per-ip` / `--rate-global`, `0` = unlimited) so a public deployment can't drain your key. Free ops (search / cached / offline demo) aren't limited.
+>
+> **Behind Cloudflare/a reverse proxy, set `PAPERMIND_TRUST_PROXY=1`** — otherwise every visitor shares one per‑IP quota (the proxy's IP) and per‑IP limiting silently breaks. Only set it when you're actually behind a trusted proxy that sets `cf-connecting-ip`.
+>
+> **Faster figures:** diagrams default to the main model (cleanest layout, slower). Point figures at a fast non‑thinking model to speed them up: `papermind config set figure-model deepseek/deepseek-chat`.
+
+## What it can do
+
+`analyze` (4‑module report) · `summary` (TL;DR) · `ask`/`chat` (grounded Q&A) · `tutor`/`debug` (reproduction help) · `compare` (multi‑paper) · `reproduce` (export setup.sh / notebook) · `search`/`batch`/`list` · `cite`.
+
+Models via [litellm](https://github.com/BerriAI/litellm): OpenAI / Anthropic / DeepSeek / Gemini / Qwen (DashScope) / local Ollama. Results are cached locally — re‑runs are instant. More: `papermind --help`.
+
+## Contributing / License
+
+PRs and issues welcome ([CONTRIBUTING.md](CONTRIBUTING.md)) · [MIT](LICENSE)

papermind_ai-0.1.0/README.md

@@ -0,0 +1,113 @@
+# PaperMind
+
+**English · [简体中文](README.zh-CN.md)**
+
+> **Read any paper — from skim to reproduction — with every key claim traced back to the source.**
+> Paste an arXiv link, DOI, paper title, or any paper page / PDF URL (or upload a PDF): structured analysis, grounded & citation‑verified Q&A, a whole‑method framework diagram (downloadable SVG), and a runnable reproduction guide.
+
+[![CI](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml/badge.svg)](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![Python](https://img.shields.io/pypi/pyversions/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+<p align="center">
+  <img src="papermind/assets/hero.svg" alt="A paper-style teaching diagram PaperMind generates for a technical point" width="760">
+</p>
+<p align="center">
+  <sub>↑ A <b>paper-style teaching diagram PaperMind generates</b> for a technical point (real output) ·
+  <a href="examples/transformer.md"><b>full sample report</b></a> · <a href="examples/README.md">gallery →</a></sub>
+</p>
+
+## Why it isn't just another chat‑with‑PDF
+
+- **🔬 We trained our own retrieval reranker — +14pt Recall@5 over a strong dense baseline** (QASPER, held‑out test). Most "chat with a paper" tools wrap an API; PaperMind's evidence retrieval is a cross‑encoder we fine‑tuned and measured (see [Benchmarks](#benchmarks-the-reranker-is-trained-and-measured-not-a-black-box)).
+- **🔎 Key claims are labeled and citation‑verified.** Answers are split into **fact / inference (with confidence) / out‑of‑scope**, and each cited quote is checked against the actual paper text — if it can't be found, it's flagged ⚠️ rather than silently trusted.
+- **📐 Whole‑method framework diagram.** Beyond per‑point figures, PaperMind reconstructs the paper's end‑to‑end method as a single Figure‑1‑style architecture diagram (steps the paper only implies are marked *inferred*) — view it on the web `/framework` tab and download it as SVG.
+- **🛠️ Reproduction grounded in the real code repo.** PaperMind locates the paper's code repository and builds `setup.sh` from the repo's **actual dependency file and README run‑commands** — not a hallucinated guess.
+- **🆓 Runs fully local & free.** `papermind demo` works offline; `--local` routes everything through Ollama; with no key it auto‑falls back to local.
+
+| | **PaperMind** | Typical chat‑with‑PDF / SaaS readers |
+| --- | :---: | :---: |
+| Per‑claim citation **with verification** (flags unverifiable ⚠️) | ✅ | — |
+| Reproduction → runnable `setup.sh` from the **real** repo | ✅ | — |
+| **Self‑trained** RAG reranker, measured on QASPER | ✅ | — |
+| Runs **fully local / offline, zero cost** | ✅ | ✗ |
+| **Open‑source & self‑hostable** | ✅ | ✗ |
+
+<sub>“—” = not a documented capability we're aware of; open an issue to correct us. Open‑source/local rows are clear‑cut for closed SaaS tools.</sub>
+
+## Three ways to use it
+
+| | How | Best for |
+| --- | --- | --- |
+| 🌐 **Online** | open **[papermind.try2026.cn](https://papermind.try2026.cn)** — zero install | trying it instantly |
+| 🖥️ **GUI** | `pip install "papermind-ai[web]"` → `papermind ui` | full features, in your browser |
+| ⌨️ **CLI / API** | `pip install papermind-ai` → `papermind analyze https://arxiv.org/abs/2307.08691` | scripting, batch, integration |
+
+> 🆓 No spend: `papermind demo` shows the output offline (no key); add `--local` to any command to run fully on local Ollama at zero cost.
+
+## What you get
+
+```
+╭──────────────── Attention Is All You Need · 2017 · arXiv:1706.03762 ───────────────╮
+🎯 Contributions   A fully attention-based model (Transformer): no recurrence/convolution…
+🔬 Technical       1. Scaled Dot-Product Attention [high]  softmax(QKᵀ/√d_k)·V; scaling avoids
+                      saturated gradients   💡 analogy + 📊 paper-style teaching diagram (SVG)
+💬 Grounded Q&A    "Why divide by √d_k?" → [FACT] large d_k inflates dot-product variance…
+                      📌 source Section 3.2.1 (p.4) ✓ verified
+🛠️ Reproduction    code repo (★24k) github.com/… → setup.sh (real deps + README run commands)
+```
+
+Full rendered reports (open on GitHub — paper‑style diagrams, jump‑to‑source citations, reproduction tables):
+**[Transformer](examples/transformer.md)** · **[ViT](examples/vit.md)** · **[PPO](examples/ppo.md)** · **[the full gallery →](examples/README.md)**
+
+## Gallery — 7 papers across 5 areas
+
+PaperMind isn't NLP‑only. Real reports generated by the pipeline, grouped by area:
+
+| Area | Papers |
+| --- | --- |
+| **NLP / Attention** | [Transformer](examples/transformer.md) · [FlashAttention‑2](examples/flashattention2.md) · [Llama 2](examples/llama2.md) |
+| **Computer Vision** | [ViT](examples/vit.md) |
+| **Generative / Diffusion** | [Latent Diffusion (Stable Diffusion)](examples/latent-diffusion.md) |
+| **Reinforcement Learning** | [PPO](examples/ppo.md) |
+| **Efficient fine‑tuning** | [LoRA](examples/lora.md) |
+
+## Benchmarks — the reranker is trained and measured, not a black box
+
+We fine‑tuned a cross‑encoder reranker (`bge‑reranker‑base`) on **QASPER**. Over all‑paragraph candidates, versus a strong dense baseline:
+
+| | Recall@5 | MRR | nDCG@10 |
+| --- | --- | --- | --- |
+| Dense (`bge‑small‑en‑v1.5`) | 0.519 | 0.463 | 0.469 |
+| **+ our reranker** | **0.660** | **0.612** | **0.609** |
+
+Consistent across dev (888 q) and a held‑out test (1309 q) — no overfitting. Reproduce it: [`docs/RESEARCH_PLAN.md`](docs/RESEARCH_PLAN.md) (`trainer/` to train · `evaluation/` to evaluate).
+
+## Self‑host the online service
+
+One Docker command. Public exposure is safe by default (demo mode is read‑only cache, never spends a key):
+
+```bash
+git clone https://github.com/Wenhao-Hua/papermind && cd papermind
+docker build -t papermind . && docker run -p 8080:8080 papermind            # demo mode
+
+docker run -p 8080:8080 -e OPENAI_API_KEY=sk-... -e PAPERMIND_TRUST_PROXY=1 papermind \
+       papermind serve --host 0.0.0.0 --port 8080 --live                    # live (your key, billed)
+```
+
+> **`--live` is rate‑limited by default** (8/IP/day, 300/day global; tune with `--rate-per-ip` / `--rate-global`, `0` = unlimited) so a public deployment can't drain your key. Free ops (search / cached / offline demo) aren't limited.
+>
+> **Behind Cloudflare/a reverse proxy, set `PAPERMIND_TRUST_PROXY=1`** — otherwise every visitor shares one per‑IP quota (the proxy's IP) and per‑IP limiting silently breaks. Only set it when you're actually behind a trusted proxy that sets `cf-connecting-ip`.
+>
+> **Faster figures:** diagrams default to the main model (cleanest layout, slower). Point figures at a fast non‑thinking model to speed them up: `papermind config set figure-model deepseek/deepseek-chat`.
+
+## What it can do
+
+`analyze` (4‑module report) · `summary` (TL;DR) · `ask`/`chat` (grounded Q&A) · `tutor`/`debug` (reproduction help) · `compare` (multi‑paper) · `reproduce` (export setup.sh / notebook) · `search`/`batch`/`list` · `cite`.
+
+Models via [litellm](https://github.com/BerriAI/litellm): OpenAI / Anthropic / DeepSeek / Gemini / Qwen (DashScope) / local Ollama. Results are cached locally — re‑runs are instant. More: `papermind --help`.
+
+## Contributing / License
+
+PRs and issues welcome ([CONTRIBUTING.md](CONTRIBUTING.md)) · [MIT](LICENSE)

papermind_ai-0.1.0/README.zh-CN.md

@@ -0,0 +1,112 @@
+# PaperMind
+
+**[English](README.md) · 简体中文**
+
+> **把任意论文读懂、读到能复现 —— 关键判断都标原文出处、逐条核验。**
+> 输入 arXiv 链接 / DOI / 论文标题 / 论文页面或 PDF 直链（也可上传 PDF）：结构化分析、带原文依据并核验的问答、整篇方法的**框架图**（可下载 SVG）、可运行的复现指南。
+
+[![CI](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml/badge.svg)](https://github.com/Wenhao-Hua/papermind/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![Python](https://img.shields.io/pypi/pyversions/papermind-ai)](https://pypi.org/project/papermind-ai/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+<p align="center">
+  <img src="examples/figures/transformer-fig2.svg" alt="PaperMind 为论文技术点生成的论文式教学示意图" width="760">
+</p>
+<p align="center">
+  <sub>↑ PaperMind 为论文技术点<b>生成的论文式教学示意图</b>（管线真实产物）·
+  <a href="examples/transformer.md"><b>看完整样例报告</b></a> · <a href="examples/README.md">样例画廊 →</a></sub>
+</p>
+
+## 凭什么不是「又一个 chat-with-PDF」
+
+- **🔬 我们自训练了检索重排器 —— 相对强稠密基线 Recall@5 +14pt**（QASPER 独立 test）。多数「和论文对话」工具只是套 API；PaperMind 的证据检索是我们**自己微调并实测**的 cross-encoder（见 [实测数据](#实测重排器是自训练实测的不是黑箱)）。
+- **🔎 关键判断分层标注、逐条核验。** 回答分 **论文事实 / 推理(带置信度) / 超纲**，每条引用都对着原文核验——核不到就标 ⚠️，绝不默默当真。
+- **📐 整篇方法的框架图。** 除了逐技术点的配图，PaperMind 还把论文的端到端方法重建成一张 Figure‑1 式的总览架构图（论文只隐含、未画出的步骤标注为*推断*）——在网页 `/framework` 页查看，可下载为 SVG。
+- **🛠️ 复现接论文的真实代码仓库。** 自动定位论文的代码仓库，用仓库里**真实的依赖文件和 README 运行命令**生成 `setup.sh`，不是模型瞎猜。
+- **🆓 全本地、零成本可跑。** `papermind demo` 离线看；`--local` 全程走 Ollama；没 key 自动回退本地。
+
+| | **PaperMind** | 常见 chat-with-PDF / SaaS 阅读器 |
+| --- | :---: | :---: |
+| 逐条引用**并核验**（核不到标 ⚠️） | ✅ | — |
+| 复现 → 接**真实仓库**的可运行 `setup.sh` | ✅ | — |
+| **自训练** RAG 重排器、QASPER 实测 | ✅ | — |
+| **全本地 / 离线、零成本**运行 | ✅ | ✗ |
+| **开源、可自托管** | ✅ | ✗ |
+
+<sub>“—” = 据我们所知对方未公开该能力（欢迎 issue 指正）；开源/本地两行对闭源 SaaS 是明确的。</sub>
+
+## 三种用法，挑最方便的
+
+| | 怎么用 | 适合 |
+| --- | --- | --- |
+| 🌐 **在线用** | 打开 **[papermind.try2026.cn](https://papermind.try2026.cn)**，零安装 | 想立刻试、不装东西 |
+| 🖥️ **图形界面** | `pip install "papermind-ai[web]"` → `papermind ui` | 本地全功能、浏览器操作 |
+| ⌨️ **命令行 / API** | `pip install papermind-ai` → `papermind analyze https://arxiv.org/abs/2307.08691` | 脚本化、批量、集成 |
+
+> 🆓 不想花钱：`papermind demo` 离线看效果（无需 key）；任何命令加 `--local` 走本地 Ollama，全程零成本。
+
+## 效果
+
+```
+╭──────────────── Attention Is All You Need · 2017 · arXiv:1706.03762 ───────────────╮
+🎯 核心贡献   提出完全基于注意力的 Transformer，去掉循环与卷积，机器翻译刷新 SOTA…
+🔬 技术细节   1. 缩放点积注意力 [high]  Q·Kᵀ 除以 √d_k 再 softmax 加权 V；缩放避免梯度饱和
+              💡 类比：像搜索引擎按匹配度加权汇总文档；📊 附论文式教学示意图（SVG）
+💬 问答       「为什么除以 √d_k？」→【论文事实】维度大时点积方差大… 📌 出处 Section 3.2.1 (p.4) ✓已核验
+🛠️ 复现       代码仓库（★24k）github.com/... → setup.sh（真实依赖 + README 运行命令）
+```
+
+完整渲染样例（GitHub 直接打开——论文式示意图、可跳转原文出处、复现表格）：
+**[Transformer](examples/transformer.md)** · **[ViT](examples/vit.md)** · **[PPO](examples/ppo.md)** · **[完整画廊 →](examples/README.md)**
+
+## 样例画廊 —— 7 篇论文，跨 5 个领域
+
+PaperMind 不只懂 NLP。下面都是管线真实跑出来的报告，按领域分组：
+
+| 领域 | 论文 |
+| --- | --- |
+| **NLP / 注意力** | [Transformer](examples/transformer.md) · [FlashAttention‑2](examples/flashattention2.md) · [Llama 2](examples/llama2.md) |
+| **计算机视觉** | [ViT](examples/vit.md) |
+| **生成 / 扩散** | [Latent Diffusion (Stable Diffusion)](examples/latent-diffusion.md) |
+| **强化学习** | [PPO](examples/ppo.md) |
+| **高效微调** | [LoRA](examples/lora.md) |
+
+## 实测——重排器是自训练、实测的，不是黑箱
+
+在 **QASPER** 上自训练 cross-encoder 重排器（`bge-reranker-base`），全段落候选下相对强稠密基线：
+
+| | Recall@5 | MRR | nDCG@10 |
+| --- | --- | --- | --- |
+| Dense (`bge-small-en-v1.5`) | 0.519 | 0.463 | 0.469 |
+| **+ 自训练 Reranker** | **0.660** | **0.612** | **0.609** |
+
+dev（888 题）与独立 test（1309 题）一致，无过拟合。复现：[`docs/RESEARCH_PLAN.md`](docs/RESEARCH_PLAN.md)（`trainer/` 训练 · `evaluation/` 评测）。
+
+## 自托管在线服务
+
+Docker 一行起服务，公网暴露也安全（默认演示模式只读缓存、不烧 key）：
+
+```bash
+git clone https://github.com/Wenhao-Hua/papermind && cd papermind
+docker build -t papermind . && docker run -p 8080:8080 papermind            # 演示模式
+
+docker run -p 8080:8080 -e OPENAI_API_KEY=sk-... -e PAPERMIND_TRUST_PROXY=1 papermind \
+       papermind serve --host 0.0.0.0 --port 8080 --live                    # 实时分析（你的 key 付费）
+```
+
+> **`--live` 默认带限流**（每 IP 8 次/天、全局 300 次/天，可用 `--rate-per-ip` / `--rate-global` 调，`0` 表示不限）——公开挂出去也不会被陌生人刷爆你的 key。免费操作（搜索 / 缓存 / 离线 demo）不受限。
+>
+> **部署在 Cloudflare / 反向代理后面时，要设 `PAPERMIND_TRUST_PROXY=1`** ——否则所有访客共用同一个 per-IP 配额（代理的 IP），per-IP 限流会静默失效。仅当确实在会设置 `cf-connecting-ip` 的可信代理后面才开启。
+>
+> **想加快出图**：配图默认用主模型（布局最干净但慢）。给配图单独配一个快速的非思考模型即可大幅提速：`papermind config set figure-model deepseek/deepseek-chat`。
+
+## 能做什么
+
+`analyze`（四模块报告）· `summary`（TL;DR）· `ask`/`chat`（带依据问答）· `tutor`/`debug`（复现辅导）· `compare`（多篇对比）· `reproduce`（导出 setup.sh/notebook）· `search`/`batch`/`list` · `cite`。
+
+模型走 [litellm](https://github.com/BerriAI/litellm)：OpenAI / Anthropic / DeepSeek / Gemini / Qwen（百炼）/ 本地 Ollama 任选；结果本地缓存，二次运行秒出。更多用法：`papermind --help`。
+
+## 贡献 / License
+
+欢迎 PR / issue（[CONTRIBUTING.md](CONTRIBUTING.md)）· [MIT](LICENSE)

papermind_ai-0.1.0/RELEASING.md

@@ -0,0 +1,35 @@
+# Releasing PaperMind
+
+Releases are published to [PyPI](https://pypi.org/project/paper-mind/) automatically by
+the [`Release`](.github/workflows/release.yml) workflow when a `vX.Y.Z` tag is pushed.
+
+## One-time setup
+
+1. Create the project on PyPI (or reserve the name).
+2. Configure **Trusted Publishing** (no API token needed): on PyPI →
+   *Manage project* → *Publishing* → add a GitHub Actions publisher for
+   `Wenhao-Hua/papermind`, workflow `release.yml`, environment `pypi`.
+3. In the GitHub repo, create an Environment named `pypi`.
+
+## Cutting a release
+
+1. Bump the version in [`pyproject.toml`](pyproject.toml) and
+   `papermind/__init__.py` (`__version__`). Keep them in sync.
+2. Update any changelog notes, commit.
+3. Tag and push:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+4. The `Release` workflow builds the sdist + wheel and publishes to PyPI.
+5. Verify: `pip install paper-mind` in a clean environment.
+
+## Pre-release checklist
+
+- [ ] `pytest` passes locally and in CI.
+- [ ] `pip install -e .` works from a fresh clone.
+- [ ] `papermind --help`, `papermind config show` work.
+- [ ] README install/usage commands are accurate.
+- [ ] Version bumped in both `pyproject.toml` and `__init__.py`.