opencode-rag-plugin 2.2.1 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api.js +2 -0
- package/dist/chunker/factory.js +48 -18
- package/dist/chunker/image.js +6 -0
- package/dist/cli/commands/clear.js +21 -1
- package/dist/cli/commands/query.js +6 -0
- package/dist/cli/commands/status.js +4 -0
- package/dist/core/bootstrap.d.ts +3 -1
- package/dist/core/bootstrap.js +5 -0
- package/dist/core/config.d.ts +69 -1
- package/dist/core/config.js +63 -1
- package/dist/core/interfaces.d.ts +34 -0
- package/dist/describer/describer.js +9 -1
- package/dist/embedder/factory.d.ts +5 -1
- package/dist/embedder/factory.js +76 -6
- package/dist/embedder/health.d.ts +1 -1
- package/dist/embedder/health.js +43 -0
- package/dist/eval/rerank-eval.d.ts +45 -0
- package/dist/eval/rerank-eval.js +581 -0
- package/dist/indexer/pipeline.d.ts +17 -0
- package/dist/indexer/pipeline.js +123 -3
- package/dist/indexer/stats.d.ts +7 -0
- package/dist/mcp/handlers.js +3 -0
- package/dist/opencode/create-read-tool.js +5 -2
- package/dist/plugin.js +67 -6
- package/dist/quirks/quirk-store.d.ts +1 -0
- package/dist/quirks/quirk-store.js +1 -1
- package/dist/quirks/tool-error-recall.d.ts +112 -0
- package/dist/quirks/tool-error-recall.js +144 -0
- package/dist/reranker/base.d.ts +47 -0
- package/dist/reranker/base.js +73 -0
- package/dist/reranker/factory.d.ts +16 -0
- package/dist/reranker/factory.js +47 -0
- package/dist/reranker/llama-server.d.ts +33 -0
- package/dist/reranker/llama-server.js +101 -0
- package/dist/retriever/keyword-index.d.ts +1 -0
- package/dist/retriever/keyword-index.js +1 -1
- package/dist/retriever/retriever.d.ts +24 -1
- package/dist/retriever/retriever.js +69 -5
- package/dist/types/opencode-plugin.d.ts +2 -2
- package/dist/v2/v2-adapter.d.ts +6 -1
- package/dist/v2/v2-adapter.js +52 -8
- package/dist/vectorstore/lancedb.d.ts +1 -1
- package/dist/vectorstore/lancedb.js +43 -7
- package/dist/web/api.js +5 -0
- package/dist/web/ui/assets/index-C0QXKA-b.js +4 -0
- package/dist/web/ui/assets/index-Dp009QCQ.css +1 -0
- package/dist/web/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/web/ui/assets/index-Cgv1RsGv.js +0 -4
- package/dist/web/ui/assets/index-DjJHIo9R.css +0 -1
package/dist/api.js
CHANGED
|
@@ -56,6 +56,8 @@ export async function search(query, options = {}) {
|
|
|
56
56
|
hybridEnabled: ctx.config.retrieval.hybridSearch?.enabled,
|
|
57
57
|
queryPrefix: ctx.config.embedding.queryPrefix,
|
|
58
58
|
explain: options.explain,
|
|
59
|
+
reranker: ctx.reranker,
|
|
60
|
+
reranking: ctx.config.reranking,
|
|
59
61
|
filter: {
|
|
60
62
|
pathPatterns: options.pathHints,
|
|
61
63
|
languages: options.languageHints,
|
package/dist/chunker/factory.js
CHANGED
|
@@ -240,27 +240,57 @@ function splitOversized(chunks, filePath, maxLines = MAX_CHUNK_LINES, maxChars =
|
|
|
240
240
|
let currentLines = [];
|
|
241
241
|
let currentCharCount = 0;
|
|
242
242
|
let lineOffset = 0;
|
|
243
|
+
const flushWindow = (endLineExclusive) => {
|
|
244
|
+
if (currentLines.length === 0)
|
|
245
|
+
return;
|
|
246
|
+
subChunks.push({
|
|
247
|
+
id: uuid(),
|
|
248
|
+
content: currentLines.join("\n"),
|
|
249
|
+
metadata: {
|
|
250
|
+
filePath,
|
|
251
|
+
startLine: chunk.metadata.startLine + lineOffset,
|
|
252
|
+
endLine: chunk.metadata.startLine + endLineExclusive - 1,
|
|
253
|
+
language: chunk.metadata.language,
|
|
254
|
+
},
|
|
255
|
+
});
|
|
256
|
+
// Seed the next window with the last `overlap` lines so split chunks
|
|
257
|
+
// still share their boundary context.
|
|
258
|
+
const tail = overlap > 0 ? currentLines.slice(Math.max(0, currentLines.length - overlap)) : [];
|
|
259
|
+
currentLines = [...tail];
|
|
260
|
+
currentCharCount = tail.reduce((sum, l) => sum + l.length + 1, 0);
|
|
261
|
+
lineOffset = endLineExclusive - tail.length;
|
|
262
|
+
};
|
|
243
263
|
for (let i = 0; i < lines.length; i++) {
|
|
244
264
|
const line = lines[i];
|
|
245
265
|
const lineLen = line.length + 1;
|
|
266
|
+
// A single line longer than the character budget cannot be split at
|
|
267
|
+
// line boundaries. Hard-wrap it by characters so no chunk exceeds
|
|
268
|
+
// maxChars -- otherwise minified bundles (one long line) become
|
|
269
|
+
// whole-file chunks that exceed the embedding model's context size.
|
|
270
|
+
if (maxChars > 0 && line.length > maxChars) {
|
|
271
|
+
flushWindow(i);
|
|
272
|
+
// The wrapped slices must stay within the character budget, so the
|
|
273
|
+
// overlap lines seeded by flushWindow are intentionally not reused.
|
|
274
|
+
currentLines = [];
|
|
275
|
+
currentCharCount = 0;
|
|
276
|
+
for (let start = 0; start < line.length; start += maxChars) {
|
|
277
|
+
subChunks.push({
|
|
278
|
+
id: uuid(),
|
|
279
|
+
content: line.slice(start, start + maxChars),
|
|
280
|
+
metadata: {
|
|
281
|
+
filePath,
|
|
282
|
+
startLine: chunk.metadata.startLine + i,
|
|
283
|
+
endLine: chunk.metadata.startLine + i,
|
|
284
|
+
language: chunk.metadata.language,
|
|
285
|
+
},
|
|
286
|
+
});
|
|
287
|
+
}
|
|
288
|
+
lineOffset = i + 1;
|
|
289
|
+
continue;
|
|
290
|
+
}
|
|
246
291
|
if (currentLines.length > 0 &&
|
|
247
292
|
(currentLines.length >= maxLines || currentCharCount + lineLen > maxChars)) {
|
|
248
|
-
|
|
249
|
-
id: uuid(),
|
|
250
|
-
content: currentLines.join("\n"),
|
|
251
|
-
metadata: {
|
|
252
|
-
filePath,
|
|
253
|
-
startLine: chunk.metadata.startLine + lineOffset,
|
|
254
|
-
endLine: chunk.metadata.startLine + i - 1,
|
|
255
|
-
language: chunk.metadata.language,
|
|
256
|
-
},
|
|
257
|
-
});
|
|
258
|
-
// Seed the next window with the last `overlap` lines so split chunks
|
|
259
|
-
// still share their boundary context.
|
|
260
|
-
const tail = overlap > 0 ? currentLines.slice(Math.max(0, currentLines.length - overlap)) : [];
|
|
261
|
-
currentLines = [...tail];
|
|
262
|
-
currentCharCount = tail.reduce((sum, l) => sum + l.length + 1, 0);
|
|
263
|
-
lineOffset = i - tail.length;
|
|
293
|
+
flushWindow(i);
|
|
264
294
|
}
|
|
265
295
|
currentLines.push(line);
|
|
266
296
|
currentCharCount += lineLen;
|
|
@@ -333,9 +363,9 @@ export async function chunkFile(filePath, content, nodeTypesOverrides, options)
|
|
|
333
363
|
chunker = withByteLimit(chunker, options.maxSvgSizeBytes);
|
|
334
364
|
}
|
|
335
365
|
}
|
|
336
|
-
|
|
366
|
+
let chunks = await chunker.chunk(filePath, content);
|
|
337
367
|
if (chunks.length === 0) {
|
|
338
|
-
|
|
368
|
+
chunks = await fallbackChunker.chunk(filePath, content);
|
|
339
369
|
}
|
|
340
370
|
const overlap = Math.max(0, options?.chunkOverlap ?? 0);
|
|
341
371
|
const maxLines = options?.maxChunkSize && options.maxChunkSize > 0 ? options.maxChunkSize : MAX_CHUNK_LINES;
|
package/dist/chunker/image.js
CHANGED
|
@@ -118,6 +118,7 @@ class OpenAIImageVisionProvider {
|
|
|
118
118
|
apiKey;
|
|
119
119
|
timeoutMs;
|
|
120
120
|
extraHeaders;
|
|
121
|
+
think;
|
|
121
122
|
proxy;
|
|
122
123
|
constructor(config, extraHeaders) {
|
|
123
124
|
this.baseUrl = config.baseUrl.replace(/\/+$/, "");
|
|
@@ -125,6 +126,7 @@ class OpenAIImageVisionProvider {
|
|
|
125
126
|
this.apiKey = config.apiKey ?? "";
|
|
126
127
|
this.timeoutMs = config.timeoutMs;
|
|
127
128
|
this.extraHeaders = extraHeaders ?? {};
|
|
129
|
+
this.think = config.think;
|
|
128
130
|
this.proxy = config.proxy;
|
|
129
131
|
}
|
|
130
132
|
async describeImage(imageBase64, mimeType, prompt, systemPrompt, abort) {
|
|
@@ -147,6 +149,10 @@ class OpenAIImageVisionProvider {
|
|
|
147
149
|
model: this.model,
|
|
148
150
|
messages,
|
|
149
151
|
max_tokens: 2048,
|
|
152
|
+
// Reasoning models (Qwen3.x / Ornith etc.) think before answering; honor
|
|
153
|
+
// `think: false` for OpenAI-compatible providers by forwarding
|
|
154
|
+
// chat_template_kwargs (llama.cpp / vLLM convention).
|
|
155
|
+
...(this.think === false ? { chat_template_kwargs: { enable_thinking: false } } : {}),
|
|
150
156
|
};
|
|
151
157
|
const headers = {
|
|
152
158
|
...this.extraHeaders,
|
|
@@ -9,6 +9,7 @@ import path from "node:path";
|
|
|
9
9
|
import readline from "node:readline";
|
|
10
10
|
import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo } from "../format.js";
|
|
11
11
|
import { manifestPathFor } from "../../core/manifest.js";
|
|
12
|
+
import { indexPathFor } from "../../retriever/keyword-index.js";
|
|
12
13
|
/**
|
|
13
14
|
* Prompt the user for a yes/no answer via the terminal.
|
|
14
15
|
* Returns `true` for "y", `false` for "n", and `undefined` on EOF.
|
|
@@ -69,8 +70,27 @@ export function registerClearCommand(program) {
|
|
|
69
70
|
}
|
|
70
71
|
logCliInfo(logFilePath, "clear", `${c.label("Clearing")} ${c.num(prevCount)} indexed chunks...`);
|
|
71
72
|
await store.clear();
|
|
73
|
+
// Trust, but verify: an interrupted clear used to leave the store AND
|
|
74
|
+
// the manifest completely untouched while printing nothing after the
|
|
75
|
+
// "Clearing…" line. Only drop the manifest/keyword index once the
|
|
76
|
+
// table is provably empty, so a failed clear cannot desynchronise them.
|
|
77
|
+
let remaining;
|
|
78
|
+
try {
|
|
79
|
+
remaining = await store.count();
|
|
80
|
+
}
|
|
81
|
+
catch (err) {
|
|
82
|
+
logCliError(logFilePath, "clear", `\nClear could not be verified: ${err.message}. Manifest and keyword index were left in place.`, err);
|
|
83
|
+
await cleanupContext(ctx);
|
|
84
|
+
process.exit(1);
|
|
85
|
+
}
|
|
86
|
+
if (remaining > 0) {
|
|
87
|
+
logCliError(logFilePath, "clear", `\nClear incomplete: ${remaining} of ${prevCount} chunks are still stored (interrupted, or the store is held open by another process). Manifest and keyword index were left in place.`);
|
|
88
|
+
await cleanupContext(ctx);
|
|
89
|
+
process.exit(1);
|
|
90
|
+
}
|
|
72
91
|
await fs.unlink(manifestPathFor(ctx.storePath)).catch(() => { });
|
|
73
|
-
|
|
92
|
+
await fs.unlink(indexPathFor(ctx.storePath)).catch(() => { });
|
|
93
|
+
logCliInfo(logFilePath, "clear", `${c.success("Done.")} vector database cleared (was ${c.num(prevCount)} chunks); manifest and keyword index removed.`);
|
|
74
94
|
await cleanupContext(ctx);
|
|
75
95
|
}
|
|
76
96
|
catch (err) {
|
|
@@ -8,6 +8,7 @@ import path from "node:path";
|
|
|
8
8
|
import pc from "picocolors";
|
|
9
9
|
import { CODE_SEARCH_FILTER } from "../../core/interfaces.js";
|
|
10
10
|
import { retrieve } from "../../retriever/retriever.js";
|
|
11
|
+
import { getRerankerFor } from "../../reranker/factory.js";
|
|
11
12
|
import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, formatDuration } from "../format.js";
|
|
12
13
|
import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "../../retriever/context-optimizer.js";
|
|
13
14
|
/**
|
|
@@ -54,6 +55,8 @@ export function registerQueryCommand(program) {
|
|
|
54
55
|
keywordWeight: hybridCfg?.keywordWeight,
|
|
55
56
|
hybridEnabled: hybridCfg?.enabled,
|
|
56
57
|
queryPrefix: config.embedding.queryPrefix,
|
|
58
|
+
reranker: getRerankerFor(config.reranking) ?? undefined,
|
|
59
|
+
reranking: config.reranking,
|
|
57
60
|
explain: options.explain ?? false,
|
|
58
61
|
filter: CODE_SEARCH_FILTER,
|
|
59
62
|
});
|
|
@@ -72,6 +75,9 @@ export function registerQueryCommand(program) {
|
|
|
72
75
|
if (r.explanation) {
|
|
73
76
|
const sb = r.explanation.scoreBreakdown;
|
|
74
77
|
logCliInfo(logFilePath, "query", ` ${c.label(" Vector:")} ${c.score(sb.rawVectorScore.toFixed(4))} ${c.label("Keyword:")} ${c.score(sb.rawKeywordScore.toFixed(4))} ${c.label("KW weight:")} ${sb.keywordWeight.toFixed(2)}`);
|
|
78
|
+
if (sb.rerankScore !== undefined) {
|
|
79
|
+
logCliInfo(logFilePath, "query", ` ${c.label(" Rerank:")} ${c.score(sb.rerankScore.toFixed(4))}`);
|
|
80
|
+
}
|
|
75
81
|
if (r.explanation.matchedTerms && r.explanation.matchedTerms.length > 0) {
|
|
76
82
|
logCliInfo(logFilePath, "query", ` ${c.label(" Matched:")} ${c.lang(r.explanation.matchedTerms.join(", "))}`);
|
|
77
83
|
}
|
|
@@ -100,6 +100,10 @@ export function registerStatusCommand(program) {
|
|
|
100
100
|
logCliInfo(logFilePath, "status", `${c.label("Pending files:")} ${c.num(summary.pendingFiles)}`);
|
|
101
101
|
logCliInfo(logFilePath, "status", `${c.label("Indexed chunks:")} ${c.num(summary.storeChunkCount)}`);
|
|
102
102
|
logCliInfo(logFilePath, "status", `${c.label("Expected chunks:")} ${c.num(summary.manifestExpectedChunks)}`);
|
|
103
|
+
logCliInfo(logFilePath, "status", `${c.label("Orphan chunks:")} ${c.num(summary.orphanChunks)}`);
|
|
104
|
+
if (summary.orphanChunks > 0) {
|
|
105
|
+
logCliInfo(logFilePath, "status", `${c.label("Unaccounted rows:")} ${c.warn("yes")} — stored chunks no manifest entry owns (files whose embedding never completed). Run 'opencode-rag index' to sweep them.`);
|
|
106
|
+
}
|
|
103
107
|
// Read watcher status from the background auto-indexer
|
|
104
108
|
const watcherStatusPath = path.join(storePath, "watcher-status.json");
|
|
105
109
|
let watchModeDisplay;
|
package/dist/core/bootstrap.d.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
* creates embedder, vector store, keyword index, and description provider.
|
|
4
4
|
*/
|
|
5
5
|
import { type RagConfig } from "./config.js";
|
|
6
|
-
import type { EmbeddingProvider, VectorStore, KeywordIndex as IKeywordIndex, DescriptionProvider } from "./interfaces.js";
|
|
6
|
+
import type { EmbeddingProvider, RerankProvider, VectorStore, KeywordIndex as IKeywordIndex, DescriptionProvider } from "./interfaces.js";
|
|
7
7
|
/** Options for bootstrapping the RAG pipeline context. */
|
|
8
8
|
export interface BootstrapOptions {
|
|
9
9
|
/** Working directory for resolving config and store paths. Defaults to process.cwd(). */
|
|
@@ -31,6 +31,8 @@ export interface RagContext {
|
|
|
31
31
|
keywordIndex: IKeywordIndex;
|
|
32
32
|
/** Optional LLM-based description provider. */
|
|
33
33
|
descriptionProvider?: DescriptionProvider;
|
|
34
|
+
/** Cross-encoder reranker for the retrieval stage (undefined when disabled). */
|
|
35
|
+
reranker?: RerankProvider;
|
|
34
36
|
/** Detected embedding dimension. */
|
|
35
37
|
dimension: number;
|
|
36
38
|
/** Resolved path to the debug log file. */
|
package/dist/core/bootstrap.js
CHANGED
|
@@ -9,6 +9,7 @@ import { loadChunkersFromConfig } from "../chunker/loader.js";
|
|
|
9
9
|
import { createEmbedder, probeEmbeddingDimension } from "../embedder/factory.js";
|
|
10
10
|
import { createDescriptionProvider } from "../describer/factory.js";
|
|
11
11
|
import { createVectorStore } from "../vectorstore/factory.js";
|
|
12
|
+
import { getRerankerFor } from "../reranker/factory.js";
|
|
12
13
|
import { readStoreDimension } from "../vectorstore/lancedb.js";
|
|
13
14
|
import { KeywordIndex } from "../retriever/keyword-index.js";
|
|
14
15
|
import { reconcileQuirks } from "../quirks/quirk-store.js";
|
|
@@ -119,6 +120,9 @@ export async function resolveRagContext(opts = {}) {
|
|
|
119
120
|
const descriptionProvider = descriptionConfig?.enabled
|
|
120
121
|
? createDescriptionProvider(descriptionConfig)
|
|
121
122
|
: undefined;
|
|
123
|
+
// Optional cross-encoder reranker (process-wide singleton per endpoint so
|
|
124
|
+
// cooldown + score cache survive across retrievals). Null/disabled by default.
|
|
125
|
+
const reranker = getRerankerFor(cfg.reranking) ?? undefined;
|
|
122
126
|
return {
|
|
123
127
|
config: cfg,
|
|
124
128
|
embedder,
|
|
@@ -126,6 +130,7 @@ export async function resolveRagContext(opts = {}) {
|
|
|
126
130
|
storePath,
|
|
127
131
|
keywordIndex,
|
|
128
132
|
descriptionProvider,
|
|
133
|
+
reranker,
|
|
129
134
|
dimension,
|
|
130
135
|
logFilePath,
|
|
131
136
|
configPath,
|
package/dist/core/config.d.ts
CHANGED
|
@@ -75,7 +75,14 @@ export interface DescriptionConfig {
|
|
|
75
75
|
retryMax?: number;
|
|
76
76
|
/** Base delay in ms between retries (exponential backoff). */
|
|
77
77
|
retryBaseDelayMs?: number;
|
|
78
|
-
/**
|
|
78
|
+
/**
|
|
79
|
+
* Whether the model may emit chain-of-thought tokens before the answer.
|
|
80
|
+
* For the Ollama provider this sets the `think` request field. For
|
|
81
|
+
* OpenAI-compatible providers `false` forwards
|
|
82
|
+
* `chat_template_kwargs.enable_thinking=false` (llama.cpp / vLLM
|
|
83
|
+
* convention); without it, reasoning models spend thousands of extra
|
|
84
|
+
* tokens per description and indexing runs ~50x slower.
|
|
85
|
+
*/
|
|
79
86
|
think?: boolean;
|
|
80
87
|
/** Context window size for the LLM. */
|
|
81
88
|
numCtx?: number;
|
|
@@ -208,6 +215,24 @@ export interface MemoryConfig {
|
|
|
208
215
|
autoCaptureMaxPerTurn: number;
|
|
209
216
|
/** Lexical similarity threshold (0-1) above which a candidate is considered a duplicate and skipped. */
|
|
210
217
|
autoCaptureDedupThreshold: number;
|
|
218
|
+
/**
|
|
219
|
+
* Inject matching quirks into the next model request after a FAILED tool call
|
|
220
|
+
* (default true). Failed calls are also appended to the auto-capture pipeline,
|
|
221
|
+
* so recurring errors can become quirks.
|
|
222
|
+
*/
|
|
223
|
+
injectOnToolError: boolean;
|
|
224
|
+
/** Minimum relevance score (0-1) for a quirk to be injected after a tool error (default 0.7). */
|
|
225
|
+
toolErrorMinScore: number;
|
|
226
|
+
/** Max quirks injected per tool error (default 2). */
|
|
227
|
+
toolErrorTopK: number;
|
|
228
|
+
/** Minimum shared word tokens (>=3 chars) between a quirk and the error text; 0 disables (default 1). */
|
|
229
|
+
toolErrorMinTokenOverlap: number;
|
|
230
|
+
/** Cooldown per normalized tool-error signature in ms (default 60000). */
|
|
231
|
+
toolErrorCooldownMs: number;
|
|
232
|
+
/** Max tool-error quirk injections per session (default 3). */
|
|
233
|
+
toolErrorMaxPerSession: number;
|
|
234
|
+
/** Latency budget (ms) for tool-error quirk recall; exceeded -> no injection (default 1500). */
|
|
235
|
+
toolErrorLatencyBudgetMs: number;
|
|
211
236
|
/** Decay settings for aging quirks. */
|
|
212
237
|
decay: {
|
|
213
238
|
/** Whether confidence decays over time. */
|
|
@@ -254,6 +279,47 @@ export interface ContextOptimizationConfig {
|
|
|
254
279
|
/** Jaccard similarity threshold (0-1) for same-file dedup. */
|
|
255
280
|
similarityThreshold: number;
|
|
256
281
|
}
|
|
282
|
+
/**
|
|
283
|
+
* Optional cross-encoder rerank stage (opt-in, default OFF).
|
|
284
|
+
*
|
|
285
|
+
* After hybrid fusion the top candidates are re-scored by a cross-encoder
|
|
286
|
+
* (e.g. Qwen3-Reranker served by llama-server's `/v1/rerank`). The stage is a
|
|
287
|
+
* pure reorder (+ optional gate); the fusion `minScore` gate runs unchanged
|
|
288
|
+
* BEFORE reranking, so disabling reranking reproduces today's behavior
|
|
289
|
+
* exactly. Provider errors/timeouts always degrade to the fusion order —
|
|
290
|
+
* retrieval never fails because of the reranker.
|
|
291
|
+
*/
|
|
292
|
+
export interface RerankingConfig {
|
|
293
|
+
/** Master switch — when false (default) no reranker is created. */
|
|
294
|
+
enabled: boolean;
|
|
295
|
+
/** Rerank provider implementation. @default "llama-server" */
|
|
296
|
+
provider?: "llama-server";
|
|
297
|
+
/** Base URL of the rerank endpoint (e.g. http://127.0.0.1:8080/v1). The stage POSTs to {baseUrl}/rerank. */
|
|
298
|
+
baseUrl: string;
|
|
299
|
+
/** Optional bearer token (e.g. llama-swap auth). */
|
|
300
|
+
apiKey?: string;
|
|
301
|
+
/** Reranker model name passed to the server. */
|
|
302
|
+
model: string;
|
|
303
|
+
/** How many fused candidates to send per query (after the fusion minScore gate). @default 20 */
|
|
304
|
+
candidates?: number;
|
|
305
|
+
/** Each candidate's document text is truncated to this many characters. @default 1200 */
|
|
306
|
+
maxDocChars?: number;
|
|
307
|
+
/** Additional gate on the rerank score itself (0 = pure reorder, default). NOT comparable to retrieval.minScore — rerank scores are provider-scaled, not calibrated. */
|
|
308
|
+
minScore?: number;
|
|
309
|
+
/** Per-call timeout in ms; on expiry the fusion order is kept. @default 1500 */
|
|
310
|
+
timeoutMs?: number;
|
|
311
|
+
/**
|
|
312
|
+
* Query template applied before scoring. With a `{query}` placeholder the
|
|
313
|
+
* query is substituted, otherwise the template is used as a prefix.
|
|
314
|
+
* Use this for instruct-style rerankers (e.g. Qwen3-Reranker) — do NOT
|
|
315
|
+
* reuse embedding.queryPrefix here. @default ""
|
|
316
|
+
*/
|
|
317
|
+
queryTemplate?: string;
|
|
318
|
+
/** Document text: raw content, or description + content. @default "content" */
|
|
319
|
+
docField?: "content" | "content+description";
|
|
320
|
+
/** Proxy configuration for the rerank endpoint. */
|
|
321
|
+
proxy?: ProxyConfig;
|
|
322
|
+
}
|
|
257
323
|
/** Complete configuration for the OpenCodeRAG pipeline. */
|
|
258
324
|
export interface RagConfig {
|
|
259
325
|
/** Embedding provider settings (model, endpoint, prefixes). */
|
|
@@ -398,6 +464,8 @@ export interface RagConfig {
|
|
|
398
464
|
/** Context window optimization settings for post-retrieval quality filtering. */
|
|
399
465
|
contextOptimization?: ContextOptimizationConfig;
|
|
400
466
|
};
|
|
467
|
+
/** Optional cross-encoder rerank stage (opt-in; absent = disabled). */
|
|
468
|
+
reranking?: RerankingConfig;
|
|
401
469
|
/** OpenCode plugin integration settings. */
|
|
402
470
|
openCode: {
|
|
403
471
|
/** Whether the OpenCode plugin is active. */
|
package/dist/core/config.js
CHANGED
|
@@ -145,6 +145,20 @@ export const DEFAULT_CONFIG = {
|
|
|
145
145
|
similarityThreshold: 0.8,
|
|
146
146
|
},
|
|
147
147
|
},
|
|
148
|
+
reranking: {
|
|
149
|
+
enabled: false,
|
|
150
|
+
provider: "llama-server",
|
|
151
|
+
// llama-server's default port; llama-swap users typically point this at
|
|
152
|
+
// their swap proxy (which routes v1/rerank) instead.
|
|
153
|
+
baseUrl: "http://127.0.0.1:8080/v1",
|
|
154
|
+
model: "qwen3-reranker-0.6b",
|
|
155
|
+
candidates: 20,
|
|
156
|
+
maxDocChars: 1200,
|
|
157
|
+
minScore: 0,
|
|
158
|
+
timeoutMs: 1500,
|
|
159
|
+
queryTemplate: "",
|
|
160
|
+
docField: "content",
|
|
161
|
+
},
|
|
148
162
|
openCode: {
|
|
149
163
|
enabled: true,
|
|
150
164
|
maxContextChunks: 10,
|
|
@@ -288,6 +302,13 @@ export const DEFAULT_CONFIG = {
|
|
|
288
302
|
sessionEndExtraction: true,
|
|
289
303
|
autoCaptureMaxPerTurn: 2,
|
|
290
304
|
autoCaptureDedupThreshold: 0.85,
|
|
305
|
+
injectOnToolError: true,
|
|
306
|
+
toolErrorMinScore: 0.7,
|
|
307
|
+
toolErrorTopK: 2,
|
|
308
|
+
toolErrorMinTokenOverlap: 1,
|
|
309
|
+
toolErrorCooldownMs: 60_000,
|
|
310
|
+
toolErrorMaxPerSession: 3,
|
|
311
|
+
toolErrorLatencyBudgetMs: 1500,
|
|
291
312
|
decay: {
|
|
292
313
|
enabled: false,
|
|
293
314
|
halfLifeDays: 30,
|
|
@@ -318,7 +339,7 @@ export function resolveLogConfig(config) {
|
|
|
318
339
|
export function validateConfig(config) {
|
|
319
340
|
const warnings = [];
|
|
320
341
|
const KNOWN_TOP_KEYS = new Set([
|
|
321
|
-
"embedding", "indexing", "vectorStore", "retrieval",
|
|
342
|
+
"embedding", "indexing", "vectorStore", "retrieval", "reranking",
|
|
322
343
|
"openCode", "chunkers", "chunking", "description",
|
|
323
344
|
"imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
|
|
324
345
|
]);
|
|
@@ -416,6 +437,23 @@ export function validateConfig(config) {
|
|
|
416
437
|
if (t < 0 || t > 1)
|
|
417
438
|
warnings.push("memory.autoCaptureDedupThreshold must be between 0 and 1");
|
|
418
439
|
}
|
|
440
|
+
if (config.memory?.toolErrorMinScore != null) {
|
|
441
|
+
const r = config.memory.toolErrorMinScore;
|
|
442
|
+
if (r < 0 || r > 1)
|
|
443
|
+
warnings.push("memory.toolErrorMinScore must be between 0 and 1");
|
|
444
|
+
}
|
|
445
|
+
if (config.memory?.toolErrorTopK != null && config.memory.toolErrorTopK < 1) {
|
|
446
|
+
warnings.push("memory.toolErrorTopK must be >= 1");
|
|
447
|
+
}
|
|
448
|
+
if (config.memory?.toolErrorCooldownMs != null && config.memory.toolErrorCooldownMs < 0) {
|
|
449
|
+
warnings.push("memory.toolErrorCooldownMs must be >= 0");
|
|
450
|
+
}
|
|
451
|
+
if (config.memory?.toolErrorMaxPerSession != null && config.memory.toolErrorMaxPerSession < 0) {
|
|
452
|
+
warnings.push("memory.toolErrorMaxPerSession must be >= 0");
|
|
453
|
+
}
|
|
454
|
+
if (config.memory?.toolErrorLatencyBudgetMs != null && config.memory.toolErrorLatencyBudgetMs < 0) {
|
|
455
|
+
warnings.push("memory.toolErrorLatencyBudgetMs must be >= 0");
|
|
456
|
+
}
|
|
419
457
|
if (config.memory?.decay && config.memory.decay.halfLifeDays <= 0) {
|
|
420
458
|
warnings.push("memory.decay.halfLifeDays must be > 0");
|
|
421
459
|
}
|
|
@@ -470,6 +508,25 @@ export function validateConfig(config) {
|
|
|
470
508
|
warnings.push("imageDescription.onDemand.timeoutMs must be > 0");
|
|
471
509
|
}
|
|
472
510
|
}
|
|
511
|
+
if (config.reranking?.enabled) {
|
|
512
|
+
const rr = config.reranking;
|
|
513
|
+
if (!rr.baseUrl)
|
|
514
|
+
warnings.push("reranking.baseUrl must be set when reranking.enabled is true");
|
|
515
|
+
if (!rr.model)
|
|
516
|
+
warnings.push("reranking.model must be set when reranking.enabled is true");
|
|
517
|
+
if (rr.candidates !== undefined && (rr.candidates < 1 || rr.candidates > 100)) {
|
|
518
|
+
warnings.push("reranking.candidates should be between 1 and 100 (latency scales linearly with document count)");
|
|
519
|
+
}
|
|
520
|
+
if (rr.minScore !== undefined && (rr.minScore < 0 || rr.minScore > 1)) {
|
|
521
|
+
warnings.push("reranking.minScore must be between 0 and 1");
|
|
522
|
+
}
|
|
523
|
+
if (rr.timeoutMs !== undefined && rr.timeoutMs <= 0) {
|
|
524
|
+
warnings.push("reranking.timeoutMs must be > 0");
|
|
525
|
+
}
|
|
526
|
+
if (rr.maxDocChars !== undefined && rr.maxDocChars <= 0) {
|
|
527
|
+
warnings.push("reranking.maxDocChars must be > 0");
|
|
528
|
+
}
|
|
529
|
+
}
|
|
473
530
|
return { valid: warnings.length === 0, warnings };
|
|
474
531
|
}
|
|
475
532
|
/** Config file locations to search, in order of precedence. */
|
|
@@ -541,6 +598,11 @@ export function loadConfig(filePath, validate = true) {
|
|
|
541
598
|
...(safeObj(parsed.retrieval?.contextOptimization) ?? {}),
|
|
542
599
|
},
|
|
543
600
|
},
|
|
601
|
+
// Flat section — no nested objects, a shallow spread merge is safe.
|
|
602
|
+
reranking: {
|
|
603
|
+
...DEFAULT_CONFIG.reranking,
|
|
604
|
+
...(safeObj(parsed.reranking) ?? {}),
|
|
605
|
+
},
|
|
544
606
|
openCode: (() => {
|
|
545
607
|
const base = DEFAULT_CONFIG.openCode;
|
|
546
608
|
const user = parsed.openCode ?? {};
|
|
@@ -81,6 +81,11 @@ export interface SearchExplanation {
|
|
|
81
81
|
vectorRank?: number;
|
|
82
82
|
/** Rank (0-indexed) in the keyword index results. */
|
|
83
83
|
keywordRank?: number;
|
|
84
|
+
/** Cross-encoder relevance from the optional rerank stage. Higher means more
|
|
85
|
+
* relevant. NOT a calibrated probability (provider-dependent, llama-server
|
|
86
|
+
* semantics) and NOT comparable to the RRF-normalized fused components.
|
|
87
|
+
* Set only when the rerank stage actually ran for this result. */
|
|
88
|
+
rerankScore?: number;
|
|
84
89
|
};
|
|
85
90
|
/** Calibrated relevance in [0,1] derived from the raw vector-score spread of the
|
|
86
91
|
* candidate set — unlike the fused `score` (RRF-normalized so rank 0 is always
|
|
@@ -128,6 +133,35 @@ export interface EmbeddingProvider {
|
|
|
128
133
|
/** Embed one or more text strings. `purpose` may apply a prefix for query vs. document embeddings. */
|
|
129
134
|
embed(texts: string[], purpose?: "query" | "document"): Promise<number[][]>;
|
|
130
135
|
}
|
|
136
|
+
/**
|
|
137
|
+
* Cross-encoder reranker: scores (query, document) pairs for relevance.
|
|
138
|
+
*
|
|
139
|
+
* Deliberately narrow so a decision model (typed classifier) can implement the
|
|
140
|
+
* same contract later. Providers never throw into retrieval hot paths by
|
|
141
|
+
* design: callers catch `rerank()` rejections, degrade to the original order,
|
|
142
|
+
* and feed the failure into `noteFailure()` so repeated outages trip an
|
|
143
|
+
* automatic cooldown (`available() === false`).
|
|
144
|
+
*/
|
|
145
|
+
export interface RerankProvider {
|
|
146
|
+
/** Provider name (e.g. "llama-server"). */
|
|
147
|
+
readonly name: string;
|
|
148
|
+
/** Model identifier used for scoring (cache/log attribution). */
|
|
149
|
+
readonly model: string;
|
|
150
|
+
/** False while a failure cooldown is active — callers must skip reranking. */
|
|
151
|
+
available(): boolean;
|
|
152
|
+
/**
|
|
153
|
+
* Score every document against the query; the returned array is index-aligned
|
|
154
|
+
* with `documents` (higher = more relevant). May reject — the caller then
|
|
155
|
+
* keeps the pre-rerank order and calls `noteFailure()`.
|
|
156
|
+
*/
|
|
157
|
+
rerank(query: string, documents: string[], opts?: {
|
|
158
|
+
timeoutMs?: number;
|
|
159
|
+
}): Promise<number[]>;
|
|
160
|
+
/** Record a failed call (counts toward the cooldown). */
|
|
161
|
+
noteFailure(): void;
|
|
162
|
+
/** Record a successful call (resets the failure streak). */
|
|
163
|
+
noteSuccess(): void;
|
|
164
|
+
}
|
|
131
165
|
/** In-memory TF-IDF inverted index for keyword-based search alongside vector search. */
|
|
132
166
|
export interface KeywordIndex {
|
|
133
167
|
/** Release resources and free memory. */
|
|
@@ -180,7 +180,15 @@ export class LlmDescriptionProvider {
|
|
|
180
180
|
: `${baseUrl}${baseUrl.endsWith("/v1") ? "" : "/v1"}/chat/completions`;
|
|
181
181
|
const body = isOllama
|
|
182
182
|
? { model: this.config.model, messages, stream: false, think: this.config.think ?? false, options: { num_ctx: this.config.numCtx }, keep_alive: normalizeKeepAlive(this.config.keepAlive) }
|
|
183
|
-
: {
|
|
183
|
+
: {
|
|
184
|
+
model: this.config.model,
|
|
185
|
+
messages,
|
|
186
|
+
// Reasoning models (Qwen3.x etc.) think before answering; a full
|
|
187
|
+
// reasoning pass per chunk makes indexing ~50x slower. Honor
|
|
188
|
+
// `think: false` for OpenAI-compatible providers as well by
|
|
189
|
+
// forwarding chat_template_kwargs (llama.cpp / vLLM convention).
|
|
190
|
+
...(this.config.think === false ? { chat_template_kwargs: { enable_thinking: false } } : {}),
|
|
191
|
+
};
|
|
184
192
|
const headers = {};
|
|
185
193
|
if (this.config.apiKey) {
|
|
186
194
|
headers.Authorization = `Bearer ${this.config.apiKey}`;
|
|
@@ -46,7 +46,11 @@ export declare function probeEmbeddingDimension(embedder: EmbeddingProvider): Pr
|
|
|
46
46
|
* for transient failures — auth/validation errors are not retried). If all
|
|
47
47
|
* retries are exhausted or the provider returns a mismatched embedding count,
|
|
48
48
|
* the batch is skipped and empty arrays are returned for those texts so the
|
|
49
|
-
* caller can still process successfully embedded batches.
|
|
49
|
+
* caller can still process successfully embedded batches. Failures are logged
|
|
50
|
+
* to the workspace debug log (scope `embedder.batch`); batches that fail for a
|
|
51
|
+
* non-permanent reason (provider context limit, request timeout, count or
|
|
52
|
+
* dimension mismatch) are split in half and retried recursively down to single
|
|
53
|
+
* texts, so one oversized or slow text cannot discard its healthy siblings.
|
|
50
54
|
*
|
|
51
55
|
* @param embedder - The embedding provider to use
|
|
52
56
|
* @param texts - Array of text strings to embed
|
package/dist/embedder/factory.js
CHANGED
|
@@ -3,6 +3,8 @@ import { OllamaProvider } from "./ollama.js";
|
|
|
3
3
|
import { OpenAIProvider } from "./openai.js";
|
|
4
4
|
import { CohereProvider } from "./cohere.js";
|
|
5
5
|
import pLimit from "p-limit";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { appendDebugLog } from "../core/fileLogger.js";
|
|
6
8
|
/**
|
|
7
9
|
* Create an embedding provider instance based on the application configuration.
|
|
8
10
|
*
|
|
@@ -73,6 +75,29 @@ const PERMANENT_STATUS_RE = /\(?(400|401|403|404|422)\)?/;
|
|
|
73
75
|
function isPermanentError(err) {
|
|
74
76
|
return PERMANENT_STATUS_RE.test(err instanceof Error ? err.message : String(err));
|
|
75
77
|
}
|
|
78
|
+
/**
|
|
79
|
+
* Provider errors that mean the request exceeded the model context window.
|
|
80
|
+
* llama.cpp rejects the WHOLE request when any single input is over the limit
|
|
81
|
+
* (HTTP 400 exceed_context_size_error), so such batches are split and retried.
|
|
82
|
+
*/
|
|
83
|
+
const CONTEXT_LIMIT_RE = /exceed_context_size|exceeds the available context size/i;
|
|
84
|
+
function isContextLimitError(err) {
|
|
85
|
+
return CONTEXT_LIMIT_RE.test(err instanceof Error ? err.message : String(err));
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Provider request timeouts. The server usually keeps chewing on an oversized
|
|
89
|
+
* input after the client gave up, so a timeout is the silent twin of a
|
|
90
|
+
* context-limit rejection: without splitting, every healthy text in the batch
|
|
91
|
+
* loses its vector too.
|
|
92
|
+
*/
|
|
93
|
+
const TIMEOUT_RE = /timed out|timeout/i;
|
|
94
|
+
function isTimeoutError(err) {
|
|
95
|
+
return TIMEOUT_RE.test(err instanceof Error ? err.message : String(err));
|
|
96
|
+
}
|
|
97
|
+
/** Resolve the workspace debug log file used for batch failure diagnostics. */
|
|
98
|
+
function getBatchLogFilePath() {
|
|
99
|
+
return path.resolve(process.cwd(), ".opencode", "opencode-rag.log");
|
|
100
|
+
}
|
|
76
101
|
/**
|
|
77
102
|
* Embed a list of texts in batches with optional concurrency control and per-batch retry.
|
|
78
103
|
*
|
|
@@ -84,7 +109,11 @@ function isPermanentError(err) {
|
|
|
84
109
|
* for transient failures — auth/validation errors are not retried). If all
|
|
85
110
|
* retries are exhausted or the provider returns a mismatched embedding count,
|
|
86
111
|
* the batch is skipped and empty arrays are returned for those texts so the
|
|
87
|
-
* caller can still process successfully embedded batches.
|
|
112
|
+
* caller can still process successfully embedded batches. Failures are logged
|
|
113
|
+
* to the workspace debug log (scope `embedder.batch`); batches that fail for a
|
|
114
|
+
* non-permanent reason (provider context limit, request timeout, count or
|
|
115
|
+
* dimension mismatch) are split in half and retried recursively down to single
|
|
116
|
+
* texts, so one oversized or slow text cannot discard its healthy siblings.
|
|
88
117
|
*
|
|
89
118
|
* @param embedder - The embedding provider to use
|
|
90
119
|
* @param texts - Array of text strings to embed
|
|
@@ -105,8 +134,15 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
|
|
|
105
134
|
for (let i = 0; i < texts.length; i += batchSize) {
|
|
106
135
|
batches.push({ index: i, texts: texts.slice(i, i + batchSize) });
|
|
107
136
|
}
|
|
108
|
-
|
|
109
|
-
|
|
137
|
+
// `depth` counts split levels: the top-level batch gets the full retry
|
|
138
|
+
// budget, every sub-batch only a single attempt — otherwise one slow text
|
|
139
|
+
// would multiply its retries across the whole split tree and stall the pass.
|
|
140
|
+
async function embedWithRetry(batchTexts, depth = 0) {
|
|
141
|
+
const maxRetries = depth === 0 ? retryMax : Math.min(1, retryMax);
|
|
142
|
+
let lastError;
|
|
143
|
+
let attempts = 0;
|
|
144
|
+
for (let attempt = 0; attempt <= maxRetries; attempt++) {
|
|
145
|
+
attempts = attempt + 1;
|
|
110
146
|
try {
|
|
111
147
|
const embeddings = await embedder.embed(batchTexts, purpose);
|
|
112
148
|
// Validate the response shape: a count mismatch would silently attach
|
|
@@ -122,15 +158,49 @@ export async function embedBatch(embedder, texts, batchSize = 10, purpose, concu
|
|
|
122
158
|
return embeddings;
|
|
123
159
|
}
|
|
124
160
|
catch (err) {
|
|
125
|
-
|
|
161
|
+
lastError = err;
|
|
162
|
+
if (attempt < maxRetries && !isPermanentError(err)) {
|
|
126
163
|
const delay = retryBaseDelayMs * Math.pow(2, attempt) * (0.8 + Math.random() * 0.4);
|
|
127
164
|
await new Promise(resolve => setTimeout(resolve, delay));
|
|
128
165
|
}
|
|
129
|
-
else if (attempt >=
|
|
130
|
-
|
|
166
|
+
else if (attempt >= maxRetries || isPermanentError(err)) {
|
|
167
|
+
break;
|
|
131
168
|
}
|
|
132
169
|
}
|
|
133
170
|
}
|
|
171
|
+
const longestText = batchTexts.reduce((max, text) => Math.max(max, text.length), 0);
|
|
172
|
+
appendDebugLog(getBatchLogFilePath(), {
|
|
173
|
+
scope: "embedder.batch",
|
|
174
|
+
severity: "warn",
|
|
175
|
+
message: `Embedding batch failed after ${attempts} attempt(s) ` +
|
|
176
|
+
`(${batchTexts.length} text(s), longest ${longestText} chars): ` +
|
|
177
|
+
`${lastError instanceof Error ? lastError.message : String(lastError)}`,
|
|
178
|
+
error: lastError,
|
|
179
|
+
});
|
|
180
|
+
// A single overlong or slow text can make the provider reject the whole
|
|
181
|
+
// request (llama.cpp HTTP 400 exceed_context_size_error) or time it out.
|
|
182
|
+
// Split the batch recursively so one bad text cannot discard its healthy
|
|
183
|
+
// siblings; text(s) that still fail come back as empty vectors and are
|
|
184
|
+
// counted by the caller. A context-limit rejection carries a permanent 400
|
|
185
|
+
// status, so it needs its own predicate; timeouts are already non-permanent
|
|
186
|
+
// (belt and braces). Genuine permanent errors never split — halving the
|
|
187
|
+
// batch would fail the same way, only slower.
|
|
188
|
+
const splittable = !isPermanentError(lastError) || isContextLimitError(lastError) || isTimeoutError(lastError);
|
|
189
|
+
if (batchTexts.length > 1 && splittable) {
|
|
190
|
+
const mid = Math.ceil(batchTexts.length / 2);
|
|
191
|
+
appendDebugLog(getBatchLogFilePath(), {
|
|
192
|
+
scope: "embedder.batch",
|
|
193
|
+
severity: "info",
|
|
194
|
+
message: `Splitting failed batch of ${batchTexts.length} text(s) into ${mid}+${batchTexts.length - mid} ` +
|
|
195
|
+
`(depth ${depth + 1}) after: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
|
|
196
|
+
});
|
|
197
|
+
const left = await embedWithRetry(batchTexts.slice(0, mid), depth + 1);
|
|
198
|
+
const right = await embedWithRetry(batchTexts.slice(mid), depth + 1);
|
|
199
|
+
return [
|
|
200
|
+
...(left ?? batchTexts.slice(0, mid).map(() => [])),
|
|
201
|
+
...(right ?? batchTexts.slice(mid).map(() => [])),
|
|
202
|
+
];
|
|
203
|
+
}
|
|
134
204
|
return null;
|
|
135
205
|
}
|
|
136
206
|
if (concurrency <= 1 || batches.length <= 1) {
|