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
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Tool-error → quirk recall: when a tool call fails, find matching quirk
|
|
3
|
+
* memory entries to inject into the next model request, and gate the existing
|
|
4
|
+
* auto-capture pipeline so recurring errors can become quirks.
|
|
5
|
+
*
|
|
6
|
+
* Design notes:
|
|
7
|
+
* - Pure and dependency-injected: the caller passes a `recall` function (the plugin
|
|
8
|
+
* wraps `recallQuirks`), so this module has no store/embedder dependencies and is
|
|
9
|
+
* cheap to unit-test.
|
|
10
|
+
* - Conservative by default: min score 0.7, max 2 hits per error, 3 injections per
|
|
11
|
+
* session, 60s cooldown per normalized error signature, plus a lexical gate so a
|
|
12
|
+
* semantically close but lexically unrelated quirk never gets injected.
|
|
13
|
+
* - A failed recall still counts as an attempt (cooldown), so a repeatedly failing
|
|
14
|
+
* tool does not hammer the embedder every call — but it does not consume the
|
|
15
|
+
* per-session budget; only actual injections do.
|
|
16
|
+
*/
|
|
17
|
+
import { sharedWords } from "./quirk-store.js";
|
|
18
|
+
/** Defaults shared by the state factory and the selector. */
|
|
19
|
+
export const TOOL_ERROR_DEFAULTS = {
|
|
20
|
+
minScore: 0.7,
|
|
21
|
+
topK: 2,
|
|
22
|
+
minTokenOverlap: 1,
|
|
23
|
+
cooldownMs: 60_000,
|
|
24
|
+
maxPerSession: 3,
|
|
25
|
+
/** Error text is truncated before it becomes a recall query / capture payload. */
|
|
26
|
+
maxErrorChars: 400,
|
|
27
|
+
/** Capture payloads are sliced to match the existing auto-capture tool-result cap. */
|
|
28
|
+
maxCaptureChars: 500,
|
|
29
|
+
};
|
|
30
|
+
/** Collapse an error into a stable signature for cooldown/dedup purposes. */
|
|
31
|
+
export function normalizeToolErrorSignature(info) {
|
|
32
|
+
const normalized = info.error
|
|
33
|
+
.toLowerCase()
|
|
34
|
+
.replace(/\s+/g, " ")
|
|
35
|
+
.replace(/\d+/g, "#")
|
|
36
|
+
.trim()
|
|
37
|
+
.slice(0, 160);
|
|
38
|
+
return `${info.tool.toLowerCase()}|${normalized}`;
|
|
39
|
+
}
|
|
40
|
+
/** Build the recall query for a failed tool call. */
|
|
41
|
+
export function buildToolErrorQuery(info) {
|
|
42
|
+
const error = info.error.replace(/\s+/g, " ").trim().slice(0, TOOL_ERROR_DEFAULTS.maxErrorChars);
|
|
43
|
+
return `Tool "${info.tool}" failed: ${error}`;
|
|
44
|
+
}
|
|
45
|
+
/** Create the per-session injection state. */
|
|
46
|
+
export function createToolErrorInjectionState(options) {
|
|
47
|
+
const cooldownMs = options?.cooldownMs ?? TOOL_ERROR_DEFAULTS.cooldownMs;
|
|
48
|
+
const maxPerSession = options?.maxPerSession ?? TOOL_ERROR_DEFAULTS.maxPerSession;
|
|
49
|
+
const lastAttemptAt = new Map();
|
|
50
|
+
const injectedIds = new Set();
|
|
51
|
+
let injections = 0;
|
|
52
|
+
return {
|
|
53
|
+
shouldInject(info, now = Date.now()) {
|
|
54
|
+
if (injections >= maxPerSession)
|
|
55
|
+
return false;
|
|
56
|
+
const signature = normalizeToolErrorSignature(info);
|
|
57
|
+
const last = lastAttemptAt.get(signature);
|
|
58
|
+
if (last !== undefined && now - last < cooldownMs)
|
|
59
|
+
return false;
|
|
60
|
+
return true;
|
|
61
|
+
},
|
|
62
|
+
record(info, quirkIds, now = Date.now()) {
|
|
63
|
+
lastAttemptAt.set(normalizeToolErrorSignature(info), now);
|
|
64
|
+
if (quirkIds.length === 0)
|
|
65
|
+
return;
|
|
66
|
+
injections += 1;
|
|
67
|
+
for (const id of quirkIds)
|
|
68
|
+
injectedIds.add(id);
|
|
69
|
+
},
|
|
70
|
+
get injectedQuirkIds() {
|
|
71
|
+
return injectedIds;
|
|
72
|
+
},
|
|
73
|
+
injectionCount() {
|
|
74
|
+
return injections;
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Select quirks for a failed tool call.
|
|
80
|
+
*
|
|
81
|
+
* Returns `[]` when the state blocks the attempt (cooldown/budget) or nothing
|
|
82
|
+
* passes the score, dedup, and lexical gates. Records the attempt in the state —
|
|
83
|
+
* with cooldown always, with budget only when at least one quirk is returned.
|
|
84
|
+
*/
|
|
85
|
+
export async function selectToolErrorQuirks(recall, info, state, options) {
|
|
86
|
+
if (!state.shouldInject(info))
|
|
87
|
+
return [];
|
|
88
|
+
const minScore = options?.minScore ?? TOOL_ERROR_DEFAULTS.minScore;
|
|
89
|
+
const topK = options?.topK ?? TOOL_ERROR_DEFAULTS.topK;
|
|
90
|
+
const minTokenOverlap = options?.minTokenOverlap ?? TOOL_ERROR_DEFAULTS.minTokenOverlap;
|
|
91
|
+
let raw = [];
|
|
92
|
+
try {
|
|
93
|
+
// Over-fetch so the lexical gate has candidates to choose from.
|
|
94
|
+
raw = await recall(buildToolErrorQuery(info), { topK: Math.max(topK * 3, 6), minScore });
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
// Recall failures must never break tool execution; fall through to recording.
|
|
98
|
+
state.record(info, []);
|
|
99
|
+
return [];
|
|
100
|
+
}
|
|
101
|
+
// Filter everything first, then sort and slice — otherwise the topK cut
|
|
102
|
+
// would keep the first raw entries instead of the highest-scoring ones.
|
|
103
|
+
const candidates = [];
|
|
104
|
+
for (const hit of raw) {
|
|
105
|
+
const { id, content } = hit.chunk;
|
|
106
|
+
if (state.injectedQuirkIds.has(id))
|
|
107
|
+
continue;
|
|
108
|
+
if (minTokenOverlap > 0 && sharedWords(content, info.error) < minTokenOverlap)
|
|
109
|
+
continue;
|
|
110
|
+
candidates.push({
|
|
111
|
+
id,
|
|
112
|
+
content,
|
|
113
|
+
quirkType: hit.chunk.metadata?.quirkType,
|
|
114
|
+
score: hit.score,
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
candidates.sort((a, b) => b.score - a.score);
|
|
118
|
+
const hits = candidates.slice(0, topK);
|
|
119
|
+
state.record(info, hits.map((h) => h.id));
|
|
120
|
+
return hits;
|
|
121
|
+
}
|
|
122
|
+
/** Format the injection block appended to the next model request. Empty when there are no hits. */
|
|
123
|
+
export function formatToolErrorQuirkBlock(info, hits) {
|
|
124
|
+
if (hits.length === 0)
|
|
125
|
+
return "";
|
|
126
|
+
const lines = ["", "---", `⚠ **Tool error** \`${info.tool}\` — matching quirk memory:`, ""];
|
|
127
|
+
for (const hit of hits) {
|
|
128
|
+
const badge = hit.quirkType ? `[\`${hit.quirkType}\`] ` : "";
|
|
129
|
+
lines.push(`- ${badge}${hit.content}`);
|
|
130
|
+
}
|
|
131
|
+
return lines.join("\n");
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Shape a tool error as an entry for the existing auto-capture pipeline
|
|
135
|
+
* (`CaptureExchange.toolResults`). Feed the returned entry into the session's
|
|
136
|
+
* tool-result list so recurring errors can become quirks at session end.
|
|
137
|
+
*/
|
|
138
|
+
export function toToolErrorCaptureEntry(info) {
|
|
139
|
+
return {
|
|
140
|
+
tool: `${info.tool} (error)`,
|
|
141
|
+
output: info.error.slice(0, TOOL_ERROR_DEFAULTS.maxCaptureChars),
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
//# sourceMappingURL=tool-error-recall.js.map
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Shared base class for RerankProvider implementations: failure
|
|
3
|
+
* cooldown and a bounded (query, document) score cache. Retrieval hot paths
|
|
4
|
+
* must never be slowed by a dead reranker, and agent sessions re-issue nearly
|
|
5
|
+
* identical queries often enough that a small in-memory cache pays off.
|
|
6
|
+
*/
|
|
7
|
+
import type { RerankProvider } from "../core/interfaces.js";
|
|
8
|
+
/** Options for the cooldown + cache behavior shared by all rerank providers. */
|
|
9
|
+
export interface RerankProviderBaseOptions {
|
|
10
|
+
/** Consecutive `noteFailure()` calls before the cooldown trips. Default 3. */
|
|
11
|
+
cooldownThreshold?: number;
|
|
12
|
+
/** How long the provider reports `available() === false` after tripping. Default 300000 ms. */
|
|
13
|
+
cooldownMs?: number;
|
|
14
|
+
/** Maximum cached (query, document) scores. Default 500. */
|
|
15
|
+
cacheMax?: number;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Base implementation of {@link RerankProvider} supplying the cooldown state
|
|
19
|
+
* machine and an LRU-ish score cache. Subclasses implement `rerank()` and use
|
|
20
|
+
* {@link cacheGet}/{@link cacheSet} for memoization.
|
|
21
|
+
*/
|
|
22
|
+
export declare abstract class RerankProviderBase implements RerankProvider {
|
|
23
|
+
abstract readonly name: string;
|
|
24
|
+
readonly model: string;
|
|
25
|
+
private failures;
|
|
26
|
+
private cooldownUntil;
|
|
27
|
+
private readonly cooldownThreshold;
|
|
28
|
+
private readonly cooldownMs;
|
|
29
|
+
private readonly cacheMax;
|
|
30
|
+
/** Insertion/re-touch-ordered Map — the first key is the least recently used. */
|
|
31
|
+
private readonly cache;
|
|
32
|
+
constructor(model: string, options?: RerankProviderBaseOptions);
|
|
33
|
+
/** False while the post-failure cooldown is active. */
|
|
34
|
+
available(): boolean;
|
|
35
|
+
/** Counts a failed call; every `cooldownThreshold` failures trip the cooldown. */
|
|
36
|
+
noteFailure(): void;
|
|
37
|
+
/** A success proves the provider is healthy again — reset the streak. */
|
|
38
|
+
noteSuccess(): void;
|
|
39
|
+
/** Look up a cached score for this provider's model + query + document. */
|
|
40
|
+
protected cacheGet(query: string, document: string): number | undefined;
|
|
41
|
+
/** Store a score, evicting the least recently used entry past the cap. */
|
|
42
|
+
protected cacheSet(query: string, document: string, score: number): void;
|
|
43
|
+
private cacheKey;
|
|
44
|
+
abstract rerank(query: string, documents: string[], opts?: {
|
|
45
|
+
timeoutMs?: number;
|
|
46
|
+
}): Promise<number[]>;
|
|
47
|
+
}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
/**
|
|
3
|
+
* Base implementation of {@link RerankProvider} supplying the cooldown state
|
|
4
|
+
* machine and an LRU-ish score cache. Subclasses implement `rerank()` and use
|
|
5
|
+
* {@link cacheGet}/{@link cacheSet} for memoization.
|
|
6
|
+
*/
|
|
7
|
+
export class RerankProviderBase {
|
|
8
|
+
model;
|
|
9
|
+
failures = 0;
|
|
10
|
+
cooldownUntil = 0;
|
|
11
|
+
cooldownThreshold;
|
|
12
|
+
cooldownMs;
|
|
13
|
+
cacheMax;
|
|
14
|
+
/** Insertion/re-touch-ordered Map — the first key is the least recently used. */
|
|
15
|
+
cache = new Map();
|
|
16
|
+
constructor(model, options = {}) {
|
|
17
|
+
this.model = model;
|
|
18
|
+
this.cooldownThreshold = options.cooldownThreshold ?? 3;
|
|
19
|
+
this.cooldownMs = options.cooldownMs ?? 300_000;
|
|
20
|
+
this.cacheMax = options.cacheMax ?? 500;
|
|
21
|
+
}
|
|
22
|
+
/** False while the post-failure cooldown is active. */
|
|
23
|
+
available() {
|
|
24
|
+
return Date.now() >= this.cooldownUntil;
|
|
25
|
+
}
|
|
26
|
+
/** Counts a failed call; every `cooldownThreshold` failures trip the cooldown. */
|
|
27
|
+
noteFailure() {
|
|
28
|
+
this.failures += 1;
|
|
29
|
+
if (this.failures >= this.cooldownThreshold) {
|
|
30
|
+
this.failures = 0;
|
|
31
|
+
this.cooldownUntil = Date.now() + this.cooldownMs;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
/** A success proves the provider is healthy again — reset the streak. */
|
|
35
|
+
noteSuccess() {
|
|
36
|
+
this.failures = 0;
|
|
37
|
+
}
|
|
38
|
+
/** Look up a cached score for this provider's model + query + document. */
|
|
39
|
+
cacheGet(query, document) {
|
|
40
|
+
const key = this.cacheKey(query, document);
|
|
41
|
+
const score = this.cache.get(key);
|
|
42
|
+
if (score !== undefined) {
|
|
43
|
+
// Touch: move to the most-recently-used end.
|
|
44
|
+
this.cache.delete(key);
|
|
45
|
+
this.cache.set(key, score);
|
|
46
|
+
}
|
|
47
|
+
return score;
|
|
48
|
+
}
|
|
49
|
+
/** Store a score, evicting the least recently used entry past the cap. */
|
|
50
|
+
cacheSet(query, document, score) {
|
|
51
|
+
const key = this.cacheKey(query, document);
|
|
52
|
+
this.cache.delete(key);
|
|
53
|
+
this.cache.set(key, score);
|
|
54
|
+
while (this.cache.size > this.cacheMax) {
|
|
55
|
+
const oldest = this.cache.keys().next();
|
|
56
|
+
if (oldest.done === true)
|
|
57
|
+
break;
|
|
58
|
+
this.cache.delete(oldest.value);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
cacheKey(query, document) {
|
|
62
|
+
const hash = createHash("sha1");
|
|
63
|
+
hash.update(this.name);
|
|
64
|
+
hash.update("\0");
|
|
65
|
+
hash.update(this.model);
|
|
66
|
+
hash.update("\0");
|
|
67
|
+
hash.update(query);
|
|
68
|
+
hash.update("\0");
|
|
69
|
+
hash.update(document);
|
|
70
|
+
return hash.digest("hex");
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
//# sourceMappingURL=base.js.map
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Factory for rerank providers. Mirrors the embedder/describer
|
|
3
|
+
* factory pattern: dispatch by config, return null when the feature is off.
|
|
4
|
+
* `getRerankerFor` memoizes one provider per distinct configuration so the
|
|
5
|
+
* failure cooldown and score cache survive across retrievals within a process.
|
|
6
|
+
*/
|
|
7
|
+
import type { RerankingConfig } from "../core/config.js";
|
|
8
|
+
import type { RerankProvider } from "../core/interfaces.js";
|
|
9
|
+
/** Create a rerank provider from config, or null when reranking is disabled/unknown. */
|
|
10
|
+
export declare function createReranker(config?: RerankingConfig): RerankProvider | null;
|
|
11
|
+
/**
|
|
12
|
+
* Process-wide singleton lookup keyed by endpoint identity (provider|baseUrl|
|
|
13
|
+
* model|apiKey). Disabled configs return null without caching; an empty
|
|
14
|
+
* baseUrl/model returns a non-cached null so a later valid config still works.
|
|
15
|
+
*/
|
|
16
|
+
export declare function getRerankerFor(config?: RerankingConfig): RerankProvider | null;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { LlamaServerReranker } from "./llama-server.js";
|
|
2
|
+
/** Create a rerank provider from config, or null when reranking is disabled/unknown. */
|
|
3
|
+
export function createReranker(config) {
|
|
4
|
+
if (!config?.enabled)
|
|
5
|
+
return null;
|
|
6
|
+
const provider = config.provider ?? "llama-server";
|
|
7
|
+
if (provider === "llama-server") {
|
|
8
|
+
if (!config.baseUrl) {
|
|
9
|
+
console.warn("[reranker] reranking.enabled is true but reranking.baseUrl is empty — reranking disabled");
|
|
10
|
+
return null;
|
|
11
|
+
}
|
|
12
|
+
if (!config.model) {
|
|
13
|
+
console.warn("[reranker] reranking.enabled is true but reranking.model is empty — reranking disabled");
|
|
14
|
+
return null;
|
|
15
|
+
}
|
|
16
|
+
return new LlamaServerReranker(config);
|
|
17
|
+
}
|
|
18
|
+
console.warn(`[reranker] unknown reranking.provider "${provider}" — reranking disabled`);
|
|
19
|
+
return null;
|
|
20
|
+
}
|
|
21
|
+
/** Distinct-provider cache bound so config churn cannot grow it unboundedly. */
|
|
22
|
+
const RERANKER_CACHE_MAX = 8;
|
|
23
|
+
const providerCache = new Map();
|
|
24
|
+
/**
|
|
25
|
+
* Process-wide singleton lookup keyed by endpoint identity (provider|baseUrl|
|
|
26
|
+
* model|apiKey). Disabled configs return null without caching; an empty
|
|
27
|
+
* baseUrl/model returns a non-cached null so a later valid config still works.
|
|
28
|
+
*/
|
|
29
|
+
export function getRerankerFor(config) {
|
|
30
|
+
if (!config?.enabled)
|
|
31
|
+
return null;
|
|
32
|
+
if (!config.baseUrl || !config.model)
|
|
33
|
+
return createReranker(config);
|
|
34
|
+
const key = `${config.provider ?? "llama-server"}|${config.baseUrl}|${config.model}|${config.apiKey ?? ""}`;
|
|
35
|
+
const cached = providerCache.get(key);
|
|
36
|
+
if (cached !== undefined)
|
|
37
|
+
return cached;
|
|
38
|
+
const provider = createReranker(config);
|
|
39
|
+
if (providerCache.size >= RERANKER_CACHE_MAX) {
|
|
40
|
+
const oldest = providerCache.keys().next();
|
|
41
|
+
if (!oldest.done)
|
|
42
|
+
providerCache.delete(oldest.value);
|
|
43
|
+
}
|
|
44
|
+
providerCache.set(key, provider);
|
|
45
|
+
return provider;
|
|
46
|
+
}
|
|
47
|
+
//# sourceMappingURL=factory.js.map
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Rerank provider for llama-server's Cohere-style /v1/rerank
|
|
3
|
+
* endpoint (llama.cpp `--reranking --pooling rank`, optionally behind
|
|
4
|
+
* llama-swap which routes v1/rerank natively).
|
|
5
|
+
*/
|
|
6
|
+
import type { RerankingConfig } from "../core/config.js";
|
|
7
|
+
import { RerankProviderBase } from "./base.js";
|
|
8
|
+
/**
|
|
9
|
+
* Cross-encoder reranker backed by llama-server.
|
|
10
|
+
*
|
|
11
|
+
* Sends `{ model, query, documents }` to `{baseUrl}/rerank` and maps
|
|
12
|
+
* `results[].relevance_score` back index-aligned with the input documents.
|
|
13
|
+
* Larger document sets are split into batches of at most
|
|
14
|
+
* `maxDocsPerRequest` and issued concurrently. Failures throw; the calling
|
|
15
|
+
* retrieval stage degrades to fusion order and records the failure for the
|
|
16
|
+
* shared cooldown in {@link RerankProviderBase}.
|
|
17
|
+
*/
|
|
18
|
+
export declare class LlamaServerReranker extends RerankProviderBase {
|
|
19
|
+
readonly name = "llama-server";
|
|
20
|
+
private readonly baseUrl;
|
|
21
|
+
private readonly apiKey?;
|
|
22
|
+
private readonly defaultTimeoutMs;
|
|
23
|
+
private readonly proxy?;
|
|
24
|
+
private readonly maxDocsPerRequest;
|
|
25
|
+
constructor(config: Pick<RerankingConfig, "baseUrl" | "model" | "apiKey" | "timeoutMs" | "proxy">, options?: {
|
|
26
|
+
maxDocsPerRequest?: number;
|
|
27
|
+
});
|
|
28
|
+
rerank(query: string, documents: string[], opts?: {
|
|
29
|
+
timeoutMs?: number;
|
|
30
|
+
}): Promise<number[]>;
|
|
31
|
+
/** One /v1/rerank call; returns scores index-aligned with `documents`. */
|
|
32
|
+
private rerankBatch;
|
|
33
|
+
}
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { postJson } from "../embedder/http.js";
|
|
2
|
+
import { RerankProviderBase } from "./base.js";
|
|
3
|
+
/**
|
|
4
|
+
* Cross-encoder reranker backed by llama-server.
|
|
5
|
+
*
|
|
6
|
+
* Sends `{ model, query, documents }` to `{baseUrl}/rerank` and maps
|
|
7
|
+
* `results[].relevance_score` back index-aligned with the input documents.
|
|
8
|
+
* Larger document sets are split into batches of at most
|
|
9
|
+
* `maxDocsPerRequest` and issued concurrently. Failures throw; the calling
|
|
10
|
+
* retrieval stage degrades to fusion order and records the failure for the
|
|
11
|
+
* shared cooldown in {@link RerankProviderBase}.
|
|
12
|
+
*/
|
|
13
|
+
export class LlamaServerReranker extends RerankProviderBase {
|
|
14
|
+
name = "llama-server";
|
|
15
|
+
baseUrl;
|
|
16
|
+
apiKey;
|
|
17
|
+
defaultTimeoutMs;
|
|
18
|
+
proxy;
|
|
19
|
+
maxDocsPerRequest;
|
|
20
|
+
constructor(config, options = {}) {
|
|
21
|
+
super(config.model);
|
|
22
|
+
this.baseUrl = config.baseUrl.replace(/\/+$/, "");
|
|
23
|
+
this.apiKey = config.apiKey;
|
|
24
|
+
this.defaultTimeoutMs = config.timeoutMs ?? 1500;
|
|
25
|
+
this.proxy = config.proxy;
|
|
26
|
+
// llama.cpp rerank context is sized for a handful of passages; batches
|
|
27
|
+
// beyond this risk context overflow on small --ctx servers.
|
|
28
|
+
this.maxDocsPerRequest = options.maxDocsPerRequest ?? 16;
|
|
29
|
+
}
|
|
30
|
+
async rerank(query, documents, opts) {
|
|
31
|
+
if (documents.length === 0)
|
|
32
|
+
return [];
|
|
33
|
+
const timeoutMs = opts?.timeoutMs ?? this.defaultTimeoutMs;
|
|
34
|
+
const scores = new Array(documents.length).fill(0);
|
|
35
|
+
const missingIndices = [];
|
|
36
|
+
for (let i = 0; i < documents.length; i++) {
|
|
37
|
+
const cached = this.cacheGet(query, documents[i] ?? "");
|
|
38
|
+
if (cached !== undefined) {
|
|
39
|
+
scores[i] = cached;
|
|
40
|
+
}
|
|
41
|
+
else {
|
|
42
|
+
missingIndices.push(i);
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
if (missingIndices.length === 0)
|
|
46
|
+
return scores;
|
|
47
|
+
const batches = [];
|
|
48
|
+
for (let i = 0; i < missingIndices.length; i += this.maxDocsPerRequest) {
|
|
49
|
+
batches.push(missingIndices.slice(i, i + this.maxDocsPerRequest));
|
|
50
|
+
}
|
|
51
|
+
const batchScores = await Promise.all(batches.map((batch) => this.rerankBatch(query, batch.map((i) => documents[i] ?? ""), timeoutMs)));
|
|
52
|
+
for (let b = 0; b < batches.length; b++) {
|
|
53
|
+
const batch = batches[b];
|
|
54
|
+
const batchResult = batchScores[b];
|
|
55
|
+
if (!batch || !batchResult)
|
|
56
|
+
continue;
|
|
57
|
+
for (let j = 0; j < batch.length; j++) {
|
|
58
|
+
const docIndex = batch[j];
|
|
59
|
+
const score = batchResult[j] ?? 0;
|
|
60
|
+
if (docIndex === undefined)
|
|
61
|
+
continue;
|
|
62
|
+
scores[docIndex] = score;
|
|
63
|
+
this.cacheSet(query, documents[docIndex] ?? "", score);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
return scores;
|
|
67
|
+
}
|
|
68
|
+
/** One /v1/rerank call; returns scores index-aligned with `documents`. */
|
|
69
|
+
async rerankBatch(query, documents, timeoutMs) {
|
|
70
|
+
const headers = {};
|
|
71
|
+
if (this.apiKey) {
|
|
72
|
+
headers.Authorization = `Bearer ${this.apiKey}`;
|
|
73
|
+
}
|
|
74
|
+
const response = await postJson(`${this.baseUrl}/rerank`, { model: this.model, query, documents }, headers, timeoutMs, this.proxy);
|
|
75
|
+
if (!response.ok) {
|
|
76
|
+
const body = await response.text().catch(() => "");
|
|
77
|
+
throw new Error(`llama-server rerank failed (${response.status}): ${body.slice(0, 200)}`);
|
|
78
|
+
}
|
|
79
|
+
const json = (await response.json());
|
|
80
|
+
if (!Array.isArray(json.results)) {
|
|
81
|
+
throw new Error(`llama-server rerank: unexpected response: ${JSON.stringify(json).slice(0, 200)}`);
|
|
82
|
+
}
|
|
83
|
+
const scores = new Array(documents.length).fill(0);
|
|
84
|
+
let matched = 0;
|
|
85
|
+
for (const entry of json.results) {
|
|
86
|
+
const index = entry?.index;
|
|
87
|
+
const score = entry?.relevance_score;
|
|
88
|
+
if (typeof index !== "number" || index < 0 || index >= documents.length)
|
|
89
|
+
continue;
|
|
90
|
+
if (typeof score !== "number" || !Number.isFinite(score))
|
|
91
|
+
continue;
|
|
92
|
+
scores[index] = score;
|
|
93
|
+
matched++;
|
|
94
|
+
}
|
|
95
|
+
if (matched === 0) {
|
|
96
|
+
throw new Error("llama-server rerank: response contained no usable relevance_score entries");
|
|
97
|
+
}
|
|
98
|
+
return scores;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
//# sourceMappingURL=llama-server.js.map
|
|
@@ -9,6 +9,7 @@ import type { Chunk, SearchResult, MetadataFilter } from "../core/interfaces.js"
|
|
|
9
9
|
* @returns Array of unique normalized tokens
|
|
10
10
|
*/
|
|
11
11
|
export declare function tokenize(text: string): string[];
|
|
12
|
+
export declare function indexPathFor(storePath: string): string;
|
|
12
13
|
/**
|
|
13
14
|
* In-memory inverted keyword index with stemming, TF-IDF scoring, and optional JSON serialization.
|
|
14
15
|
*
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @fileoverview Performs hybrid vector-keyword retrieval with configurable scoring and explanation.
|
|
3
3
|
*/
|
|
4
|
-
import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
|
|
4
|
+
import type { EmbeddingProvider, KeywordIndex, RerankProvider, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
|
|
5
5
|
/** Options controlling the retrieval behavior. */
|
|
6
6
|
export interface RetrieveOptions {
|
|
7
7
|
topK?: number;
|
|
@@ -20,6 +20,29 @@ export interface RetrieveOptions {
|
|
|
20
20
|
queryPrefix?: string;
|
|
21
21
|
explain?: boolean;
|
|
22
22
|
filter?: MetadataFilter;
|
|
23
|
+
/**
|
|
24
|
+
* Optional cross-encoder reranker. When set (and not cooling down), the top
|
|
25
|
+
* fused candidates are re-scored and re-ordered after the fusion `minScore`
|
|
26
|
+
* gate. Any provider failure/timeout degrades to the fusion order.
|
|
27
|
+
*/
|
|
28
|
+
reranker?: RerankProvider;
|
|
29
|
+
/** Tunables for the rerank stage (defaults apply when omitted). */
|
|
30
|
+
reranking?: RerankStageOptions;
|
|
31
|
+
}
|
|
32
|
+
/** Tunables for the optional rerank stage inside retrieve(). */
|
|
33
|
+
export interface RerankStageOptions {
|
|
34
|
+
/** Candidates (after the fusion minScore gate) sent to the reranker. Default 20. */
|
|
35
|
+
candidates?: number;
|
|
36
|
+
/** Per-document text truncation in characters. Default 1200. */
|
|
37
|
+
maxDocChars?: number;
|
|
38
|
+
/** Gate on the rerank score itself; 0 (default) = pure reorder, nothing dropped. */
|
|
39
|
+
minScore?: number;
|
|
40
|
+
/** `{query}`-placeholder template or prefix applied to the query before scoring. */
|
|
41
|
+
queryTemplate?: string;
|
|
42
|
+
/** Score raw chunk content or description+content. Default "content". */
|
|
43
|
+
docField?: "content" | "content+description";
|
|
44
|
+
/** Per-call timeout in ms handed to the provider. Default 1500. */
|
|
45
|
+
timeoutMs?: number;
|
|
23
46
|
}
|
|
24
47
|
/**
|
|
25
48
|
* Perform hybrid vector-keyword retrieval with configurable scoring.
|
|
@@ -5,6 +5,71 @@ const FETCH_OVERFETCH_FACTOR = 3;
|
|
|
5
5
|
const RRF_K = 60;
|
|
6
6
|
/** Multiply raw RRF scores by (K+1) to normalize to ~[0,1]. */
|
|
7
7
|
const RRF_NORMALIZE = RRF_K + 1;
|
|
8
|
+
const RERANK_DEFAULTS = {
|
|
9
|
+
candidates: 20,
|
|
10
|
+
maxDocChars: 1200,
|
|
11
|
+
minScore: 0,
|
|
12
|
+
timeoutMs: 1500,
|
|
13
|
+
};
|
|
14
|
+
/** Apply the rerank query template: `{query}` substitution, else prefix. */
|
|
15
|
+
function applyQueryTemplate(query, template) {
|
|
16
|
+
if (!template)
|
|
17
|
+
return query;
|
|
18
|
+
return template.includes("{query}") ? template.split("{query}").join(query) : template + query;
|
|
19
|
+
}
|
|
20
|
+
/** Build the rerank document text for a chunk, honoring docField + truncation. */
|
|
21
|
+
function buildRerankDoc(chunk, docField, maxChars) {
|
|
22
|
+
const text = docField === "content+description" && chunk.description
|
|
23
|
+
? `${chunk.description}\n${chunk.content}`
|
|
24
|
+
: chunk.content;
|
|
25
|
+
return text.length > maxChars ? text.slice(0, maxChars) : text;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Optional reorder stage applied to minScore-filtered, fusion-sorted results.
|
|
29
|
+
*
|
|
30
|
+
* The first `candidates` results are scored by the reranker and re-ordered
|
|
31
|
+
* (rerank score desc, fusion rank as tie-breaker); the remainder keeps its
|
|
32
|
+
* fusion order and trails the pool. `result.score` is replaced by the rerank
|
|
33
|
+
* score (the fused components stay in `explanation.scoreBreakdown`, plus the
|
|
34
|
+
* new `rerankScore`). A provider in cooldown, missing, or failing never
|
|
35
|
+
* changes behavior beyond that reorder.
|
|
36
|
+
*/
|
|
37
|
+
async function applyRerankStage(query, results, topK, reranker, stage) {
|
|
38
|
+
if (!reranker)
|
|
39
|
+
return results.slice(0, topK);
|
|
40
|
+
const pool = results.slice(0, Math.max(topK, stage?.candidates ?? RERANK_DEFAULTS.candidates));
|
|
41
|
+
const tail = results.slice(pool.length);
|
|
42
|
+
if (pool.length === 0)
|
|
43
|
+
return results.slice(0, topK);
|
|
44
|
+
if (!reranker.available())
|
|
45
|
+
return [...pool, ...tail].slice(0, topK);
|
|
46
|
+
const maxChars = stage?.maxDocChars ?? RERANK_DEFAULTS.maxDocChars;
|
|
47
|
+
const docField = stage?.docField ?? "content";
|
|
48
|
+
const docs = pool.map((r) => buildRerankDoc(r.chunk, docField, maxChars));
|
|
49
|
+
let scores;
|
|
50
|
+
try {
|
|
51
|
+
scores = await reranker.rerank(applyQueryTemplate(query, stage?.queryTemplate), docs, { timeoutMs: stage?.timeoutMs ?? RERANK_DEFAULTS.timeoutMs });
|
|
52
|
+
}
|
|
53
|
+
catch (err) {
|
|
54
|
+
reranker.noteFailure();
|
|
55
|
+
console.warn(`[retriever] rerank skipped (${err instanceof Error ? err.message : String(err)}) — keeping fusion order`);
|
|
56
|
+
return [...pool, ...tail].slice(0, topK);
|
|
57
|
+
}
|
|
58
|
+
reranker.noteSuccess();
|
|
59
|
+
const minRerank = stage?.minScore ?? RERANK_DEFAULTS.minScore;
|
|
60
|
+
const indexed = pool.map((r, i) => ({ r, i, score: scores[i] ?? 0 }));
|
|
61
|
+
for (const entry of indexed) {
|
|
62
|
+
entry.r.score = entry.score;
|
|
63
|
+
if (entry.r.explanation) {
|
|
64
|
+
entry.r.explanation.scoreBreakdown.rerankScore = entry.score;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
const reordered = indexed
|
|
68
|
+
.filter((e) => minRerank <= 0 || e.score >= minRerank)
|
|
69
|
+
.sort((a, b) => b.score - a.score || a.i - b.i)
|
|
70
|
+
.map((e) => e.r);
|
|
71
|
+
return [...reordered, ...tail].slice(0, topK);
|
|
72
|
+
}
|
|
8
73
|
/** Classify a query as a bare symbol lookup vs. natural-language prose.
|
|
9
74
|
* Symbol queries have no whitespace and look like one (possibly dotted) identifier. */
|
|
10
75
|
function detectQueryShape(query) {
|
|
@@ -81,7 +146,7 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
81
146
|
keywordResults = options.keywordIndex.search(query, topK * FETCH_OVERFETCH_FACTOR, options.filter);
|
|
82
147
|
}
|
|
83
148
|
if (keywordResults.length === 0) {
|
|
84
|
-
const filtered = vectorResults.filter((r) => r.score >= minScore)
|
|
149
|
+
const filtered = vectorResults.filter((r) => r.score >= minScore);
|
|
85
150
|
if (options.explain) {
|
|
86
151
|
for (const r of filtered) {
|
|
87
152
|
r.explanation = {
|
|
@@ -97,7 +162,7 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
97
162
|
}
|
|
98
163
|
attachConfidence(filtered);
|
|
99
164
|
}
|
|
100
|
-
return filtered;
|
|
165
|
+
return applyRerankStage(query, filtered, topK, options.reranker, options.reranking);
|
|
101
166
|
}
|
|
102
167
|
const vRank = new Map(vectorResults.map((r, i) => [r.chunk.id, i]));
|
|
103
168
|
const kRank = new Map(keywordResults.map((r, i) => [r.chunk.id, i]));
|
|
@@ -142,11 +207,10 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
142
207
|
})
|
|
143
208
|
.filter((r) => r !== null)
|
|
144
209
|
.filter((r) => r.score >= minScore)
|
|
145
|
-
.sort((a, b) => b.score - a.score)
|
|
146
|
-
.slice(0, topK);
|
|
210
|
+
.sort((a, b) => b.score - a.score);
|
|
147
211
|
if (options.explain)
|
|
148
212
|
attachConfidence(combinedResults);
|
|
149
|
-
return combinedResults;
|
|
213
|
+
return applyRerankStage(query, combinedResults, topK, options.reranker, options.reranking);
|
|
150
214
|
}
|
|
151
215
|
catch (err) {
|
|
152
216
|
// Never silently mask retrieval failures as "no results" — an embedder
|
|
@@ -39,8 +39,8 @@ declare module "@opencode-ai/plugin" {
|
|
|
39
39
|
output: { args: Record<string, unknown> }
|
|
40
40
|
) => Promise<void>;
|
|
41
41
|
"tool.execute.after"?: (
|
|
42
|
-
input: { tool: string; sessionID: string; callID: string },
|
|
43
|
-
output: { title: string; output: string; metadata: unknown }
|
|
42
|
+
input: { tool: string; sessionID: string; callID: string; status?: "completed" | "error" },
|
|
43
|
+
output: { title: string; output: string; metadata: unknown; error?: string }
|
|
44
44
|
) => Promise<void>;
|
|
45
45
|
"experimental.chat.messages.transform"?: (
|
|
46
46
|
input: Record<string, never>,
|
package/dist/v2/v2-adapter.d.ts
CHANGED
|
@@ -68,7 +68,7 @@ type V2Tool = {
|
|
|
68
68
|
metadata?: Record<string, unknown>;
|
|
69
69
|
}>;
|
|
70
70
|
};
|
|
71
|
-
/** V2 `execute.after` hook event
|
|
71
|
+
/** V2 `execute.after` hook event — fires for BOTH the completed and the error branch. */
|
|
72
72
|
type V2ToolExecuteAfterEvent = {
|
|
73
73
|
tool: string;
|
|
74
74
|
sessionID: string;
|
|
@@ -77,7 +77,12 @@ type V2ToolExecuteAfterEvent = {
|
|
|
77
77
|
result?: {
|
|
78
78
|
output?: unknown;
|
|
79
79
|
content?: string | readonly unknown[];
|
|
80
|
+
error?: unknown;
|
|
81
|
+
message?: unknown;
|
|
80
82
|
};
|
|
83
|
+
/** Error payload fields observed on the error branch (defensively optional). */
|
|
84
|
+
error?: unknown;
|
|
85
|
+
message?: unknown;
|
|
81
86
|
};
|
|
82
87
|
/** V2 `prompt` hook event. */
|
|
83
88
|
type V2PromptHookEvent = {
|