@farukada/langchain-ts-rms 0.1.0

package/dist/infra/rateLimit/circuitBreaker.d.ts

@@ -0,0 +1,54 @@
+/** Circuit breaker states. */
+type CircuitState = "closed" | "open" | "half_open";
+/** Configuration for a CircuitBreaker instance. */
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures before tripping to OPEN. Default: 5. */
+    failureThreshold: number;
+    /** Milliseconds to wait in OPEN before transitioning to HALF_OPEN. Default: 30000. */
+    resetTimeMs: number;
+    /** Human-readable name for logging. */
+    name: string;
+}
+/**
+ * In-process circuit breaker — no external dependencies.
+ *
+ * Three states:
+ * - **CLOSED**: Normal operation. Failures are counted.
+ * - **OPEN**: Fast-fail. After `failureThreshold` consecutive failures, all calls
+ *   are rejected immediately without executing `fn`.
+ * - **HALF_OPEN**: After `resetTimeMs`, one probe request is allowed through.
+ *   On success → CLOSED. On failure → OPEN again.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({ failureThreshold: 5, resetTimeMs: 30_000, name: "searxng" });
+ * const result = await breaker.execute(() => fetch(url));
+ * ```
+ */
+export declare class CircuitBreaker {
+    private readonly opts;
+    private _state;
+    private consecutiveFailures;
+    private lastFailureTime;
+    constructor(opts: CircuitBreakerOptions);
+    /** Current state (for diagnostics/testing). */
+    get state(): CircuitState;
+    /** Wraps an async operation with circuit breaker logic. */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    /** Reset the breaker to CLOSED state (for testing). */
+    reset(): void;
+}
+/**
+ * SearxNG circuit breaker: trips after 5 consecutive failures, 30s cooldown.
+ * Prevents burning time on a down meta-search engine.
+ */
+export declare const searchBreaker: CircuitBreaker;
+/**
+ * Content extraction circuit breaker: trips after 8 failures, 60s cooldown.
+ * Higher threshold because individual sites fail independently.
+ */
+export declare const contentBreaker: CircuitBreaker;
+export {};
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/infra/rateLimit/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/infra/rateLimit/circuitBreaker.ts"],"names":[],"mappings":"AAMA,8BAA8B;AAC9B,KAAK,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAc;IAKb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,eAAe,CAAK;gBAEC,IAAI,EAAE,qBAAqB;IAExD,+CAA+C;IAC/C,IAAI,KAAK,IAAI,YAAY,CAExB;IAED,2DAA2D;IACrD,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBlD,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,SAAS;IAYjB,uDAAuD;IACvD,KAAK,IAAI,IAAI;CAKd;AAMD;;;GAGG;AACH,eAAO,MAAM,aAAa,gBAIxB,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,cAAc,gBAIzB,CAAC"}

package/dist/infra/rateLimit/circuitBreaker.js

