rag-lite-ts 1.0.1 → 1.0.2

package/dist/core/interfaces.d.ts

@@ -0,0 +1,408 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ *
+ * This module defines the core interfaces for dependency injection in the search engine.
+ * These interfaces enable:
+ * 1. Different embedding implementations (text-only, multimodal, etc.)
+ * 2. Different reranking strategies (cross-encoder, neural, etc.)
+ * 3. Support for multiple content types (text, image, etc.)
+ * 4. Different embedding dimensions (384, 512, 768, etc.)
+ *
+ * DEPENDENCY INJECTION PATTERNS:
+ *
+ * 1. Direct Function Injection (Advanced Users):
+ * ```typescript
+ * // Text-only implementation
+ * const textEmbedFn: EmbedFunction = async (query) => textEmbedder.embedSingle(query);
+ * const textRerankFn: RerankFunction = async (query, results) => textReranker.rerank(query, results);
+ * const search = new SearchEngine(textEmbedFn, indexManager, db, textRerankFn);
+ *
+ * // Custom implementation
+ * const customEmbedFn: EmbedFunction = async (query) => ({
+ *   embedding_id: generateId(),
+ *   vector: await myCustomModel.embed(query)
+ * });
+ * const search = new SearchEngine(customEmbedFn, indexManager, db);
+ * ```
+ *
+ * 2. Factory Pattern (Recommended for Common Use Cases):
+ * ```typescript
+ * // Using factory for convenience
+ * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', {
+ *   embeddingModel: 'all-MiniLM-L6-v2',
+ *   enableReranking: true
+ * });
+ *
+ * // Factory with custom configuration
+ * const ingestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', {
+ *   chunkSize: 300,
+ *   chunkOverlap: 50
+ * });
+ * ```
+ *
+ * 3. Interface-Based Implementation (Plugin Architecture):
+ * ```typescript
+ * // Implement interfaces for custom behavior
+ * class CustomEmbeddingInterface implements EmbeddingQueryInterface {
+ *   async embedQuery(query: string): Promise<EmbeddingResult> {
+ *     return { embedding_id: generateId(), vector: await this.model.embed(query) };
+ *   }
+ *   supportedContentTypes = ['text', 'code'];
+ *   embeddingDimensions = 384;
+ *   modelIdentifier = 'custom-model-v1';
+ * }
+ *
+ * const customInterface = new CustomEmbeddingInterface();
+ * const embedFn = customInterface.embedQuery.bind(customInterface);
+ * const search = new SearchEngine(embedFn, indexManager, db);
+ * ```
+ *
+ * 4. Multimodal Implementation (Future):
+ * ```typescript
+ * // Multimodal embedding function
+ * const multimodalEmbedFn: EmbedFunction = async (query, contentType) => {
+ *   if (contentType === 'image') return clipEmbedder.embedImage(query);
+ *   return clipEmbedder.embedText(query);
+ * };
+ *
+ * // Multimodal reranking function
+ * const multimodalRerankFn: RerankFunction = async (query, results, contentType) => {
+ *   return multimodalReranker.rerank(query, results, contentType);
+ * };
+ *
+ * const search = new SearchEngine(multimodalEmbedFn, indexManager, db, multimodalRerankFn);
+ * ```
+ */
+import type { SearchResult, EmbeddingResult } from './types.js';
+/**
+ * Core embedding function interface for dependency injection
+ * Supports different content types and embedding dimensions (384, 512, 768, etc.)
+ */
+export type EmbedFunction = (query: string, contentType?: string) => Promise<EmbeddingResult>;
+/**
+ * Core reranking function interface for dependency injection
+ * Supports different content types and query-result pairs
+ */
+export type RerankFunction = (query: string, results: SearchResult[], contentType?: string) => Promise<SearchResult[]>;
+/**
+ * Interface for embedding query operations
+ * Enables dependency injection of different embedding implementations
+ *
+ * This interface provides a standardized way to interact with different
+ * embedding models while maintaining compatibility checking and metadata.
+ * Implementations can be text-only, multimodal, or custom models.
+ *
+ * @example
+ * ```typescript
+ * // Text embedding implementation
+ * class TextEmbeddingInterface implements EmbeddingQueryInterface {
+ *   embedQuery = async (query: string) => textEmbedder.embedSingle(query);
+ *   supportedContentTypes = ['text', 'code'];
+ *   embeddingDimensions = 384;
+ *   modelIdentifier = 'all-MiniLM-L6-v2';
+ * }
+ *
+ * // Use with SearchEngine
+ * const embeddingInterface = new TextEmbeddingInterface();
+ * const embedFn = embeddingInterface.embedQuery.bind(embeddingInterface);
+ * const search = new SearchEngine(embedFn, indexManager, db);
+ * ```
+ */
+export interface EmbeddingQueryInterface {
+    /**
+     * Function to embed a query string into a vector
+     * Should handle the specific content types listed in supportedContentTypes
+     */
+    embedQuery: EmbedFunction;
+    /**
+     * Content types this embedder supports (e.g., ['text'], ['text', 'image'])
+     * Used for validation and routing of different content types
+     */
+    supportedContentTypes: string[];
+    /**
+     * Dimensions of the embedding vectors this embedder produces
+     * Must match the vector index dimensions for compatibility
+     */
+    embeddingDimensions: number;
+    /**
+     * Model name or identifier for compatibility checking
+     * Used to ensure consistent model usage across sessions
+     */
+    modelIdentifier: string;
+}
+/**
+ * Interface for reranking operations
+ * Enables dependency injection of different reranking implementations
+ *
+ * This interface provides a standardized way to interact with different
+ * reranking models. Reranking improves search quality by re-scoring
+ * initial search results using more sophisticated models.
+ *
+ * @example
+ * ```typescript
+ * // Text reranking implementation
+ * class TextRerankingInterface implements RerankingInterface {
+ *   rerankResults = async (query: string, results: SearchResult[]) =>
+ *     textReranker.rerank(query, results);
+ *   supportedContentTypes = ['text'];
+ *   isEnabled = true;
+ *   modelIdentifier = 'cross-encoder/ms-marco-MiniLM-L-6-v2';
+ * }
+ *
+ * // Use with SearchEngine
+ * const rerankingInterface = new TextRerankingInterface();
+ * const rerankFn = rerankingInterface.rerankResults.bind(rerankingInterface);
+ * const search = new SearchEngine(embedFn, indexManager, db, rerankFn);
+ * ```
+ */
+export interface RerankingInterface {
+    /**
+     * Function to rerank search results
+     * Takes a query and initial results, returns reordered results with updated scores
+     */
+    rerankResults: RerankFunction;
+    /**
+     * Content types this reranker supports
+     * Should match or be a subset of the embedding interface content types
+     */
+    supportedContentTypes: string[];
+    /**
+     * Whether reranking is currently enabled and available
+     * Can be used to gracefully disable reranking if models fail to load
+     */
+    isEnabled: boolean;
+    /**
+     * Model name or identifier for the reranking model
+     * Used for logging and compatibility tracking
+     */
+    modelIdentifier: string;
+}
+/**
+ * Configuration interface for search engine dependency injection
+ * Allows different implementations to be plugged in with optional settings
+ *
+ * This interface provides a way to configure SearchEngine instances with
+ * different embedding and reranking implementations, along with default
+ * behaviors for content type handling and initialization.
+ *
+ * @example
+ * ```typescript
+ * // Configuration with custom interfaces
+ * const config: SearchEngineConfig = {
+ *   embeddingInterface: new CustomEmbeddingInterface(),
+ *   rerankingInterface: new CustomRerankingInterface(),
+ *   defaultContentType: 'text',
+ *   autoInitialize: true
+ * };
+ *
+ * // Use configuration (implementation-specific)
+ * const search = new ConfigurableSearchEngine(config);
+ * ```
+ */
+export interface SearchEngineConfig {
+    /**
+     * Optional embedding interface for dependency injection
+     * If provided, will be used instead of direct function injection
+     */
+    embeddingInterface?: EmbeddingQueryInterface;
+    /**
+     * Optional reranking interface for dependency injection
+     * If provided, will be used for result reranking
+     */
+    rerankingInterface?: RerankingInterface;
+    /**
+     * Default content type for queries when not specified
+     * Used when content type cannot be inferred from context
+     */
+    defaultContentType?: string;
+    /**
+     * Whether to enable automatic initialization
+     * When true, models and resources are loaded lazily on first use
+     */
+    autoInitialize?: boolean;
+}
+/**
+ * Interface for content type strategies
+ * Enables different handling for different content types
+ */
+export interface ContentTypeStrategy {
+    /**
+     * Content type this strategy handles
+     */
+    contentType: string;
+    /**
+     * Whether this strategy can handle the given content type
+     */
+    canHandle(contentType: string): boolean;
+    /**
+     * Process query for this content type before embedding
+     */
+    preprocessQuery?(query: string): string;
+    /**
+     * Post-process search results for this content type
+     */
+    postprocessResults?(results: SearchResult[]): SearchResult[];
+}
+/**
+ * Generic interface for model-agnostic operations
+ * Base interface that all model-specific implementations should extend
+ */
+export interface ModelAgnosticInterface {
+    /**
+     * Initialize the interface (load models, set up resources, etc.)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Clean up resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Check if the interface is ready for use
+     */
+    isReady(): boolean;
+    /**
+     * Get interface metadata
+     */
+    getMetadata(): {
+        name: string;
+        version: string;
+        supportedContentTypes: string[];
+    };
+}
+/**
+ * Extended embedding interface that includes model-agnostic operations
+ */
+export interface ExtendedEmbeddingInterface extends EmbeddingQueryInterface, ModelAgnosticInterface {
+    /**
+     * Batch embed multiple queries for efficiency
+     */
+    embedBatch?(queries: string[], contentType?: string): Promise<EmbeddingResult[]>;
+}
+/**
+ * Extended reranking interface that includes model-agnostic operations
+ */
+export interface ExtendedRerankingInterface extends RerankingInterface, ModelAgnosticInterface {
+    /**
+     * Batch rerank multiple query-result pairs for efficiency
+     */
+    rerankBatch?(queries: string[], resultSets: SearchResult[][], contentType?: string): Promise<SearchResult[][]>;
+}
+/**
+ * Interface for search pipeline coordination
+ * Defines the core search pipeline steps that are model-agnostic
+ */
+export interface SearchPipelineInterface {
+    /**
+     * Step 1: Process and embed the query
+     */
+    embedQuery(query: string, contentType?: string): Promise<EmbeddingResult>;
+    /**
+     * Step 2: Perform vector search
+     */
+    vectorSearch(queryVector: Float32Array, topK: number): Promise<{
+        embeddingIds: string[];
+        distances: number[];
+    }>;
+    /**
+     * Step 3: Retrieve metadata from database
+     */
+    retrieveMetadata(embeddingIds: string[]): Promise<any[]>;
+    /**
+     * Step 4: Format initial results
+     */
+    formatResults(chunks: any[], distances: number[], embeddingIds: string[]): SearchResult[];
+    /**
+     * Step 5: Optional reranking
+     */
+    rerankResults?(query: string, results: SearchResult[], contentType?: string): Promise<SearchResult[]>;
+}
+/**
+ * Factory interface for creating embedding and reranking functions
+ * Enables clean dependency injection patterns and simplifies common use cases
+ *
+ * FACTORY PATTERN BENEFITS:
+ * - Handles complex initialization logic (model loading, configuration)
+ * - Provides simple API for common use cases
+ * - Maintains access to underlying dependency injection architecture
+ * - Supports different content types and embedding models
+ *
+ * USAGE EXAMPLES:
+ * ```typescript
+ * // Text factory implementation
+ * class TextSearchDependencyFactory implements SearchDependencyFactory {
+ *   createEmbedFunction(contentType = 'text'): EmbedFunction {
+ *     const embedder = new TextEmbeddingEngine();
+ *     return async (query) => embedder.embedSingle(query);
+ *   }
+ *
+ *   createRerankFunction(contentType = 'text'): RerankFunction {
+ *     const reranker = new CrossEncoderReranker();
+ *     return async (query, results) => reranker.rerank(query, results);
+ *   }
+ * }
+ *
+ * // Factory usage in practice
+ * const factory = new TextSearchDependencyFactory();
+ * const embedFn = factory.createEmbedFunction();
+ * const rerankFn = factory.createRerankFunction();
+ * const search = new SearchEngine(embedFn, indexManager, db, rerankFn);
+ *
+ * // Multimodal factory (future)
+ * class MultimodalSearchDependencyFactory implements SearchDependencyFactory {
+ *   createEmbedFunction(contentType = 'text'): EmbedFunction {
+ *     const clipModel = new CLIPEmbeddingEngine();
+ *     return async (query, type) => {
+ *       if (type === 'image') return clipModel.embedImage(query);
+ *       return clipModel.embedText(query);
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface SearchDependencyFactory {
+    /**
+     * Create an embedding function for the specified content type
+     * @param contentType - Content type to create embedder for ('text', 'image', etc.)
+     * @returns EmbedFunction that can handle the specified content type
+     */
+    createEmbedFunction(contentType?: string): EmbedFunction;
+    /**
+     * Create a reranking function for the specified content type
+     * @param contentType - Content type to create reranker for ('text', 'image', etc.)
+     * @returns RerankFunction for the content type, or undefined if not supported
+     */
+    createRerankFunction(contentType?: string): RerankFunction | undefined;
+    /**
+     * Get supported content types for this factory
+     * @returns Array of supported content type strings
+     */
+    getSupportedContentTypes(): string[];
+    /**
+     * Get embedding dimensions for compatibility checking
+     * @returns Number of dimensions in embedding vectors produced by this factory
+     */
+    getEmbeddingDimensions(): number;
+}
+/**
+ * Validation utilities for interface compatibility
+ */
+export declare class InterfaceValidator {
+    /**
+     * Validate that an EmbedFunction is compatible with expected interface
+     */
+    static validateEmbedFunction(embedFn: EmbedFunction): boolean;
+    /**
+     * Validate that a RerankFunction is compatible with expected interface
+     */
+    static validateRerankFunction(rerankFn: RerankFunction): boolean;
+    /**
+     * Validate embedding dimensions compatibility
+     */
+    static validateEmbeddingDimensions(expected: number, actual: number): boolean;
+    /**
+     * Validate content type support
+     */
+    static validateContentTypeSupport(supportedTypes: string[], requestedType: string): boolean;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/core/interfaces.d.ts.map

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

package/dist/core/interfaces.js

@@ -0,0 +1,106 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ *
+ * This module defines the core interfaces for dependency injection in the search engine.
+ * These interfaces enable:
+ * 1. Different embedding implementations (text-only, multimodal, etc.)
+ * 2. Different reranking strategies (cross-encoder, neural, etc.)
+ * 3. Support for multiple content types (text, image, etc.)
+ * 4. Different embedding dimensions (384, 512, 768, etc.)
+ *
+ * DEPENDENCY INJECTION PATTERNS:
+ *
+ * 1. Direct Function Injection (Advanced Users):
+ * ```typescript
+ * // Text-only implementation
+ * const textEmbedFn: EmbedFunction = async (query) => textEmbedder.embedSingle(query);
+ * const textRerankFn: RerankFunction = async (query, results) => textReranker.rerank(query, results);
+ * const search = new SearchEngine(textEmbedFn, indexManager, db, textRerankFn);
+ *
+ * // Custom implementation
+ * const customEmbedFn: EmbedFunction = async (query) => ({
+ *   embedding_id: generateId(),
+ *   vector: await myCustomModel.embed(query)
+ * });
+ * const search = new SearchEngine(customEmbedFn, indexManager, db);
+ * ```
+ *
+ * 2. Factory Pattern (Recommended for Common Use Cases):
+ * ```typescript
+ * // Using factory for convenience
+ * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', {
+ *   embeddingModel: 'all-MiniLM-L6-v2',
+ *   enableReranking: true
+ * });
+ *
+ * // Factory with custom configuration
+ * const ingestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', {
+ *   chunkSize: 300,
+ *   chunkOverlap: 50
+ * });
+ * ```
+ *
+ * 3. Interface-Based Implementation (Plugin Architecture):
+ * ```typescript
+ * // Implement interfaces for custom behavior
+ * class CustomEmbeddingInterface implements EmbeddingQueryInterface {
+ *   async embedQuery(query: string): Promise<EmbeddingResult> {
+ *     return { embedding_id: generateId(), vector: await this.model.embed(query) };
+ *   }
+ *   supportedContentTypes = ['text', 'code'];
+ *   embeddingDimensions = 384;
+ *   modelIdentifier = 'custom-model-v1';
+ * }
+ *
+ * const customInterface = new CustomEmbeddingInterface();
+ * const embedFn = customInterface.embedQuery.bind(customInterface);
+ * const search = new SearchEngine(embedFn, indexManager, db);
+ * ```
+ *
+ * 4. Multimodal Implementation (Future):
+ * ```typescript
+ * // Multimodal embedding function
+ * const multimodalEmbedFn: EmbedFunction = async (query, contentType) => {
+ *   if (contentType === 'image') return clipEmbedder.embedImage(query);
+ *   return clipEmbedder.embedText(query);
+ * };
+ *
+ * // Multimodal reranking function
+ * const multimodalRerankFn: RerankFunction = async (query, results, contentType) => {
+ *   return multimodalReranker.rerank(query, results, contentType);
+ * };
+ *
+ * const search = new SearchEngine(multimodalEmbedFn, indexManager, db, multimodalRerankFn);
+ * ```
+ */
+/**
+ * Validation utilities for interface compatibility
+ */
+export class InterfaceValidator {
+    /**
+     * Validate that an EmbedFunction is compatible with expected interface
+     */
+    static validateEmbedFunction(embedFn) {
+        return typeof embedFn === 'function';
+    }
+    /**
+     * Validate that a RerankFunction is compatible with expected interface
+     */
+    static validateRerankFunction(rerankFn) {
+        return typeof rerankFn === 'function';
+    }
+    /**
+     * Validate embedding dimensions compatibility
+     */
+    static validateEmbeddingDimensions(expected, actual) {
+        return expected === actual;
+    }
+    /**
+     * Validate content type support
+     */
+    static validateContentTypeSupport(supportedTypes, requestedType) {
+        return supportedTypes.includes(requestedType);
+    }
+}
+//# sourceMappingURL=interfaces.js.map

package/dist/core/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../src/core/interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAkWH;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC7B;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,OAAsB;QACjD,OAAO,OAAO,OAAO,KAAK,UAAU,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAwB;QACpD,OAAO,OAAO,QAAQ,KAAK,UAAU,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,2BAA2B,CAChC,QAAgB,EAChB,MAAc;QAEd,OAAO,QAAQ,KAAK,MAAM,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,0BAA0B,CAC/B,cAAwB,EACxB,aAAqB;QAErB,OAAO,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAChD,CAAC;CACF"}

package/dist/{path-manager.d.ts → core/path-manager.d.ts}

@@ -1,5 +1,10 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ */
 /**
  * Manages document path storage and resolution strategies
+ * Model-agnostic - works with any content type (text, image, etc.)
  */
 export declare class DocumentPathManager {
     private strategy;

package/dist/core/path-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-manager.d.ts","sourceRoot":"","sources":["../../src/core/path-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;GAGG;AACH,qBAAa,mBAAmB;IAExB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ;gBADR,QAAQ,EAAE,UAAU,GAAG,UAAU,EACjC,QAAQ,EAAE,MAAM;IAG5B;;;;OAIG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM;IAS3C;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAS3C;;OAEG;IACH,WAAW,IAAI,UAAU,GAAG,UAAU;IAItC;;OAEG;IACH,WAAW,IAAI,MAAM;IAIrB;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB;IAItD;;;;;OAKG;IACH,YAAY,CAAC,WAAW,EAAE,UAAU,GAAG,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,mBAAmB;CAGhG"}

package/dist/{path-manager.js → core/path-manager.js}

@@ -1,6 +1,11 @@
+/**
+ * CORE MODULE — Shared between text-only (rag-lite-ts) and future multimodal (rag-lite-mm)
+ * Model-agnostic. No transformer or modality-specific logic.
+ */
 import { relative, resolve, isAbsolute } from 'path';
 /**
  * Manages document path storage and resolution strategies
+ * Model-agnostic - works with any content type (text, image, etc.)
  */
 export class DocumentPathManager {
     strategy;

package/dist/core/path-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-manager.js","sourceRoot":"","sources":["../../src/core/path-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAErD;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IAEhB;IACA;IAFZ,YACY,QAAiC,EACjC,QAAgB;QADhB,aAAQ,GAAR,QAAQ,CAAyB;QACjC,aAAQ,GAAR,QAAQ,CAAQ;IACxB,CAAC;IAEL;;;;OAIG;IACH,aAAa,CAAC,YAAoB;QAC9B,IAAI,IAAI,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC/B,OAAO,YAAY,CAAC;QACxB,CAAC;QAED,qDAAqD;QACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IACjD,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,WAAmB;QAC9B,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC1B,OAAO,WAAW,CAAC;QACvB,CAAC;QAED,0CAA0C;QAC1C,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,WAAW;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,WAAW;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,WAAmB;QAC5B,OAAO,IAAI,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,WAAoC,EAAE,WAAoB;QACnE,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9E,CAAC;CACJ"}

package/dist/core/search-example.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CORE MODULE — Example usage of the new SearchEngine with dependency injection
+ * This file demonstrates how the refactored SearchEngine works with injected dependencies
+ */
+import type { EmbedFunction, RerankFunction } from './interfaces.js';
+/**
+ * Example embedding function that could be injected
+ * In practice, this would be created from a text embedder or multimodal embedder
+ */
+declare const exampleEmbedFunction: EmbedFunction;
+/**
+ * Example reranking function that could be injected
+ * In practice, this would be created from a cross-encoder reranker
+ */
+declare const exampleRerankFunction: RerankFunction;
+/**
+ * Example usage of the new SearchEngine with dependency injection
+ */
+export declare function exampleUsage(): Promise<void>;
+/**
+ * Example of how to create embedding and reranking functions from existing components
+ */
+export declare function createAdapterExample(): void;
+export { exampleEmbedFunction, exampleRerankFunction };
+//# sourceMappingURL=search-example.d.ts.map

package/dist/core/search-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-example.d.ts","sourceRoot":"","sources":["../../src/core/search-example.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIrE;;;GAGG;AACH,QAAA,MAAM,oBAAoB,EAAE,aAU3B,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,qBAAqB,EAAE,cAS5B,CAAC;AAEF;;GAEG;AACH,wBAAsB,YAAY,kBA4CjC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,SAoFnC;AAGD,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,CAAC"}