AI-Hints Anki Add-on

AI-Hints is a powerful Anki add-on that uses Artificial Intelligence to generate helpful hints or multiple-choice options for your flashcards during review. It helps simulate real exam conditions by including the correct answer alongside plausible distractors even for open-ended cards.

Install from anki web

github:https://github.com/athulkrishna2015/AI-Hints

Features

🔌 Multi-Provider AI Engine

• Broad Provider Support: Generate hints using OpenAI, Anthropic, Gemini, DeepSeek, Grok (xAI), Groq, OpenRouter, and custom local endpoints via Custom Providers (Ollama, LM Studio, vLLM).
• Automated Fallbacks: Automatically retries alternative models or providers in case of API rate limits or failures, with editable provider and model priority lists. Transient 429 and 503 outages stop the provider for the current card after one key attempt instead of burning every key and model on a temporarily dead service — the failed key cools down, so the next card rotates to the next key (cyclic rotation across cards, configurable per provider and per code from the provider ✏️ edit window).
• API Key Rotation: Register and rotate multiple API keys per provider to prevent exhaustion.
• Active Provider Auto-Derivation: The primary provider is derived automatically from the first usable entry in your fallback priority list (first enabled provider with an API key, or the first custom provider) — no separate dropdown to maintain.
• Per-Card Model Override: Alt+click Generate/Regenerate to open a theme-aware dialog and force a specific provider + model for that card's regeneration (all active models are listed, including ones on cooldown; it remembers your last choice).
• Unified Learning Prompt: One refined system prompt drives every provider — SRS-friendly, cloze-aware, exactly 3 progressive hints, factual errors prefixed with ⚠️, subject-specific guidance, MathJax/JSON escaping, and a single canonical output schema.

🎮 Interactive MCQ & Review UI

• Multiple-Choice Options: Select MCQ options on the front side (via click, touch, or hotkeys 1-9) with color-coded results (green for correct, red for incorrect).
• Auto-Rating: Instantly rate cards (e.g. Good or Again) automatically upon selecting an option.
• Inline Editor: Edit generated hints or options directly on the card during review (via Ctrl+Click / Cmd+Click). Holding Ctrl/Cmd also reveals a + Add row at the end of each list — Ctrl+click it, type, and press Enter to append a new hint or option without regenerating (or spending an API call). Clearing an item's text and confirming removes it.
• Factual Error Alerts: Automatically detects and flags factual errors in your notes with custom warning highlights during study.
• Skip AI Generation: Permanently skip AI generation for individual cards. Skipped cards render an "AI generation skipped" message (with all desktop buttons, or message-only on mobile) until you generate or clear them.
• LaTeX Math Support: Seamlessly parses and formats LaTeX math formulas on your cards.

⚡ Batch & Maintenance Tools

• Queued Batch Generation: Queue multiple bulk generation runs to process entire decks in the background.
• View-in-Browser Confirm: The pre-run confirmation shows the exact queued cards in Anki's Browser via a non-modal Proceed / View in Browser / Cancel dialog — no rescan, no focus stealing, Anki stays usable.
• ⚡ Force Start: One-run bypass of the API-key readiness check and offline detection for queues wrongly parked as 🌐 Offline (saved settings untouched).
• Ignore Network/Offline Checks: Advanced-toggle global bypass for false-positive offline detection, honored on every path (batch, reviewer, pregen, fallbacks).
• Incremental Fast Scan: Re-running a batch only scans notes created since the deck's last full scan (tracked per-deck, including sub-decks), making repeat runs near-instant — with a Force FULL scan option to re-check everything. Already-skipped cards are treated as done instead of being re-queued every run.
• Smart Auto-Regeneration: Keep hints updated by automatically regenerating them if a note is edited or generated by an older addon version.
• Bulk Skip & Unskip: Exclude or include groups of cards for AI generation directly from Anki's card browser.
• Hint Tagging: Notes are automatically tagged (ai-hints) when hints are generated and un-tagged when cleared/skipped, enabling fast batch scanning. A "Tag All Cards with Hints" tool in Advanced settings covers cards created before tagging was enabled.
• Cloze Deletion Support: Fully compatible with cards containing multiple Cloze deletions on a single note.

Intelligence-Ranked Fallback Hierarchy

The add-on features a multi-tiered, intelligence-driven fallback system. If your primary provider fails (due to rate limits, API key exhaustion, or network issues), the system automatically attempts fallback providers and models strictly ranked by absolute intelligence and reasoning capability.