@@ -0,0 +1,97 @@
+import { logWarn, logInfo } from "../observability/tracing.js";
+/**
+ * In-process circuit breaker — no external dependencies.
+ *
+ * Three states:
+ * - **CLOSED**: Normal operation. Failures are counted.
+ * - **OPEN**: Fast-fail. After `failureThreshold` consecutive failures, all calls
+ *   are rejected immediately without executing `fn`.
+ * - **HALF_OPEN**: After `resetTimeMs`, one probe request is allowed through.
+ *   On success → CLOSED. On failure → OPEN again.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({ failureThreshold: 5, resetTimeMs: 30_000, name: "searxng" });
+ * const result = await breaker.execute(() => fetch(url));
+ * ```
+ */
+export class CircuitBreaker {
+    opts;
+    _state = "closed";
+    consecutiveFailures = 0;
+    lastFailureTime = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Current state (for diagnostics/testing). */
+    get state() {
+        return this._state;
+    }
+    /** Wraps an async operation with circuit breaker logic. */
+    async execute(fn) {
+        if (this._state === "open") {
+            // Check if enough time has passed to try a probe
+            if (Date.now() - this.lastFailureTime >= this.opts.resetTimeMs) {
+                this._state = "half_open";
+                logInfo(`Circuit breaker "${this.opts.name}" → HALF_OPEN (probe allowed)`);
+            }
+            else {
+                throw new Error(`Circuit breaker "${this.opts.name}" is OPEN — rejecting request. ` +
+                    `${this.consecutiveFailures} consecutive failures. ` +
+                    `Will retry after ${this.opts.resetTimeMs}ms cooldown.`);
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (err) {
+            this.onFailure();
+            throw err;
+        }
+    }
+    onSuccess() {
+        if (this._state === "half_open") {
+            logInfo(`Circuit breaker "${this.opts.name}" → CLOSED (probe succeeded)`);
+        }
+        this._state = "closed";
+        this.consecutiveFailures = 0;
+    }
+    onFailure() {
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        if (this.consecutiveFailures >= this.opts.failureThreshold) {
+            this._state = "open";
+            logWarn(`Circuit breaker "${this.opts.name}" → OPEN after ${this.consecutiveFailures} failures`);
+        }
+    }
+    /** Reset the breaker to CLOSED state (for testing). */
+    reset() {
+        this._state = "closed";
+        this.consecutiveFailures = 0;
+        this.lastFailureTime = 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-configured breakers for RMS infrastructure services
+// ---------------------------------------------------------------------------
+/**
+ * SearxNG circuit breaker: trips after 5 consecutive failures, 30s cooldown.
+ * Prevents burning time on a down meta-search engine.
+ */
+export const searchBreaker = new CircuitBreaker({
+    failureThreshold: 5,
+    resetTimeMs: 30_000,
+    name: "searxng",
+});
+/**
+ * Content extraction circuit breaker: trips after 8 failures, 60s cooldown.
+ * Higher threshold because individual sites fail independently.
+ */
+export const contentBreaker = new CircuitBreaker({
+    failureThreshold: 8,
+    resetTimeMs: 60_000,
+    name: "content-extraction",
+});
+//# sourceMappingURL=circuitBreaker.js.map

package/dist/infra/rateLimit/circuitBreaker.js.map

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

package/dist/infra/rateLimit/rateLimiter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * In-process token bucket rate limiter — no external dependencies.
+ *
+ * Allows short bursts up to `maxTokens` while maintaining a steady-state
+ * throughput of `refillRatePerSecond`. Callers that exceed the budget are
+ * queued and resolved in FIFO order.
+ *
+ * @example
+ * ```ts
+ * const limiter = new TokenBucketLimiter(5, 2); // 5 burst, 2/sec refill
+ * await limiter.acquire(); // wait until a token is available
+ * ```
+ */
+export declare class TokenBucketLimiter {
+    private readonly maxTokens;
+    private readonly refillRatePerSecond;
+    private tokens;
+    private lastRefill;
+    private readonly waitQueue;
+    constructor(maxTokens: number, refillRatePerSecond: number);
+    /** Refill tokens based on elapsed time since last refill. */
+    private refill;
+    /** Wait until a token is available, then consume it. */
+    acquire(): Promise<void>;
+    /** Current number of available tokens (for testing/diagnostics). */
+    get availableTokens(): number;
+}
+/** Creates a new search rate limiter instance (for DI or testing). */
+export declare function createSearchLimiter(): TokenBucketLimiter;
+/** Creates a new content extraction rate limiter instance (for DI or testing). */
+export declare function createContentLimiter(): TokenBucketLimiter;
+/**
+ * SearxNG rate limiter: 5 burst, 2/sec refill.
+ * Prevents overwhelming the meta-search engine with rapid concurrent queries.
+ */
+export declare const searchLimiter: TokenBucketLimiter;
+/**
+ * Content extraction rate limiter: 3 burst, 1/sec refill.
+ * Prevents target websites from IP-blocking the research bot.
+ */
+export declare const contentLimiter: TokenBucketLimiter;
+//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/infra/rateLimit/rateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../src/infra/rateLimit/rateLimiter.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IANtC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAGhC,SAAS,EAAE,MAAM,EACjB,mBAAmB,EAAE,MAAM;IAM9C,6DAA6D;IAC7D,OAAO,CAAC,MAAM;IAQd,wDAAwD;IAClD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B9B,oEAAoE;IACpE,IAAI,eAAe,IAAI,MAAM,CAG5B;CACF;AAMD,sEAAsE;AACtE,wBAAgB,mBAAmB,IAAI,kBAAkB,CAExD;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,IAAI,kBAAkB,CAEzD;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,oBAAwB,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,cAAc,oBAAyB,CAAC"}

package/dist/infra/rateLimit/rateLimiter.js

@@ -0,0 +1,89 @@
+import { logDebug } from "../observability/tracing.js";
+// ---------------------------------------------------------------------------
+// Token Bucket Rate Limiter
+// ---------------------------------------------------------------------------
+/**
+ * In-process token bucket rate limiter — no external dependencies.
+ *
+ * Allows short bursts up to `maxTokens` while maintaining a steady-state
+ * throughput of `refillRatePerSecond`. Callers that exceed the budget are
+ * queued and resolved in FIFO order.
+ *
+ * @example
+ * ```ts
+ * const limiter = new TokenBucketLimiter(5, 2); // 5 burst, 2/sec refill
+ * await limiter.acquire(); // wait until a token is available
+ * ```
+ */
+export class TokenBucketLimiter {
+    maxTokens;
+    refillRatePerSecond;
+    tokens;
+    lastRefill;
+    waitQueue = [];
+    constructor(maxTokens, refillRatePerSecond) {
+        this.maxTokens = maxTokens;
+        this.refillRatePerSecond = refillRatePerSecond;
+        this.tokens = maxTokens;
+        this.lastRefill = Date.now();
+    }
+    /** Refill tokens based on elapsed time since last refill. */
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000;
+        const newTokens = elapsed * this.refillRatePerSecond;
+        this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+        this.lastRefill = now;
+    }
+    /** Wait until a token is available, then consume it. */
+    async acquire() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return;
+        }
+        // Wait for a token to become available
+        const waitMs = ((1 - this.tokens) / this.refillRatePerSecond) * 1000;
+        logDebug("Rate limiter queued", { waitMs: Math.round(waitMs) });
+        return new Promise((resolve) => {
+            this.waitQueue.push(resolve);
+            setTimeout(() => {
+                this.refill();
+                if (this.tokens >= 1) {
+                    this.tokens -= 1;
+                }
+                // Resolve the first queued waiter
+                const waiter = this.waitQueue.shift();
+                if (waiter)
+                    waiter();
+            }, waitMs);
+        });
+    }
+    /** Current number of available tokens (for testing/diagnostics). */
+    get availableTokens() {
+        this.refill();
+        return Math.floor(this.tokens);
+    }
+}
+// ---------------------------------------------------------------------------
+// Pre-configured limiters for RMS infrastructure services
+// ---------------------------------------------------------------------------
+/** Creates a new search rate limiter instance (for DI or testing). */
+export function createSearchLimiter() {
+    return new TokenBucketLimiter(5, 2);
+}
+/** Creates a new content extraction rate limiter instance (for DI or testing). */
+export function createContentLimiter() {
+    return new TokenBucketLimiter(3, 1);
+}
+/**
+ * SearxNG rate limiter: 5 burst, 2/sec refill.
+ * Prevents overwhelming the meta-search engine with rapid concurrent queries.
+ */
+export const searchLimiter = createSearchLimiter();
+/**
+ * Content extraction rate limiter: 3 burst, 1/sec refill.
+ * Prevents target websites from IP-blocking the research bot.
+ */
+export const contentLimiter = createContentLimiter();
+//# sourceMappingURL=rateLimiter.js.map

package/dist/infra/rateLimit/rateLimiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rateLimiter.js","sourceRoot":"","sources":["../../../src/infra/rateLimit/rateLimiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAEvD,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,kBAAkB;IAMV;IACA;IANX,MAAM,CAAS;IACf,UAAU,CAAS;IACV,SAAS,GAAsB,EAAE,CAAC;IAEnD,YACmB,SAAiB,EACjB,mBAA2B;QAD3B,cAAS,GAAT,SAAS,CAAQ;QACjB,wBAAmB,GAAnB,mBAAmB,CAAQ;QAE5C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED,6DAA6D;IACrD,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QAC/C,MAAM,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACrD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QAChE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAED,wDAAwD;IACxD,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO;QACT,CAAC;QAED,uCAAuC;QACvC,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAAC;QACrE,QAAQ,CAAC,qBAAqB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAEhE,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAE7B,UAAU,CAAC,GAAG,EAAE;gBACd,IAAI,CAAC,MAAM,EAAE,CAAC;gBACd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;oBACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;gBACnB,CAAC;gBACD,kCAAkC;gBAClC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;gBACtC,IAAI,MAAM;oBAAE,MAAM,EAAE,CAAC;YACvB,CAAC,EAAE,MAAM,CAAC,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,IAAI,eAAe;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;CACF;AAED,8EAA8E;AAC9E,0DAA0D;AAC1D,8EAA8E;AAE9E,sEAAsE;AACtE,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,EAAE,CAAC"}

package/dist/infra/search/searxngClient.d.ts

@@ -0,0 +1,29 @@
+import { type TokenBucketLimiter } from "../rateLimit/rateLimiter.js";
+import { type CircuitBreaker } from "../rateLimit/circuitBreaker.js";
+export interface SearxngSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+    engine: string;
+}
+/**
+ * Performs a web search via the SearxNG JSON API and returns typed results.
+ *
+ * This calls the SearxNG `/search` endpoint directly via `fetch()` instead
+ * of going through LangChain's `SearxngSearch.invoke()`, which has multiple
+ * issues:
+ *   - Returns comma-separated JSON objects (not a valid JSON array)
+ *   - Uses `link` instead of `url` as the key, losing URL info during parsing
+ *   - Hardcoded 5s AbortSignal that kills slow engines
+ *   - Sends POST with content-type JSON while SearxNG expects GET
+ *
+ * The API base URL is always read from `SEARXNG_API_BASE` env var.
+ */
+export declare function performSearch(query: string, options?: {
+    numResults?: number;
+    /** Override the default search rate limiter (for DI/testing). */
+    limiter?: TokenBucketLimiter;
+    /** Override the default search circuit breaker (for DI/testing). */
+    breaker?: CircuitBreaker;
+}): Promise<SearxngSearchResult[]>;
+//# sourceMappingURL=searxngClient.d.ts.map

