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 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,
@@ -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. */
@@ -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.
@@ -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 score = vContrib + kContrib;
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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-rag-plugin",
3
- "version": "2.8.0",
3
+ "version": "2.9.0",
4
4
  "description": "OpenCode plugin for local-first RAG-based semantic code search",
5
5
  "type": "module",
6
6
  "main": "./dist/plugin-entry.js",