# 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.