aidea-zotero

AIdea

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français

🌐 Website: https://visterainer.github.io/aidea-zotero/en/

A free, open-source AI assistant for Zotero
💬 Chat with your papers · ✍️ Translate selected text · 📄 Translate full PDFs into bilingual documents

Connect any way you like:
🔐 Your existing subscription — ChatGPT or GitHub Copilot via OAuth, no API key needed
🔑 Any OpenAI-compatible API — OpenAI, DeepSeek, OpenRouter, and more
💻 Local models — Ollama, LM Studio, vLLM, your data stays on your machine

Features  |  Installation  |  Getting Started  |  Configuration  |  License

---

✨ Features

💬 AI Chat in the Side Panel

Chat with AI directly in Zotero’s side panel, available in the Library view and the PDF or EPUB Reader. Ask questions, get summaries, and stay inside the same research workflow. EPUB conversations use the book’s EPUB 2/3 publisher structure and bounded local retrieval to select relevant sections without an additional planning-model request.

📄 Paper-Aware Context

Select text in the PDF or EPUB reader and click Add Text to attach the selected passage to the context area. AIdea can then answer against the selected passage instead of relying on a generic summary.

📝 Selection Translation

Translate selected text directly in Zotero’s PDF or EPUB reader popup. AIdea detects the active format automatically, with no manual switch required. Selection translation uses the same OAuth/API model list as the chat panel, but can be configured with its own enable switch, model, source language, and target language.

For PDFs, the first selection translation creates a local cold-start cache with a compact paper overview and terminology summary. If that context exceeds the model’s input limit, AIdea progressively reduces it and retries, then falls back to translating only the selected text if needed. EPUB selections instead use bounded, selection-anchored book context without a separate warm-up request. Translated passages can be added to Zotero notes or written into a new highlight annotation by selecting Write translation to annotation before choosing a color; existing annotation comments are preserved. The checkbox remembers both enabling and disabling across selections, documents, and Zotero restarts. It is off by default; when enabled, wait for the translation to finish, then choose a highlight color.

⚡ Quick Action Shortcuts

Use one-click shortcuts for common tasks such as Summarize, Explain, and Translate. Shortcuts can be added, edited, reordered, or removed to match your workflow.

🖼️ Multimodal Support

Attach screenshots, figures, and charts to your messages. AIdea supports drag and drop, clipboard paste, and screenshot capture directly from PDF content.

🔐 OAuth Login Without an API Key

Sign in with your existing account through OAuth. AIdea supports multiple providers with provider-specific OAuth flows, so you can start without managing an API key manually.

📄 Full-Document Translation

Translate full papers directly inside Zotero and export either a bilingual PDF (side-by-side or top-bottom layout) or a single-language PDF. The translation workflow supports model selection, output path configuration, and end-to-end execution in the side panel.

Example outputs:

🌐 Multi-Provider Support

Provider	Auth Method	Extra Setup
OpenAI (ChatGPT)	OAuth via Codex CLI	Codex CLI (auto-installed)
GitHub Copilot	In-plugin OAuth (Device Code)	None; GPT and Claude models available

📝 Note Export

Save AI responses as Zotero notes with one click. Responses are stored in Markdown and support LaTeX math rendering.

💾 Persistent Chat History

All conversations are stored locally in Zotero’s database. You can switch between conversations, continue previous threads, and manage local chat history.

Manually export and import chat archives with optional screenshots, images, and uploaded files. Imports merge new messages and preserve conversation branches without duplicating repeated imports. Settings, credentials, and the Memory database are not included.

Answers can include clickable PDF page or EPUB chapter citations when reliable locations are available. Cross-device navigation requires matching Zotero library items and unchanged source files; paper originals are not bundled in chat archives.

🧠 Memory System

AIdea captures and recalls useful information across conversations to improve continuity and context awareness over time.

• Auto-capture detects preferences, decisions, facts, and key entities from natural conversation
• Per-library isolation keeps memories scoped to each Zotero library
• Smart deduplication uses Jaccard token similarity to prevent redundant memories
• Relevance-ranked retrieval combines overlap, substring match, recency, and importance
• Prompt injection defense blocks malicious or irrelevant content from being stored
• Fully local storage keeps memory data inside Zotero’s SQLite database

🎨 Rich Rendering

• Full Markdown rendering, including headings, lists, code blocks, and tables
• LaTeX math support via KaTeX
• Syntax highlighting for code blocks
• Smooth streaming responses

🌍 Interface Languages

The plugin interface now supports 12 UI languages: English, 简体中文, 繁體中文, 日本語, 한국어, Français, Deutsch, Español, Русский, Português, العربية, and हिन्दी. Full-document translation keeps its broader target-language list independent from the UI language list.

---

📦 Installation

Requirements

• Zotero 7 or later
• The standalone Codex CLI, required for OpenAI OAuth, is installed by the plugin when needed (no Node.js required; curl or wget must be available on macOS/Linux)
• Python environment running pdf2zh_next, required only for full-document translation. The Install/Update Translation Environment button installs a tested dependency set with uv; existing Miniconda environments remain usable. Installation needs an internet connection unless the packages are cached.

Note: The Translate tab checks AIdea’s independently published, tested environment catalog once per day and shows an inline notice when an update is available. Install/Update Translation Environment checks again when clicked and changes the environment only if installation, repair, or an update is needed. An update is installed in a new directory and activated only after validation; an upstream PyPI release alone is not treated as a verified update. The provider-card Install/Update Env button manages its separate OAuth CLI environment.

Install the Plugin

1. Download the latest AIdea-x.x.x.xpi from Releases
2. In Zotero, go to Tools → Add-ons
3. Click the gear icon ⚙️ and choose Install Add-on From File…
4. Select the downloaded .xpi file
5. Restart Zotero

