opencode-rag-plugin 1.19.5 → 1.19.8

package/dist/chunker/image.js

@@ -42,6 +42,7 @@ class OllamaImageVisionProvider {
     timeoutMs;
     think;
     numCtx;
+    keepAlive;
     proxy;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, "");
@@ -49,6 +50,7 @@ class OllamaImageVisionProvider {
         this.timeoutMs = config.timeoutMs;
         this.think = config.think ?? false;
         this.numCtx = config.numCtx;
+        this.keepAlive = config.keepAlive;
         this.proxy = config.proxy;
     }
     async describeImage(imageBase64, _mimeType, prompt, abort) {
@@ -65,6 +67,9 @@ class OllamaImageVisionProvider {
             think: this.think,
             options: { num_ctx: this.numCtx },
         };
+        if (this.keepAlive) {
+            body.keep_alive = this.keepAlive;
+        }
         let lastError;
         for (let attempt = 0; attempt <= VISION_RETRY_MAX; attempt++) {
             const response = await postJson(`${this.baseUrl}/chat`, body, {}, this.timeoutMs, this.proxy, abort);

package/dist/cli/commands/backend-detect.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Auto-detect the Ollama backend (CPU vs GPU) during `init` and
+ * pick embedding batch settings tuned for the detected backend.
+ */
+/**
+ * Auto-detect whether Ollama runs models on the GPU or on the CPU and return
+ * matching embedding batch tuning.
+ *
+ * Detection uses `GET /api/ps`: loaded models report `size_vram` (bytes
+ * resident in VRAM). `size_vram > 0` means the model is (at least partially)
+ * offloaded to the GPU. If no model is loaded yet, a minimal `/api/embed`
+ * warmup loads the default embedding model first.
+ *
+ * Tuning is derived from benchmarks (see quirk memory):
+ * - GPU:  batch 40 + concurrency 4 ≈ 86 texts/s (~97% of the ~88 texts/s ceiling)
+ * - CPU:  flat ~3.5 texts/s regardless of batch size → small batches (20) with
+ *         concurrency 1 keep each request fast and under the 4096-token context
+ * - unreachable/unknown: defaults (100 / 3 / 100)
+ */
+import { type ProxyConfig } from "../../core/config.js";
+/** Detected Ollama backend kind. */
+export type OllamaBackend = "gpu" | "cpu" | "unreachable" | "unknown";
+/** Embedding batch settings written into the generated config. */
+export interface IndexingTuning {
+    embedBatchSize: number;
+    embedConcurrency: number;
+    ollamaMaxBatchSize: number;
+}
+/** Result of the backend detection. */
+export interface OllamaBackendInfo {
+    backend: OllamaBackend;
+    /** Tuning to write into the generated config. */
+    tuning: IndexingTuning;
+    /** Human-readable summary for the init output. */
+    message: string;
+}
+interface PsModel {
+    name: string;
+    size_vram?: number;
+}
+/**
+ * Classify loaded Ollama models into a backend + tuning profile.
+ *
+ * Prefers the configured default embedding model when it is loaded, falling
+ * back to any loaded model (a loaded GPU model means the host has a working
+ * GPU that Ollama will also use for embeddings).
+ *
+ * @param models - The `models` array from `GET /api/ps`.
+ * @returns The backend info with the matching tuning profile.
+ */
+export declare function classifyOllamaModels(models: PsModel[]): OllamaBackendInfo;
+/**
+ * Detect the Ollama backend by probing `/api/ps`, warming up the default
+ * embedding model when nothing is loaded yet.
+ *
+ * @param baseUrl - Ollama API base URL (defaults to the config default).
+ * @param proxy - Optional proxy configuration.
+ * @returns Backend info; never throws.
+ */
+export declare function detectOllamaBackend(baseUrl?: string, proxy?: ProxyConfig): Promise<OllamaBackendInfo>;
+export {};

package/dist/cli/commands/backend-detect.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Auto-detect the Ollama backend (CPU vs GPU) during `init` and
+ * pick embedding batch settings tuned for the detected backend.
+ */
+/**
+ * Auto-detect whether Ollama runs models on the GPU or on the CPU and return
+ * matching embedding batch tuning.
+ *
+ * Detection uses `GET /api/ps`: loaded models report `size_vram` (bytes
+ * resident in VRAM). `size_vram > 0` means the model is (at least partially)
+ * offloaded to the GPU. If no model is loaded yet, a minimal `/api/embed`
+ * warmup loads the default embedding model first.
+ *
+ * Tuning is derived from benchmarks (see quirk memory):
+ * - GPU:  batch 40 + concurrency 4 ≈ 86 texts/s (~97% of the ~88 texts/s ceiling)
+ * - CPU:  flat ~3.5 texts/s regardless of batch size → small batches (20) with
+ *         concurrency 1 keep each request fast and under the 4096-token context
+ * - unreachable/unknown: defaults (100 / 3 / 100)
+ */
+import { DEFAULT_CONFIG } from "../../core/config.js";
+import { fetchWithProxy, postJson } from "../../embedder/http.js";
+/** Benchmarked optimum on a GPU-backed Ollama (RTX 4090, qwen3-embedding:0.6b). */
+const GPU_TUNING = {
+    embedBatchSize: 40,
+    embedConcurrency: 4,
+    ollamaMaxBatchSize: 40,
+};
+/** CPU-backed Ollama: throughput is flat, so keep batches small and sequential. */
+const CPU_TUNING = {
+    embedBatchSize: 20,
+    embedConcurrency: 1,
+    ollamaMaxBatchSize: 20,
+};
+/** Fallback when Ollama is unreachable or the backend cannot be determined. */
+const DEFAULT_TUNING = {
+    embedBatchSize: DEFAULT_CONFIG.indexing.embedBatchSize,
+    embedConcurrency: DEFAULT_CONFIG.indexing.embedConcurrency ?? 3,
+    ollamaMaxBatchSize: DEFAULT_CONFIG.indexing.ollamaMaxBatchSize ?? 100,
+};
+/**
+ * Classify loaded Ollama models into a backend + tuning profile.
+ *
+ * Prefers the configured default embedding model when it is loaded, falling
+ * back to any loaded model (a loaded GPU model means the host has a working
+ * GPU that Ollama will also use for embeddings).
+ *
+ * @param models - The `models` array from `GET /api/ps`.
+ * @returns The backend info with the matching tuning profile.
+ */
+export function classifyOllamaModels(models) {
+    if (!models || models.length === 0) {
+        return {
+            backend: "unknown",
+            tuning: DEFAULT_TUNING,
+            message: "Could not determine the Ollama backend (no models loaded) — using default batch settings.",
+        };
+    }
+    const embedModel = DEFAULT_CONFIG.embedding.model;
+    const probe = models.find((m) => m.name === embedModel) ?? models[0];
+    const onGpu = probe ? (probe.size_vram ?? 0) > 0 : false;
+    if (onGpu) {
+        return {
+            backend: "gpu",
+            tuning: GPU_TUNING,
+            message: `Ollama detected on GPU — tuned embedding for batch 40 / concurrency 4 (${(probe?.size_vram ?? 0) / (1024 * 1024) | 0} MiB in VRAM).`,
+        };
+    }
+    return {
+        backend: "cpu",
+        tuning: CPU_TUNING,
+        message: "Ollama detected on CPU — tuned embedding for batch 20 / concurrency 1.",
+    };
+}
+/** Fetch `GET /api/ps`, returning null when Ollama is unreachable or errors. */
+async function getOllamaPs(baseUrl, proxy) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/ps`;
+    try {
+        const res = await fetchWithProxy(url, { method: "GET", signal: AbortSignal.timeout(3000) }, proxy);
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.models ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect the Ollama backend by probing `/api/ps`, warming up the default
+ * embedding model when nothing is loaded yet.
+ *
+ * @param baseUrl - Ollama API base URL (defaults to the config default).
+ * @param proxy - Optional proxy configuration.
+ * @returns Backend info; never throws.
+ */
+export async function detectOllamaBackend(baseUrl = DEFAULT_CONFIG.embedding.baseUrl, proxy) {
+    let models = await getOllamaPs(baseUrl, proxy);
+    if (models === null) {
+        return {
+            backend: "unreachable",
+            tuning: DEFAULT_TUNING,
+            message: "Ollama not reachable — using default batch settings.",
+        };
+    }
+    if (models.length === 0) {
+        // Nothing loaded yet: a minimal embed request loads the default
+        // embedding model so /api/ps can report its backend.
+        const embedUrl = `${baseUrl.replace(/\/+$/, "")}/embed`;
+        try {
+            await postJson(embedUrl, { model: DEFAULT_CONFIG.embedding.model, input: "warmup" }, {}, 15000, proxy);
+        }
+        catch {
+            // Model missing or request failed — classification will stay unknown.
+        }
+        models = (await getOllamaPs(baseUrl, proxy)) ?? [];
+    }
+    return classifyOllamaModels(models);
+}
+//# sourceMappingURL=backend-detect.js.map

package/dist/cli/commands/index-command.js

@@ -13,6 +13,7 @@ import readline from "node:readline";
 import chokidar from "chokidar";
 import { appendDebugLog } from "../../core/fileLogger.js";
 import { createWatchPassScheduler, createWatchIgnore, runIndexPass, } from "../../indexer.js";
+import { tryAcquireWatcherLock, releaseWatcherLock } from "../../watcher.js";
 import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, logIndexSummary, formatDuration, } from "../format.js";
 /**
  * Build a logger that suppresses console output when watchTriggered is true.
@@ -129,6 +130,15 @@ export function registerIndexCommand(program) {
                 await cleanupContext(ctx);
                 process.exit(sigReceived ? 130 : 0);
             }
+            // Only one watcher may run per workspace — a background auto-indexer
+            // in an OpenCode session (or another `index --watch`) may already own
+            // this store. The initial pass above still ran; just don't start a
+            // duplicate watcher.
+            if (!tryAcquireWatcherLock(storePath)) {
+                logCliInfo(logFilePath, "index", c.warn("Another watcher is already running for this workspace (e.g. an OpenCode session with auto-index enabled) — not starting a second one. The index is up to date."));
+                await cleanupContext(ctx);
+                process.exit(0);
+            }
             logCliInfo(logFilePath, "index", `\n${c.heading("Watching for changes...")}`);
             const scheduler = createWatchPassScheduler(async (changedPaths) => { await runPass(true, undefined, changedPaths); }, (error) => {
                 const message = error.message || String(error);
@@ -154,6 +164,7 @@ export function registerIndexCommand(program) {
                     watcher.close(),
                     new Promise((r) => setTimeout(r, 5000)),
                 ]);
+                releaseWatcherLock(storePath);
                 await cleanupContext(ctx);
                 process.exit(0);
             };

package/dist/cli/commands/init-helpers.d.ts

@@ -6,6 +6,7 @@
  * dependency installation, and gitignore merging.
  */
 import type { PackageMetadata } from "../types.js";
+import type { IndexingTuning } from "./backend-detect.js";
 /**
  * Build the workspace-local `.opencode/package.json` content.
  *
@@ -115,6 +116,8 @@ export declare function installPluginFromGlobal(opencodeDir: string, packageName
 /**
  * Generate the default `opencode-rag.json` configuration content.
  *
+ * @param tuning - Optional embedding batch tuning (auto-detected from the
+ *   Ollama backend). Falls back to `DEFAULT_CONFIG` for any omitted field.
  * @returns A pretty-printed JSON string with all default configuration values.
  */
-export declare function generateDefaultConfigJson(): string;
+export declare function generateDefaultConfigJson(tuning?: Partial<IndexingTuning>): string;

package/dist/cli/commands/init-helpers.js

@@ -414,9 +414,11 @@ export async function installPluginFromGlobal(opencodeDir, packageName, skipInst
 /**
  * Generate the default `opencode-rag.json` configuration content.
  *
+ * @param tuning - Optional embedding batch tuning (auto-detected from the
+ *   Ollama backend). Falls back to `DEFAULT_CONFIG` for any omitted field.
  * @returns A pretty-printed JSON string with all default configuration values.
  */
-export function generateDefaultConfigJson() {
+export function generateDefaultConfigJson(tuning) {
     return JSON.stringify({
         embedding: {
             provider: DEFAULT_CONFIG.embedding.provider,
@@ -430,7 +432,9 @@ export function generateDefaultConfigJson() {
             chunkOverlap: DEFAULT_CONFIG.indexing.chunkOverlap,
             minFileSizeBytes: DEFAULT_CONFIG.indexing.minFileSizeBytes,
             concurrency: DEFAULT_CONFIG.indexing.concurrency,
-            embedBatchSize: DEFAULT_CONFIG.indexing.embedBatchSize,
+            embedBatchSize: tuning?.embedBatchSize ?? DEFAULT_CONFIG.indexing.embedBatchSize,
+            embedConcurrency: tuning?.embedConcurrency ?? DEFAULT_CONFIG.indexing.embedConcurrency ?? 3,
+            ollamaMaxBatchSize: tuning?.ollamaMaxBatchSize ?? DEFAULT_CONFIG.indexing.ollamaMaxBatchSize ?? 100,
         },
         vectorStore: {
             path: DEFAULT_CONFIG.vectorStore.path,

package/dist/cli/commands/init.js

@@ -17,6 +17,7 @@ import { destroyAllPooledConnections } from "../../embedder/http.js";
 import { c } from "../format.js";
 import { getPackageMetadata, readJsonObject, writeJsonFile } from "../helpers.js";
 import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJson, generateSkillFile, generateWorkspacePluginFile, generateWorkspaceTuiPluginFile, installPluginFromGlobal, mergeAgentsMdContent, mergeGitignoreContent, } from "./init-helpers.js";
+import { detectOllamaBackend } from "./backend-detect.js";
 /**
  * Register the `init` command on the given Commander program.
  *
@@ -29,7 +30,14 @@ import { buildOpencodeConfig, buildWorkspacePackageJson, generateDefaultConfigJs
 export function registerInitCommand(program) {
     program
         .command("init")
-        .description("Configure the current workspace for OpenCodeRAG")
+        .description("Configure this workspace (files + auto-tuned opencode-rag.json)")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time workspace setup: creates .opencode/, the RAG skill file, AGENTS.md\n" +
+        "    guidance, and opencode-rag.json with embedding batches auto-detected for the\n" +
+        "    Ollama backend (GPU vs CPU).\n" +
+        "  - Re-running in an existing workspace: re-syncs plugin/skill files and keeps the\n" +
+        "    existing opencode-rag.json (overwriting requires interactive confirmation).\n" +
+        "\nWorkspace-level step — run AFTER 'opencode-rag setup' on this machine, then 'opencode-rag index'.\n")
         .option("-f, --force", "overwrite existing files")
         .option("--skip-install", "skip installing workspace-local plugin dependencies")
         .option("--skip-health-check", "skip provider connectivity and model availability check")
@@ -189,8 +197,27 @@ export function registerInitCommand(program) {
                 console.log(`  ${c.exists("Exists:")}   .opencode/package.json`);
             }
             const configExists = existsSync(configPath);
+            // Detect the Ollama backend (CPU vs GPU) lazily — only when we are
+            // actually about to write a config — and tune embedding batches for it.
+            let detectedTuning;
+            const configContent = async () => {
+                if (!detectedTuning) {
+                    try {
+                        const info = await detectOllamaBackend();
+                        detectedTuning = info.tuning;
+                        const icon = info.backend === "gpu" ? c.success("GPU:") :
+                            info.backend === "cpu" ? c.warn("CPU:") :
+                                c.dim("Backend:");
+                        console.log(`  ${icon} ${info.message}`);
+                    }
+                    catch {
+                        detectedTuning = undefined;
+                    }
+                }
+                return generateDefaultConfigJson(detectedTuning);
+            };
             if (!configExists) {
-                writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                writeFileSync(configPath, await configContent(), "utf-8");
                 console.log(`  ${c.created("Created:")} opencode-rag.json`);
             }
             else {
@@ -208,7 +235,7 @@ export function registerInitCommand(program) {
                 if (overwrite) {
                     copyFileSync(configPath, `${configPath}.bak`);
                     console.log(`  ${c.dim("Backup:")}        opencode-rag.json.bak`);
-                    writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                    writeFileSync(configPath, await configContent(), "utf-8");
                     console.log(`  ${c.updated("Updated:")}  opencode-rag.json`);
                 }
                 else {

package/dist/cli/commands/setup.js

@@ -36,7 +36,13 @@ function checkOpenCodeRunning() {
 export function registerSetupCommand(program) {
     program
         .command("setup")
-        .description("Set up the OpenCodeRAG runtime (~/.opencode/) for OpenCode plugin discovery")
+        .description("Install/update the OpenCodeRAG runtime once per machine")
+        .addHelpText("after", "\nUse cases:\n" +
+        "  - First-time install: run once per machine to install the plugin runtime\n" +
+        "    into ~/.opencode/ so OpenCode can discover the RAG plugin.\n" +
+        "  - Updating: re-sync the runtime to the published plugin version.\n" +
+        "  - Troubleshooting: use --check to inspect the runtime, or --force to reinstall.\n" +
+        "\nMachine-level step — run BEFORE 'opencode-rag init' (init configures each workspace).\n")
         .option("--uninstall", "remove the runtime and cleanup")
         .option("-f, --force", "force re-setup even if up-to-date")
         .option("--check", "check whether the runtime is correctly installed")

package/dist/core/config.d.ts

@@ -54,7 +54,18 @@ export interface DescriptionConfig {
     proxy?: ProxyConfig;
     /** System prompt instructing the LLM how to describe code. */
     systemPrompt: string;
-    /** Maximum chunks per batch request. */
+    /**
+     * EXPERIMENTAL: enable multi-chunk batch description requests (Ollama
+     * provider only). Off by default — each chunk is described with its own
+     * request. When enabled, up to `batchMaxChunks` chunks share one request
+     * using ordinal labels ([CHUNK 1] ... reply "1: <desc>"); small models can
+     * mangle the structured output, so batches that fail to parse fall back to
+     * individual requests and batching auto-disables after 2 consecutive
+     * failures. Part of the description manifest fingerprint — toggling it
+     * re-describes files.
+     */
+    batchEnabled?: boolean;
+    /** Maximum chunks per batch request. Only applies when `batchEnabled` is true. */
     batchMaxChunks?: number;
     /** Timeout per batch request in milliseconds. */
     batchTimeoutMs?: number;
@@ -68,6 +79,8 @@ export interface DescriptionConfig {
     think?: boolean;
     /** Context window size for the LLM. */
     numCtx?: number;
+    /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/chat requests. */
+    keepAlive?: string;
     /** Maximum content characters sent to the LLM. Chunks exceeding this use fallback descriptions. */
     maxContentChars?: number;
 }
@@ -91,6 +104,8 @@ export interface ImageDescriptionConfig {
     think?: boolean;
     /** Context window size. */
     numCtx?: number;
+    /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/chat requests. */
+    keepAlive?: string;
     /** Proxy configuration. */
     proxy?: ProxyConfig;
     /** Maximum image dimension (pixels) — larger images are resized before sending. */
@@ -220,6 +235,8 @@ export interface RagConfig {
         queryPrefix?: string;
         /** Cached embedding vector dimension. Probed once on first startup, then persisted to config. */
         vectorDimension?: number;
+        /** Ollama keep_alive value (e.g. "-1" for keep-in-memory) sent with /api/embed requests. */
+        keepAlive?: string;
     };
     /** Indexing pipeline controls: what to index, concurrency, batch sizes. */
     indexing: {
@@ -268,6 +285,15 @@ export interface RagConfig {
          * @default 1_048_576 (1 MB)
          */
         maxSvgSizeBytes?: number;
+        /**
+         * Run vector-store compaction + version pruning every N windows during a
+         * long index pass. LanceDB keeps every committed version on disk, so
+         * without periodic maintenance the store phase slows down as the index
+         * grows (version-manifest accumulation). 0 disables mid-run optimization
+         * (the store is still optimized once at the end of a pass).
+         * @default 8
+         */
+        optimizeIntervalWindows?: number;
     };
     /** Vector storage backend configuration. */
     vectorStore: {

package/dist/core/config.js

@@ -115,9 +115,10 @@ export const DEFAULT_CONFIG = {
         concurrency: 8,
         embedBatchSize: 100,
         embedConcurrency: 3,
-        ollamaMaxBatchSize: 500,
+        ollamaMaxBatchSize: 100,
         descriptionConcurrency: 4,
         maxSvgSizeBytes: 1_048_576,
+        optimizeIntervalWindows: 8,
     },
     vectorStore: {
         path: "./.opencode/rag_db",
@@ -169,7 +170,10 @@ export const DEFAULT_CONFIG = {
         think: false,
         numCtx: 4096,
         timeoutMs: 60000,
-        systemPrompt: "Describe this code in 2-3 sentences: purpose, key concepts, inputs/outputs, and dependencies. No code repetition.",
+        systemPrompt: "Describe this code in ONE concise sentence (max 20 words): purpose, key inputs/outputs. No code repetition.",
+        batchEnabled: false,
+        batchMaxChunks: 25,
+        batchTimeoutMs: 120000,
         batchConcurrency: 1,
         retryMax: 3,
         retryBaseDelayMs: 1000,
@@ -427,6 +431,10 @@ export function validateConfig(config) {
         if (config.description.timeoutMs != null && config.description.timeoutMs <= 0) {
             warnings.push("description.timeoutMs must be > 0");
         }
+        if (config.description.batchEnabled === true) {
+            warnings.push("description.batchEnabled is EXPERIMENTAL — batching several chunks into one LLM request (Ollama only) " +
+                "is unreliable on small models; disable it if descriptions look wrong");
+        }
     }
     if (config.imageDescription) {
         if (config.imageDescription.enabled) {

package/dist/core/interfaces.d.ts

@@ -157,10 +157,31 @@ export interface FileSummary {
     language: string;
     chunkCount: number;
 }
+/**
+ * A single file's chunk payload for a bulk store write.
+ * `dedup: true` removes prior-revision rows for the same file path that are
+ * not part of this write; `dedup: false` appends only (safe when writing into
+ * a freshly-created store where no rows can collide).
+ */
+export interface BulkChunkWrite {
+    chunks: Chunk[];
+    dedup: boolean;
+}
 /** Persistent vector storage and retrieval backend (LanceDB or in-memory). */
 export interface VectorStore {
-    /** Store a batch of chunks with their embeddings. */
-    addChunks(chunks: Chunk[]): Promise<void>;
+    /**
+     * Store a batch of chunks with their embeddings.
+     * @param options - `dedup: false` skips prior-revision cleanup (append-only).
+     */
+    addChunks(chunks: Chunk[], options?: {
+        dedup?: boolean;
+    }): Promise<void>;
+    /**
+     * Store chunks for multiple files in a single write transaction.
+     * Optional — stores without it fall back to per-file `addChunks` calls.
+     * @param items - Per-file chunk payloads with dedup flags.
+     */
+    addChunksBulk?(items: BulkChunkWrite[]): Promise<void>;
     /** Search for the top-K nearest neighbor chunks by embedding similarity. */
     search(embedding: number[], topK: number): Promise<SearchResult[]>;
     /** Search with optional metadata filtering. */
@@ -183,8 +204,15 @@ export interface VectorStore {
     getChunksByFilePath(filePath: string): Promise<Chunk[]>;
     /** Re-open the store, optionally pointing at a new database path. */
     reopen?(newPath?: string): Promise<void>;
-    /** Compact fragments and prune old versions to prevent version-manifest accumulation. */
-    optimize?(): Promise<void>;
+    /**
+     * Compact fragments and prune old versions to prevent version-manifest
+     * accumulation.
+     * @param options - `aggressive: true` prunes all but the current version
+     *   (only safe when no other process reads the store, e.g. temp rebuilds).
+     */
+    optimize?(options?: {
+        aggressive?: boolean;
+    }): Promise<void>;
     /**
      * Verify that the store's data is actually readable.
      * Returns false if data integrity is compromised (e.g., data files missing from disk).

package/dist/core/manifest.js

@@ -44,7 +44,7 @@ export function computeDescriptionConfigHash(config) {
         return undefined;
     const parts = [];
     if (desc) {
-        parts.push(`desc:${desc.provider}|${desc.model}|${desc.baseUrl}|${desc.systemPrompt}`);
+        parts.push(`desc:${desc.provider}|${desc.model}|${desc.baseUrl}|${desc.systemPrompt}|batch:${desc.batchEnabled === true ? 1 : 0}`);
     }
     if (img) {
         parts.push(`img:${img.provider}|${img.model}|${img.baseUrl}|${img.prompt}`);

package/dist/describer/describer.d.ts

@@ -11,6 +11,10 @@ import type { DescriptionConfig } from "../core/config.js";
  */
 export declare class LlmDescriptionProvider implements DescriptionProvider {
     private readonly config;
+    /** Consecutive batches that needed individual fallback; disables batching past BATCH_MAX_STREAK. */
+    private batchFailStreak;
+    /** Whether multi-chunk batching is still active (adaptive, per provider instance / index run). */
+    private adaptiveBatchActive;
     /**
      * @param config - Configuration for the LLM provider, including base URL, model, API key, proxy, and retry settings.
      */
@@ -23,6 +27,22 @@ export declare class LlmDescriptionProvider implements DescriptionProvider {
     }): Promise<string>;
     /** @inheritdoc */
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
+    /**
+     * Describe a group of chunks in a single LLM request and parse the response.
+     *
+     * Builds one chat request whose user message contains all chunks wrapped in
+     * `[CHUNK <n>]` markers and expects a `<n>: <description>` line per chunk.
+     * Labels are ordinals and are mapped back to chunks by position in the
+     * calling group; labels outside the group's range (hallucinations) are
+     * naturally dropped, prompting the caller to fall back to individual
+     * requests for the missing chunks.
+     *
+     * @param group - Chunks to describe in one request (length > 1)
+     * @param log - Logger for diagnostic messages
+     * @returns Map of ordinal label to description (may be partial or empty)
+     * @throws When the LLM request itself fails (caller falls back per chunk)
+     */
+    private batchDescribe;
     /**
      * Sends a chat completion request to the LLM API with retry and exponential backoff.
      * For Ollama, uses the `/api/chat` endpoint with streaming disabled; otherwise uses the standard `/v1/chat/completions` endpoint.