opencode-rag-plugin 1.19.5 → 1.19.8

package/dist/describer/describer.js

@@ -1,8 +1,10 @@
 import { postJson } from "../embedder/http.js";
-import { buildUserMessage, sleep } from "./shared.js";
+import { buildUserMessage, buildBatchUserMessage, parseBatchDescriptions, sleep } from "./shared.js";
 import pLimit from "p-limit";
 /** HTTP status codes that are safe to retry on. */
 const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+/** Consecutive failed batch attempts after which batching is disabled for the rest of the run. */
+const BATCH_MAX_STREAK = 2;
 /**
  * Description provider that works with any OpenAI-compatible chat API (including Ollama).
  *
@@ -11,6 +13,10 @@ const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
  */
 export class LlmDescriptionProvider {
     config;
+    /** Consecutive batches that needed individual fallback; disables batching past BATCH_MAX_STREAK. */
+    batchFailStreak = 0;
+    /** Whether multi-chunk batching is still active (adaptive, per provider instance / index run). */
+    adaptiveBatchActive = true;
     /**
      * @param config - Configuration for the LLM provider, including base URL, model, API key, proxy, and retry settings.
      */
@@ -37,28 +43,125 @@ export class LlmDescriptionProvider {
     async generateBatchDescriptions(chunks, logger, opts) {
         const log = logger ?? { info: (msg) => process.stderr.write(`${msg}\n`), warn: (msg) => process.stderr.write(`${msg}\n`), debug: (msg) => process.stderr.write(`${msg}\n`) };
         const concurrency = this.config.batchConcurrency ?? 3;
+        // Batching is an EXPERIMENTAL opt-in (description.batchEnabled). Off by
+        // default — a batch size of 1 routes every group through the individual
+        // request path below, which is exactly the per-chunk behavior.
+        const batchEnabled = this.config.batchEnabled === true;
+        const batchMaxChunks = batchEnabled ? (this.config.batchMaxChunks ?? 25) : 1;
         const total = chunks.length;
-        log.debug(`[describer] Generating descriptions for ${total} chunks via ${this.config.provider}/${this.config.model} (concurrency: ${concurrency})`);
+        log.debug(`[describer] Generating descriptions for ${total} chunks via ${this.config.provider}/${this.config.model} (concurrency: ${concurrency}, batch: ${batchEnabled ? batchMaxChunks : "off"})`);
         const result = new Map();
         const limit = pLimit(concurrency);
         let completed = 0;
-        await Promise.all(chunks.map((chunk) => limit(async () => {
-            const userMsg = buildUserMessage(chunk, this.config.maxContentChars);
-            log.debug(`[describer] REQUEST chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}):\n${userMsg}`);
-            try {
-                const desc = await this.generateDescription(chunk);
-                result.set(chunk.id, desc);
-                log.debug(`[describer] RESPONSE chunk ${chunk.id}: ${desc}`);
-            }
-            catch (err) {
-                log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
-            }
+        const emitProgress = (chunk) => {
             completed++;
             opts?.onProgress?.(chunk, completed, opts.total ?? total);
+        };
+        // Group chunks so that up to batchMaxChunks share a single LLM request,
+        // cutting round trips (one prefill + one generation per group instead of
+        // per chunk). Groups with a single chunk use the individual path for
+        // consistent error handling.
+        const groups = [];
+        for (let i = 0; i < chunks.length; i += batchMaxChunks) {
+            groups.push(chunks.slice(i, i + batchMaxChunks));
+        }
+        await Promise.all(groups.map((group) => limit(async () => {
+            if (group.length === 1) {
+                const chunk = group[0];
+                try {
+                    const desc = await this.generateDescription(chunk);
+                    result.set(chunk.id, desc);
+                }
+                catch (err) {
+                    log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                emitProgress(chunk);
+                return;
+            }
+            // Small models are unreliable at structured multi-item output — if a
+            // batch response can't be parsed, fall back to individual requests
+            // and degrade to per-chunk mode for the rest of the run after
+            // BATCH_MAX_STREAK consecutive failures.
+            let resolved;
+            let batchFailed = false;
+            if (this.adaptiveBatchActive) {
+                try {
+                    resolved = await this.batchDescribe(group, log);
+                }
+                catch (err) {
+                    log.warn(`[describer] Batch description failed for ${group.length} chunks, falling back to individual: ${err instanceof Error ? err.message : String(err)}`);
+                    resolved = new Map();
+                    batchFailed = true;
+                }
+            }
+            else {
+                resolved = new Map();
+            }
+            // Batch labels are ordinals (1..N); map back to chunks by position.
+            const missing = [];
+            for (let i = 0; i < group.length; i++) {
+                const chunk = group[i];
+                const desc = resolved.get(String(i + 1));
+                if (desc && desc.trim().length > 0) {
+                    result.set(chunk.id, desc.trim());
+                    emitProgress(chunk);
+                }
+                else {
+                    missing.push(chunk);
+                }
+            }
+            if (batchFailed || missing.length > 0) {
+                this.batchFailStreak++;
+                if (this.adaptiveBatchActive && this.batchFailStreak >= BATCH_MAX_STREAK) {
+                    this.adaptiveBatchActive = false;
+                    log.warn(`[describer] Batch descriptions unreliable (${this.batchFailStreak} consecutive failures), switching to individual requests for the rest of the run`);
+                }
+            }
+            else {
+                this.batchFailStreak = 0;
+            }
+            // Fall back to individual requests for chunks the batch did not cover.
+            for (const chunk of missing) {
+                try {
+                    const desc = await this.generateDescription(chunk);
+                    result.set(chunk.id, desc);
+                }
+                catch (err) {
+                    log.warn(`[describer] Failed to describe chunk ${chunk.id} (${chunk.metadata.filePath}:${chunk.metadata.startLine}): ${err instanceof Error ? err.message : String(err)}`);
+                }
+                emitProgress(chunk);
+            }
         })));
         log.debug(`[describer] Descriptions generated: ${result.size}/${total}`);
         return result;
     }
+    /**
+     * 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)
+     */
+    async batchDescribe(group, log) {
+        const messages = [
+            { role: "system", content: this.config.systemPrompt },
+            { role: "user", content: buildBatchUserMessage(group, this.config.maxContentChars) },
+        ];
+        const timeoutMs = this.config.batchTimeoutMs ?? this.config.timeoutMs ?? 120000;
+        log.debug(`[describer] BATCH REQUEST ${group.length} chunks (${group[0].metadata.filePath}):\n${messages[1].content}`);
+        const content = await this.chatRequest(messages, timeoutMs);
+        const parsed = parseBatchDescriptions(content);
+        log.debug(`[describer] BATCH RESPONSE parsed ${parsed.size}/${group.length} chunks`);
+        return parsed;
+    }
     /**
      * 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.
@@ -75,7 +178,7 @@ export class LlmDescriptionProvider {
             ? `${baseUrl}/chat`
             : `${baseUrl}${baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
         const body = isOllama
-            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx } }
+            ? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: this.config.keepAlive }
             : { model: this.config.model, messages };
         const headers = {};
         if (this.config.apiKey) {

package/dist/describer/shared.d.ts

@@ -15,3 +15,31 @@ import type { Chunk } from "../core/interfaces.js";
 export declare function buildUserMessage(chunk: Chunk, maxContentChars?: number): string;
 /** Promise-based delay for use with async/await. */
 export declare function sleep(ms: number): Promise<void>;
+/**
+ * Build a user message describing multiple chunks in a single LLM request.
+ *
+ * Each chunk is wrapped in `[CHUNK <n>] ... [END CHUNK <n>]` markers using
+ * short ordinal labels (1-based position in the group) rather than chunk
+ * UUIDs — small models reliably reproduce `n: <description>` lines but often
+ * mangle long random ids. The model is asked to reply with exactly one line
+ * per chunk in `<n>: <one-line description>` format (see
+ * `parseBatchDescriptions`); labels map back to chunks by position.
+ *
+ * @param chunks - The chunks to describe in one request
+ * @param maxContentChars - Optional per-chunk content truncation limit
+ * @returns Formatted message string for the batched LLM request
+ */
+export declare function buildBatchUserMessage(chunks: Chunk[], maxContentChars?: number): string;
+/**
+ * Parse a batched description response into a `label → description` map.
+ *
+ * Tolerant parser: only lines matching `<label>: <text>` are kept, so
+ * preamble, trailing prose, or markdown fences are ignored. Labels are the
+ * short ordinals used in `buildBatchUserMessage` (e.g. `1: handles auth`);
+ * they are mapped back to chunk IDs by position in the calling group.
+ * Duplicate labels keep the first occurrence.
+ *
+ * @param content - Raw response text from the LLM
+ * @returns Map of label to description (may be empty or partial)
+ */
+export declare function parseBatchDescriptions(content: string): Map<string, string>;

package/dist/describer/shared.js

@@ -31,4 +31,64 @@ export function buildUserMessage(chunk, maxContentChars) {
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Build a user message describing multiple chunks in a single LLM request.
+ *
+ * Each chunk is wrapped in `[CHUNK <n>] ... [END CHUNK <n>]` markers using
+ * short ordinal labels (1-based position in the group) rather than chunk
+ * UUIDs — small models reliably reproduce `n: <description>` lines but often
+ * mangle long random ids. The model is asked to reply with exactly one line
+ * per chunk in `<n>: <one-line description>` format (see
+ * `parseBatchDescriptions`); labels map back to chunks by position.
+ *
+ * @param chunks - The chunks to describe in one request
+ * @param maxContentChars - Optional per-chunk content truncation limit
+ * @returns Formatted message string for the batched LLM request
+ */
+export function buildBatchUserMessage(chunks, maxContentChars) {
+    const parts = [
+        "Describe each code chunk below in ONE short sentence (max 20 words) each.",
+        "Do not repeat code in your descriptions.",
+        "Reply with EXACTLY one line per chunk, in this format:",
+        "<number>: <one-line description>",
+        "",
+    ];
+    chunks.forEach((chunk, index) => {
+        const label = index + 1;
+        parts.push(`[CHUNK ${label}]`);
+        parts.push(buildUserMessage(chunk, maxContentChars));
+        parts.push(`[END CHUNK ${label}]`);
+        parts.push("");
+    });
+    return parts.join("\n").trim();
+}
+/**
+ * Parse a batched description response into a `label → description` map.
+ *
+ * Tolerant parser: only lines matching `<label>: <text>` are kept, so
+ * preamble, trailing prose, or markdown fences are ignored. Labels are the
+ * short ordinals used in `buildBatchUserMessage` (e.g. `1: handles auth`);
+ * they are mapped back to chunk IDs by position in the calling group.
+ * Duplicate labels keep the first occurrence.
+ *
+ * @param content - Raw response text from the LLM
+ * @returns Map of label to description (may be empty or partial)
+ */
+export function parseBatchDescriptions(content) {
+    const result = new Map();
+    const lineRe = /^([A-Za-z0-9_.-]+):\s*(.+)$/;
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const match = lineRe.exec(line);
+        if (match && match[1] && match[2] && match[2].trim().length > 0) {
+            const id = match[1];
+            if (!result.has(id)) {
+                result.set(id, match[2].trim());
+            }
+        }
+    }
+    return result;
+}
 //# sourceMappingURL=shared.js.map

package/dist/embedder/factory.js

@@ -24,7 +24,7 @@ export function createEmbedder(config) {
             "Use an embedding-capable provider (ollama, openai, cohere, nvidia, azure, mistral, together, fireworks).");
     }
     if (provider === "ollama") {
-        return new OllamaProvider(baseUrl, model, apiKey, effectiveTimeoutMs, proxy, config.logging.level);
+        return new OllamaProvider(baseUrl, model, apiKey, effectiveTimeoutMs, proxy, config.logging.level, config.embedding.keepAlive);
     }
     if (provider === "cohere") {
         if (!apiKey) {

package/dist/embedder/ollama.d.ts

@@ -12,6 +12,7 @@ import type { ProxyConfig } from "../core/config.js";
    * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  * @param logLevel - Optional logging level for debug output
+ * @param keepAlive - Optional Ollama keep_alive value sent with /api/embed requests (e.g. "-1")
  */
 export declare class OllamaProvider implements EmbeddingProvider {
     readonly name = "ollama";
@@ -21,7 +22,8 @@ export declare class OllamaProvider implements EmbeddingProvider {
     private readonly timeoutMs;
     private proxy?;
     private readonly logLevel?;
-    constructor(baseUrl: string, model: string, apiKey?: string, timeoutMs?: number, proxy?: ProxyConfig, logLevel?: string);
+    private readonly keepAlive?;
+    constructor(baseUrl: string, model: string, apiKey?: string, timeoutMs?: number, proxy?: ProxyConfig, logLevel?: string, keepAlive?: string);
     private getLogFilePath;
     private debug;
     embed(texts: string[], _purpose?: "query" | "document"): Promise<number[][]>;

package/dist/embedder/ollama.js

@@ -10,6 +10,7 @@ import { appendDebugLog } from "../core/fileLogger.js";
    * @param timeoutMs - Request timeout in milliseconds (default 120000)
  * @param proxy - Optional proxy configuration
  * @param logLevel - Optional logging level for debug output
+ * @param keepAlive - Optional Ollama keep_alive value sent with /api/embed requests (e.g. "-1")
  */
 export class OllamaProvider {
     name = "ollama";
@@ -19,13 +20,15 @@ export class OllamaProvider {
     timeoutMs;
     proxy;
     logLevel;
-    constructor(baseUrl, model, apiKey, timeoutMs = 120000, proxy, logLevel) {
+    keepAlive;
+    constructor(baseUrl, model, apiKey, timeoutMs = 120000, proxy, logLevel, keepAlive) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.model = model;
         this.apiKey = apiKey;
         this.timeoutMs = timeoutMs;
         this.proxy = proxy;
         this.logLevel = logLevel;
+        this.keepAlive = keepAlive;
     }
     getLogFilePath() {
         return path.resolve(process.cwd(), ".opencode", "opencode-rag.log");
@@ -44,7 +47,14 @@ export class OllamaProvider {
         }
         this.debug(`OllamaProvider requesting ${texts.length} embedding vector${texts.length === 1 ? "" : "s"}`);
         try {
-            const response = await postJson(`${this.baseUrl}/embed`, { model: this.model, input: texts.length === 1 ? texts[0] : texts }, headers, this.timeoutMs, this.proxy);
+            const body = {
+                model: this.model,
+                input: texts.length === 1 ? texts[0] : texts,
+            };
+            if (this.keepAlive) {
+                body.keep_alive = this.keepAlive;
+            }
+            const response = await postJson(`${this.baseUrl}/embed`, body, headers, this.timeoutMs, this.proxy);
             if (!response.ok) {
                 const body = await response.text();
                 throw new Error(`Ollama embedding failed (${response.status}): ${body}`);