@framers/agentos 0.1.6 → 0.1.8

package/dist/rag/reranking/providers/CohereReranker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview Cohere Rerank API provider implementation.
+ * Uses Cohere's cloud-based cross-encoder reranking service.
+ *
+ * @module backend/agentos/rag/reranking/providers/CohereReranker
+ * @see https://docs.cohere.com/reference/rerank
+ */
+import type { IRerankerProvider, RerankerInput, RerankerOutput, RerankerRequestConfig, RerankerProviderConfig } from '../IRerankerService';
+/**
+ * Cohere-specific provider configuration.
+ */
+export interface CohereRerankerConfig extends RerankerProviderConfig {
+    providerId: 'cohere';
+    /** Cohere API key (required) */
+    apiKey: string;
+    /** Base URL for Cohere API. Default: 'https://api.cohere.ai' */
+    baseUrl?: string;
+}
+/**
+ * Available Cohere reranker models.
+ */
+export declare const COHERE_RERANKER_MODELS: readonly ["rerank-english-v3.0", "rerank-multilingual-v3.0", "rerank-english-v2.0", "rerank-multilingual-v2.0"];
+export type CohereRerankerModel = (typeof COHERE_RERANKER_MODELS)[number];
+/**
+ * Cohere Rerank API provider.
+ *
+ * Cloud-based cross-encoder reranking using Cohere's Rerank models.
+ * Provides high-quality relevance scoring with low latency (~100ms for 50 docs).
+ *
+ * **Pricing**: ~$0.10 per 1,000 search queries (as of 2024)
+ *
+ * @example
+ * ```typescript
+ * const reranker = new CohereReranker({
+ *   providerId: 'cohere',
+ *   apiKey: process.env.COHERE_API_KEY!,
+ *   defaultModelId: 'rerank-english-v3.0'
+ * });
+ *
+ * const result = await reranker.rerank(
+ *   { query: 'machine learning', documents: [...] },
+ *   { providerId: 'cohere', modelId: 'rerank-english-v3.0', topN: 5 }
+ * );
+ * ```
+ */
+export declare class CohereReranker implements IRerankerProvider {
+    readonly providerId: "cohere";
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultModelId;
+    private readonly defaultTimeoutMs;
+    constructor(config: CohereRerankerConfig);
+    /**
+     * Check if the Cohere API is accessible.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get supported Cohere reranker models.
+     */
+    getSupportedModels(): string[];
+    /**
+     * Rerank documents using Cohere's Rerank API.
+     */
+    rerank(input: RerankerInput, config: RerankerRequestConfig): Promise<RerankerOutput>;
+}
+//# sourceMappingURL=CohereReranker.d.ts.map

package/dist/rag/reranking/providers/CohereReranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CohereReranker.d.ts","sourceRoot":"","sources":["../../../../src/rag/reranking/providers/CohereReranker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,UAAU,EAAE,QAAQ,CAAC;IACrB,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiBD;;GAEG;AACH,eAAO,MAAM,sBAAsB,iHAKzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,cAAe,YAAW,iBAAiB;IACtD,SAAgB,UAAU,EAAG,QAAQ,CAAU;IAE/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,MAAM,EAAE,oBAAoB;IAQxC;;OAEG;IACU,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAS5C;;OAEG;IACI,kBAAkB,IAAI,MAAM,EAAE;IAIrC;;OAEG;IACU,MAAM,CACjB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC;CAiF3B"}

