paper-piggy

<div align="center"> # Tool List **Transform Your Literature Library into an AI-Powered Research Assistant** A Desktop Application for Legal and Social Science Researchers [](LICENSE) []() []() [](https://github.com/DrinkTea905/paper-piggy/releases) [](https://github.com/DrinkTea905/paper-piggy/stargazers) </div> --- ## What is This Transform your Zotero library (or any folder filled with PDFs) into an indexed repository, and **let AI agents like Claude Code take control of it**—not just by dragging PDFs into a chatbox, but by enabling the agent to search, navigate to specific pages, verify citations, and compile conclusions into accumulative knowledge pages. --- ## 🤖 What Can the Agent Do (The Focus of This Project) After integrating with MCP, the AI gains access to **32 tools**. These tools are not just fancy wrappers around a single "search" action but a comprehensive research workflow. ### It Can Read and Know Which Page It's On The agent doesn't just provide a 220-word snippet when searching; it can **read the full text** (page by page) and provide **journal page numbers** (the actual page numbers you'd see in a printed journal, not "PDF page 37"). This means you can directly use AI-generated footnotes in your paper. ### It Can't Fabricate Information Because There Are Tools to Verify This is fundamentally different from simply feeding PDFs into a chatbox: | Tool | Function | |---|---| | **Citation Verification** | Given a citation, verify if the statement exists in the original text and on which page. Use this before writing footnotes to prevent fabricated citations. | | **Argument Verification** | Given a substantial argument, return its status: supported by library evidence, contradicted by library evidence, or no relevant evidence in the library. In the third case, the AI must admit it doesn't know rather than fabricating a reference. | | **Coverage Honesty Labeling** | When generating reviews, label each subtopic as ◎sufficient ○partial △weak ▲mostly missing and explicitly state where the material gaps are—not covering up gaps with "your library doesn't have it" as if it's a scholarly blank. | ### It Has Its Own Workspace, and It's Human-Readable After integration, PaperPiggy will create two folders in the **installation directory** (where the index and models are stored, e.g., `D:\PaperPiggy\`), which work independently of your Zotero library: ``` 0_Agent资料库/ ← What the AI uses to work (not your literature) ├─ 记忆/ │ ├─ 项目记忆.md What has been decided: who you are, your preferences, decisions made, and what you're doing │ └─ 变更日志.md Historical log (only additions, no changes) ├─ 技能/ ★ Workflow, one process per .md file — you can directly modify │ ├─ 写论文与综述.md │ ├─ 维护综述库.md │ └─ 跨学科发散与补文献.md ├─ 参考格式/ Place your template .docx here, and the AI will format accordingly ├─ 交付模板/ Modify here = modify the output format of the AI └─ 定时任务/ What to do periodically, how often, and where to save the results 0_Agent交付物/ ← Finished products are stored here (draft papers, compilations, weekly reports) ``` **The key point is that all these are in Markdown format, stored locally, and you can access and modify them anytime.** - **Switch AI assistants without starting over.** From Claude Code to another agent? The new assistant reads through `0_Agent资料库/`, and it picks up all previous decisions, preferences, and progress. Memories are not locked to a specific vendor's server. - **The workflow is yours, not mine.** `技能/写论文与综述.md` is just the default. If the citation style is incorrect, negotiate with the AI to modify this file. Your modifications won't be overwritten during updates (a new version will be saved for you to merge). ### Three Out-of-the-Box Workflows | Workflow | Function | |---|---| | **Write Papers and Reviews** | Topic decomposition → Three-level outline (each section with ★core/☆auxiliary literature) → Evidence recall for each section → Writing a review with page-level citations → Labeling material gaps and suggestions for further search | | **Maintain Review Library** | Organize scattered conclusions into interconnected knowledge pages; check for orphan pages, broken links, and outdated pages | | **Interdisciplinary Divergence and Literature Supplementation** | Used before writing: open up theoretical perspectives, find transferable frameworks from other disciplines, and suggest supplementary literature | ### It Will Actively Tell You When Your Old Conclusions Are Outdated After new literature is added to the library, the agent can retroactively check: **which existing knowledge pages are affected by the new literature and how each page should be updated.** Review library pages will be automatically marked as "possibly outdated" and given lower priority in searches—ensuring you don't use a three-month-old conclusion, before a new judgment was made, for publication. ### More Features - **Single Article Intake**: throw a PDF path into the chat, and the agent will directly add it to your library. - **Similar Article Search**: given an article, return **vector neighbors** (not keyword matching)—after thoroughly reading an article, expand your search with a different perspective. - **New Literature Overview**: if you haven't accessed your library in a while, ask "what's new since last time?" - **AI Usage Statement**: generate a statement on the usage of generative AI according to the pages you select—many journals now require this. > 📎 For the complete tool list, see [MCP Integration Instructions](src/MCP%E6%96%87%E4%BB%B2%E6%8C%87%E5%AF%BCO.md) (automatically generated from the code, consistent with implementation). > Integration method: open the **🤖 Agent** page in the application, copy the command line, and **no manual installation of skill packages is required**. --- ## 🔍 Search Engine No matter how smart the agent is, inaccurate search results are useless. Therefore, the search engine is designed to be robust: - **Hybrid Search**: vector (LanceDB) + BM25 lexical → RRF fusion → re-ranking (bge-reranker-v2-m3) - **Journal Weight Enhancement**: top-tier journals, C journals, legal sources, and reports are weighted differently (with built-in journal ranking engine, including SJR / Peking University Core / CSSCI catalog) - **Chinese Legal Optimization**: legal term segmentation dictionary, legal article segmentation, and legal source timeliness identification - **Three-Level Progressive Indexing**: lexical (available within seconds) → semantic (within minutes) → deep search (reading full PDF text, can run in the background) ## 🧠 Wiki Layer On top of RAG, there's a layer that **solidifies** the question-and-answer results into citable, accumulative, and interconnected knowledge pages, rather than letting the answers get lost in chat logs. Pages will be automatically marked as "possibly outdated" with new literature additions and checked for orphan pages and broken links. This is what makes this project different from ordinary RAG tools. --- ## Installation **[⬇️ Download the Latest Version](https://github.com/DrinkTea905/paper-piggy/releases/latest)** → `PaperPiggy-x.y.z-win64.exe` (about 177 MB) For Windows 10/11 64-bit. No prior installation of Python or VC++ runtime library required. If WebView2 is missing, the installer will automatically install it. **No administrator privileges** are needed, and UAC won't pop up during installation. Search engine options: **Local ONNX** (models run on your machine, downloading about 900 MB on the first launch) or **API Mode** (saves disk space and memory, no download required). Choose in the setup wizard. ### Where Are Your Data Stored **In the same folder as the program.** You can choose the location during installation—for example, installing to `D:\PaperPiggy`, then indexes, models, reviews wiki, `0_Agent交付物`, and `0_Agent资料库` are all stored in this folder, not occupying your C drive (default location is `C:\Users\<your username>\AppData\Local\Programs\PaperPiggy`; you can change it). - **Upgrade**: in-app 「⚙ Settings → ⬆️ Application Update」for a one-click upgrade (only the program body is replaced, data remains untouched, and the application restarts); or directly run the new installer for the same effect. - **Uninstallation**: your data will **stay** in that folder and won't be deleted. You can reinstall and continue using; delete only when you're sure you don't need it. - ⚠️ **Do not manually delete the entire folder**—data is stored there. To clear, back up first. - ⛔ **Do not install in OneDrive /坚果云 / Dropbox** or other cloud sync directories. The index is a continuously read and written vector database (a few GB, repeatedly rewritten and merged), which cloud storage may fail to handle properly—causing write failures, file locking during sync, or duplicate copies. Install to a regular local directory (e.g., `D:\PaperPiggy`). ### Slow Downloads in China? Use a Mirror The application downloads from GitHub (models and incremental update packages during application updates). Sometimes, GitHub connections can time out in China. **Application updates** only download a ~1MB incremental package. Setting up a mirror is lightweight: 1. For each release, put `paper-piggy-app-<version>.zip` and the corresponding `.sha256` (just these two small files) in a domestically accessible location—**Gitee Release** is convenient (free, no filing requirements), or use object storage (Cloudflare R2 / Alibaba Cloud OSS, etc.). 2. In the application「⚙ Settings → ⬆️ Application Update → Domestic Mirror」, fill in the **directory prefix** (ending with `/`) of these files, e.g., `https://gitee.com/yourname/paper-piggy/releases/download/v<version>/`. 3. After that, application updates will try GitHub first and then the mirror if GitHub is unreachable. Update checks still use the GitHub API (small and usually accessible). (Initial model downloads use a different mirror setup in `models_manifest.json` with `mirror_base` for a 900MB large file, which requires a bandwidth-sufficient object storage.) --- ## Running from Source ```powershell git clone https://github.com/DrinkTea905/paper-piggy.git cd paper-piggy python -m venv .venv .\.venv\Scripts\pip install -r src\requirements.lock # Use this lock file, as it's the only combination verified on a real machine $env:LOCALKB_MODELS = 'X:\path\to\models' # Required for local mode; skip for API mode .\.venv\Scripts\python src\launcher.py # Native window .\.venv\Scripts\python src\server.py # Or start the backend only, open http://127.0.0.1:8770 in your browser ``` **Running on macOS / Linux?** Although the official release is only for Windows, the entire project is in pure Python + local web, **you can run it directly from the source** (data storage, Zotero detection, and dependencies are handled by platform)— see **[MAC-Run-from-Source.md](MAC-Run-from-Source.md)** (for technical users, with macOS-specific notes). **If an AI agent takes over this project for development?** Read [CLAUDE.md](CLAUDE.md) for your entry point. ## Documentation | | | |---|---| | [CLAUDE.md](CLAUDE.md) | AI agent development guidelines (working rules, code modification principles, pitfalls) | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Architecture: process model, three-level indexing, search pipeline, Wiki, Agent layer | | [docs/MAINTENANCE.md](docs/MAINTENANCE.md) | Maintenance: "Modified X → must synchronize Y" mapping table | | [docs/RELEASE.md](docs/RELEASE.md) | Packaging and automatic updates | | [MAC-Run-from-Source.md](MAC-Run-from-Source.md) | Running from source on macOS (for technical users) | | [src/MCP%E6%96%87%E4%BB%B2%E6%8C%87%E5%AF%BCO.md](src/MCP%E6%96%87%E4%BB%B2%E6%8C%87%E5%AF%BCO.md) | MCP integration (32 tools, automatically generated from code) | ## Tech Stack Python 3.12 · FastAPI · pywebview(WebView2) · LanceDB · bm25s · ONNX Runtime · BAAI/bge-m3 (embedding) · BAAI/bge-reranker-v2-m3 (reranking) · jieba · pypdfium2 The frontend is **plain JS with no build steps**. The backend is **plain `.py`, not compiled or obfuscated**—you can directly modify code in the package. (Upgrades: in-app 「⚙ Settings → ⬆️ Application Update」for a one-click upgrade—only replacing the program body, your data remains untouched, and modified `.py` files are saved to 「your modified old code-<version>」folder. You can also download a new installer from GitHub and install over, with the same effect but covering your modified `app\` files—**backup first**.) ## License [Apache-2.0](LICENSE). See [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) for third-party component declarations.