Upgrade

Install the newer .xpi package over the existing one. Chat history, stored memory, and local settings are preserved.

---

🚀 Getting Started

1. Open Settings

Go to Tools → Add-ons → AIdea → Settings. On older Zotero builds, the path may appear under Edit → Settings → AIdea.

2. Choose a Connection Mode

AIdea supports two connection modes. You can use either one or combine both.

Option A: OAuth Login

For each provider card, the typical setup order is:

① Install/Update Env → ② OAuth Login → ③ Refresh Models

Button	What it does
Install/Update Env	Installs or updates the official standalone Codex CLI using OpenAI’s install script. GitHub Copilot does not require this step. Run it again whenever the provider’s CLI is updated upstream; this is independent of plugin updates.
OAuth Login	Starts the provider-specific login flow. OpenAI opens the browser directly. GitHub Copilot shows a device code, copies it, and opens the browser for authorization.
Refresh Models	Loads the list of available models for the provider after login.
Remove Auth	Clears the locally stored OAuth token for that provider.

💡 Tip: Each provider only needs to be configured once. The login session is stored locally and remains available after Zotero restarts.

For Codex OAuth and API Key connections with explicit model capability metadata, Reasoning effort has its own lightbulb icon beside the chat model selector, and is also available on the Translate tab for full-PDF translation and in Settings → Selection Translation. The three choices are saved separately. The chat choice stays fixed when you switch models; the icon color indicates the effective level. If the new model does not support that level, requests use the nearest weaker supported level while the saved choice remains unchanged. Menus contain explicit levels only. An empty legacy choice is initialized once to the catalog default, or the weakest non-none supported level if no default is supplied, and saved. If no weaker compatible level exists, the request uses that same explicit fallback. Refresh the Codex model list to load each model’s supported levels, including Ultra when available. If capability data is missing, the plugin does not assume three levels: the lamp is gray with a refresh hint. For unsupported models or connection types, the gray lamp explains that effort adjustment is unavailable; chat continues without an explicit effort. For API Key connections, use Auto Fetch Models or refresh the saved provider list. The plugin reads explicit per-model supported_reasoning_levels or reasoning.supported_efforts; a model name or a reasoning-support flag alone is insufficient. API capability caches are isolated by endpoint and credentials, expire after 24 hours, and are cleared on a failed refresh. Requests use the declared Chat Completions field (reasoning_effort or reasoning) or Responses reasoning.effort. Confirmed adaptive Anthropic routes on OpenRouter use verbosity only when the catalog advertises it. Chat and selection translation disable the control for that connection after an explicit parameter rejection and retry without it; refreshing capabilities enables another attempt. The full-PDF proxy also removes a rejected effort and remembers that decision for the remaining translation batches.

Option B: OpenAI-Compatible API Endpoint

AIdea can also connect to any OpenAI-compatible chat endpoint, including local, self-hosted, or third-party services such as Ollama, LM Studio, vLLM, DeepSeek, OpenRouter, or Groq.

In Settings, switch to API Mode and fill in:

Field	Required	Description
API Base URL	Yes	The base URL of the compatible endpoint, such as https://api.openai.com/v1 or http://localhost:11434/v1
API Key	No	Required only when the endpoint expects authentication
Model	Yes	Enter the model manually or click Auto Fetch Models to detect available models

Note: API mode targets compatible /chat/completions endpoints. It does not guarantee support for provider-specific features beyond standard chat completion.

3. Start Chatting

• In the Library Panel, select an item and use the AIdea panel in the right sidebar
• In the PDF or EPUB Reader, open a document and use the AIdea panel in the reader sidebar
• Type your question and press Send or hit Enter

4. Use Quick Actions

Click shortcut buttons such as Summarize, Explain, or Translate for one-click actions. Right-click a shortcut to edit or remove it.

---

⚙️ Configuration

Setting	Description	Default
UI Language	Plugin interface language	Auto-detected, fallback EN
System Prompt	Custom instructions for the model	Empty
Show “Add Text”	Show the Add Text option in the reader selection popup	On
Selection Translation	Translate selected reader text with automatic bounded document context	On
Selection Translation Model	Dedicated model for reader selection translation	First available model unless changed
Show All Models	Show all available models instead of a curated subset	Off
Tab Bar	Show or hide the tab navigation bar	Hidden

---

The default chat prompt favors direct, natural answers, with enough detail for the task and citations grounded in the available material. Extracted text does not imply access to unavailable pages or figure images.

To customize the response style, open Settings → Advanced → Custom System Prompt. Leave it blank to use the default; a non-empty value replaces the default chat prompt. Existing custom prompts are preserved. Changes apply to the next request without restarting Zotero; start a new conversation for a clean comparison because earlier answers remain in history. Selection translation, cold-start summaries, conversation compaction, and author profiles use independent task prompts, unaffected by this chat setting. Full-document translation retains its own configuration.

🔒 Privacy & Security

• OAuth tokens are stored locally only
• API requests are sent directly to the selected provider or configured endpoint
• AIdea does not collect usage telemetry or user data
• Chat history and memory remain in Zotero’s local database
• The code is fully available for inspection on GitHub

---

🗺️ Roadmap

Planned directions for future releases include:

• One-click architecture diagrams, for generating structural visualizations from paper content

💡 Feature requests are welcome through Issues.

---

🛠️ Development

# Install dependencies
npm install

# Development mode
npm start

# Build production XPI
npm run build

# Run tests
npm run test:unit

---

📄 License

AGPL-3.0-or-later

This project is derived from llm-for-zotero by Yile Wang. See THIRD_PARTY_NOTICES.md for attribution details.

---

⭐ Star History

---

Author: zhile