opencode-rag-plugin 2.8.0 → 2.9.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.d.ts +8 -0
- package/dist/api.js +1 -0
- package/dist/cli/commands/eval.js +1 -0
- package/dist/cli/commands/query.js +1 -0
- package/dist/core/config.d.ts +12 -0
- package/dist/core/config.js +4 -0
- package/dist/core/interfaces.d.ts +6 -0
- package/dist/mcp/handlers.js +1 -0
- package/dist/plugin.js +5 -4
- package/dist/retriever/retriever.d.ts +25 -0
- package/dist/retriever/retriever.js +20 -1
- package/package.json +1 -1
package/dist/api.d.ts
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
* @fileoverview High-level public API for OpenCodeRAG: search, indexWorkspace, getContext,
|
|
3
3
|
* scanWorkspace, and related types.
|
|
4
4
|
*/
|
|
5
|
+
import type { MinScoreMode } from "./retriever/retriever.js";
|
|
5
6
|
import { type IndexRunStats } from "./indexer.js";
|
|
6
7
|
import { type WorkspaceFile } from "./content/reader.js";
|
|
7
8
|
import { type SearchResult } from "./core/interfaces.js";
|
|
@@ -15,6 +16,13 @@ export interface SearchOptions {
|
|
|
15
16
|
topK?: number;
|
|
16
17
|
/** Minimum relevance score threshold (0-1). */
|
|
17
18
|
minScore?: number;
|
|
19
|
+
/**
|
|
20
|
+
* How the `minScore` gate reads the score: `"fused"` (default, today's
|
|
21
|
+
* behaviour) or `"normalized"` (scale-free — the score is divided by the
|
|
22
|
+
* maximum that result could reach, so the threshold keeps its meaning at
|
|
23
|
+
* every keyword weight).
|
|
24
|
+
*/
|
|
25
|
+
minScoreMode?: MinScoreMode;
|
|
18
26
|
/** Weight for hybrid keyword search (0-1). */
|
|
19
27
|
keywordWeight?: number;
|
|
20
28
|
/** Filter results to files matching these path patterns. */
|
package/dist/api.js
CHANGED
|
@@ -48,6 +48,7 @@ export async function search(query, options = {}) {
|
|
|
48
48
|
const rawResults = await retrieve(query, ctx.embedder, ctx.store, {
|
|
49
49
|
topK,
|
|
50
50
|
minScore: options.minScore ?? ctx.config.retrieval.minScore,
|
|
51
|
+
minScoreMode: options.minScoreMode ?? ctx.config.retrieval.minScoreMode,
|
|
51
52
|
keywordIndex: ctx.keywordIndex,
|
|
52
53
|
keywordWeight: options.keywordWeight ?? ctx.config.retrieval.hybridSearch?.keywordWeight ?? 0.4,
|
|
53
54
|
symbolKeywordWeight: ctx.config.retrieval.hybridSearch?.symbolKeywordWeight,
|
|
@@ -240,6 +240,7 @@ export function registerEvalGateCommand(program) {
|
|
|
240
240
|
const retrieveOptions = {
|
|
241
241
|
topK,
|
|
242
242
|
minScore: ctx.config.retrieval.minScore,
|
|
243
|
+
minScoreMode: ctx.config.retrieval.minScoreMode,
|
|
243
244
|
keywordIndex: ctx.keywordIndex,
|
|
244
245
|
keywordWeight: hybrid?.keywordWeight,
|
|
245
246
|
symbolKeywordWeight: hybrid?.symbolKeywordWeight,
|
|
@@ -51,6 +51,7 @@ export function registerQueryCommand(program) {
|
|
|
51
51
|
const rawResults = await retrieve(query, embedder, store, {
|
|
52
52
|
topK,
|
|
53
53
|
minScore,
|
|
54
|
+
minScoreMode: config.retrieval.minScoreMode,
|
|
54
55
|
keywordIndex,
|
|
55
56
|
keywordWeight: hybridCfg?.keywordWeight,
|
|
56
57
|
hybridEnabled: hybridCfg?.enabled,
|
package/dist/core/config.d.ts
CHANGED
|
@@ -535,6 +535,18 @@ export interface RagConfig {
|
|
|
535
535
|
topK: number;
|
|
536
536
|
/** Minimum relevance score threshold (0-1). */
|
|
537
537
|
minScore: number;
|
|
538
|
+
/**
|
|
539
|
+
* How `minScore` reads the score (default `"fused"`).
|
|
540
|
+
*
|
|
541
|
+
* The fused hybrid score's scale depends on `hybridSearch.keywordWeight`:
|
|
542
|
+
* a vector-only hit can never exceed `1 - kw`, so at `kw = 0.4` a fixed
|
|
543
|
+
* `minScore` of 0.65 silently demands a DUAL hit (13.5 of 20 results
|
|
544
|
+
* survive vs 17.7 at `kw = 0`). `"normalized"` divides the score by the
|
|
545
|
+
* maximum that result could reach, so the threshold keeps its meaning at
|
|
546
|
+
* every keyword weight. `"fused"` keeps today's behaviour — the default
|
|
547
|
+
* does not change silently; a default flip needs a bigger golden set.
|
|
548
|
+
*/
|
|
549
|
+
minScoreMode?: "fused" | "normalized";
|
|
538
550
|
/** Hybrid search (vector + keyword) configuration. */
|
|
539
551
|
hybridSearch?: {
|
|
540
552
|
/** Whether hybrid search is enabled. */
|
package/dist/core/config.js
CHANGED
|
@@ -130,6 +130,7 @@ export const DEFAULT_CONFIG = {
|
|
|
130
130
|
retrieval: {
|
|
131
131
|
topK: 20,
|
|
132
132
|
minScore: 0.35,
|
|
133
|
+
minScoreMode: "fused",
|
|
133
134
|
hybridSearch: {
|
|
134
135
|
enabled: true,
|
|
135
136
|
keywordWeight: 0.4,
|
|
@@ -492,6 +493,9 @@ export function validateConfig(config) {
|
|
|
492
493
|
if (config.memory?.toolErrorProactiveMaxItems != null && config.memory.toolErrorProactiveMaxItems < 0) {
|
|
493
494
|
warnings.push("memory.toolErrorProactiveMaxItems must be >= 0");
|
|
494
495
|
}
|
|
496
|
+
if (config.retrieval?.minScoreMode != null && !["fused", "normalized"].includes(config.retrieval.minScoreMode)) {
|
|
497
|
+
warnings.push(`retrieval.minScoreMode "${config.retrieval.minScoreMode}" — expected "fused" or "normalized"`);
|
|
498
|
+
}
|
|
495
499
|
if (config.memory?.decay && config.memory.decay.halfLifeDays <= 0) {
|
|
496
500
|
warnings.push("memory.decay.halfLifeDays must be > 0");
|
|
497
501
|
}
|
|
@@ -150,6 +150,12 @@ export interface SearchExplanation {
|
|
|
150
150
|
vectorRank?: number;
|
|
151
151
|
/** Rank (0-indexed) in the keyword index results. */
|
|
152
152
|
keywordRank?: number;
|
|
153
|
+
/**
|
|
154
|
+
* The highest score a result with these legs could reach (rank 0 in
|
|
155
|
+
* each). Set only in `minScoreMode: "normalized"`, where the reported
|
|
156
|
+
* score is the fused score divided by this value.
|
|
157
|
+
*/
|
|
158
|
+
maxReachableScore?: number;
|
|
153
159
|
/** Cross-encoder relevance from the optional rerank stage. Higher means more
|
|
154
160
|
* relevant. NOT a calibrated probability (provider-dependent, llama-server
|
|
155
161
|
* semantics) and NOT comparable to the RRF-normalized fused components.
|
package/dist/mcp/handlers.js
CHANGED
|
@@ -91,6 +91,7 @@ export async function handleSearchSemantic(params, embedder, store, cfg, keyword
|
|
|
91
91
|
const retrieveOpts = {
|
|
92
92
|
topK,
|
|
93
93
|
minScore: cfg.retrieval.minScore,
|
|
94
|
+
minScoreMode: cfg.retrieval.minScoreMode,
|
|
94
95
|
keywordIndex,
|
|
95
96
|
keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight,
|
|
96
97
|
hybridEnabled: cfg.retrieval.hybridSearch?.enabled,
|
package/dist/plugin.js
CHANGED
|
@@ -433,10 +433,10 @@ function buildRetrievalQuery(hints) {
|
|
|
433
433
|
* Perform a retrieval query against the vector store with the given parameters.
|
|
434
434
|
* Returns an empty array for blank queries.
|
|
435
435
|
*/
|
|
436
|
-
async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false, hybridEnabled, filter, reranker, reranking) {
|
|
436
|
+
async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false, hybridEnabled, filter, reranker, reranking, minScoreMode) {
|
|
437
437
|
if (query.trim().length === 0)
|
|
438
438
|
return [];
|
|
439
|
-
return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, hybridEnabled, queryPrefix, explain, filter, reranker, reranking });
|
|
439
|
+
return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, hybridEnabled, queryPrefix, explain, filter, reranker, reranking, minScoreMode });
|
|
440
440
|
}
|
|
441
441
|
/**
|
|
442
442
|
* Load results from one or two queries (primary + optional extra), optimize
|
|
@@ -445,11 +445,12 @@ async function retrieveContext(query, embedder, store, topK, retrieveFn = retrie
|
|
|
445
445
|
*/
|
|
446
446
|
async function loadRetrievedResults(query, embedder, store, cfg, retrieveFn = retrieve, topK = cfg.retrieval.topK, extraQuery, keywordIndex, queryPrefix, explain = false, filter, reranker, reranking) {
|
|
447
447
|
const minScore = cfg.retrieval.minScore;
|
|
448
|
+
const minScoreMode = cfg.retrieval.minScoreMode;
|
|
448
449
|
const kw = cfg.retrieval.hybridSearch?.keywordWeight;
|
|
449
450
|
const hybridEnabled = cfg.retrieval.hybridSearch?.enabled;
|
|
450
|
-
const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled, filter, reranker, reranking);
|
|
451
|
+
const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled, filter, reranker, reranking, minScoreMode);
|
|
451
452
|
const extraResults = extraQuery
|
|
452
|
-
? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled, filter, reranker, reranking)
|
|
453
|
+
? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled, filter, reranker, reranking, minScoreMode)
|
|
453
454
|
: [];
|
|
454
455
|
const optCfg = cfg.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
|
|
455
456
|
return optimizeContext([...primaryResults, ...extraResults], { topK, config: optCfg })
|
|
@@ -2,10 +2,35 @@
|
|
|
2
2
|
* @fileoverview Performs hybrid vector-keyword retrieval with configurable scoring and explanation.
|
|
3
3
|
*/
|
|
4
4
|
import type { EmbeddingProvider, KeywordIndex, RerankProvider, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
|
|
5
|
+
/**
|
|
6
|
+
* How the `minScore` gate reads the score.
|
|
7
|
+
*
|
|
8
|
+
* - `"fused"` — compare against the raw fused RRF score. Its scale depends on
|
|
9
|
+
* `keywordWeight`, so the same threshold means different things at
|
|
10
|
+
* different weights.
|
|
11
|
+
* - `"normalized"` — compare against the score divided by the maximum that
|
|
12
|
+
* result could reach. Scale-free: the threshold keeps its meaning when
|
|
13
|
+
* `keywordWeight` changes.
|
|
14
|
+
*/
|
|
15
|
+
export type MinScoreMode = "fused" | "normalized";
|
|
5
16
|
/** Options controlling the retrieval behavior. */
|
|
6
17
|
export interface RetrieveOptions {
|
|
7
18
|
topK?: number;
|
|
8
19
|
minScore?: number;
|
|
20
|
+
/**
|
|
21
|
+
* How the `minScore` gate reads the score.
|
|
22
|
+
*
|
|
23
|
+
* - `"fused"` (default): the gate compares against the raw fused RRF score.
|
|
24
|
+
* That score's scale DEPENDS on `keywordWeight` — a vector-only hit can
|
|
25
|
+
* never exceed `(1 - kw)`, so at `kw = 0.4` the fused score maxes out at
|
|
26
|
+
* 0.6 and a fixed `minScore` of 0.65 silently demands a DUAL hit.
|
|
27
|
+
* - `"normalized"`: the fused score is divided by the maximum that result
|
|
28
|
+
* could reach given the legs it has (a dual hit reaches the same maximum
|
|
29
|
+
* at every `keywordWeight`, a vector-only hit reaches `(1 - kw)` times
|
|
30
|
+
* that). The score becomes scale-free, so `minScore` means the same
|
|
31
|
+
* thing at every `keywordWeight`.
|
|
32
|
+
*/
|
|
33
|
+
minScoreMode?: MinScoreMode;
|
|
9
34
|
keywordIndex?: KeywordIndex;
|
|
10
35
|
keywordWeight?: number;
|
|
11
36
|
/** Keyword weight for symbol-style queries (a bare identifier like `cosineSimilarity`).
|
|
@@ -5,6 +5,18 @@ 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
|
+
/**
|
|
9
|
+
* The highest score a result with the given legs could reach (rank 0 in each).
|
|
10
|
+
*
|
|
11
|
+
* A dual hit reaches `(1 - kw) + kw` of the maximum — the same at every
|
|
12
|
+
* `keywordWeight`. A vector-only hit reaches `(1 - kw)` of it, a keyword-only
|
|
13
|
+
* hit `kw` of it. Dividing by this value is what makes the score scale-free.
|
|
14
|
+
*/
|
|
15
|
+
function maxReachableScore(hasVector, hasKeyword, keywordWeight) {
|
|
16
|
+
const vector = hasVector ? ((1 - keywordWeight) * RRF_NORMALIZE) / (RRF_K + 1) : 0;
|
|
17
|
+
const keyword = hasKeyword ? (keywordWeight * RRF_NORMALIZE) / (RRF_K + 1) : 0;
|
|
18
|
+
return vector + keyword;
|
|
19
|
+
}
|
|
8
20
|
const RERANK_DEFAULTS = {
|
|
9
21
|
candidates: 20,
|
|
10
22
|
maxDocChars: 1200,
|
|
@@ -122,6 +134,7 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
122
134
|
try {
|
|
123
135
|
const topK = options.topK ?? 10;
|
|
124
136
|
const minScore = options.minScore ?? 0;
|
|
137
|
+
const minScoreMode = options.minScoreMode ?? "fused";
|
|
125
138
|
const queryShape = detectQueryShape(query);
|
|
126
139
|
const baseKw = options.keywordWeight ?? 0.4;
|
|
127
140
|
// Symbol queries are exact-identifier lookups — keyword search is the strong
|
|
@@ -182,7 +195,12 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
182
195
|
const kMultiplier = kR !== undefined ? keywordDemotion(chunk, docDemotion, testDemotion) : 1;
|
|
183
196
|
const vContrib = vR !== undefined ? ((1 - kw) * RRF_NORMALIZE) / (RRF_K + vR + 1) : 0;
|
|
184
197
|
const kContrib = kR !== undefined ? (kw * RRF_NORMALIZE) / (RRF_K + kR + 1) * kMultiplier : 0;
|
|
185
|
-
const
|
|
198
|
+
const fusedScore = vContrib + kContrib;
|
|
199
|
+
// In "normalized" mode the score is divided by the maximum this result
|
|
200
|
+
// could reach, so the `minScore` gate keeps its meaning no matter what
|
|
201
|
+
// `keywordWeight` is set to.
|
|
202
|
+
const maxReachable = maxReachableScore(vR !== undefined, kR !== undefined, kw);
|
|
203
|
+
const score = minScoreMode === "normalized" && maxReachable > 0 ? fusedScore / maxReachable : fusedScore;
|
|
186
204
|
const result = { chunk, score };
|
|
187
205
|
if (options.explain) {
|
|
188
206
|
result.explanation = {
|
|
@@ -194,6 +212,7 @@ export async function retrieve(query, embedder, store, options = {}) {
|
|
|
194
212
|
keywordWeight: kw,
|
|
195
213
|
vectorRank: vR,
|
|
196
214
|
keywordRank: kR,
|
|
215
|
+
...(minScoreMode === "normalized" ? { maxReachableScore: maxReachable } : {}),
|
|
197
216
|
},
|
|
198
217
|
queryShape,
|
|
199
218
|
};
|