@memberjunction/search-engine 5.33.0 → 5.34.0

package/dist/generic/BaseReRanker.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Optional re-ranker primitive for scope search.
+ *
+ * A re-ranker runs AFTER per-scope RRF and cross-scope RRF and BEFORE deduplication.
+ * It takes a fused candidate list plus the original query and produces a more accurate
+ * final ordering — typically via a cross-encoder LLM call (Cohere Rerank, BGE Reranker,
+ * Voyage Rerank). Implementations are registered via `@RegisterClass(BaseReRanker, 'DriverClassName')`
+ * and selected per-scope via `SearchScope.ScopeConfig.reRanker.driverClass`.
+ *
+ * This class is a thin adapter over `@memberjunction/ai`'s `BaseReranker`. Subclasses
+ * that wrap a real provider (Cohere, BGE, Voyage) return an AI-layer reranker from
+ * `getAIReranker()` and inherit the AI layer's validation, timing, and error shape.
+ * The default `ReRank()` handles the conversion between `SearchResultItem[]` and the
+ * AI layer's `RerankDocument[]` / `RerankResult[]` so subclasses don't have to.
+ *
+ * Subclasses that don't need the AI layer (e.g. `NoopReRanker`) can override `ReRank()`
+ * directly.
+ *
+ * See Section 8.3 of plans/search-scopes-rag-plus.md.
+ *
+ * @module @memberjunction/search-engine
+ */
+import { UserInfo } from '@memberjunction/core';
+import { BaseReranker as AIBaseReranker } from '@memberjunction/ai';
+import { SearchResultItem } from './search.types.js';
+/**
+ * Lightweight catalog entry for a registered reranker, returned by
+ * `BaseReRanker.GetAvailableRerankers()`. Designed for UI dropdown population on
+ * the SearchScope form (P2D.7) — a single call gives the form everything it
+ * needs to render selectable options without separately instantiating each
+ * registered class.
+ */
+export interface RegisteredReRankerInfo {
+    /** ClassFactory registration key — what goes into ScopeConfig.reRanker.driverClass */
+    DriverClass: string;
+    /** Human-friendly label for UI display (BaseReRanker.Name) */
+    Name: string;
+    /** Reranker version (BaseReRanker.Version) */
+    Version: string;
+    /** Whether this reranker incurs API cost (true) or runs free locally (false) */
+    HasCost: boolean;
+}
+/**
+ * Abstract primitive for a search re-ranker. Provides a default implementation of
+ * `ReRank()` that delegates to an AI-layer `BaseReranker` returned by
+ * `getAIReranker()`. When `getAIReranker()` returns null (the base default), the
+ * candidates are sliced to `topN` and returned unchanged.
+ *
+ * The `NoopReRanker` default implementation (in `NoopReRanker.ts`) returns candidates
+ * unchanged and serves as the wiring verification point — the SearchEngine's re-rank
+ * stage always resolves a concrete class, even when no real re-ranker is configured.
+ */
+/**
+ * Optional per-call cost-reporting callback. Real-provider rerankers (Cohere, Voyage,
+ * OpenAI) invoke this with the actual cents charged for a single Rerank call so the
+ * SearchEngine / scope-level budget guard can accumulate spend and short-circuit
+ * runaway agents. NoopReRanker and BGE (local) report 0.
+ */
+export type ReRankerCostReporter = (cents: number) => void;
+export declare abstract class BaseReRanker {
+    /**
+     * The `DriverClass` key used by `@RegisterClass(BaseReRanker, 'DriverClassName')` so
+     * the SearchEngine can resolve this subclass via `ClassFactory` from the scope's
+     * `ScopeConfig.reRanker.driverClass` value.
+     */
+    abstract get DriverClass(): string;
+    /**
+     * Human-friendly display name. Defaults to `DriverClass` so subclasses don't have to
+     * override unless they want a different label in UI dropdowns / cost reports.
+     */
+    get Name(): string;
+    /**
+     * Reranker semantic version (independent of the package version). Bump this on a
+     * subclass when the prompt, scoring formula, or upstream model identifier changes
+     * in a way that invalidates cached scores. Defaults to `'1'`.
+     */
+    get Version(): string;
+    /**
+     * Maximum number of candidates a single Rerank call can score. Real providers cap
+     * this (Cohere: 1000, Voyage: 1000, OpenAI: varies). The SearchEngine should respect
+     * this cap by chunking large candidate lists. Defaults to `Number.MAX_SAFE_INTEGER`
+     * (no cap) — subclasses should override.
+     */
+    GetMaxResultCount(): number;
+    /**
+     * Pre-call cost estimate in cents for reranking the given candidate count. Used by
+     * the budget guard to short-circuit BEFORE making the call when the projected cost
+     * exceeds `SearchScope.RerankerBudgetCents`.
+     *
+     * Default: 0 (free / local). Real-provider subclasses override based on their pricing.
+     *
+     * @param resultCount - The number of candidates to be reranked.
+     * @returns Estimated cost in cents (whole + fractional, e.g. `0.25` for ¼¢).
+     */
+    EstimateCostCents(resultCount: number): number;
+    /**
+     * Optional cost reporter. When set, the reranker invokes it after each successful
+     * Rerank call with the actual cents charged. The SearchEngine wires this from the
+     * `RerankerBudgetGuard` to the scope-level spend tracker — see Phase 2D.6.
+     */
+    CostReporter: ReRankerCostReporter | null;
+    /**
+     * Helper for subclasses: report a cost AND record it on the optional callback. Always
+     * safe to call even when no callback is set.
+     */
+    protected reportCost(cents: number): void;
+    /**
+     * Enumerate every reranker currently registered with ClassFactory under
+     * `BaseReRanker`. Designed for the SearchScope form's reranker dropdown (P2D.7) —
+     * the form populates the dropdown from this single call rather than hardcoding
+     * a list, so any ClassFactory-registered reranker (including third-party ones
+     * published as separate packages) shows up automatically.
+     *
+     * Each entry includes the driver-class registration key, the friendly Name,
+     * Version, and a `HasCost` flag (true when EstimateCostCents(1) > 0). Sorted
+     * by Name for stable UI ordering.
+     */
+    static GetAvailableRerankers(): RegisteredReRankerInfo[];
+    /**
+     * Score and re-order candidates against the query.
+     *
+     * Default implementation:
+     * 1. Returns empty when `topN <= 0` or `candidates` is empty.
+     * 2. Resolves an AI-layer reranker via `getAIReranker()`. If none, slices to `topN`.
+     * 3. Maps `SearchResultItem[]` to `RerankDocument[]` (preserving each original item
+     *    in `metadata.__mjSearchItem`).
+     * 4. Calls the AI reranker's `Rerank()` — inherits validation, timing, error handling.
+     * 5. On success, maps the `RerankResult[]` back to `SearchResultItem[]`, replacing
+     *    `Score` with `relevanceScore` and augmenting `ScoreBreakdown` with a `ReRank` key.
+     * 6. On failure, logs and falls back to the unchanged top-N slice.
+     *
+     * Subclasses that bypass the AI layer (e.g. `NoopReRanker`) may override this method.
+     *
+     * @param query - The original query text.
+     * @param candidates - The fused candidate list (post-RRF, pre-dedup).
+     * @param topN - Maximum number of candidates to return after re-ranking.
+     * @param contextUser - The calling user (for auth / tenant propagation).
+     * @param config - Optional provider-specific config from `ScopeConfig.reRanker.config`.
+     */
+    ReRank(query: string, candidates: SearchResultItem[], topN: number, contextUser: UserInfo, config?: Record<string, unknown>): Promise<SearchResultItem[]>;
+    /**
+     * Return the underlying `@memberjunction/ai` `BaseReranker` instance to use.
+     *
+     * Provider-specific subclasses (Cohere, BGE, Voyage) override this to return a
+     * configured AI reranker. Returning `null` (the default) tells `ReRank()` to
+     * skip the AI layer and fall back to a simple top-N slice — useful for Noop
+     * and test implementations.
+     *
+     * @param _config - Provider-specific config from `ScopeConfig.reRanker.config`.
+     * @param _contextUser - The calling user (for auth / tenant propagation).
+     */
+    protected getAIReranker(_config: Record<string, unknown> | undefined, _contextUser: UserInfo): AIBaseReranker | null;
+    /**
+     * Build the text representation of a `SearchResultItem` for the rerank model.
+     * Default concatenates `Title` and `Snippet` separated by newline. Override to
+     * customize (e.g. include tags or entity context).
+     */
+    protected buildRerankText(item: SearchResultItem): string;
+    /** Convert the search result candidates into the AI layer's document shape. */
+    private toRerankDocuments;
+    /** Recover the original `SearchResultItem` and attach the rerank score. */
+    private fromRerankResult;
+}
+//# sourceMappingURL=BaseReRanker.d.ts.map