package/dist/rag/reranking/providers/CohereReranker.js

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Cohere Rerank API provider implementation.
+ * Uses Cohere's cloud-based cross-encoder reranking service.
+ *
+ * @module backend/agentos/rag/reranking/providers/CohereReranker
+ * @see https://docs.cohere.com/reference/rerank
+ */
+/**
+ * Available Cohere reranker models.
+ */
+export const COHERE_RERANKER_MODELS = [
+    'rerank-english-v3.0',
+    'rerank-multilingual-v3.0',
+    'rerank-english-v2.0',
+    'rerank-multilingual-v2.0',
+];
+/**
+ * Cohere Rerank API provider.
+ *
+ * Cloud-based cross-encoder reranking using Cohere's Rerank models.
+ * Provides high-quality relevance scoring with low latency (~100ms for 50 docs).
+ *
+ * **Pricing**: ~$0.10 per 1,000 search queries (as of 2024)
+ *
+ * @example
+ * ```typescript
+ * const reranker = new CohereReranker({
+ *   providerId: 'cohere',
+ *   apiKey: process.env.COHERE_API_KEY!,
+ *   defaultModelId: 'rerank-english-v3.0'
+ * });
+ *
+ * const result = await reranker.rerank(
+ *   { query: 'machine learning', documents: [...] },
+ *   { providerId: 'cohere', modelId: 'rerank-english-v3.0', topN: 5 }
+ * );
+ * ```
+ */
+export class CohereReranker {
+    constructor(config) {
+        this.providerId = 'cohere';
+        // Allow empty apiKey for graceful isAvailable() checks
+        this.apiKey = config.apiKey || '';
+        this.baseUrl = config.baseUrl ?? 'https://api.cohere.ai';
+        this.defaultModelId = config.defaultModelId ?? 'rerank-english-v3.0';
+        this.defaultTimeoutMs = config.defaultTimeoutMs ?? 30000;
+    }
+    /**
+     * Check if the Cohere API is accessible.
+     */
+    async isAvailable() {
+        try {
+            // Simple check - verify API key format
+            return this.apiKey.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get supported Cohere reranker models.
+     */
+    getSupportedModels() {
+        return [...COHERE_RERANKER_MODELS];
+    }
+    /**
+     * Rerank documents using Cohere's Rerank API.
+     */
+    async rerank(input, config) {
+        if (!this.apiKey) {
+            throw new Error('CohereReranker: apiKey is required for reranking');
+        }
+        const modelId = config.modelId || this.defaultModelId;
+        const timeoutMs = config.timeoutMs ?? this.defaultTimeoutMs;
+        const startTime = Date.now();
+        // Prepare request body
+        const requestBody = {
+            model: modelId,
+            query: input.query,
+            documents: input.documents.map((d) => d.content),
+            top_n: config.topN ?? input.documents.length,
+            return_documents: false,
+            ...config.params,
+        };
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}/v1/rerank`, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'X-Client-Name': 'agentos',
+                },
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Cohere API error (${response.status}): ${errorText}`);
+            }
+            const data = await response.json();
+            const latencyMs = Date.now() - startTime;
+            // Map results back to documents (Cohere returns indices)
+            const results = data.results.map((r) => {
+                const doc = input.documents[r.index];
+                return {
+                    id: doc.id,
+                    content: doc.content,
+                    relevanceScore: r.relevance_score,
+                    originalScore: doc.originalScore,
+                    metadata: doc.metadata,
+                };
+            });
+            return {
+                results,
+                diagnostics: {
+                    modelId,
+                    providerId: this.providerId,
+                    latencyMs,
+                    documentsProcessed: input.documents.length,
+                    tokensUsed: data.meta?.billed_units?.search_units,
+                    providerMetrics: {
+                        cohereRequestId: data.id,
+                        apiVersion: data.meta?.api_version?.version,
+                    },
+                },
+            };
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`CohereReranker: Request timed out after ${timeoutMs}ms`);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=CohereReranker.js.map

package/dist/rag/reranking/providers/CohereReranker.js.map

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