⏳ Linger-on-Timeout Fallback

A read timeout no longer throws the request away. The slow-but-alive request is re-dispatched in a background thread with an extended deadline (default: 3× the request timeout, clamped to 180–900s) while fallback continues immediately with the next candidate:

• First-timeout coverage: even a timeout on the first model of a provider spawns the background retry (pure read timeouts are also never blacklisted — slow ≠ broken).
• Priority wins races: if a lower-priority candidate succeeds while a higher-priority lingering attempt is still running, generation waits out its extended deadline and prefers the smarter result (linger_race_policy: "priority", default — the button shows an amber "⏳ Waiting for higher-priority model…" state). Set "first" to make the first usable result win instantly instead.
• Rescue on total failure: if every foreground candidate fails, generation waits out the lingering attempts instead of returning empty.
• Reasoning-model responses recovered: gateways like the Cline BYOK API wrap completions in a top-level data envelope, and reasoning models (e.g. some Minimax models) often return the JSON in message.reasoning / reasoning_details instead of content. Responses are now unwrapped and parsed from those fields too, so a good but unusually-shaped reply is no longer reported as "no parseable hints/options".
• Works everywhere: explicit review, pre-generation, and batch (linger_on_timeout: false disables it).

Per-Flow Timeouts

Each generation flow has its own base request budget — request_timeout (explicit review), pregen_request_timeout (pre-generation), batch_request_timeout (batch, default 120s) — and custom per-model/per-provider timeouts are honored by every flow with extend-only semantics: a value greater than the flow's base wins; a smaller one never shortens an unattended budget.

Default Provider Priority

1. Anthropic (Claude 3.7/3.5 Sonnet)
2. OpenAI (GPT-4o)
3. DeepSeek (Reasoner/V3)
4. Grok (xAI) (Grok 2)
5. Gemini (Gemini 2.0 Pro/Flash)
6. OpenRouter (Unified Router)
7. Hugging Face (Serverless DeepSeek-V3 / Llama 3.3)
8. Groq
9. SambaNova
10. NVIDIA
11. Mistral
12. Cerebras
13. Custom Providers (Ollama/LM Studio/Local Endpoints)

Model Status Highlights in Fallback Lists

Fallback lists colour-code models after a fetch so you can spot stale entries at a glance:

• 🆕 Newly Added (green): models the fetch just added to your list.
• ⚠️ Deprecated (red) — models flagged as deprecated/retired by the provider's own API or legacy mappings.
• ⚠️ No Longer Returned (amber) — models that were in your list before the fetch but the provider no longer returns.

A single Remove dropdown removes the models you choose: Selected, Deprecated, No Longer Returned, or both flagged types. Tests are unified under one Test dropdown (Checked / Row / All) in both per-provider and global fallback dialogs.

Batch Generation & Resumption

The batch generation queue is designed for heavy-duty background processing with maximum reliability:

• Concurrent Multi-Provider Generation: Leverages multiple AI providers concurrently to process batches significantly faster, with independent fallback queues per provider.
• Unattended-Friendly Timeouts: Batch requests use their own generous budget (batch_request_timeout, default 120s) instead of the short review timeout. Batch linger retries are disabled by default so timed-out requests do not keep threads and memory alive after a job finishes; opt in with batch_linger_on_timeout: true when late results are worth the extra resource use.
• Multiple Queued Jobs: Add another deck, browser selection, or sidebar group while a batch is already running. Pending jobs can be reordered, canceled, or cleared from the Batch tab.
• Granular Queue Management: View the next 5 pending cards in the queue directly in the Batch tab status. Includes individual [✖ Discard] buttons to surgically remove cards from the current batch.
• Deck Browser Cogwheel Option: Start batch generation for any deck directly from the deck browser's options menu.
• Continuous Checkpointing: Progress is saved to disk (batch_state.json) at most every 30 seconds during steady progress — immediately on every lifecycle event — and the state file excludes volatile per-model tables (MBs → KBs).
• Accidental Quit Protection: If you close Anki or it crashes mid-batch, your progress is preserved.
• Non-Blocking Background Execution: The process runs in a dedicated background thread, allowing you to study or browse while it works.

Mobile Setup & Troubleshooting

The Mobile Support tab allows you to run AI-Hints on mobile devices (AnkiDroid, AnkiMobile, or AnkiWeb) with a premium, responsive layout.