package/dist/generic/BaseReRanker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseReRanker.d.ts","sourceRoot":"","sources":["../../src/generic/BaseReRanker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,YAAY,IAAI,cAAc,EAAgC,MAAM,oBAAoB,CAAC;AAClG,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACnC,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;AAE3D,8BAAsB,YAAY;IAC9B;;;;OAIG;IACH,aAAoB,WAAW,IAAI,MAAM,CAAC;IAE1C;;;OAGG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;;;;OAKG;IACI,iBAAiB,IAAI,MAAM;IAIlC;;;;;;;;;OASG;IACI,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKrD;;;;OAIG;IACI,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAQ;IAExD;;;OAGG;IACH,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMzC;;;;;;;;;;OAUG;WACW,qBAAqB,IAAI,sBAAsB,EAAE;IA6B/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAAE,EAC9B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,EACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA4B9B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,aAAa,CACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,YAAY,EAAE,QAAQ,GACvB,cAAc,GAAG,IAAI;IAIxB;;;;OAIG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;IAKzD,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB;IASzB,2EAA2E;IAC3E,OAAO,CAAC,gBAAgB;CAc3B"}

package/dist/generic/BaseReRanker.js

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Optional re-ranker primitive for scope search.
+ *
+ * A re-ranker runs AFTER per-scope RRF and cross-scope RRF and BEFORE deduplication.
+ * It takes a fused candidate list plus the original query and produces a more accurate
+ * final ordering — typically via a cross-encoder LLM call (Cohere Rerank, BGE Reranker,
+ * Voyage Rerank). Implementations are registered via `@RegisterClass(BaseReRanker, 'DriverClassName')`
+ * and selected per-scope via `SearchScope.ScopeConfig.reRanker.driverClass`.
+ *
+ * This class is a thin adapter over `@memberjunction/ai`'s `BaseReranker`. Subclasses
+ * that wrap a real provider (Cohere, BGE, Voyage) return an AI-layer reranker from
+ * `getAIReranker()` and inherit the AI layer's validation, timing, and error shape.
+ * The default `ReRank()` handles the conversion between `SearchResultItem[]` and the
+ * AI layer's `RerankDocument[]` / `RerankResult[]` so subclasses don't have to.
+ *
+ * Subclasses that don't need the AI layer (e.g. `NoopReRanker`) can override `ReRank()`
+ * directly.
+ *
+ * See Section 8.3 of plans/search-scopes-rag-plus.md.
+ *
+ * @module @memberjunction/search-engine
+ */
+import { LogError } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+export class BaseReRanker {
+    constructor() {
+        /**
+         * Optional cost reporter. When set, the reranker invokes it after each successful
+         * Rerank call with the actual cents charged. The SearchEngine wires this from the
+         * `RerankerBudgetGuard` to the scope-level spend tracker — see Phase 2D.6.
+         */
+        this.CostReporter = null;
+    }
+    /**
+     * Human-friendly display name. Defaults to `DriverClass` so subclasses don't have to
+     * override unless they want a different label in UI dropdowns / cost reports.
+     */
+    get Name() {
+        return this.DriverClass;
+    }
+    /**
+     * Reranker semantic version (independent of the package version). Bump this on a
+     * subclass when the prompt, scoring formula, or upstream model identifier changes
+     * in a way that invalidates cached scores. Defaults to `'1'`.
+     */
+    get Version() {
+        return '1';
+    }
+    /**
+     * Maximum number of candidates a single Rerank call can score. Real providers cap
+     * this (Cohere: 1000, Voyage: 1000, OpenAI: varies). The SearchEngine should respect
+     * this cap by chunking large candidate lists. Defaults to `Number.MAX_SAFE_INTEGER`
+     * (no cap) — subclasses should override.
+     */
+    GetMaxResultCount() {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    /**
+     * Pre-call cost estimate in cents for reranking the given candidate count. Used by
+     * the budget guard to short-circuit BEFORE making the call when the projected cost
+     * exceeds `SearchScope.RerankerBudgetCents`.
+     *
+     * Default: 0 (free / local). Real-provider subclasses override based on their pricing.
+     *
+     * @param resultCount - The number of candidates to be reranked.
+     * @returns Estimated cost in cents (whole + fractional, e.g. `0.25` for ¼¢).
+     */
+    EstimateCostCents(resultCount) {
+        void resultCount;
+        return 0;
+    }
+    /**
+     * Helper for subclasses: report a cost AND record it on the optional callback. Always
+     * safe to call even when no callback is set.
+     */
+    reportCost(cents) {
+        if (cents > 0 && this.CostReporter) {
+            this.CostReporter(cents);
+        }
+    }
+    /**
+     * Enumerate every reranker currently registered with ClassFactory under
+     * `BaseReRanker`. Designed for the SearchScope form's reranker dropdown (P2D.7) —
+     * the form populates the dropdown from this single call rather than hardcoding
+     * a list, so any ClassFactory-registered reranker (including third-party ones
+     * published as separate packages) shows up automatically.
+     *
+     * Each entry includes the driver-class registration key, the friendly Name,
+     * Version, and a `HasCost` flag (true when EstimateCostCents(1) > 0). Sorted
+     * by Name for stable UI ordering.
+     */
+    static GetAvailableRerankers() {
+        const registrations = MJGlobal.Instance.ClassFactory.GetAllRegistrations(BaseReRanker);
+        const seen = new Set();
+        const out = [];
+        for (const reg of registrations) {
+            const key = reg.Key;
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                const Ctor = reg.SubClass;
+                const instance = new Ctor();
+                out.push({
+                    DriverClass: key,
+                    Name: instance.Name,
+                    Version: instance.Version,
+                    HasCost: instance.EstimateCostCents(1) > 0,
+                });
+            }
+            catch (err) {
+                // Some rerankers may require args we can't supply at enumeration time.
+                // Fall back to the registration key alone — the UI still gets an
+                // option, it just lacks the friendly label.
+                LogError(`BaseReRanker.GetAvailableRerankers: could not introspect "${key}" — ${err instanceof Error ? err.message : String(err)}`);
+                out.push({ DriverClass: key, Name: key, Version: '?', HasCost: false });
+            }
+        }
+        out.sort((a, b) => a.Name.localeCompare(b.Name));
+        return out;
+    }
+    /**
+     * Score and re-order candidates against the query.
+     *
+     * Default implementation:
+     * 1. Returns empty when `topN <= 0` or `candidates` is empty.
+     * 2. Resolves an AI-layer reranker via `getAIReranker()`. If none, slices to `topN`.
+     * 3. Maps `SearchResultItem[]` to `RerankDocument[]` (preserving each original item
+     *    in `metadata.__mjSearchItem`).
+     * 4. Calls the AI reranker's `Rerank()` — inherits validation, timing, error handling.
+     * 5. On success, maps the `RerankResult[]` back to `SearchResultItem[]`, replacing
+     *    `Score` with `relevanceScore` and augmenting `ScoreBreakdown` with a `ReRank` key.
+     * 6. On failure, logs and falls back to the unchanged top-N slice.
+     *
+     * Subclasses that bypass the AI layer (e.g. `NoopReRanker`) may override this method.
+     *
+     * @param query - The original query text.
+     * @param candidates - The fused candidate list (post-RRF, pre-dedup).
+     * @param topN - Maximum number of candidates to return after re-ranking.
+     * @param contextUser - The calling user (for auth / tenant propagation).
+     * @param config - Optional provider-specific config from `ScopeConfig.reRanker.config`.
+     */
+    async ReRank(query, candidates, topN, contextUser, config) {
+        if (topN <= 0 || candidates.length === 0)
+            return [];
+        const aiReranker = this.getAIReranker(config, contextUser);
+        if (!aiReranker) {
+            return candidates.slice(0, topN);
+        }
+        const documents = this.toRerankDocuments(candidates);
+        const response = await aiReranker.Rerank({
+            query,
+            documents,
+            topK: topN,
+            options: config,
+        });
+        if (!response.success) {
+            LogError(`SearchEngine: AI reranker "${this.DriverClass}" failed (${response.durationMs}ms): ${response.errorMessage ?? 'unknown error'}`);
+            return candidates.slice(0, topN);
+        }
+        return response.results.map(r => this.fromRerankResult(r));
+    }
+    /**
+     * Return the underlying `@memberjunction/ai` `BaseReranker` instance to use.
+     *
+     * Provider-specific subclasses (Cohere, BGE, Voyage) override this to return a
+     * configured AI reranker. Returning `null` (the default) tells `ReRank()` to
+     * skip the AI layer and fall back to a simple top-N slice — useful for Noop
+     * and test implementations.
+     *
+     * @param _config - Provider-specific config from `ScopeConfig.reRanker.config`.
+     * @param _contextUser - The calling user (for auth / tenant propagation).
+     */
+    getAIReranker(_config, _contextUser) {
+        return null;
+    }
+    /**
+     * Build the text representation of a `SearchResultItem` for the rerank model.
+     * Default concatenates `Title` and `Snippet` separated by newline. Override to
+     * customize (e.g. include tags or entity context).
+     */
+    buildRerankText(item) {
+        const parts = [item.Title, item.Snippet].filter(p => p != null && p.length > 0);
+        return parts.join('\n');
+    }
+    /** Convert the search result candidates into the AI layer's document shape. */
+    toRerankDocuments(candidates) {
+        return candidates.map(item => ({
+            id: item.ID,
+            text: this.buildRerankText(item),
+            metadata: { __mjSearchItem: item },
+            originalScore: item.Score,
+        }));
+    }
+    /** Recover the original `SearchResultItem` and attach the rerank score. */
+    fromRerankResult(result) {
+        const original = result.document.metadata?.__mjSearchItem;
+        if (!original) {
+            throw new Error('BaseReRanker: rerank result missing original SearchResultItem in metadata — ' +
+                'did a subclass strip the metadata.__mjSearchItem key?');
+        }
+        return {
+            ...original,
+            Score: result.relevanceScore,
+            ScoreBreakdown: { ...original.ScoreBreakdown, ReRank: result.relevanceScore },
+        };
+    }
+}
+//# sourceMappingURL=BaseReRanker.js.map

