@librechat/agents 3.4.0 → 3.4.2

package/src/tools/search/rerankers.ts

@@ -225,6 +225,250 @@ export class CohereReranker extends BaseReranker {
   }
 }
 
+/** rag_api's `/v1/rerank` contract caps candidates at 50 and `top_n` at 25;
+ * violating either is a client bug, not a server error, so both are clamped
+ * locally with a debug log instead of erroring. */
+const RAG_API_MAX_CANDIDATES = 50;
+const RAG_API_MAX_TOP_N = 25;
+const RAG_API_DEFAULT_PROFILE = 'fast-v1';
+
+const getDefaultRagApiUrl = (): string | undefined =>
+  process.env.RAG_API_URL != null && process.env.RAG_API_URL !== ''
+    ? process.env.RAG_API_URL
+    : undefined;
+
+const toRagApiCandidate = (
+  text: string,
+  index: number
+): t.RagApiRerankCandidate => ({ id: String(index), text, base_score: 0 });
+
+/** A single source split into overlapping chunks routinely exceeds the
+ * contract limit, so documents are capped before any candidate is built:
+ * only the submittable window is ever allocated. */
+const buildRagApiCandidates = (
+  documents: string[],
+  logger: t.Logger
+): t.RagApiRerankCandidate[] => {
+  if (documents.length <= RAG_API_MAX_CANDIDATES) {
+    return documents.map(toRagApiCandidate);
+  }
+  logger.debug(
+    `rag_api fast-v1 accepts at most ${RAG_API_MAX_CANDIDATES} candidates; truncating ${documents.length} to ${RAG_API_MAX_CANDIDATES}.`
+  );
+  return documents.slice(0, RAG_API_MAX_CANDIDATES).map(toRagApiCandidate);
+};
+
+const clampRagApiTopN = (topN: number, logger: t.Logger): number => {
+  if (topN <= RAG_API_MAX_TOP_N) {
+    return topN;
+  }
+  logger.debug(
+    `rag_api fast-v1 accepts top_n <= ${RAG_API_MAX_TOP_N}; clamping ${topN} to ${RAG_API_MAX_TOP_N}.`
+  );
+  return RAG_API_MAX_TOP_N;
+};
+
+/** Deterministic tie ordering: rank by score descending, breaking ties on
+ * original candidate index rather than relying on rag_api's response order. */
+const sortRagApiResults = (
+  results: t.RagApiRerankResult[]
+): t.RagApiRerankResult[] =>
+  [...results].sort((a, b) => b.score - a.score || a.index - b.index);
+
+/** Indices are only meaningful against the candidates actually submitted:
+ * anything beyond `candidateCount` refers to text the server never saw. */
+const isValidRagApiResult = (
+  result: t.RagApiRerankResult | undefined,
+  candidateCount: number
+): result is t.RagApiRerankResult =>
+  result != null &&
+  typeof result.index === 'number' &&
+  Number.isInteger(result.index) &&
+  result.index >= 0 &&
+  result.index < candidateCount &&
+  typeof result.score === 'number' &&
+  Number.isFinite(result.score);
+
+/** A repeated index would map one document into several `top_n` slots and
+ * silently drop distinct results, so a duplicate invalidates the batch just
+ * like any other malformed row. Seen indices are tracked in the same pass
+ * that validates each row. */
+const isValidRagApiBatch = (
+  results: t.RagApiRerankResult[],
+  candidateCount: number
+): boolean => {
+  const seenIndices = new Set<number>();
+  return results.every((result) => {
+    if (!isValidRagApiResult(result, candidateCount)) {
+      return false;
+    }
+    if (seenIndices.has(result.index)) {
+      return false;
+    }
+    seenIndices.add(result.index);
+    return true;
+  });
+};
+
+/** Bounds the whole rerank round trip, token acquisition included: the
+ * supplier mints its token over the network, so awaiting it before axios
+ * starts would leave the search unbounded whenever an auth service stalls.
+ * The signal reaches both legs, so returning a fallback also cancels whatever
+ * is still in flight rather than leaving a request running past its caller.
+ * A non-positive timeout keeps axios' "no timeout" semantics. */
+const withRerankDeadline = <T>(
+  operation: (signal?: AbortSignal) => Promise<T>,
+  timeout: number
+): Promise<T> => {
+  if (timeout <= 0) {
+    return operation();
+  }
+
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`rag_api rerank exceeded its ${timeout}ms timeout.`));
+    }, timeout);
+  });
+
+  const pending = operation(controller.signal);
+  pending.catch(() => undefined);
+
+  return Promise.race([pending, deadline]).finally(() => clearTimeout(timer));
+};
+
+/**
+ * Calls the public `danny-avila/rag_api` `/v1/rerank` endpoint (the
+ * `fast-v1` profile). Auth is supplied per call by a token supplier (a
+ * short-lived JWT minted by the host app) rather than a static key. A
+ * reranker failure must never throw into the search flow: on a missing
+ * base URL/token supplier, a timeout (covering token acquisition as well as
+ * the request), a non-2xx response, or any malformed payload, this falls back
+ * to the candidates' original order via {@link BaseReranker.getDefaultRanking}.
+ */
+export class RagApiReranker extends BaseReranker {
+  private baseUrl?: string;
+  private tokenSupplier?: t.RagApiTokenSupplier;
+  private profile: string;
+  private timeout: number;
+  private httpAgent?: t.HttpAgent;
+  private httpsAgent?: t.HttpsAgent;
+
+  constructor({
+    baseUrl = getDefaultRagApiUrl(),
+    tokenSupplier,
+    profile = RAG_API_DEFAULT_PROFILE,
+    timeout = DEFAULT_RERANKER_TIMEOUT,
+    logger,
+    httpAgent,
+    httpsAgent,
+  }: {
+    baseUrl?: string;
+    tokenSupplier?: t.RagApiTokenSupplier;
+    profile?: string;
+    timeout?: number;
+    logger?: t.Logger;
+  } & t.HttpAgentConfig) {
+    super(logger);
+    this.baseUrl = baseUrl?.replace(/\/+$/, '');
+    this.tokenSupplier = tokenSupplier;
+    this.profile = profile;
+    this.timeout = timeout;
+    this.httpAgent = httpAgent;
+    this.httpsAgent = httpsAgent;
+  }
+
+  async rerank(
+    query: string,
+    documents: string[],
+    topK: number = 5
+  ): Promise<t.Highlight[]> {
+    if (documents.length === 0) {
+      return [];
+    }
+
+    this.logger.debug(
+      `Reranking ${documents.length} chunks with rag_api (${this.profile}) using base URL: ${this.baseUrl}`
+    );
+
+    const baseUrl = this.baseUrl;
+    if (baseUrl == null || baseUrl === '') {
+      this.logger.warn('RAG_API_URL is not set. Using default ranking.');
+      return this.getDefaultRanking(documents, topK);
+    }
+
+    const tokenSupplier = this.tokenSupplier;
+    if (tokenSupplier == null) {
+      this.logger.warn(
+        'No rag_api token supplier configured. Using default ranking.'
+      );
+      return this.getDefaultRanking(documents, topK);
+    }
+
+    const candidates = buildRagApiCandidates(documents, this.logger);
+    const topN = clampRagApiTopN(Math.max(0, topK), this.logger);
+    const requestData: t.RagApiRerankRequestBody = {
+      profile: this.profile,
+      query,
+      candidates,
+      top_n: topN,
+    };
+
+    try {
+      const data = await withRerankDeadline(async (signal) => {
+        const token = await tokenSupplier(signal);
+        const response = await axios.post<t.RagApiRerankResponse | undefined>(
+          `${baseUrl}/v1/rerank`,
+          requestData,
+          {
+            headers: {
+              'Content-Type': 'application/json',
+              Authorization: `Bearer ${token}`,
+            },
+            timeout: this.timeout,
+            httpAgent: this.httpAgent,
+            httpsAgent: this.httpsAgent,
+            signal,
+          }
+        );
+        return response.data;
+      }, this.timeout);
+
+      this.logger.debug('rag_api rerank model:', data?.model);
+
+      const rawResults = data?.results;
+      if (!Array.isArray(rawResults) || rawResults.length === 0) {
+        this.logger.warn(
+          'Unexpected response format from rag_api rerank. Using default ranking.'
+        );
+        return this.getDefaultRanking(documents, topK);
+      }
+
+      if (!isValidRagApiBatch(rawResults, candidates.length)) {
+        this.logger.warn(
+          'rag_api rerank response contained no valid results. Using default ranking.'
+        );
+        return this.getDefaultRanking(documents, topK);
+      }
+
+      return sortRagApiResults(rawResults)
+        .slice(0, topN)
+        .map((result) => ({
+          text: documents[result.index],
+          score: result.score,
+        }));
+    } catch (error) {
+      this.logger.error(
+        'Error using rag_api reranker',
+        formatErrorForLog(error)
+      );
+      return this.getDefaultRanking(documents, topK);
+    }
+  }
+}
+
 export class InfinityReranker extends BaseReranker {
   constructor(logger?: t.Logger) {
     super(logger);
@@ -253,6 +497,9 @@ export const createReranker = (
     jinaApiKey?: string;
     jinaApiUrl?: string;
     cohereApiKey?: string;
+    ragApiUrl?: string;
+    ragApiTokenSupplier?: t.RagApiTokenSupplier;
+    ragApiProfile?: string;
     rerankerTimeout?: number;
     logger?: t.Logger;
   } & t.HttpAgentConfig
@@ -262,6 +509,9 @@ export const createReranker = (
     jinaApiKey,
     jinaApiUrl,
     cohereApiKey,
+    ragApiUrl,
+    ragApiTokenSupplier,
+    ragApiProfile,
     rerankerTimeout,
     logger,
     httpAgent,
@@ -289,6 +539,16 @@ export const createReranker = (
       httpAgent,
       httpsAgent,
     });
+  case 'rag-api':
+    return new RagApiReranker({
+      baseUrl: ragApiUrl,
+      tokenSupplier: ragApiTokenSupplier,
+      profile: ragApiProfile,
+      timeout: rerankerTimeout,
+      logger: defaultLogger,
+      httpAgent,
+      httpsAgent,
+    });
   case 'infinity':
     return new InfinityReranker(defaultLogger);
   case 'none':

package/src/tools/search/tool.ts

@@ -452,6 +452,9 @@ export const createSearchTool = (
     jinaApiKey,
     jinaApiUrl,
     cohereApiKey,
+    ragApiUrl,
+    ragApiTokenSupplier,
+    ragApiProfile,
     httpAgent,
     httpsAgent,
     onSearchResults: _onSearchResults,
@@ -571,6 +574,9 @@ export const createSearchTool = (
     jinaApiKey,
     jinaApiUrl,
     cohereApiKey,
+    ragApiUrl,
+    ragApiTokenSupplier,
+    ragApiProfile,
     rerankerTimeout,
     httpAgent,
     httpsAgent,

package/src/tools/search/types.ts

@@ -32,7 +32,7 @@ export type ScraperProvider =
   | 'tavily'
   | 'crw'
   | 'keenable';
-export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
+export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'rag-api' | 'none';
 
 export interface Highlight {
   score: number;
@@ -353,6 +353,41 @@ export interface CohereRerankerResponse {
   };
 }
 
+/** Mints a short-lived JWT per call; rag_api tokens are never cached or
+ * reused across requests by the reranker itself. Receives the rerank
+ * deadline's `AbortSignal` so a supplier minting its token over the network
+ * can cancel that request when the deadline fires instead of leaving it
+ * running past its caller. The argument is optional: zero-argument suppliers
+ * remain valid. */
+export type RagApiTokenSupplier = (
+  signal?: AbortSignal
+) => string | Promise<string>;
+
+export interface RagApiRerankCandidate {
+  id: string;
+  text: string;
+  base_score: number;
+}
+
+export interface RagApiRerankRequestBody {
+  profile: string;
+  query: string;
+  candidates: RagApiRerankCandidate[];
+  top_n: number;
+}
+
+export interface RagApiRerankResult {
+  id: string;
+  index: number;
+  score: number;
+}
+
+export interface RagApiRerankResponse {
+  profile: string;
+  model: string;
+  results: RagApiRerankResult[];
+}
+
 export type SafeSearchLevel = 0 | 1 | 2;
 
 export type Logger = WinstonLogger;
@@ -375,6 +410,15 @@ export interface SearchToolConfig
   jinaApiKey?: string;
   jinaApiUrl?: string;
   cohereApiKey?: string;
+  /** Base URL of the public `rag_api` service (`RAG_API_URL` env fallback).
+   * Requests post to `${ragApiUrl}/v1/rerank`. */
+  ragApiUrl?: string;
+  /** Resolves a short-lived rag_api JWT immediately before each rerank call.
+   * Required for the `'rag-api'` reranker type — without it, reranking falls
+   * back to default (unranked) ordering. */
+  ragApiTokenSupplier?: RagApiTokenSupplier;
+  /** rag_api rerank profile. Defaults to `'fast-v1'`. */
+  ragApiProfile?: string;
   rerankerType?: RerankerType;
   /** Timeout (ms) for rerank API requests. Defaults to 10,000. */
   rerankerTimeout?: number;