⚡ Getting Started (One-Click Setup)

1. Go to Tools -> Add-ons -> AI-Hints -> Config -> Mobile Support.
2. Click One-Click Install: Setup All Note Types. (This inserts the safe injection tags into your templates and copies the modern _ai_hints_template.js script to your media folder automatically).
3. Sync Anki on PC to upload the fresh template script to AnkiWeb.
4. Sync AnkiDroid/AnkiMobile on your phone to download the new files.

⚠️ Troubleshooting AnkiDroid Cache (WebView)

If you have recently updated the add-on and still see the old card style, duplicate labels (e.g., AI Hints:), or missing buttons on AnkiDroid, it is because Android's internal WebView aggressively caches local JavaScript files.

To force AnkiDroid to load the new script:

1. Sync AnkiDroid to ensure all files are downloaded.
2. Force-Close the App: Swipe AnkiDroid away from your phone's Recent Apps list. This terminates the persistent WebView session and clears the cache.
3. Reopen AnkiDroid: Open the app and review a card. The clean desktop-style UI will render perfectly.

⚠️ Troubleshooting AnkiMobile "undefined" on Tap (MCQ Reveal)

On AnkiMobile (iOS), tapping an answer option used to blank the card and show the literal text undefined at the top instead of flipping to the answer side.

Cause: AnkiMobile has no JavaScript API for showing the answer. Older builds of the add-on called pycmd('ans') / showAnswer() when an option was tapped (the same API used on Desktop). On iOS that call makes the WebView navigate to a blank page whose content is the string undefined.

Fix (built into v5.8.2+): On iOS, the add-on now detects the AnkiMobile WebView bridge and skips the JS reveal call entirely — tapping an option only saves your selection and lets AnkiMobile's own tap-to-reveal flip the card, exactly as it does for blank areas, so no undefined screen appears. Desktop and AnkiDroid are unchanged and continue to use their platform JS reveal APIs (pycmd('ans') / showAnswer()). On AnkiWeb (ankiuser.net/study) — which exposes no JS reveal API either — the option tap now simulates a click on the reviewer's own Show Answer button instead.

To update your phone:

1. Sync Anki on PC so the fresh _ai_hints_template.js reaches AnkiWeb.
2. Sync AnkiMobile to download it.
3. Force-Close the app in the app switcher and reopen it.

[!IMPORTANT] Because the reveal uses the native tap zones, keep Review → Tap Zones → When Question Shown → "tap anywhere" (or a zone covering the options) → Show Answer enabled in AnkiMobile preferences. If you pick a more restrictive zone (e.g. only left/right), tap an option in the middle won't flip the card.

[!TIP] Quick Script Force-Refresh: Sometimes after an update, in order to guarantee loading the absolute latest Javascript template, go to Tools -> Add-ons -> AI-Hints -> Config -> Mobile Support, first click Remove from All Note Types to clean the old assets, and then click One-Click Install: Setup All Note Types again to install the fresh script. Then sync your devices.

🧹 Clean Uninstallation

If you want to remove AI-Hints from mobile:

1. Go to the Mobile Support tab and click Remove from All Note Types.
2. This will instantly strip the injection code from all templates, automatically delete the _ai_hints_template.js file from your media folder, and trigger a sync to push the cleanup to AnkiWeb in a single click!

Configuration

Go to Tools -> Add-ons -> AI-Hints -> Config to open the graphical configuration window.