package/dist/generic/BaseReRanker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseReRanker.js","sourceRoot":"","sources":["../../src/generic/BaseReRanker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAwClD,MAAM,OAAgB,YAAY;IAAlC;QAkDI;;;;WAIG;QACI,iBAAY,GAAgC,IAAI,CAAC;IAgK5D,CAAC;IA/MG;;;OAGG;IACH,IAAW,IAAI;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,IAAW,OAAO;QACd,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACI,iBAAiB;QACpB,OAAO,MAAM,CAAC,gBAAgB,CAAC;IACnC,CAAC;IAED;;;;;;;;;OASG;IACI,iBAAiB,CAAC,WAAmB;QACxC,KAAK,WAAW,CAAC;QACjB,OAAO,CAAC,CAAC;IACb,CAAC;IASD;;;OAGG;IACO,UAAU,CAAC,KAAa;QAC9B,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACjC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACI,MAAM,CAAC,qBAAqB;QAC/B,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC;QACvF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,GAAG,GAA6B,EAAE,CAAC;QACzC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;YACpB,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,IAAI,CAAC;gBACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAA6C,CAAC;gBAC/D,MAAM,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;gBAC5B,GAAG,CAAC,IAAI,CAAC;oBACL,WAAW,EAAE,GAAG;oBAChB,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,OAAO,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC;iBAC7C,CAAC,CAAC;YACP,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,uEAAuE;gBACvE,iEAAiE;gBACjE,4CAA4C;gBAC5C,QAAQ,CAAC,6DAA6D,GAAG,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBACpI,GAAG,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC5E,CAAC;QACL,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,KAAK,CAAC,MAAM,CACf,KAAa,EACb,UAA8B,EAC9B,IAAY,EACZ,WAAqB,EACrB,MAAgC;QAEhC,IAAI,IAAI,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEpD,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC;YACrC,KAAK;YACL,SAAS;YACT,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,MAAM;SAClB,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;YACpB,QAAQ,CACJ,8BAA8B,IAAI,CAAC,WAAW,aAAa,QAAQ,CAAC,UAAU,QAC1E,QAAQ,CAAC,YAAY,IAAI,eAC7B,EAAE,CACL,CAAC;YACF,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;;;;OAUG;IACO,aAAa,CACnB,OAA4C,EAC5C,YAAsB;QAEtB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACO,eAAe,CAAC,IAAsB;QAC5C,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAChF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,+EAA+E;IACvE,iBAAiB,CAAC,UAA8B;QACpD,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC3B,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,IAAI,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;YAChC,QAAQ,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE;YAClC,aAAa,EAAE,IAAI,CAAC,KAAK;SAC5B,CAAC,CAAC,CAAC;IACR,CAAC;IAED,2EAA2E;IACnE,gBAAgB,CAAC,MAAoB;QACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,cAA8C,CAAC;QAC1F,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACX,8EAA8E;gBAC1E,uDAAuD,CAC9D,CAAC;QACN,CAAC;QACD,OAAO;YACH,GAAG,QAAQ;YACX,KAAK,EAAE,MAAM,CAAC,cAAc;YAC5B,cAAc,EAAE,EAAE,GAAG,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE;SAChF,CAAC;IACN,CAAC;CACJ"}