package/dist/rag/reranking/providers/LocalCrossEncoderReranker.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Local cross-encoder reranker using transformers.js or ONNX runtime.
+ * Runs reranking models locally without external API calls.
+ *
+ * @module backend/agentos/rag/reranking/providers/LocalCrossEncoderReranker
+ */
+import type { IRerankerProvider, RerankerInput, RerankerOutput, RerankerRequestConfig, RerankerProviderConfig } from '../IRerankerService';
+/**
+ * Local reranker configuration.
+ */
+export interface LocalCrossEncoderConfig extends RerankerProviderConfig {
+    providerId: 'local';
+    /**
+     * Model ID from Hugging Face Hub.
+     * Default: 'cross-encoder/ms-marco-MiniLM-L-6-v2'
+     */
+    defaultModelId?: string;
+    /**
+     * Device to run inference on.
+     * - 'cpu': Use CPU (default, most compatible)
+     * - 'gpu': Use GPU if available (requires CUDA/WebGPU)
+     * - 'auto': Automatically select best available
+     */
+    device?: 'cpu' | 'gpu' | 'auto';
+    /**
+     * Maximum sequence length for the model.
+     * Default: 512
+     */
+    maxSequenceLength?: number;
+    /**
+     * Batch size for inference.
+     * Default: 32
+     */
+    batchSize?: number;
+    /**
+     * Path to cache downloaded models.
+     * Default: system cache directory
+     */
+    cacheDir?: string;
+}
+/**
+ * Available local cross-encoder models (Hugging Face model IDs).
+ */
+export declare const LOCAL_RERANKER_MODELS: readonly ["cross-encoder/ms-marco-MiniLM-L-6-v2", "cross-encoder/ms-marco-MiniLM-L-12-v2", "BAAI/bge-reranker-base", "BAAI/bge-reranker-large", "sentence-transformers/ce-ms-marco-TinyBERT-L-4"];
+export type LocalRerankerModel = (typeof LOCAL_RERANKER_MODELS)[number];
+/**
+ * Local cross-encoder reranker.
+ *
+ * Runs cross-encoder models locally using transformers.js for Node.js/browser
+ * or ONNX runtime. No API calls, fully offline capable.
+ *
+ * **Performance**: ~200-500ms for 50 documents on CPU (varies by model/hardware)
+ *
+ * **Note**: First run downloads the model (~100-500MB depending on model).
+ * Subsequent runs use cached model.
+ *
+ * @example
+ * ```typescript
+ * const reranker = new LocalCrossEncoderReranker({
+ *   providerId: 'local',
+ *   defaultModelId: 'cross-encoder/ms-marco-MiniLM-L-6-v2',
+ *   device: 'cpu',
+ *   batchSize: 32
+ * });
+ *
+ * await reranker.initialize(); // Downloads model if not cached
+ *
+ * const result = await reranker.rerank(
+ *   { query: 'machine learning', documents: [...] },
+ *   { providerId: 'local', modelId: 'cross-encoder/ms-marco-MiniLM-L-6-v2' }
+ * );
+ * ```
+ */
+export declare class LocalCrossEncoderReranker implements IRerankerProvider {
+    readonly providerId: "local";
+    private readonly config;
+    private pipeline;
+    private isInitialized;
+    private initializationPromise;
+    constructor(config: LocalCrossEncoderConfig);
+    /**
+     * Initialize the model pipeline.
+     * Call this before first use or let rerank() handle lazy initialization.
+     */
+    initialize(modelId?: string): Promise<void>;
+    private _doInitialize;
+    /**
+     * Check if the local reranker is available.
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get supported local reranker models.
+     */
+    getSupportedModels(): string[];
+    /**
+     * Rerank documents using a local cross-encoder model.
+     */
+    rerank(input: RerankerInput, config: RerankerRequestConfig): Promise<RerankerOutput>;
+    /**
+     * Unload the model from memory.
+     * Call this when you're done with the reranker to free resources.
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=LocalCrossEncoderReranker.d.ts.map

package/dist/rag/reranking/providers/LocalCrossEncoderReranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalCrossEncoderReranker.d.ts","sourceRoot":"","sources":["../../../../src/rag/reranking/providers/LocalCrossEncoderReranker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAChC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,mMAMxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,yBAA0B,YAAW,iBAAiB;IACjE,SAAgB,UAAU,EAAG,OAAO,CAAU;IAE9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,qBAAqB,CAA8B;gBAE/C,MAAM,EAAE,uBAAuB;IAU3C;;;OAGG;IACU,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAgB1C,aAAa;IAkC3B;;OAEG;IACU,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAU5C;;OAEG;IACI,kBAAkB,IAAI,MAAM,EAAE;IAIrC;;OAEG;IACU,MAAM,CACjB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC;IAwF1B;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAOtC"}

package/dist/rag/reranking/providers/LocalCrossEncoderReranker.js

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview Local cross-encoder reranker using transformers.js or ONNX runtime.
+ * Runs reranking models locally without external API calls.
+ *
+ * @module backend/agentos/rag/reranking/providers/LocalCrossEncoderReranker
+ */
+/**
+ * Available local cross-encoder models (Hugging Face model IDs).
+ */
+export const LOCAL_RERANKER_MODELS = [
+    'cross-encoder/ms-marco-MiniLM-L-6-v2', // Fast, good quality
+    'cross-encoder/ms-marco-MiniLM-L-12-v2', // Better quality, slower
+    'BAAI/bge-reranker-base', // BGE reranker (smaller)
+    'BAAI/bge-reranker-large', // BGE reranker (larger, better)
+    'sentence-transformers/ce-ms-marco-TinyBERT-L-4', // Tiny, fastest
+];
+/**
+ * Local cross-encoder reranker.
+ *
+ * Runs cross-encoder models locally using transformers.js for Node.js/browser
+ * or ONNX runtime. No API calls, fully offline capable.
+ *
+ * **Performance**: ~200-500ms for 50 documents on CPU (varies by model/hardware)
+ *
+ * **Note**: First run downloads the model (~100-500MB depending on model).
+ * Subsequent runs use cached model.
+ *
+ * @example
+ * ```typescript
+ * const reranker = new LocalCrossEncoderReranker({
+ *   providerId: 'local',
+ *   defaultModelId: 'cross-encoder/ms-marco-MiniLM-L-6-v2',
+ *   device: 'cpu',
+ *   batchSize: 32
+ * });
+ *
+ * await reranker.initialize(); // Downloads model if not cached
+ *
+ * const result = await reranker.rerank(
+ *   { query: 'machine learning', documents: [...] },
+ *   { providerId: 'local', modelId: 'cross-encoder/ms-marco-MiniLM-L-6-v2' }
+ * );
+ * ```
+ */
+export class LocalCrossEncoderReranker {
+    constructor(config) {
+        this.providerId = 'local';
+        this.pipeline = null;
+        this.isInitialized = false;
+        this.initializationPromise = null;
+        this.config = {
+            ...config,
+            defaultModelId: config.defaultModelId ?? 'cross-encoder/ms-marco-MiniLM-L-6-v2',
+            device: config.device ?? 'cpu',
+            maxSequenceLength: config.maxSequenceLength ?? 512,
+            batchSize: config.batchSize ?? 32,
+        };
+    }
+    /**
+     * Initialize the model pipeline.
+     * Call this before first use or let rerank() handle lazy initialization.
+     */
+    async initialize(modelId) {
+        if (this.isInitialized && !modelId) {
+            return;
+        }
+        // Prevent multiple concurrent initializations
+        if (this.initializationPromise) {
+            await this.initializationPromise;
+            return;
+        }
+        this.initializationPromise = this._doInitialize(modelId ?? this.config.defaultModelId);
+        await this.initializationPromise;
+        this.initializationPromise = null;
+    }
+    async _doInitialize(modelId) {
+        try {
+            // Dynamic import to avoid bundling issues and allow optional dependency
+            const { pipeline, env } = await import('@xenova/transformers');
+            // Configure cache directory if specified
+            if (this.config.cacheDir) {
+                env.cacheDir = this.config.cacheDir;
+            }
+            // Configure device
+            if (this.config.device === 'gpu') {
+                env.backends.onnx.wasm.numThreads = 1; // Use GPU
+            }
+            // Load the cross-encoder pipeline
+            // For cross-encoders, we use 'text-classification' pipeline
+            // since they output a relevance score
+            this.pipeline = await pipeline('text-classification', modelId, {
+                quantized: true, // Use quantized model for faster inference
+            });
+            this.isInitialized = true;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Cannot find module')) {
+                throw new Error('LocalCrossEncoderReranker: @xenova/transformers is not installed. ' +
+                    'Install it with: pnpm add @xenova/transformers');
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if the local reranker is available.
+     */
+    async isAvailable() {
+        try {
+            // Check if transformers.js is available
+            await import('@xenova/transformers');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get supported local reranker models.
+     */
+    getSupportedModels() {
+        return [...LOCAL_RERANKER_MODELS];
+    }
+    /**
+     * Rerank documents using a local cross-encoder model.
+     */
+    async rerank(input, config) {
+        const modelId = config.modelId || this.config.defaultModelId;
+        const startTime = Date.now();
+        // Lazy initialization
+        if (!this.isInitialized) {
+            await this.initialize(modelId);
+        }
+        // Cross-encoders take query-document pairs and output relevance scores
+        // Format: "query [SEP] document" or as separate inputs depending on model
+        const pairs = input.documents.map((doc) => ({
+            text: input.query,
+            text_pair: doc.content,
+        }));
+        // Process in batches
+        const batchSize = this.config.batchSize;
+        const scores = [];
+        for (let i = 0; i < pairs.length; i += batchSize) {
+            const batch = pairs.slice(i, i + batchSize);
+            // Run inference
+            // Most cross-encoders output a single score (or logits that we convert to score)
+            for (const pair of batch) {
+                try {
+                    // transformers.js text-classification returns array of {label, score}
+                    // For cross-encoders, we typically want the positive class score
+                    const result = await this.pipeline(`${pair.text} [SEP] ${pair.text_pair}`, {
+                        truncation: true,
+                        max_length: this.config.maxSequenceLength,
+                    });
+                    // Handle different output formats
+                    let score;
+                    if (Array.isArray(result) && result.length > 0) {
+                        // Standard text-classification output
+                        // For binary classifiers: find LABEL_1 or positive class
+                        const positiveResult = result.find((r) => r.label === 'LABEL_1' || r.label === 'POSITIVE' || r.label === '1');
+                        score = positiveResult?.score ?? result[0].score;
+                    }
+                    else if (typeof result === 'number') {
+                        score = result;
+                    }
+                    else {
+                        score = 0;
+                    }
+                    scores.push(score);
+                }
+                catch (error) {
+                    console.warn(`LocalCrossEncoderReranker: Error scoring document, using 0:`, error);
+                    scores.push(0);
+                }
+            }
+        }
+        const latencyMs = Date.now() - startTime;
+        // Combine scores with documents and sort by score descending
+        const scoredDocs = input.documents.map((doc, idx) => ({
+            id: doc.id,
+            content: doc.content,
+            relevanceScore: scores[idx],
+            originalScore: doc.originalScore,
+            metadata: doc.metadata,
+        }));
+        scoredDocs.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        // Apply topN if specified
+        const results = config.topN ? scoredDocs.slice(0, config.topN) : scoredDocs;
+        return {
+            results,
+            diagnostics: {
+                modelId,
+                providerId: this.providerId,
+                latencyMs,
+                documentsProcessed: input.documents.length,
+                providerMetrics: {
+                    batchSize: this.config.batchSize,
+                    device: this.config.device,
+                },
+            },
+        };
+    }
+    /**
+     * Unload the model from memory.
+     * Call this when you're done with the reranker to free resources.
+     */
+    async dispose() {
+        if (this.pipeline && typeof this.pipeline.dispose === 'function') {
+            await this.pipeline.dispose();
+        }
+        this.pipeline = null;
+        this.isInitialized = false;
+    }
+}
+//# sourceMappingURL=LocalCrossEncoderReranker.js.map

package/dist/rag/reranking/providers/LocalCrossEncoderReranker.js.map

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

package/dist/rag/reranking/providers/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Reranker provider implementations.
+ * @module backend/agentos/rag/reranking/providers
+ */
+export { CohereReranker, type CohereRerankerConfig, COHERE_RERANKER_MODELS, type CohereRerankerModel } from './CohereReranker';
+export { LocalCrossEncoderReranker, type LocalCrossEncoderConfig, LOCAL_RERANKER_MODELS, type LocalRerankerModel } from './LocalCrossEncoderReranker';
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/reranking/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/rag/reranking/providers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC/H,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/rag/reranking/providers/index.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Reranker provider implementations.
+ * @module backend/agentos/rag/reranking/providers
+ */
+export { CohereReranker, COHERE_RERANKER_MODELS } from './CohereReranker.js';
+export { LocalCrossEncoderReranker, LOCAL_RERANKER_MODELS } from './LocalCrossEncoderReranker.js';
+//# sourceMappingURL=index.js.map

package/dist/rag/reranking/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/rag/reranking/providers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAA6B,sBAAsB,EAA4B,MAAM,kBAAkB,CAAC;AAC/H,OAAO,EAAE,yBAAyB,EAAgC,qBAAqB,EAA2B,MAAM,6BAA6B,CAAC"}

package/dist/rag/reranking/tests/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Reranking module test suite index
+ * @module backend/agentos/rag/reranking/tests
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/reranking/tests/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/rag/reranking/tests/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC"}

package/dist/rag/reranking/tests/index.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Reranking module test suite index
+ * @module backend/agentos/rag/reranking/tests
+ */
+export {};
+// Test utilities and fixtures for reranking tests
+// Import individual test files to run the suite:
+// - RerankerService.test.ts
+// - CohereReranker.test.ts
+// - LocalCrossEncoderReranker.test.ts
+//# sourceMappingURL=index.js.map

package/dist/rag/reranking/tests/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/rag/reranking/tests/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAIH,kDAAkD;AAClD,iDAAiD;AACjD,4BAA4B;AAC5B,2BAA2B;AAC3B,sCAAsC"}

package/dist/types/optionalDependencies.d.ts

@@ -0,0 +1,5 @@
+declare module '@xenova/transformers' {
+    const env: any;
+    const pipeline: any;
+}
+//# sourceMappingURL=optionalDependencies.d.ts.map

package/dist/types/optionalDependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionalDependencies.d.ts","sourceRoot":"","sources":["../../src/types/optionalDependencies.ts"],"names":[],"mappings":"AAGA,OAAO,QAAQ,sBAAsB,CAAC;IAE7B,MAAM,GAAG,EAAE,GAAG,CAAC;IACf,MAAM,QAAQ,EAAE,GAAG,CAAC;CAC5B"}

package/dist/types/optionalDependencies.js

@@ -0,0 +1,4 @@
+"use strict";
+// Optional dependency shims for TypeScript builds.
+// These modules are loaded dynamically at runtime when installed.
+//# sourceMappingURL=optionalDependencies.js.map

package/dist/types/optionalDependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optionalDependencies.js","sourceRoot":"","sources":["../../src/types/optionalDependencies.ts"],"names":[],"mappings":";AAAA,mDAAmD;AACnD,kEAAkE"}