rag-lite-ts 1.0.2 → 2.0.0

package/dist/core/types.d.ts

@@ -19,6 +19,7 @@ export interface EmbeddingResult {
     embedding_id: string;
     vector: Float32Array;
     contentType?: string;
+    metadata?: Record<string, any>;
 }
 export type EmbedFunction = (query: string, contentType?: string) => Promise<EmbeddingResult>;
 export interface SearchResult {
@@ -30,6 +31,7 @@ export interface SearchResult {
         source: string;
         title: string;
         contentType: string;
+        contentId?: string;
     };
     metadata?: Record<string, any>;
 }
@@ -57,6 +59,7 @@ export interface Document {
     source: string;
     title: string;
     content: string;
+    metadata?: Record<string, any>;
 }
 export type { DatabaseConnection } from './db.js';
 export type { ContentChunk as ChunkResult } from './db.js';

package/dist/core/universal-embedder.d.ts

@@ -0,0 +1,177 @@
+/**
+ * CORE MODULE — Universal Embedder Interface for Chameleon Architecture
+ *
+ * Model-agnostic interfaces supporting both text and multimodal models.
+ * Designed for runtime polymorphism and extensibility.
+ *
+ * ARCHITECTURAL ROLE:
+ * This file contains ONLY interfaces, types, and utility functions - no implementation logic.
+ * It defines the contract that all embedder implementations must follow.
+ *
+ * CONTENTS:
+ * - UniversalEmbedder interface: Core contract for all embedders
+ * - Type definitions: ModelType, ContentType, etc.
+ * - Error classes: ModelValidationError, ContentTypeError, etc.
+ * - Utility functions: Type guards and validation helpers
+ * - Constants: Default capabilities and content types
+ *
+ * USAGE:
+ * - Implementation layers (text, multimodal) implement these interfaces
+ * - Core layer uses these types for dependency injection
+ * - Public API exports these types for external use
+ */
+import type { EmbeddingResult } from '../types.js';
+/**
+ * Universal embedder interface supporting both text and multimodal models
+ * Provides a consistent API across different model types and content types
+ */
+export interface UniversalEmbedder {
+    readonly modelName: string;
+    readonly modelType: ModelType;
+    readonly dimensions: number;
+    readonly supportedContentTypes: readonly string[];
+    embedText(text: string): Promise<EmbeddingResult>;
+    embedImage?(imagePath: string): Promise<EmbeddingResult>;
+    embedBatch(items: EmbeddingBatchItem[]): Promise<EmbeddingResult[]>;
+    loadModel(): Promise<void>;
+    isLoaded(): boolean;
+    getModelInfo(): ModelInfo;
+    cleanup(): Promise<void>;
+}
+/**
+ * Enhanced embedding result with content type and metadata support
+ * Extends the existing EmbeddingResult interface for multimodal compatibility
+ */
+export interface EnhancedEmbeddingResult extends EmbeddingResult {
+    contentType: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Batch embedding item for efficient processing
+ */
+export interface EmbeddingBatchItem {
+    content: string;
+    contentType: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Model information interface for runtime introspection
+ */
+export interface ModelInfo {
+    name: string;
+    type: ModelType;
+    dimensions: number;
+    version: string;
+    supportedContentTypes: readonly string[];
+    capabilities: ModelCapabilities;
+    requirements: ModelRequirements;
+}
+/**
+ * Model capabilities for feature detection
+ */
+export interface ModelCapabilities {
+    supportsText: boolean;
+    supportsImages: boolean;
+    supportsBatchProcessing: boolean;
+    supportsMetadata: boolean;
+    maxBatchSize?: number;
+    maxTextLength?: number;
+    supportedImageFormats?: readonly string[];
+    supportsMultimodal?: boolean;
+    supportsCrossModalSearch?: boolean;
+    unifiedEmbeddingSpace?: boolean;
+    reliableImplementation?: boolean;
+}
+/**
+ * Model requirements for validation and compatibility checking
+ */
+export interface ModelRequirements {
+    transformersJsVersion: string;
+    minimumMemory?: number;
+    requiredFeatures?: readonly string[];
+    platformSupport?: readonly string[];
+}
+/**
+ * Supported model types in the Chameleon architecture
+ */
+export type ModelType = 'sentence-transformer' | 'clip';
+/**
+ * Content types supported by the system
+ */
+export type ContentType = 'text' | 'image' | 'pdf' | 'docx';
+/**
+ * Model validation result for compatibility checking
+ */
+export interface ModelValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+    suggestions: string[];
+}
+/**
+ * Simple embedder creation function type
+ * Replaces complex factory patterns with a straightforward function approach
+ */
+export type CreateEmbedderFunction = (modelName: string, options?: EmbedderCreationOptions) => Promise<UniversalEmbedder>;
+/**
+ * Options for creating embedder instances
+ */
+export interface EmbedderCreationOptions {
+    cachePath?: string;
+    maxBatchSize?: number;
+    timeout?: number;
+    enableGPU?: boolean;
+    customConfig?: Record<string, any>;
+}
+/**
+ * Model validation error for unsupported or incompatible models
+ */
+export declare class ModelValidationError extends Error {
+    readonly modelName: string;
+    readonly availableModels: readonly string[];
+    constructor(modelName: string, availableModels: readonly string[], message: string);
+}
+/**
+ * Transformers.js compatibility error for version mismatches
+ */
+export declare class TransformersCompatibilityError extends Error {
+    readonly modelName: string;
+    readonly requiredVersion: string;
+    readonly currentVersion: string;
+    constructor(modelName: string, requiredVersion: string, currentVersion: string, message: string);
+}
+/**
+ * Content type error for unsupported content types
+ */
+export declare class ContentTypeError extends Error {
+    readonly contentType: string;
+    readonly supportedTypes: readonly string[];
+    constructor(contentType: string, supportedTypes: readonly string[], message: string);
+}
+/**
+ * Type guard for checking if an embedder supports images
+ */
+export declare function supportsImages(embedder: UniversalEmbedder): embedder is UniversalEmbedder & {
+    embedImage(imagePath: string): Promise<EmbeddingResult>;
+};
+/**
+ * Type guard for checking if an embedder supports a specific content type
+ */
+export declare function supportsContentType(embedder: UniversalEmbedder, contentType: string): boolean;
+/**
+ * Utility function to create enhanced embedding results
+ */
+export declare function createEnhancedEmbeddingResult(embeddingId: string, vector: Float32Array, contentType: string, metadata?: Record<string, any>): EnhancedEmbeddingResult;
+/**
+ * Utility function to validate content type against supported types
+ */
+export declare function validateContentType(contentType: string, supportedTypes: readonly string[]): void;
+/**
+ * Default supported content types for different model types
+ */
+export declare const DEFAULT_CONTENT_TYPES: Record<ModelType, readonly string[]>;
+/**
+ * Default model capabilities for different model types
+ */
+export declare const DEFAULT_CAPABILITIES: Record<ModelType, ModelCapabilities>;
+//# sourceMappingURL=universal-embedder.d.ts.map

package/dist/core/universal-embedder.js

@@ -0,0 +1,139 @@
+/**
+ * CORE MODULE — Universal Embedder Interface for Chameleon Architecture
+ *
+ * Model-agnostic interfaces supporting both text and multimodal models.
+ * Designed for runtime polymorphism and extensibility.
+ *
+ * ARCHITECTURAL ROLE:
+ * This file contains ONLY interfaces, types, and utility functions - no implementation logic.
+ * It defines the contract that all embedder implementations must follow.
+ *
+ * CONTENTS:
+ * - UniversalEmbedder interface: Core contract for all embedders
+ * - Type definitions: ModelType, ContentType, etc.
+ * - Error classes: ModelValidationError, ContentTypeError, etc.
+ * - Utility functions: Type guards and validation helpers
+ * - Constants: Default capabilities and content types
+ *
+ * USAGE:
+ * - Implementation layers (text, multimodal) implement these interfaces
+ * - Core layer uses these types for dependency injection
+ * - Public API exports these types for external use
+ */
+// =============================================================================
+// ERROR TYPES
+// =============================================================================
+/**
+ * Model validation error for unsupported or incompatible models
+ */
+export class ModelValidationError extends Error {
+    modelName;
+    availableModels;
+    constructor(modelName, availableModels, message) {
+        super(message);
+        this.modelName = modelName;
+        this.availableModels = availableModels;
+        this.name = 'ModelValidationError';
+    }
+}
+/**
+ * Transformers.js compatibility error for version mismatches
+ */
+export class TransformersCompatibilityError extends Error {
+    modelName;
+    requiredVersion;
+    currentVersion;
+    constructor(modelName, requiredVersion, currentVersion, message) {
+        super(message);
+        this.modelName = modelName;
+        this.requiredVersion = requiredVersion;
+        this.currentVersion = currentVersion;
+        this.name = 'TransformersCompatibilityError';
+    }
+}
+/**
+ * Content type error for unsupported content types
+ */
+export class ContentTypeError extends Error {
+    contentType;
+    supportedTypes;
+    constructor(contentType, supportedTypes, message) {
+        super(message);
+        this.contentType = contentType;
+        this.supportedTypes = supportedTypes;
+        this.name = 'ContentTypeError';
+    }
+}
+// =============================================================================
+// UTILITY TYPES
+// =============================================================================
+/**
+ * Type guard for checking if an embedder supports images
+ */
+export function supportsImages(embedder) {
+    return embedder.supportedContentTypes.includes('image') &&
+        typeof embedder.embedImage === 'function';
+}
+/**
+ * Type guard for checking if an embedder supports a specific content type
+ */
+export function supportsContentType(embedder, contentType) {
+    return embedder.supportedContentTypes.includes(contentType);
+}
+/**
+ * Utility function to create enhanced embedding results
+ */
+export function createEnhancedEmbeddingResult(embeddingId, vector, contentType, metadata) {
+    return {
+        embedding_id: embeddingId,
+        vector,
+        contentType,
+        metadata
+    };
+}
+/**
+ * Utility function to validate content type against supported types
+ */
+export function validateContentType(contentType, supportedTypes) {
+    if (!supportedTypes.includes(contentType)) {
+        throw new ContentTypeError(contentType, supportedTypes, `Content type '${contentType}' is not supported. Supported types: ${supportedTypes.join(', ')}`);
+    }
+}
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Default supported content types for different model types
+ */
+export const DEFAULT_CONTENT_TYPES = {
+    'sentence-transformer': ['text'],
+    'clip': ['text', 'image']
+};
+/**
+ * Default model capabilities for different model types
+ */
+export const DEFAULT_CAPABILITIES = {
+    'sentence-transformer': {
+        supportsText: true,
+        supportsImages: false,
+        supportsBatchProcessing: true,
+        supportsMetadata: true,
+        maxBatchSize: 32,
+        maxTextLength: 512
+    },
+    'clip': {
+        supportsText: true,
+        supportsImages: true,
+        supportsBatchProcessing: true,
+        supportsMetadata: true,
+        maxBatchSize: 16,
+        maxTextLength: 77,
+        supportedImageFormats: ['jpg', 'jpeg', 'png', 'webp', 'gif'],
+        // Enhanced capabilities for fixed CLIP implementation
+        supportsMultimodal: true,
+        supportsCrossModalSearch: true,
+        unifiedEmbeddingSpace: true,
+        reliableImplementation: true
+    }
+};
+//# sourceMappingURL=universal-embedder.js.map

package/dist/core/validation-messages.d.ts

@@ -0,0 +1,99 @@
+/**
+ * CORE MODULE — Validation Messages and Error Descriptions
+ * Comprehensive error messages and user guidance for model validation
+ * Provides helpful, actionable error messages with troubleshooting steps
+ */
+import type { ModelType } from './universal-embedder.js';
+/**
+ * Error message templates for different validation scenarios
+ */
+export declare const ERROR_MESSAGES: {
+    readonly MODEL_NOT_FOUND: (modelName: string, suggestions: string[]) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+    readonly TRANSFORMERS_VERSION_INCOMPATIBLE: (modelName: string, required: string, current: string) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+    readonly INSUFFICIENT_MEMORY: (modelName: string, required: number, available: number) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+    readonly PLATFORM_UNSUPPORTED: (modelName: string, currentPlatform: string, supportedPlatforms: string[]) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+    readonly FEATURES_MISSING: (modelName: string, missingFeatures: string[]) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+    readonly CONTENT_TYPE_UNSUPPORTED: (contentType: string, modelName: string, supportedTypes: string[]) => {
+        title: string;
+        description: string;
+        details: string[];
+        suggestions: string[];
+        actions: string[];
+    };
+};
+/**
+ * Warning message templates for non-critical issues
+ */
+export declare const WARNING_MESSAGES: {
+    readonly HIGH_MEMORY_USAGE: (modelName: string, memoryMB: number) => {
+        title: string;
+        message: string;
+        suggestions: string[];
+    };
+    readonly LIMITED_BATCH_SIZE: (modelName: string, maxBatchSize: number) => {
+        title: string;
+        message: string;
+        suggestions: string[];
+    };
+    readonly EXPERIMENTAL_FEATURES: (modelName: string, features: string[]) => {
+        title: string;
+        message: string;
+        suggestions: string[];
+    };
+    readonly PERFORMANCE_IMPACT: (modelName: string, reason: string) => {
+        title: string;
+        message: string;
+        suggestions: string[];
+    };
+};
+/**
+ * Format an error message for console output
+ */
+export declare function formatErrorMessage(error: ReturnType<typeof ERROR_MESSAGES[keyof typeof ERROR_MESSAGES]>): string;
+/**
+ * Format a warning message for console output
+ */
+export declare function formatWarningMessage(warning: ReturnType<typeof WARNING_MESSAGES[keyof typeof WARNING_MESSAGES]>): string;
+/**
+ * Create a comprehensive error message for model validation failure
+ */
+export declare function createValidationErrorMessage(modelName: string, errorType: 'not_found' | 'version_incompatible' | 'insufficient_memory' | 'platform_unsupported' | 'features_missing' | 'content_type_unsupported', context?: Record<string, any>): string;
+/**
+ * Create helpful suggestions based on model type and use case
+ */
+export declare function createModelSuggestions(modelType?: ModelType, contentTypes?: string[], memoryLimit?: number): string[];
+/**
+ * Get troubleshooting steps for common issues
+ */
+export declare function getTroubleshootingSteps(issue: string): string[];
+//# sourceMappingURL=validation-messages.d.ts.map