package/dist/generic/EntitySearchProvider.d.ts

@@ -9,7 +9,7 @@
  */
 import { UserInfo } from '@memberjunction/core';
 import { BaseSearchProvider } from './ISearchProvider.js';
-import { SearchSource, SearchFilters, SearchResultItem } from './search.types.js';
+import { SearchSource, SearchFilters, SearchResultItem, ScopeConstraints } from './search.types.js';
 /**
  * Provides entity-level LIKE-based search using RunView + UserSearchString.
  * Searches all entities where AllowUserSearchAPI=true, returning results
@@ -39,15 +39,29 @@ export declare class EntitySearchProvider extends BaseSearchProvider {
      * @param contextUser - The user performing the search
      * @returns Scored result items from entity search
      */
-    Search(query: string, topK: number, filters: SearchFilters | undefined, contextUser: UserInfo): Promise<SearchResultItem[]>;
+    Search(query: string, topK: number, filters: SearchFilters | undefined, contextUser: UserInfo, scopeConstraints?: ScopeConstraints): Promise<SearchResultItem[]>;
+    /**
+     * Resolve the entity list to actually search.
+     *
+     * - If `scopeConstraints.Entities` is provided, use those directly (each carries its own
+     *   rendered ExtraFilter + UserSearchString) — this is the "scoped" path.
+     * - Otherwise fall back to the legacy unscoped path (`AllowUserSearchAPI=true` with
+     *   optional `filters.EntityNames` restriction) and wrap each in a trivial constraint.
+     */
+    private buildScopedEntityList;
     /**
      * Get the list of entities eligible for search, optionally filtered by name.
      */
     private getSearchableEntities;
     /**
      * Search a single entity using RunView with UserSearchString. Wraps the
-     * underlying RunView in a hard timeout so a slow entity cannot hold up
-     * the whole fan-out — partial results from the other entities still land.
+     * underlying RunView in a hard PER_ENTITY_TIMEOUT_MS timeout so a slow
+     * entity cannot hold up the whole fan-out — partial results from the
+     * other entities still land.
+     *
+     * Note: `contextUser` is passed to RunView so row-level security (RLS) is applied
+     * automatically — this is the Entity provider's permission push-down per Section 3.6
+     * of plans/search-scopes-rag-plus.md.
      */
     private searchOneEntity;
     private searchOneEntityRaw;