package/dist/infra/search/searxngClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searxngClient.d.ts","sourceRoot":"","sources":["../../../src/infra/search/searxngClient.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGpF,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AA0BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,oEAAoE;IACpE,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,GACA,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAsEhC"}

package/dist/infra/search/searxngClient.js

@@ -0,0 +1,85 @@
+import { loadEnv } from "../../config/env.js";
+import { logInfo, logWarn, logError, ErrorCodes } from "../observability/tracing.js";
+import { searchLimiter } from "../rateLimit/rateLimiter.js";
+import { searchBreaker } from "../rateLimit/circuitBreaker.js";
+import { filterBlockedUrls } from "./urlBlocklist.js";
+/** Default request timeout for SearxNG API calls (ms). */
+const SEARXNG_TIMEOUT_MS = 15_000;
+/**
+ * Performs a web search via the SearxNG JSON API and returns typed results.
+ *
+ * This calls the SearxNG `/search` endpoint directly via `fetch()` instead
+ * of going through LangChain's `SearxngSearch.invoke()`, which has multiple
+ * issues:
+ *   - Returns comma-separated JSON objects (not a valid JSON array)
+ *   - Uses `link` instead of `url` as the key, losing URL info during parsing
+ *   - Hardcoded 5s AbortSignal that kills slow engines
+ *   - Sends POST with content-type JSON while SearxNG expects GET
+ *
+ * The API base URL is always read from `SEARXNG_API_BASE` env var.
+ */
+export async function performSearch(query, options) {
+    const env = loadEnv();
+    const apiBase = env.SEARXNG_API_BASE;
+    const limit = options?.numResults ?? 10;
+    const limiter = options?.limiter ?? searchLimiter;
+    const breaker = options?.breaker ?? searchBreaker;
+    logInfo("SearXNG search", { query, numResults: limit });
+    // Build query parameters for the SearxNG JSON API
+    const params = new URLSearchParams({
+        q: query,
+        format: "json",
+    });
+    if (env.SEARXNG_ENGINES)
+        params.set("engines", env.SEARXNG_ENGINES);
+    if (env.SEARXNG_LANGUAGE)
+        params.set("language", env.SEARXNG_LANGUAGE);
+    if (env.SEARXNG_TIME_RANGE)
+        params.set("time_range", env.SEARXNG_TIME_RANGE);
+    const url = `${apiBase}/search?${params.toString()}`;
+    return breaker.execute(async () => {
+        try {
+            await limiter.acquire();
+            const resp = await fetch(url, {
+                method: "GET",
+                signal: AbortSignal.timeout(SEARXNG_TIMEOUT_MS),
+            });
+            if (!resp.ok) {
+                throw new Error(`SearxNG returned HTTP ${resp.status}: ${resp.statusText}`);
+            }
+            const data = (await resp.json());
+            // Log unresponsive engines for diagnostics
+            if (data.unresponsive_engines?.length) {
+                logWarn("SearxNG unresponsive engines", {
+                    engines: data.unresponsive_engines
+                        .map(([name, reason]) => `${name}: ${reason}`)
+                        .join(", "),
+                });
+            }
+            // Map native SearxNG results to our typed interface
+            const rawResults = data.results.slice(0, limit).map((r) => ({
+                title: r.title ?? "",
+                url: r.url ?? "",
+                snippet: r.content ?? "",
+                engine: r.engine ?? r.engines?.[0] ?? "unknown",
+            }));
+            // Remove spam/commercial URLs before they consume result slots
+            const results = filterBlockedUrls(rawResults, (r) => r.url);
+            logInfo("SearXNG results", {
+                query,
+                resultCount: results.length,
+                totalResults: data.number_of_results,
+                answersCount: data.answers?.length ?? 0,
+            });
+            return results;
+        }
+        catch (err) {
+            logError("SearXNG search failed", {
+                errorCode: ErrorCodes.SEARCH_FAILED,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+    });
+}
+//# sourceMappingURL=searxngClient.js.map

package/dist/infra/search/searxngClient.js.map

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

package/dist/infra/search/urlBlocklist.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hardcoded list of domains that never produce useful technical content.
+ * Matching is done on hostname suffix, so `samsclub.com` also blocks
+ * `shop.samsclub.com`.
+ */
+export declare const DEFAULT_BLOCKED_DOMAINS: readonly string[];
+/**
+ * Returns the merged blocklist: hardcoded defaults + user-supplied domains
+ * from the `SEARXNG_URL_BLOCKLIST` env var (comma-separated).
+ */
+export declare function getBlockedDomains(): readonly string[];
+/**
+ * Checks whether a URL's hostname matches any blocked domain.
+ * Uses suffix matching so blocking `example.com` also blocks `shop.example.com`.
+ *
+ * @returns `true` if the URL should be filtered out.
+ */
+export declare function isBlockedUrl(url: string, blocklist?: readonly string[]): boolean;
+/**
+ * Filters out items whose URL matches the blocklist and logs the count of
+ * removed items for diagnostics.
+ *
+ * @param items   - Array of items to filter
+ * @param getUrl  - Accessor to extract the URL from each item
+ * @returns Filtered array with blocked items removed
+ */
+export declare function filterBlockedUrls<T>(items: readonly T[], getUrl: (item: T) => string): T[];
+//# sourceMappingURL=urlBlocklist.d.ts.map

package/dist/infra/search/urlBlocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlBlocklist.d.ts","sourceRoot":"","sources":["../../../src/infra/search/urlBlocklist.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAgBpD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAWrD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAWhF;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GAAG,CAAC,EAAE,CAa1F"}

package/dist/infra/search/urlBlocklist.js

@@ -0,0 +1,78 @@
+import { loadEnv } from "../../config/env.js";
+import { logInfo } from "../observability/tracing.js";
+/**
+ * Hardcoded list of domains that never produce useful technical content.
+ * Matching is done on hostname suffix, so `samsclub.com` also blocks
+ * `shop.samsclub.com`.
+ */
+export const DEFAULT_BLOCKED_DOMAINS = [
+    "advanceautoparts.com",
+    "samsclub.com",
+    "walmart.com",
+    "target.com",
+    "ebay.com",
+    "amazon.com",
+    "aliexpress.com",
+    "wish.com",
+    "etsy.com",
+    "bestbuy.com",
+    "homedepot.com",
+    "lowes.com",
+    "costco.com",
+    "wayfair.com",
+    "overstock.com",
+];
+/**
+ * Returns the merged blocklist: hardcoded defaults + user-supplied domains
+ * from the `SEARXNG_URL_BLOCKLIST` env var (comma-separated).
+ */
+export function getBlockedDomains() {
+    const env = loadEnv();
+    const extra = env.SEARXNG_URL_BLOCKLIST;
+    if (!extra)
+        return DEFAULT_BLOCKED_DOMAINS;
+    const userDomains = extra
+        .split(",")
+        .map((d) => d.trim().toLowerCase())
+        .filter(Boolean);
+    return [...DEFAULT_BLOCKED_DOMAINS, ...userDomains];
+}
+/**
+ * Checks whether a URL's hostname matches any blocked domain.
+ * Uses suffix matching so blocking `example.com` also blocks `shop.example.com`.
+ *
+ * @returns `true` if the URL should be filtered out.
+ */
+export function isBlockedUrl(url, blocklist) {
+    const domains = blocklist ?? getBlockedDomains();
+    let hostname;
+    try {
+        hostname = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        // Malformed URLs are not blocked — let downstream handle them
+        return false;
+    }
+    return domains.some((blocked) => hostname === blocked || hostname.endsWith(`.${blocked}`));
+}
+/**
+ * Filters out items whose URL matches the blocklist and logs the count of
+ * removed items for diagnostics.
+ *
+ * @param items   - Array of items to filter
+ * @param getUrl  - Accessor to extract the URL from each item
+ * @returns Filtered array with blocked items removed
+ */
+export function filterBlockedUrls(items, getUrl) {
+    const blocklist = getBlockedDomains();
+    const filtered = items.filter((item) => !isBlockedUrl(getUrl(item), blocklist));
+    const removedCount = items.length - filtered.length;
+    if (removedCount > 0) {
+        logInfo("Blocked URLs filtered from search results", {
+            removedCount,
+            remainingCount: filtered.length,
+        });
+    }
+    return filtered;
+}
+//# sourceMappingURL=urlBlocklist.js.map

package/dist/infra/search/urlBlocklist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlBlocklist.js","sourceRoot":"","sources":["../../../src/infra/search/urlBlocklist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB;IACxD,sBAAsB;IACtB,cAAc;IACd,aAAa;IACb,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,gBAAgB;IAChB,UAAU;IACV,UAAU;IACV,aAAa;IACb,eAAe;IACf,WAAW;IACX,YAAY;IACZ,aAAa;IACb,eAAe;CAChB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,GAAG,CAAC,qBAAqB,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,uBAAuB,CAAC;IAE3C,MAAM,WAAW,GAAG,KAAK;SACtB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnB,OAAO,CAAC,GAAG,uBAAuB,EAAE,GAAG,WAAW,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,SAA6B;IACrE,MAAM,OAAO,GAAG,SAAS,IAAI,iBAAiB,EAAE,CAAC;IACjD,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,8DAA8D;QAC9D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,QAAQ,KAAK,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAI,KAAmB,EAAE,MAA2B;IACnF,MAAM,SAAS,GAAG,iBAAiB,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAEpD,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,2CAA2C,EAAE;YACnD,YAAY;YACZ,cAAc,EAAE,QAAQ,CAAC,MAAM;SAChC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/infra/vector/qdrantClient.d.ts

@@ -0,0 +1,18 @@
+import { QdrantClient } from "@qdrant/qdrant-js";
+export declare const RESEARCH_COLLECTION = "rms_research";
+export interface QdrantClientConfig {
+    url: string;
+    apiKey?: string;
+    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    timeout?: number;
+}
+export declare function createQdrantClient(config?: Partial<QdrantClientConfig>): QdrantClient;
+/**
+ * Ensures collections exist and creates payload indexes for filtered search.
+ * Idempotent: safe to call on every startup.
+ *
+ * If an existing collection has different vector dimensions (e.g. after
+ * switching embedding models), it is automatically deleted and recreated.
+ */
+export declare function bootstrapQdrantCollections(client: QdrantClient, vectorSize: number): Promise<void>;
+//# sourceMappingURL=qdrantClient.d.ts.map

package/dist/infra/vector/qdrantClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrantClient.d.ts","sourceRoot":"","sources":["../../../src/infra/vector/qdrantClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAIjD,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAWlD,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,YAAY,CASrF;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/dist/infra/vector/qdrantClient.js

@@ -0,0 +1,82 @@
+import { QdrantClient } from "@qdrant/qdrant-js";
+import { loadEnv } from "../../config/env.js";
+import { logInfo } from "../observability/tracing.js";
+export const RESEARCH_COLLECTION = "rms_research";
+const PAYLOAD_INDEX_FIELDS = [
+    { field_name: "metadata.research_id", field_schema: "keyword" },
+    { field_name: "metadata.subject", field_schema: "keyword" },
+    { field_name: "metadata.status", field_schema: "keyword" },
+    { field_name: "metadata.tenant_id", field_schema: "keyword" },
+    { field_name: "metadata.updated_at", field_schema: "keyword" },
+    { field_name: "metadata.tags", field_schema: "keyword" },
+];
+export function createQdrantClient(config) {
+    const env = loadEnv();
+    const opts = {
+        url: config?.url ?? env.QDRANT_URL,
+        timeout: config?.timeout ?? env.QDRANT_TIMEOUT_MS,
+    };
+    const apiKey = config?.apiKey ?? env.QDRANT_API_KEY;
+    if (apiKey)
+        opts.apiKey = apiKey;
+    return new QdrantClient(opts);
+}
+/**
+ * Ensures collections exist and creates payload indexes for filtered search.
+ * Idempotent: safe to call on every startup.
+ *
+ * If an existing collection has different vector dimensions (e.g. after
+ * switching embedding models), it is automatically deleted and recreated.
+ */
+export async function bootstrapQdrantCollections(client, vectorSize) {
+    const collections = await client.getCollections();
+    const names = new Set(collections.collections.map((c) => c.name));
+    for (const name of [RESEARCH_COLLECTION]) {
+        // If collection exists, validate vector dimensions match
+        if (names.has(name)) {
+            const info = await client.getCollection(name);
+            const existingSize = typeof info.config.params.vectors === "object" && "size" in info.config.params.vectors
+                ? info.config.params.vectors.size
+                : undefined;
+            if (existingSize !== undefined && existingSize !== vectorSize) {
+                logInfo(`Collection "${name}" has vector size ${String(existingSize)}, expected ${String(vectorSize)}. Recreating.`);
+                await client.deleteCollection(name);
+                names.delete(name);
+            }
+        }
+        if (!names.has(name)) {
+            try {
+                await client.createCollection(name, {
+                    vectors: {
+                        size: vectorSize,
+                        distance: "Cosine",
+                    },
+                });
+            }
+            catch (e) {
+                // Handle TOCTOU race: another process may have created the collection
+                // between our getCollections() check and this createCollection() call.
+                const msg = e instanceof Error ? e.message : String(e);
+                if (!msg.includes("Conflict") && !msg.includes("already exists")) {
+                    throw e;
+                }
+            }
+        }
+        for (const { field_name, field_schema } of PAYLOAD_INDEX_FIELDS) {
+            try {
+                await client.createPayloadIndex(name, {
+                    field_name,
+                    field_schema: { type: field_schema },
+                    wait: true,
+                });
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (!msg.includes("already exists") && !msg.includes("AlreadyExists")) {
+                    throw e;
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=qdrantClient.js.map