steven-jianhao-li/zotero-AI-Butler

📚 What is Zotero‑AI‑Butler?

A free, open‑source Zotero plug‑in that lets you call large language models (LLMs) from inside your reference manager. It automatically reads the PDFs you add to Zotero, sends them to a model you configure (Gemini, OpenAI, Claude, etc.), and writes back structured Markdown notes, mind‑maps, one‑page “poster” images and even literature‑review drafts. In short, it turns Zotero into an AI research assistant.

---

🎯 Core capabilities (as described in the README)

Feature	What it does	How you trigger it
AI Butler Agent (v5.0)	Answers research questions by searching your library, pulling evidence, and replying with model‑generated answers.	Open the Agent tab in the Butler dashboard and type a query.
Automatic note generation	When a new PDF is added, the plug‑in extracts the full document (Base64 for multimodal models) and asks the LLM to produce a clear Markdown summary that is saved as a Zotero note.	Enable Auto‑scan new items in the settings or run a manual scan.
Deep reading / multi‑round summarisation	Splits a paper into sections (background, methods, experiments, conclusion) and runs several model calls, then merges the results into a detailed note.	Right‑click → AI Butler multi‑round re‑read → choose multi‑round splice or multi‑round summary.
One‑image summary	Generates a single academic‑poster‑style image (via the “Nano Banana Pro” service) that visualises the paper’s key points.	Right‑click → Summarise with one image (requires API key).
Mind‑map export	Produces an interactive hierarchical map of a paper’s structure; can be exported as PNG or OPML for other tools.	Right‑click → Generate mind map.
Batch literature review	Select a collection/folder, and the plug‑in writes a combined review document that links all source PDFs.	Right‑click a collection → AI Butler literature review.
Sidebar preview	Shows the AI‑generated note beside the PDF, with LaTeX rendered via KaTeX, foldable sections, font scaling, and a quick‑ask box for follow‑up questions.	Open the sidebar or click the AI‑Butler icon.
Prompt‑template manager	Built‑in and user‑defined prompt sets for single‑shot, multi‑round, or final‑summary calls; live preview of variable substitution.	Settings → Prompt templates.
Multi‑model support	Works with Google Gemini, OpenAI (including gpt‑5), Anthropic Claude, SiliconFlow‑compatible APIs, Volcano‑Argo, Ollama, etc.	Settings → API configuration.
Theme & UI adaptation	Matches Zotero’s light/dark mode; selectable note rendering themes (GitHub, Redstriking) and custom CSS.	Settings → UI theme.

---

🛠️ How it works under the hood (high‑level, from the README)

1. PDF handling – The plug‑in can either extract plain text or send the whole file as a Base64‑encoded blob, allowing multimodal models (e.g., Gemini 2.5 Pro) to see figures, tables, and equations.
2. Task queue – Papers are placed in a producer‑consumer queue; you can view status (pending, running, finished, failed) on the Task Queue page.
3. Prompt‑driven LLM calls – Each feature corresponds to a prompt template. The plug‑in substitutes variables like {{title}}, {{authors}}, etc., then calls the configured API.
4. Result storage – The LLM’s response is saved as a Zotero note attached to the same item, and optionally displayed in the sidebar or exported as images/OPML.
5. Configuration – API keys are stored locally; the plug‑in never forwards your bibliography or keys to any third‑party server.

---

🚀 Getting started

1. Install – Download the latest .xpi from the Releases page, drag it into Zotero’s Tools → Add‑ons window.
2. Configure an LLM – Open AI Butler → Settings → API and paste a Gemini, OpenAI, Claude, etc., key. Click Test connection.
3. Enable auto‑scan (optional) – Settings → Interface → check Auto‑scan new literature.
4. Run a task – Right‑click a PDF → Summarise with AI Butler (or use the dashboard’s batch scanner).

---

🎓 Who benefits?

• Researchers & students who need quick, consistent paper summaries without manually copying text to a chat window.
• Literature‑review writers who want an initial draft that already links to the source PDFs.
• Anyone using Zotero who wants AI‑enhanced note‑taking, mind‑maps, or visual abstracts.

---

⚠️ Limitations & considerations (as per the README)

• You must provide your own API key – the plug‑in does not host any model.
• Token cost – multi‑round or image‑generation modes can consume many tokens; the README warns about high API fees.
• Performance – automatic scanning is disabled by default to avoid slowing Zotero; you must enable it.
• Model compatibility – Base64‑mode only works with multimodal models; text‑only models need the plain‑text extraction path.
• Privacy – All requests are sent directly from your machine to the model endpoint; the plug‑in claims no data collection.

---

📚 Further reading

• Full user guide: https://steven-jianhao-li.github.io/zotero-AI-Butler/
• Agent usage details: docs/agent.md
• Cite the software with the provided BibTeX entry (DOI 10.5281/zenodo.20457937).

---

Zotero‑AI‑Butler is a genuine, feature‑rich AI‑augmented research tool that lives inside the Zotero ecosystem, turning your bibliography into an interactive, model‑powered study partner.