@@ -66,5 +80,23 @@ export declare class EntitySearchProvider extends BaseSearchProvider {
      * Extract a display snippet from record data using entity metadata.
      */
     private extractSnippet;
+    /**
+     * Remove SQL LIKE wildcard characters from a user-supplied search string.
+     *
+     * The downstream `GenericDatabaseProvider.createViewUserSearchSQL`
+     * interpolates user input directly into `LIKE '%${input}%'`, only
+     * escaping single quotes. Unstripped LIKE wildcards (`%`, `_`, `[`, `]`)
+     * would either match too much (e.g. `Query="%"` matches every row) or
+     * trigger LIKE character-class parsing (`Query="[abc]"`).
+     *
+     * Behavior intent: these characters are treated as not-meaningful for
+     * entity LIKE search. A query containing literal `%` (e.g. `100%`) will
+     * not find records that contain `100%` — the trade-off is documented
+     * to keep the behavior predictable and safe.
+     *
+     * Trailing/leading whitespace is collapsed; an all-wildcard query
+     * returns empty and the caller short-circuits to zero results.
+     */
+    private sanitizeUserSearchString;
 }
 //# sourceMappingURL=EntitySearchProvider.d.ts.map

package/dist/generic/EntitySearchProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EntitySearchProvider.d.ts","sourceRoot":"","sources":["../../src/generic/EntitySearchProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA6D,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAoB,MAAM,gBAAgB,CAAC;AAEjG;;;;GAIG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,SAAgB,UAAU,EAAE,YAAY,CAAY;IAEpD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAK;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAU;IAEvD;;;;;;;;OAQG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,WAAW,EAAE,QAAQ,GACtB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA2C9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;OAIG;YACW,eAAe;YAqBf,kBAAkB;IA4BhC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAwDtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;IACH,OAAO,CAAC,cAAc;CAczB"}
+{"version":3,"file":"EntitySearchProvider.d.ts","sourceRoot":"","sources":["../../src/generic/EntitySearchProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAmD,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEjG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAoB,gBAAgB,EAAyB,MAAM,gBAAgB,CAAC;AAE1I;;;;GAIG;AACH,qBACa,oBAAqB,SAAQ,kBAAkB;IACxD,SAAgB,UAAU,EAAE,YAAY,CAAY;IAEpD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAK;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAU;IAEvD;;;;;;;;OAQG;IACU,MAAM,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,WAAW,EAAE,QAAQ,EACrB,gBAAgB,CAAC,EAAE,gBAAgB,GACpC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IA8E9B;;;;;;;OAOG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;;;;;;OASG;YACW,eAAe;YAsBf,kBAAkB;IA8BhC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAwDtB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,wBAAwB;CAGnC"}

package/dist/generic/EntitySearchProvider.js

@@ -50,31 +50,59 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
      * @param contextUser - The user performing the search
      * @returns Scored result items from entity search
      */
-    async Search(query, topK, filters, contextUser) {
+    async Search(query, topK, filters, contextUser, scopeConstraints) {
         const trimmed = (query ?? '').trim();
         if (trimmed.length < EntitySearchProvider_1.MIN_TERM_LENGTH)
             return [];
         try {
+            // Honor per-provider query transform (e.g., FTS keyword extraction, AI rewrite)
+            const rawQuery = scopeConstraints?.QueryTransforms?.[this.SourceType] ?? query;
+            // Strip SQL LIKE wildcards (`%`, `_`, `[`, `]`) before passing through to
+            // RunView's UserSearchString. The downstream `GenericDatabaseProvider`
+            // builds `LIKE '%${input}%'` clauses with only single-quote escaping —
+            // unstripped `%` would silently match every row, and `[abc]` would
+            // become a LIKE character-class. We treat these characters as
+            // not-meaningful for entity LIKE search rather than offering a
+            // user-facing "match wildcard" feature.
+            const effectiveQuery = this.sanitizeUserSearchString(rawQuery);
+            if (!effectiveQuery) {
+                // Query was entirely wildcard chars — nothing meaningful to match
+                LogStatus('EntitySearchProvider: Query reduced to empty after wildcard strip — returning no results');
+                return [];
+            }
+            // Multi-provider migration (v5.31+): use `this.Provider` instead of
+            // `new Metadata()` so the search honors a non-default IMetadataProvider
+            // when the calling component supplies one. Falls back to the global
+            // default when unset.
             const md = this.Provider;
-            const searchableEntities = this.getSearchableEntities(md, filters);
-            if (searchableEntities.length === 0) {
-                LogStatus('EntitySearchProvider: No searchable entities found');
+            // Build the scoped subset: if scopeConstraints.Entities is provided, use those
+            // verbatim (they already went through the scope's Nunjucks-rendered ExtraFilter +
+            // UserSearchString pipeline). Otherwise fall back to legacy AllowUserSearchAPI
+            // behavior with optional filters.EntityNames restriction.
+            const scoped = this.buildScopedEntityList(md, scopeConstraints, filters);
+            if (scoped.length === 0) {
+                LogStatus('EntitySearchProvider: No searchable entities (scope or metadata match empty)');
                 return [];
             }
-            // Debug: log searchable entities and their search fields
-            LogStatus(`EntitySearchProvider: Searching ${searchableEntities.length} entities for "${trimmed}"`);
-            for (const e of searchableEntities.slice(0, 3)) {
-                const entity = md.EntityByName(e.Name);
+            // Debug: log scoped entities and their search fields
+            LogStatus(`EntitySearchProvider: Searching ${scoped.length} entities for "${effectiveQuery}"${scopeConstraints ? ' (scoped)' : ''}`);
+            for (const e of scoped.slice(0, 3)) {
+                const entity = md.EntityByName(e.EntityName);
                 if (entity) {
                     const searchFields = entity.Fields.filter(f => f.IncludeInUserSearchAPI);
-                    LogStatus(`  Entity "${e.Name}": ${searchFields.length} searchable fields [${searchFields.slice(0, 5).map(f => f.Name).join(', ')}${searchFields.length > 5 ? '...' : ''}]`);
+                    LogStatus(`  Entity "${e.EntityName}": ${searchFields.length} searchable fields [${searchFields.slice(0, 5).map(f => f.Name).join(', ')}${searchFields.length > 5 ? '...' : ''}]`);
                 }
             }
             // Calculate per-entity limit: distribute topK across entities
-            const perEntityLimit = Math.max(3, Math.ceil(topK / Math.max(1, searchableEntities.length)));
-            // Search all entities in parallel, each gated by a hard timeout
-            const searchPromises = searchableEntities.map(entity => this.searchOneEntity(entity.Name, trimmed, perEntityLimit, contextUser));
+            const perEntityLimit = Math.max(3, Math.ceil(topK / Math.max(1, scoped.length)));
+            // Search all entities in parallel, threading per-entity ExtraFilter + UserSearchString
+            // override; each call is gated by a hard PER_ENTITY_TIMEOUT_MS timeout (next PR #2532)
+            // so a slow entity cannot hold up the whole fan-out — partial results from the other
+            // entities still land.
+            const searchPromises = scoped.map(item => this.searchOneEntity(item.EntityName, item.UserSearchString ?? effectiveQuery, perEntityLimit, contextUser, item.ExtraFilter));
             const results = await Promise.all(searchPromises);
+            // Re-score against the original query for field-match relevance (not the transform)
+            // to keep snippets/field-match semantics consistent with what the user typed.
             const allResults = results.flat();
             // Sort by score descending and limit to topK
             allResults.sort((a, b) => b.Score - a.Score);
@@ -86,6 +114,28 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
             return [];
         }
     }
+    /**
+     * Resolve the entity list to actually search.
+     *
+     * - If `scopeConstraints.Entities` is provided, use those directly (each carries its own
+     *   rendered ExtraFilter + UserSearchString) — this is the "scoped" path.
+     * - Otherwise fall back to the legacy unscoped path (`AllowUserSearchAPI=true` with
+     *   optional `filters.EntityNames` restriction) and wrap each in a trivial constraint.
+     */
+    buildScopedEntityList(md, scopeConstraints, filters) {
+        if (scopeConstraints?.Entities?.length) {
+            // Honor the scope's explicit entity list verbatim.
+            return scopeConstraints.Entities;
+        }
+        const unscoped = this.getSearchableEntities(md, filters);
+        return unscoped.map(e => {
+            const info = md.EntityByName(e.Name);
+            return {
+                EntityID: info?.ID ?? '',
+                EntityName: e.Name,
+            };
+        });
+    }
     /**
      * Get the list of entities eligible for search, optionally filtered by name.
      */
@@ -99,11 +149,16 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
     }
     /**
      * Search a single entity using RunView with UserSearchString. Wraps the
-     * underlying RunView in a hard timeout so a slow entity cannot hold up
-     * the whole fan-out — partial results from the other entities still land.
+     * underlying RunView in a hard PER_ENTITY_TIMEOUT_MS timeout so a slow
+     * entity cannot hold up the whole fan-out — partial results from the
+     * other entities still land.
+     *
+     * Note: `contextUser` is passed to RunView so row-level security (RLS) is applied
+     * automatically — this is the Entity provider's permission push-down per Section 3.6
+     * of plans/search-scopes-rag-plus.md.
      */
-    async searchOneEntity(entityName, query, maxRows, contextUser) {
-        const work = this.searchOneEntityRaw(entityName, query, maxRows, contextUser);
+    async searchOneEntity(entityName, userSearchString, maxRows, contextUser, extraFilter) {
+        const work = this.searchOneEntityRaw(entityName, userSearchString, maxRows, contextUser, extraFilter);
         let timer;
         const timeout = new Promise(resolve => {
             timer = setTimeout(() => {
@@ -119,12 +174,13 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
                 clearTimeout(timer);
         }
     }
-    async searchOneEntityRaw(entityName, query, maxRows, contextUser) {
+    async searchOneEntityRaw(entityName, userSearchString, maxRows, contextUser, extraFilter) {
         try {
             const rv = new RunView();
             const result = await rv.RunView({
                 EntityName: entityName,
-                UserSearchString: query,
+                UserSearchString: userSearchString,
+                ExtraFilter: extraFilter && extraFilter.trim() ? extraFilter : undefined,
                 MaxRows: maxRows,
                 ResultType: 'simple'
             }, contextUser);
@@ -132,7 +188,7 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
                 LogError(`EntitySearchProvider: Failed to search "${entityName}": ${result.ErrorMessage}`);
                 return [];
             }
-            return this.convertResults(result.Results, entityName, query);
+            return this.convertResults(result.Results, entityName, userSearchString);
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -236,6 +292,26 @@ let EntitySearchProvider = class EntitySearchProvider extends BaseSearchProvider
         }
         return entityInfo ? `Matched in ${entityInfo.Name}` : 'Matched record';
     }
+    /**
+     * Remove SQL LIKE wildcard characters from a user-supplied search string.
+     *
+     * The downstream `GenericDatabaseProvider.createViewUserSearchSQL`
+     * interpolates user input directly into `LIKE '%${input}%'`, only
+     * escaping single quotes. Unstripped LIKE wildcards (`%`, `_`, `[`, `]`)
+     * would either match too much (e.g. `Query="%"` matches every row) or
+     * trigger LIKE character-class parsing (`Query="[abc]"`).
+     *
+     * Behavior intent: these characters are treated as not-meaningful for
+     * entity LIKE search. A query containing literal `%` (e.g. `100%`) will
+     * not find records that contain `100%` — the trade-off is documented
+     * to keep the behavior predictable and safe.
+     *
+     * Trailing/leading whitespace is collapsed; an all-wildcard query
+     * returns empty and the caller short-circuits to zero results.
+     */
+    sanitizeUserSearchString(input) {
+        return input.replace(/[%_[\]]/g, '').trim();
+    }
 };
 EntitySearchProvider = EntitySearchProvider_1 = __decorate([
     RegisterClass(BaseSearchProvider, 'EntitySearchProvider')