batch generation

Batch Generation

Batch generation lets you generate hints and MCQ options for entire decks in the background, so you don't have to generate each card manually during review.

Getting Started

1. Go to Tools → Add-ons → AI-Hints → Config → Batch Generation.
2. Choose a Source Deck (type to search — a live-filtered list appears below the field as you type, case-insensitive, including Entire Collection), choose Entire Collection, or select cards in the browser first.
3. Optionally set a Force Provider / Force Model.
4. Set the Batch Limit (max cards, default 1000).
5. Click 🚀 Initiate Queue (or ⚡ Force Start to bypass the API-key readiness check and offline detection for one run).

The batch runs in a dedicated background thread, so you can keep studying while it works.

Methods

Sequential Local Queue (Recommended)

Processes cards one-by-one in the background. Supports all providers and fallbacks, and is free-tier friendly. This is the default.

Native Async API (Cloud)

Bundles requests and submits them to a cloud provider's native async API. Gemini only, requires paid billing, and does not support fallbacks. Use it when you need very high throughput.

Options

• Force Provider — override which provider the batch uses (default: Standard Config (Follows Fallback Matrix)).
• Force Model — override which model to use (default: System Default).
• Source Deck — the deck to batch. Editable/searchable with a live filtering popup (substring match, capped so it never spans the screen). Choosing a deck includes all of its sub-decks; Entire Collection covers everything.
• Skip cards that already have AI Hints generated — skip cards that already have hints.
• 🧹 Force FULL scan (ignore last-scan cursor) — re-check every card, bypassing the incremental cursor.
• Except if Generated Version < — cards with a version older than this value are still queued.
• Batch Limit — max cards to process (1–1,000,000).
• Concurrent Multi-Provider Generation (Multithreaded) — generate in parallel using all ready/enabled providers (bypasses the Force Provider/Model overrides).
• Entire Collection — process cards across all decks in the collection. This mode does not update a per-deck incremental scan cursor.
• ⚡ Force Start — starts the run bypassing the "No configured API Keys" readiness check and ignoring offline detection for that run only (saved settings are untouched; the dormant-queue resume prompt still applies). Use when a queue is wrongly parked with every thread on 🌐 Offline.

Incremental Fast Scan

By default, re-running a batch only scans notes created since the deck's last full scan. This cursor is tracked per deck (including all sub-decks), so scanning a sub-deck never wrongly skips cards based on another deck's timestamp.

The cursor only advances after a full, eligible pass (no cards dropped to the safety limit, and not a browser selection). Use Force FULL scan to re-check everything.

Multiple Queued Jobs

You can add another deck, browser selection, or sidebar group while a batch is already running (the 🚀 Initiate Queue button stays enabled during a run or a pause and appends the new job):

• Reorder pending jobs.
• Cancel or clear pending jobs.
• View the next 5 pending cards directly in the Batch tab status with individual [✖ Discard] buttons.

Reliability

• Continuous checkpointing: progress is saved to disk (batch_state.json) at most every 30 seconds during steady progress, and immediately on every lifecycle event (pass changes, job finish, pause/stop/discard). The persisted snapshot excludes volatile per-model timeout tables, keeping the state file small.
• Post-Job Resource Cleanup: Batch lingering retries are disabled by default (batch_linger_on_timeout: false) because a timed-out retry can otherwise keep a thread and HTTP client alive for several minutes after the queue finishes. Review and pre-generation lingering are unchanged. Set batch_linger_on_timeout to true only when late batch results are worth the extra CPU and memory.
• Accidental quit protection: close Anki or crash mid-batch and your progress is preserved; queues resume on restart.
• Concurrent multi-provider: use multiple providers in parallel with independent fallback queues. When a provider's models are all blacklisted/on cooldown but another worker is still serving cards, that provider exits the pass instead of idly re-checking the blacklist; a lone cooldown-stalled provider waits up to a bounded grace period (batch timeout + 60s) before ceding to the verification pass, so a dead key set can't pin the pass open.
• Automatic verification passes: the system automatically retries cards that failed to generate (up to 10 sequential passes).
• "Draining" status: when the queue reaches "0 left" but worker threads are still finishing in-flight requests, the status shows a 🧼 Draining notice (how many requests remain and how long the longest has run), so a batch that is winding down no longer looks stuck.
• Hung-provider watchdog: If all cards have been dispatched but one provider thread remains, the pass is released after a 45-second grace period measured from the moment that thread becomes the lone survivor (not from pass start). The log distinguishes a genuinely busy request (still busy with an empty queue) from an idle waiter (lingered idle with an empty queue), and the leftover thread still lands its result once its HTTP call resolves. In-flight cards are not requeued by the verification pass while their request is still running, so a released thread never triggers a duplicate (billed) generation.

Queue Stuck on 🌐 Offline

If every thread in the status view shows 🌐 Offline while your connection works, the add-on's connectivity probe is giving a false negative (captive portal, DNS, proxy). Two escapes:

1. ⚡ Force Start — one-run bypass of readiness + offline checks (nothing saved).
2. Advanced → Model Cooldowns & Blacklist → Ignore network/offline checks — permanent bypass (ignore_network_checks). Real failures still trigger normal cooldowns.

Starting from the Deck Browser

You can also start batch generation directly from the deck browser's cogwheel options menu.

Regenerate by Stored Model

The Regenerate Cards by Stored Model tool can target the selected deck, Entire Collection, or a browser selection. It queues only cards whose stored provider/model matches the requested model and uses the same background queue and verification behavior as normal batch generation.

Note Tagging & Fast Scan

When note tagging is enabled, generated notes get the ai-hints tag and untagged notes are the only ones scanned during batch runs, making repeat scans near-instant. Use 🏷️ Tag All Cards with Hints in the Advanced tab to tag cards created before tagging was enabled.