• General Tab: Configure MCQ options, storage, and auto-generation rules including modified-card, version, and generation-time based regeneration. The primary provider is derived from fallback priority; there is no separate provider dropdown. Configure auto-show defaults for hints and MCQ options independently on the question and answer sides (each reset automatically per card, including during relearn/retries).
• AI Providers Tab: Unified settings where each provider is grouped into a clean card layout containing its API Key (with eye visibility 👁️ toggles), active model selection, Up/Down priority sorting, dynamic fetch and test features, and checkbox toggles to completely disable fallbacks to specific providers.
  • Custom Providers: Add any OpenAI-compatible API endpoint (e.g., Ollama, LM Studio, vLLM, AIHubMix) by clicking Add under Custom Providers. Endpoint URLs are automatically normalized (e.g., http://localhost:11434/v1 or https://aihubmix.com/v1/chat/completions), and models can be dynamically fetched directly from the local server.
    • No API Key Required: Local endpoints without authentication can leave the API Key field blank.
    • Body Params: Send extra JSON fields in the request body (e.g., {"think": "low"} to control model reasoning traces on thinking-capable models like GPT-OSS or Qwen3).
    • Editable Name: Provider names can be changed after creation via the Edit button.
  • Per-Model Thinking Levels & Timeouts: In the Fallbacks dialog for any provider, each model has a Thinking Level dropdown (off/low/medium/high) and a Timeout spinbox. Set thinking to "low" for minimal reasoning traces on GPT-OSS or Qwen3, or "off" to disable (where supported). Timeout overrides the provider/global timeout for that specific model — and is honored by every generation flow (review, pregen, batch) whenever it is greater than that flow's base budget (extend-only).
  • Multi-Select Test Row: Ctrl+click or Shift+click to select multiple rows, then click Test → Test Row to test them.
  • Model Status Highlights: Fallback lists highlight 🆕 newly fetched models (green), ⚠️ deprecated (red), and ⚠️ no-longer-returned (amber) models after a fetch, with a unified Remove dropdown to strip Selected / Deprecated / No Longer Returned / both flagged types, and a unified Test dropdown (Checked / Row / All).
  • Token Usage Logging: Every successful provider call logs its token usage (prompt_tokens/completion_tokens/total_tokens) to ai_hints.log, visible in the Logs tab.
  • Debug Logging: Enable "Debug logging" in the Logs tab to see full request/response payloads in the log file (addon/ai_hints.log).
• Mobile Support Tab: Smart one-click installer for AnkiDroid/AnkiMobile with Emoji mode settings.
• Shortcuts Tab: Customize AI-Hints action keys and the modifier used on the answer side. The front side also accepts the action keys without the modifier for faster review.
• Advanced Tab: Customize your system prompt, tune per-flow API request timeouts (active-review, pregeneration, batch — custom per-model/per-provider values extend any flow), toggle Linger-on-Timeout behavior (linger_on_timeout, timeout_linger_seconds, linger_race_policy via raw config), migrate hints inside your collection, use maintenance cleanups (now with Searchable Deck Scoping), hide visible hint boxes with the HTML to JSON tool, edit raw JSON configs, and manage the Model Cooldowns & Blacklist (including the Ignore network/offline checks bypass).
• Logs Tab: View, filter, search, and copy real-time addon logs with Level and Source filters (including Lingering, which isolates the background linger-on-timeout lines). Includes a Debug logging toggle to enable verbose DEBUG-level output instantly (no restart needed), and a Clear on startup option.
• Scrollbar Support: Smooth scrollbars automatically wrap the Advanced, Mobile, and Batch tabs, ensuring the GUI scales perfectly to fit compact laptops and high-DPI screens.

Get Your API Keys

• Google Gemini: aistudio.google.com
• Groq: console.groq.com
• SambaNova: cloud.sambanova.ai/apis
• Hugging Face: huggingface.co
• OpenRouter: openrouter.ai
• OpenAI: platform.openai.com
• Anthropic: console.anthropic.com

ai-latex-fixer is included as a Git submodule at addon/latex_fixer/. When cloning for development, run git submodule update --init to pull it.

Development

See docs/setup.md for build, test, and release instructions, and docs/architecture.md for the high-level architecture and per-module description.

License

MIT

<img width="2083" height="1188" alt="Screenshot_20260507_215546" src="https://github.com/user-attachments/assets/b3b54ab4-fefb-44cf-85c4-3cf02b7cbe88" /> <img width="1920" height="1025" alt="Screenshot_20260601_002447" src="https://github.com/user-attachments/assets/90a4fea1-bd1d-4dc8-8052-218b017b6131" /> <img width="337" height="750" alt="image" src="https://github.com/user-attachments/assets/1965d9f5-c353-423d-8721-c7581aecae82" />

Mobile support (AnkiDroid and AnkiMobile) is achieved through a “Zero-Addon” architecture. This means that while the Desktop requires the Python addon to generate data, the mobile devices only need the data itself and a lightweight JavaScript renderer to display it.

Changelog

See changelog.md for the full history of changes and releases.

Documentation

Full user documentation is available in the docs folder:

• Installation & API Keys
• Features
• Configuration (all settings)
• Batch Generation
• Mobile Support
• Troubleshooting

Developer documentation: docs/architecture.md (architecture and code) and docs/setup.md#install-from-github-development (build / test / release).