tea-rags 0.9.0

package/build/core/domains/explore/reranker.js

@@ -0,0 +1,399 @@
+/**
+ * Reranker module for search result scoring
+ *
+ * Descriptor-based scoring: each DerivedSignalDescriptor knows how to
+ * extract its normalized value from the raw signals. The Reranker:
+ * 1. Computes per-source adaptive bounds (p95 from batch, floored with defaultBound per-descriptor)
+ * 2. Calls descriptor.extract(rawSignals, { bounds, dampeningThreshold }) for each signal
+ * 3. Computes weighted sum score
+ * 4. Attaches ranking overlay (raw file/chunk signals for transparency)
+ */
+import { p95 } from "../../contracts/signal-utils.js";
+// ---------------------------------------------------------------------------
+// Reranker — descriptor-based scoring with ranking overlay
+// ---------------------------------------------------------------------------
+/**
+ * Reranker — descriptor-based scoring with ranking overlay.
+ *
+ * Uses DerivedSignalDescriptor.extract(rawSignals, ctx) for all signal extraction.
+ * Applies adaptive bounds (p95 from result batch, floored with defaultBound).
+ * Confidence dampening is handled by each descriptor internally.
+ * Attaches RankingOverlay to explain WHY each result scored the way it did.
+ */
+export class Reranker {
+    descriptors;
+    resolvedPresets;
+    descriptorMap;
+    signalKeyMap;
+    collectionStats;
+    constructor(descriptors, resolvedPresets, payloadSignals = []) {
+        this.descriptors = descriptors;
+        this.resolvedPresets = resolvedPresets;
+        this.descriptorMap = new Map();
+        for (const d of this.descriptors) {
+            this.descriptorMap.set(d.name, d);
+        }
+        this.signalKeyMap = buildSignalKeyMap(payloadSignals);
+    }
+    /** Whether collection-level stats are currently loaded. */
+    get hasCollectionStats() {
+        return this.collectionStats !== undefined;
+    }
+    /** Set collection-wide signal stats (computed after indexing). */
+    setCollectionStats(stats) {
+        this.collectionStats = stats;
+    }
+    /** Invalidate stats (called when reindex starts). */
+    invalidateStats() {
+        this.collectionStats = undefined;
+    }
+    /**
+     * Rerank results with ranking overlay.
+     */
+    rerank(results, mode, presetSet) {
+        // Resolve weights, overlay mask, and groupBy
+        let weights;
+        let presetName;
+        let mask;
+        let groupBy;
+        if (typeof mode === "string") {
+            presetName = mode;
+            const fullPreset = this.resolvedPresets.find((p) => p.name === mode && this.matchesTool(p, presetSet));
+            weights = fullPreset?.weights ?? { similarity: 1.0 };
+            mask = fullPreset?.overlayMask;
+            groupBy = fullPreset?.groupBy;
+        }
+        else if (mode.preset) {
+            // Custom weights with preset overlay mask (used by rank_chunks)
+            presetName = mode.preset;
+            weights = mode.custom;
+            const fullPreset = this.resolvedPresets.find((p) => p.name === mode.preset && this.matchesTool(p, presetSet));
+            mask = fullPreset?.overlayMask;
+            groupBy = fullPreset?.groupBy;
+        }
+        else {
+            presetName = "custom";
+            weights = mode.custom;
+        }
+        // Fast path: similarity-only -> no reranking, no overlay
+        const activeKeys = Object.keys(weights).filter((k) => {
+            const w = weights[k];
+            return w !== undefined && w !== 0;
+        });
+        if (activeKeys.length === 1 && activeKeys[0] === "similarity") {
+            return results.map((r) => ({ ...r }));
+        }
+        // Compute adaptive bounds from result batch
+        const bounds = this.computeAdaptiveBounds(results);
+        // Score each result and attach overlay
+        const scored = results.map((result) => {
+            const payload = this.buildExtractPayload(result);
+            const signals = this.extractAllDerived(payload, bounds);
+            const score = calculateScore(signals, weights);
+            const overlay = this.buildOverlay(result, presetName, weights, signals, mask);
+            return { ...result, score, rankingOverlay: overlay };
+        });
+        const sorted = scored.sort((a, b) => b.score - a.score);
+        // Group by payload field: keep highest-scored (first) per group
+        if (groupBy) {
+            const seen = new Map();
+            for (const r of sorted) {
+                const raw = r.payload?.[groupBy];
+                const key = typeof raw === "string" ? raw : "";
+                if (!key || !seen.has(key)) {
+                    seen.set(key || `__ungrouped_${seen.size}`, r);
+                }
+            }
+            return [...seen.values()];
+        }
+        return sorted;
+    }
+    /**
+     * Get preset weights for a specific preset name and tool.
+     */
+    getPreset(name, tool) {
+        return this.resolvedPresets.find((p) => p.name === name && this.matchesTool(p, tool))?.weights;
+    }
+    /**
+     * Get full preset object for a specific preset name and tool.
+     */
+    getFullPreset(name, tool) {
+        return this.resolvedPresets.find((p) => p.name === name && this.matchesTool(p, tool));
+    }
+    /**
+     * Get available preset names for a tool.
+     */
+    getAvailablePresets(tool) {
+        return this.resolvedPresets.filter((p) => this.matchesTool(p, tool)).map((p) => p.name);
+    }
+    /** Descriptor info for MCP schema generation. */
+    getDescriptorInfo() {
+        return this.descriptors.map((d) => ({ name: d.name, description: d.description }));
+    }
+    /** All derived signal descriptors (for RankModule). */
+    getDescriptors() {
+        return this.descriptors;
+    }
+    /** Preset names for a specific tool. */
+    getPresetNames(tool) {
+        return this.resolvedPresets.filter((p) => this.matchesTool(p, tool)).map((p) => p.name);
+    }
+    // -- Private methods --
+    /** Check if a preset serves the given tool. */
+    matchesTool(preset, tool) {
+        return preset.tools.includes(tool);
+    }
+    /**
+     * Build the payload Record<string, unknown> used by descriptor extract().
+     * Includes _score field for similarity descriptor and all payload fields.
+     */
+    buildExtractPayload(result) {
+        return { _score: result.score, ...(result.payload ?? {}) };
+    }
+    /**
+     * Compute adaptive bounds from the result batch — per-source.
+     * For each unique source across all descriptors, read raw values from every payload,
+     * compute p95, and floor with collection-level p95.
+     * Returns Map<sourceKey, adaptiveBound>.
+     */
+    computeAdaptiveBounds(results) {
+        const rawValues = new Map();
+        for (const result of results) {
+            for (const d of this.descriptors) {
+                if (d.defaultBound === undefined)
+                    continue;
+                for (const source of d.sources) {
+                    const raw = this.readRawSource(result, source);
+                    if (raw !== undefined && raw > 0) {
+                        let arr = rawValues.get(source);
+                        if (!arr) {
+                            arr = [];
+                            rawValues.set(source, arr);
+                        }
+                        arr.push(raw);
+                    }
+                }
+            }
+        }
+        const sourceBounds = new Map();
+        for (const [source, values] of rawValues) {
+            const batchP95 = p95(values);
+            const collectionP95 = this.getCollectionP95(source);
+            sourceBounds.set(source, Math.max(batchP95, collectionP95 ?? 0));
+        }
+        return sourceBounds;
+    }
+    /**
+     * Extract all derived signal values from a payload.
+     * Builds per-descriptor bounds record from source-level bounds.
+     * When collectionStats is loaded, sourceBounds already contains max(batchP95, collP95)
+     * which is fully adaptive — no static floor needed.
+     * Without collectionStats, defaultBound serves as a static fallback floor.
+     */
+    extractAllDerived(payload, sourceBounds) {
+        const signals = {};
+        for (const d of this.descriptors) {
+            const bounds = {};
+            for (const source of d.sources) {
+                const sourceBound = sourceBounds.get(source) ?? 0;
+                // With collection stats: adaptive bounds only (minimal floor of 1 for safety).
+                // Without stats: defaultBound as static fallback floor.
+                const floor = this.collectionStats ? 1 : (d.defaultBound ?? 1);
+                bounds[source] = Math.max(sourceBound, floor);
+            }
+            const dampeningThreshold = this.resolveDampeningThreshold(d);
+            signals[d.name] = d.extract(payload, { bounds, dampeningThreshold, collectionStats: this.collectionStats });
+        }
+        return signals;
+    }
+    /**
+     * Resolve dampening threshold for a specific descriptor from its dampeningSource.
+     * Returns undefined if descriptor has no dampeningSource or collectionStats is not loaded —
+     * derived signals fall back to their per-signal FALLBACK_THRESHOLD.
+     */
+    resolveDampeningThreshold(descriptor) {
+        if (!this.collectionStats || !descriptor.dampeningSource)
+            return undefined;
+        const { key, percentile } = descriptor.dampeningSource;
+        const stats = this.collectionStats.perSignal.get(key);
+        return stats?.percentiles?.[percentile];
+    }
+    /**
+     * Look up collection-level p95 for a source key.
+     * Resolves short name → full path via signalKeyMap, then reads from collectionStats.
+     */
+    getCollectionP95(source) {
+        if (!this.collectionStats)
+            return undefined;
+        const fullPath = this.signalKeyMap.get(source) ?? source;
+        return this.collectionStats.perSignal.get(fullPath)?.percentiles?.[95];
+    }
+    /**
+     * Read a raw source value from the payload for adaptive bounds computation.
+     * Uses signalKeyMap to resolve short source names (e.g. "ageDays") to full
+     * payload paths (e.g. "git.file.ageDays"). Falls back to treating source as
+     * a dotted path if no mapping exists.
+     */
+    readRawSource(result, source) {
+        const payload = result.payload ?? {};
+        // 1. Try signalKeyMap: shortName -> full dotted path
+        const fullPath = this.signalKeyMap.get(source);
+        if (fullPath) {
+            const val = readPayloadPath(payload, fullPath);
+            return typeof val === "number" ? val : undefined;
+        }
+        // 2. Fallback: source as payload path (dotted or top-level)
+        const val = readPayloadPath(payload, source);
+        return typeof val === "number" ? val : undefined;
+    }
+    /**
+     * Build ranking overlay for a single result.
+     * When mask is present, only include raw signals listed in the mask.
+     * When mask is absent (custom weights), include raw sources for all active weight keys.
+     */
+    buildOverlay(result, presetName, weights, derivedValues, mask) {
+        const rawFile = {};
+        const rawChunk = {};
+        if (mask) {
+            if (mask.file) {
+                for (const field of mask.file) {
+                    this.extractRawSource(result, field, rawFile, rawChunk);
+                }
+            }
+            if (mask.chunk) {
+                for (const field of mask.chunk) {
+                    this.extractRawSource(result, `chunk.${field}`, rawFile, rawChunk);
+                }
+            }
+        }
+        else {
+            // Fallback: weight-based (custom weights) — extract raw sources for each active weight
+            for (const key of Object.keys(weights)) {
+                const w = weights[key];
+                if (w === undefined || w === 0)
+                    continue;
+                const descriptor = this.descriptorMap.get(key);
+                if (descriptor) {
+                    for (const source of descriptor.sources) {
+                        this.extractRawSource(result, source, rawFile, rawChunk);
+                    }
+                }
+            }
+        }
+        // Extract derived signal values when mask specifies them
+        let derivedOverlay;
+        if (mask?.derived) {
+            derivedOverlay = {};
+            for (const name of mask.derived) {
+                if (name in derivedValues) {
+                    derivedOverlay[name] = derivedValues[name];
+                }
+            }
+            if (Object.keys(derivedOverlay).length === 0)
+                derivedOverlay = undefined;
+        }
+        return {
+            preset: presetName,
+            ...(Object.keys(rawFile).length > 0 ? { file: rawFile } : {}),
+            ...(Object.keys(rawChunk).length > 0 ? { chunk: rawChunk } : {}),
+            ...(derivedOverlay ? { derived: derivedOverlay } : {}),
+        };
+    }
+    /**
+     * Extract a raw source value from payload into the correct level (file/chunk).
+     * Uses signalKeyMap to resolve short source names to full payload paths.
+     * Determines file vs chunk level from the resolved path (paths containing
+     * ".chunk." go to rawChunk, everything else to rawFile).
+     */
+    extractRawSource(result, source, rawFile, rawChunk) {
+        const payload = result.payload ?? {};
+        // Resolve full path via signalKeyMap or use source as-is
+        const fullPath = this.signalKeyMap.get(source) ?? source;
+        const val = readPayloadPath(payload, fullPath);
+        if (val === undefined)
+            return;
+        const segments = fullPath.split(".");
+        const field = segments[segments.length - 1];
+        if (fullPath.includes(".chunk.")) {
+            rawChunk[field] = val;
+        }
+        else {
+            rawFile[field] = val;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Scoring
+// ---------------------------------------------------------------------------
+/**
+ * Calculate final score based on weights and signals
+ */
+function calculateScore(signals, weights) {
+    let score = 0;
+    let totalWeight = 0;
+    for (const [key, weight] of Object.entries(weights)) {
+        if (typeof weight === "number" && weight !== 0 && key in signals) {
+            const signalValue = signals[key];
+            if (typeof signalValue === "number") {
+                score += signalValue * weight;
+                totalWeight += Math.abs(weight);
+            }
+        }
+    }
+    // Normalize by total weight to keep score in 0-1 range
+    return totalWeight > 0 ? score / totalWeight : signals.similarity || 0;
+}
+// ---------------------------------------------------------------------------
+// Payload path utilities
+// ---------------------------------------------------------------------------
+/**
+ * Traverse a nested payload using dot-notation path.
+ * E.g. readPayloadPath(payload, "git.file.ageDays") walks payload.git.file.ageDays.
+ */
+function readPayloadPath(payload, path) {
+    const parts = path.split(".");
+    let current = payload;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== "object")
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Build a mapping from short source names (as used in DerivedSignalDescriptor.sources
+ * and OverlayMask) to full payload dot-notation paths.
+ *
+ * For each PayloadSignalDescriptor with key "git.file.ageDays", generates suffix keys:
+ *   - "ageDays"       -> "git.file.ageDays"  (1-segment suffix, set only if not already taken)
+ *   - "file.ageDays"  -> "git.file.ageDays"  (2-segment suffix, always set)
+ *
+ * For "git.chunk.commitCount":
+ *   - "commitCount"         -> "git.chunk.commitCount" (only if not already taken by file-level)
+ *   - "chunk.commitCount"   -> "git.chunk.commitCount" (always set, this is the canonical form)
+ *
+ * This ensures that descriptor sources like "ageDays" resolve to file-level and
+ * "chunk.commitCount" resolves to chunk-level, matching the existing convention.
+ */
+function buildSignalKeyMap(payloadSignals) {
+    const map = new Map();
+    for (const ps of payloadSignals) {
+        const segments = ps.key.split(".");
+        // Generate suffix keys from longest (N-1 segments) to shortest (1 segment)
+        for (let len = segments.length - 1; len >= 1; len--) {
+            const suffix = segments.slice(segments.length - len).join(".");
+            if (len === 1) {
+                // 1-segment suffix: only set if not already taken (avoids file/chunk collision)
+                if (!map.has(suffix)) {
+                    map.set(suffix, ps.key);
+                }
+            }
+            else {
+                // Multi-segment suffix: always set (canonical form like "chunk.commitCount")
+                map.set(suffix, ps.key);
+            }
+        }
+    }
+    return map;
+}
+//# sourceMappingURL=reranker.js.map

package/build/core/domains/explore/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../../../src/core/domains/explore/reranker.ts"],"names":[],"mappings":"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"}

package/build/core/domains/explore/strategies/base.d.ts

@@ -0,0 +1,45 @@
+/**
+ * BaseExploreStrategy — abstract base for all explore strategies.
+ *
+ * Template Method pattern:
+ *   execute() = applyDefaults() → executeExplore() → postProcess()
+ *
+ * Concrete strategies implement only `executeExplore()` and `type`.
+ */
+import type { QdrantManager } from "../../../adapters/qdrant/client.js";
+import type { PayloadSignalDescriptor } from "../../../contracts/types/trajectory.js";
+import type { Reranker } from "../reranker.js";
+import type { ExploreContext, ExploreResult, ExploreStrategy } from "./types.js";
+export declare abstract class BaseExploreStrategy implements ExploreStrategy {
+    protected readonly qdrant: QdrantManager;
+    protected readonly reranker: Reranker;
+    private readonly payloadSignals;
+    private readonly essentialKeys;
+    abstract readonly type: "vector" | "hybrid" | "scroll-rank";
+    constructor(qdrant: QdrantManager, reranker: Reranker, payloadSignals: PayloadSignalDescriptor[], essentialKeys: string[]);
+    /** Main entry point: apply defaults → execute search → post-process. */
+    execute(ctx: ExploreContext): Promise<ExploreResult[]>;
+    /** Concrete strategy implements the actual search call. */
+    protected abstract executeExplore(ctx: ExploreContext): Promise<ExploreResult[]>;
+    /**
+     * Apply defaults to context before passing to executeExplore.
+     * - Enforces minimum limit of 5
+     * - Computes overfetch limit when pathPattern or non-relevance rerank present
+     * Returns a new context with adjusted limit (fetchLimit for Qdrant).
+     */
+    protected applyDefaults(ctx: ExploreContext): ExploreContext;
+    /**
+     * Post-process raw results:
+     *   1. Glob filter (if pathPattern present)
+     *   2. Rerank (if non-relevance preset)
+     *   3. Trim to requested limit
+     *   4. metaOnly formatting (if ctx.metaOnly)
+     */
+    protected postProcess(results: ExploreResult[], originalCtx: ExploreContext): ExploreResult[];
+    /**
+     * Apply metaOnly formatting: strip raw content, keep metadata from payloadSignals.
+     * Wraps filterMetaOnly output back as ExploreResult[].
+     */
+    protected applyMetaOnly(results: ExploreResult[]): ExploreResult[];
+}
+//# sourceMappingURL=base.d.ts.map

package/build/core/domains/explore/strategies/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAExE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AAEtF,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjF,8BAAsB,mBAAoB,YAAW,eAAe;IAIhE,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa;IACxC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IANhC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;gBAGvC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,EACpB,cAAc,EAAE,uBAAuB,EAAE,EACzC,aAAa,EAAE,MAAM,EAAE;IAG1C,wEAAwE;IAClE,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAM5D,2DAA2D;IAC3D,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAEhF;;;;;OAKG;IACH,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc;IAQ5D;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,WAAW,EAAE,cAAc,GAAG,aAAa,EAAE;IAyB7F;;;OAGG;IACH,SAAS,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;CAOnE"}

package/build/core/domains/explore/strategies/base.js

@@ -0,0 +1,79 @@
+/**
+ * BaseExploreStrategy — abstract base for all explore strategies.
+ *
+ * Template Method pattern:
+ *   execute() = applyDefaults() → executeExplore() → postProcess()
+ *
+ * Concrete strategies implement only `executeExplore()` and `type`.
+ */
+import { calculateFetchLimit, filterResultsByGlob } from "../../../adapters/qdrant/filters/index.js";
+import { filterMetaOnly } from "../post-process.js";
+export class BaseExploreStrategy {
+    qdrant;
+    reranker;
+    payloadSignals;
+    essentialKeys;
+    constructor(qdrant, reranker, payloadSignals, essentialKeys) {
+        this.qdrant = qdrant;
+        this.reranker = reranker;
+        this.payloadSignals = payloadSignals;
+        this.essentialKeys = essentialKeys;
+    }
+    /** Main entry point: apply defaults → execute search → post-process. */
+    async execute(ctx) {
+        const prepared = this.applyDefaults(ctx);
+        const rawResults = await this.executeExplore(prepared);
+        return this.postProcess(rawResults, ctx);
+    }
+    /**
+     * Apply defaults to context before passing to executeExplore.
+     * - Enforces minimum limit of 5
+     * - Computes overfetch limit when pathPattern or non-relevance rerank present
+     * Returns a new context with adjusted limit (fetchLimit for Qdrant).
+     */
+    applyDefaults(ctx) {
+        const requestedLimit = Math.max(ctx.limit ?? 0, 5);
+        const rerank = ctx.rerank;
+        const needsOverfetch = Boolean(ctx.pathPattern) || Boolean(rerank && rerank !== "relevance");
+        const fetchLimit = calculateFetchLimit(requestedLimit, needsOverfetch);
+        return { ...ctx, limit: fetchLimit };
+    }
+    /**
+     * Post-process raw results:
+     *   1. Glob filter (if pathPattern present)
+     *   2. Rerank (if non-relevance preset)
+     *   3. Trim to requested limit
+     *   4. metaOnly formatting (if ctx.metaOnly)
+     */
+    postProcess(results, originalCtx) {
+        const requestedLimit = Math.max(originalCtx.limit ?? 0, 5);
+        const rerank = originalCtx.rerank;
+        // 1. Glob filter
+        let filtered = originalCtx.pathPattern
+            ? filterResultsByGlob(results, originalCtx.pathPattern)
+            : results;
+        // 2. Rerank
+        if (rerank && rerank !== "relevance") {
+            filtered = this.reranker.rerank(filtered, rerank, "semantic_search");
+        }
+        // 3. Trim to requested limit
+        filtered = filtered.slice(0, requestedLimit);
+        // 4. metaOnly formatting
+        if (originalCtx.metaOnly) {
+            return this.applyMetaOnly(filtered);
+        }
+        return filtered;
+    }
+    /**
+     * Apply metaOnly formatting: strip raw content, keep metadata from payloadSignals.
+     * Wraps filterMetaOnly output back as ExploreResult[].
+     */
+    applyMetaOnly(results) {
+        const metaResults = filterMetaOnly(results, this.payloadSignals, this.essentialKeys);
+        return metaResults.map((meta) => ({
+            score: meta.score,
+            payload: meta,
+        }));
+    }
+}
+//# sourceMappingURL=base.js.map

package/build/core/domains/explore/strategies/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAErG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAIpD,MAAM,OAAgB,mBAAmB;IAIlB;IACA;IACF;IACA;IAJnB,YACqB,MAAqB,EACrB,QAAkB,EACpB,cAAyC,EACzC,aAAuB;QAHrB,WAAM,GAAN,MAAM,CAAe;QACrB,aAAQ,GAAR,QAAQ,CAAU;QACpB,mBAAc,GAAd,cAAc,CAA2B;QACzC,kBAAa,GAAb,aAAa,CAAU;IACvC,CAAC;IAEJ,wEAAwE;IACxE,KAAK,CAAC,OAAO,CAAC,GAAmB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAC3C,CAAC;IAKD;;;;;OAKG;IACO,aAAa,CAAC,GAAmB;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAwC,CAAC;QAC5D,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,MAAM,KAAK,WAAW,CAAC,CAAC;QAC7F,MAAM,UAAU,GAAG,mBAAmB,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;QACvE,OAAO,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACO,WAAW,CAAC,OAAwB,EAAE,WAA2B;QACzE,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAwC,CAAC;QAEpE,iBAAiB;QACjB,IAAI,QAAQ,GAAoB,WAAW,CAAC,WAAW;YACrD,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,WAAW,CAAC;YACvD,CAAC,CAAC,OAAO,CAAC;QAEZ,YAAY;QACZ,IAAI,MAAM,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YACrC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC;QACvE,CAAC;QAED,6BAA6B;QAC7B,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAE7C,yBAAyB;QACzB,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;OAGG;IACO,aAAa,CAAC,OAAwB;QAC9C,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QACrF,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAChC,KAAK,EAAE,IAAI,CAAC,KAAe;YAC3B,OAAO,EAAE,IAAI;SACd,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/build/core/domains/explore/strategies/factory.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Explore strategy factory — creates the appropriate strategy for a search type.
+ */
+import type { QdrantManager } from "../../../adapters/qdrant/client.js";
+import type { PayloadSignalDescriptor } from "../../../contracts/types/trajectory.js";
+import type { Reranker } from "../reranker.js";
+import type { BaseExploreStrategy } from "./base.js";
+export type ExploreStrategyType = "vector" | "hybrid" | "scroll-rank";
+export declare function createExploreStrategy(type: ExploreStrategyType, qdrant: QdrantManager, reranker: Reranker, payloadSignals: PayloadSignalDescriptor[], essentialKeys: string[]): BaseExploreStrategy;
+//# sourceMappingURL=factory.d.ts.map

package/build/core/domains/explore/strategies/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAKrD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEtE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,uBAAuB,EAAE,EACzC,aAAa,EAAE,MAAM,EAAE,GACtB,mBAAmB,CAWrB"}

package/build/core/domains/explore/strategies/factory.js

@@ -0,0 +1,19 @@
+/**
+ * Explore strategy factory — creates the appropriate strategy for a search type.
+ */
+import { HybridSearchStrategy } from "./hybrid.js";
+import { ScrollRankStrategy } from "./scroll-rank.js";
+import { VectorSearchStrategy } from "./vector.js";
+export function createExploreStrategy(type, qdrant, reranker, payloadSignals, essentialKeys) {
+    switch (type) {
+        case "vector":
+            return new VectorSearchStrategy(qdrant, reranker, payloadSignals, essentialKeys);
+        case "hybrid":
+            return new HybridSearchStrategy(qdrant, reranker, payloadSignals, essentialKeys);
+        case "scroll-rank":
+            return new ScrollRankStrategy(qdrant, reranker, payloadSignals, essentialKeys);
+        default:
+            throw new Error(`Unknown search strategy type: ${type}`);
+    }
+}
+//# sourceMappingURL=factory.js.map

package/build/core/domains/explore/strategies/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAInD,MAAM,UAAU,qBAAqB,CACnC,IAAyB,EACzB,MAAqB,EACrB,QAAkB,EAClB,cAAyC,EACzC,aAAuB;IAEvB,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,IAAI,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC;QACnF,KAAK,QAAQ;YACX,OAAO,IAAI,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC;QACnF,KAAK,aAAa;YAChB,OAAO,IAAI,kBAAkB,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC;QACjF;YACE,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAc,EAAE,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}

package/build/core/domains/explore/strategies/hybrid.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HybridSearchStrategy — combined dense + sparse (BM25) vector search.
+ *
+ * Validates that the collection has hybrid search enabled,
+ * generates sparse vector from query, and executes hybrid search.
+ * Extracted from MCP search.ts hybrid_search handler.
+ */
+import { BaseExploreStrategy } from "./base.js";
+import { type ExploreContext, type ExploreResult } from "./types.js";
+export declare class HybridSearchStrategy extends BaseExploreStrategy {
+    readonly type: "hybrid";
+    protected executeExplore(ctx: ExploreContext): Promise<ExploreResult[]>;
+}
+//# sourceMappingURL=hybrid.d.ts.map

package/build/core/domains/explore/strategies/hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.d.ts","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/hybrid.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAyB,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5F,qBAAa,oBAAqB,SAAQ,mBAAmB;IAC3D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;cAElB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAc9E"}

package/build/core/domains/explore/strategies/hybrid.js

@@ -0,0 +1,25 @@
+/**
+ * HybridSearchStrategy — combined dense + sparse (BM25) vector search.
+ *
+ * Validates that the collection has hybrid search enabled,
+ * generates sparse vector from query, and executes hybrid search.
+ * Extracted from MCP search.ts hybrid_search handler.
+ */
+import { BM25SparseVectorGenerator } from "../../../adapters/qdrant/sparse.js";
+import { BaseExploreStrategy } from "./base.js";
+import { HybridNotEnabledError } from "./types.js";
+export class HybridSearchStrategy extends BaseExploreStrategy {
+    type = "hybrid";
+    async executeExplore(ctx) {
+        if (!ctx.embedding) {
+            throw new Error("HybridSearchStrategy requires an embedding in the context.");
+        }
+        const collectionInfo = await this.qdrant.getCollectionInfo(ctx.collectionName);
+        if (!collectionInfo.hybridEnabled) {
+            throw new HybridNotEnabledError(ctx.collectionName);
+        }
+        const sparseVector = ctx.sparseVector ?? BM25SparseVectorGenerator.generateSimple(ctx.query ?? "");
+        return this.qdrant.hybridSearch(ctx.collectionName, ctx.embedding, sparseVector, ctx.limit, ctx.filter);
+    }
+}
+//# sourceMappingURL=hybrid.js.map

package/build/core/domains/explore/strategies/hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid.js","sourceRoot":"","sources":["../../../../../src/core/domains/explore/strategies/hybrid.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAA2C,MAAM,YAAY,CAAC;AAE5F,MAAM,OAAO,oBAAqB,SAAQ,mBAAmB;IAClD,IAAI,GAAG,QAAiB,CAAC;IAExB,KAAK,CAAC,cAAc,CAAC,GAAmB;QAChD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAC/E,IAAI,CAAC,cAAc,CAAC,aAAa,EAAE,CAAC;YAClC,MAAM,IAAI,qBAAqB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,IAAI,yBAAyB,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAEnG,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1G,CAAC;CACF"}