vector-inspector 0.2.7__py3-none-any.whl → 0.3.2__py3-none-any.whl

vector_inspector/core/embedding_providers/__init__.py

@@ -0,0 +1,14 @@
+"""Embedding provider system for loading and managing embedding models."""
+
+from .base_provider import EmbeddingProvider, EmbeddingMetadata
+from .sentence_transformer_provider import SentenceTransformerProvider
+from .clip_provider import CLIPProvider
+from .provider_factory import ProviderFactory
+
+__all__ = [
+    'EmbeddingProvider',
+    'EmbeddingMetadata',
+    'SentenceTransformerProvider',
+    'CLIPProvider',
+    'ProviderFactory',
+]

vector_inspector/core/embedding_providers/base_provider.py

@@ -0,0 +1,128 @@
+"""Base interface for embedding providers."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import List, Union, Optional, Any
+from enum import Enum
+import numpy as np
+
+
+class Modality(Enum):
+    """Embedding modality types."""
+    TEXT = "text"
+    IMAGE = "image"
+    MULTIMODAL = "multimodal"
+
+
+class Normalization(Enum):
+    """Embedding normalization types."""
+    NONE = "none"
+    L2 = "l2"
+
+
+@dataclass
+class EmbeddingMetadata:
+    """Metadata about an embedding model."""
+    name: str  # Model identifier (e.g., "all-MiniLM-L6-v2")
+    dimension: int  # Vector dimension
+    modality: Modality  # text, image, or multimodal
+    normalization: Normalization  # none or l2
+    model_type: str  # sentence-transformer, clip, openai, etc.
+    source: str = "unknown"  # hf, local, custom, cloud
+    version: Optional[str] = None  # Model version if available
+    max_sequence_length: Optional[int] = None  # Maximum input length
+    description: Optional[str] = None  # Human-readable description
+
+
+class EmbeddingProvider(ABC):
+    """Abstract base class for embedding providers.
+    
+    Providers handle loading, encoding, and metadata extraction for embedding models.
+    They implement lazy-loading to avoid UI freezes when working with large models.
+    """
+    
+    def __init__(self, model_name: str):
+        """Initialize provider with a model name.
+        
+        Args:
+            model_name: Model identifier (HuggingFace ID, path, or API model name)
+        """
+        self.model_name = model_name
+        self._model = None  # Lazy-loaded model instance
+        self._is_loaded = False
+        
+    @abstractmethod
+    def get_metadata(self) -> EmbeddingMetadata:
+        """Get metadata about the embedding model.
+        
+        This should be fast and not require loading the full model if possible.
+        
+        Returns:
+            EmbeddingMetadata with model information
+        """
+        pass
+    
+    @abstractmethod
+    def encode(
+        self, 
+        inputs: Union[str, List[str], Any],
+        normalize: bool = True,
+        show_progress: bool = False
+    ) -> np.ndarray:
+        """Encode inputs into embeddings.
+        
+        Args:
+            inputs: Text strings, images, or other inputs depending on modality
+            normalize: Whether to L2-normalize the embeddings
+            show_progress: Whether to show progress bar for batch encoding
+            
+        Returns:
+            numpy array of embeddings, shape (n_inputs, dimension)
+        """
+        pass
+    
+    def warmup(self, progress_callback=None):
+        """Load and initialize the model (warm up for faster subsequent calls).
+        
+        Args:
+            progress_callback: Optional callback(message: str, progress: float) for UI updates
+        """
+        if self._is_loaded:
+            return
+            
+        if progress_callback:
+            progress_callback(f"Loading {self.model_name}...", 0.0)
+        
+        self._load_model()
+        self._is_loaded = True
+        
+        if progress_callback:
+            progress_callback(f"Model {self.model_name} loaded", 1.0)
+    
+    @abstractmethod
+    def _load_model(self):
+        """Internal method to load the actual model. Override in subclasses."""
+        pass
+    
+    def close(self):
+        """Release model resources and cleanup."""
+        if self._model is not None:
+            # Try to free memory
+            del self._model
+            self._model = None
+            self._is_loaded = False
+    
+    @property
+    def is_loaded(self) -> bool:
+        """Check if model is currently loaded in memory."""
+        return self._is_loaded
+    
+    def __enter__(self):
+        """Context manager support."""
+        self.warmup()
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager cleanup."""
+        self.close()
+        return False

vector_inspector/core/embedding_providers/clip_provider.py

@@ -0,0 +1,260 @@
+"""CLIP embedding provider for multimodal (text + image) embeddings."""
+
+from typing import List, Union, Optional, Any
+import numpy as np
+from pathlib import Path
+
+from .base_provider import (
+    EmbeddingProvider,
+    EmbeddingMetadata,
+    Modality,
+    Normalization
+)
+
+
+class CLIPProvider(EmbeddingProvider):
+    """Provider for CLIP models supporting text and image embeddings.
+    
+    Lazy-loads the transformers library and CLIP model on first use.
+    Supports OpenAI CLIP and LAION CLIP variants:
+    - openai/clip-vit-base-patch32
+    - openai/clip-vit-large-patch14
+    - laion/CLIP-ViT-B-32-laion2B-s34B-b79K
+    - And other CLIP-compatible models
+    """
+    
+    def __init__(self, model_name: str):
+        """Initialize CLIP provider.
+        
+        Args:
+            model_name: HuggingFace model ID (e.g., "openai/clip-vit-base-patch32")
+        """
+        super().__init__(model_name)
+        self._processor = None
+        self._metadata = None
+    
+    def get_metadata(self) -> EmbeddingMetadata:
+        """Get metadata about the CLIP model."""
+        if self._metadata is not None:
+            return self._metadata
+        
+        try:
+            from transformers import CLIPConfig
+            
+            # Try to get config without loading full model
+            try:
+                config = CLIPConfig.from_pretrained(self.model_name)
+                dimension = config.projection_dim
+                max_length = config.text_config.max_position_embeddings
+            except Exception:
+                # Fallback dimensions for common CLIP models
+                dimension_map = {
+                    "openai/clip-vit-base-patch32": 512,
+                    "openai/clip-vit-base-patch16": 512,
+                    "openai/clip-vit-large-patch14": 768,
+                    "openai/clip-vit-large-patch14-336": 768,
+                }
+                dimension = dimension_map.get(self.model_name, 512)
+                max_length = 77  # Standard CLIP text length
+            
+            self._metadata = EmbeddingMetadata(
+                name=self.model_name,
+                dimension=dimension,
+                modality=Modality.MULTIMODAL,
+                normalization=Normalization.L2,  # CLIP normalizes embeddings
+                model_type="clip",
+                source="huggingface",
+                max_sequence_length=max_length,
+                description=f"CLIP multimodal model: {self.model_name}"
+            )
+            
+        except ImportError:
+            raise ImportError(
+                "transformers library not installed. "
+                "Install with: pip install transformers"
+            )
+        except Exception as e:
+            # Fallback metadata
+            self._metadata = EmbeddingMetadata(
+                name=self.model_name,
+                dimension=512,  # Common CLIP dimension
+                modality=Modality.MULTIMODAL,
+                normalization=Normalization.L2,
+                model_type="clip",
+                source="huggingface",
+                description=f"CLIP model: {self.model_name} (dimension not verified)"
+            )
+        
+        return self._metadata
+    
+    def _load_model(self):
+        """Load the CLIP model and processor."""
+        try:
+            from transformers import CLIPModel, CLIPProcessor
+        except ImportError:
+            raise ImportError(
+                "transformers library not installed. "
+                "Install with: pip install transformers"
+            )
+        
+        self._model = CLIPModel.from_pretrained(self.model_name)
+        self._processor = CLIPProcessor.from_pretrained(self.model_name)
+        
+        # Move to GPU if available
+        try:
+            import torch
+            if torch.cuda.is_available():
+                self._model = self._model.to('cuda')
+        except ImportError:
+            pass  # PyTorch not available, stay on CPU
+    
+    def encode(
+        self,
+        inputs: Union[str, List[str], Any],
+        normalize: bool = True,
+        show_progress: bool = False,
+        input_type: str = "text"
+    ) -> np.ndarray:
+        """Encode text or images into embeddings.
+        
+        Args:
+            inputs: Text strings, image paths, or PIL images
+            normalize: Whether to L2-normalize embeddings
+            show_progress: Whether to show progress (not implemented for CLIP)
+            input_type: "text" or "image"
+            
+        Returns:
+            numpy array of embeddings
+        """
+        if not self._is_loaded:
+            self.warmup()
+        
+        try:
+            import torch
+        except ImportError:
+            raise ImportError("PyTorch required for CLIP. Install with: pip install torch")
+        
+        # Convert single input to list
+        if isinstance(inputs, str) or not isinstance(inputs, list):
+            inputs = [inputs]
+        
+        if self._processor is None:
+            raise RuntimeError("Model not loaded. Call warmup() first.")
+        
+        with torch.no_grad():
+            if input_type == "text":
+                # Process text
+                processed = self._processor(
+                    text=inputs,
+                    return_tensors="pt",
+                    padding=True,
+                    truncation=True
+                )
+                
+                # Move to same device as model
+                if next(self._model.parameters()).is_cuda:
+                    processed = {k: v.cuda() for k, v in processed.items()}
+                
+                # Get text embeddings
+                embeddings = self._model.get_text_features(**processed)
+                
+            elif input_type == "image":
+                # Load images if they're paths
+                images = []
+                for inp in inputs:
+                    if isinstance(inp, (str, Path)):
+                        from PIL import Image
+                        images.append(Image.open(inp))
+                    else:
+                        images.append(inp)  # Assume already PIL Image
+                
+                # Process images
+                processed = self._processor(
+                    images=images,
+                    return_tensors="pt"
+                )
+                
+                # Move to same device as model
+                if next(self._model.parameters()).is_cuda:
+                    processed = {k: v.cuda() for k, v in processed.items()}
+                
+                # Get image embeddings
+                embeddings = self._model.get_image_features(**processed)
+            else:
+                raise ValueError(f"Unknown input_type: {input_type}. Use 'text' or 'image'")
+            
+            # Convert to numpy
+            embeddings = embeddings.cpu().numpy()
+            
+            # Normalize if requested (CLIP typically normalizes, but we can ensure it)
+            if normalize:
+                norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
+                embeddings = embeddings / norms
+        
+        return embeddings
+    
+    def encode_text(
+        self,
+        texts: Union[str, List[str]],
+        normalize: bool = True
+    ) -> np.ndarray:
+        """Encode text inputs into embeddings.
+        
+        Args:
+            texts: Single text or list of texts
+            normalize: Whether to L2-normalize
+            
+        Returns:
+            numpy array of text embeddings
+        """
+        return self.encode(texts, normalize=normalize, input_type="text")
+    
+    def encode_image(
+        self,
+        images: Union[str, Path, Any, List],
+        normalize: bool = True
+    ) -> np.ndarray:
+        """Encode images into embeddings.
+        
+        Args:
+            images: Image path(s) or PIL Image(s)
+            normalize: Whether to L2-normalize
+            
+        Returns:
+            numpy array of image embeddings
+        """
+        return self.encode(images, normalize=normalize, input_type="image")
+    
+    def similarity(
+        self,
+        query: Union[str, np.ndarray],
+        corpus: List[str],
+        query_type: str = "text",
+        corpus_type: str = "text"
+    ) -> np.ndarray:
+        """Compute similarity between query and corpus (text or image).
+        
+        Args:
+            query: Query string/image or embedding
+            corpus: List of corpus items (text or images)
+            query_type: "text" or "image"
+            corpus_type: "text" or "image"
+            
+        Returns:
+            Similarity scores (cosine similarity)
+        """
+        if not self._is_loaded:
+            self.warmup()
+        
+        # Get embeddings
+        if isinstance(query, np.ndarray):
+            query_emb = query
+        else:
+            query_emb = self.encode(query, normalize=True, input_type=query_type)
+        
+        corpus_emb = self.encode(corpus, normalize=True, input_type=corpus_type)
+        
+        # Compute cosine similarity (dot product if normalized)
+        similarities = np.dot(corpus_emb, query_emb.T).squeeze()
+        
+        return similarities

vector_inspector/core/embedding_providers/provider_factory.py

@@ -0,0 +1,176 @@
+"""Factory for creating embedding providers."""
+
+from typing import Optional, Dict, Type
+from .base_provider import EmbeddingProvider
+from .sentence_transformer_provider import SentenceTransformerProvider
+from .clip_provider import CLIPProvider
+from ..model_registry import get_model_registry
+
+
+class ProviderFactory:
+    """Factory for creating appropriate embedding providers based on model type."""
+    
+    # Registry of provider classes by type
+    _PROVIDER_REGISTRY: Dict[str, Type[EmbeddingProvider]] = {
+        "sentence-transformer": SentenceTransformerProvider,
+        "clip": CLIPProvider,
+    }
+    
+    # Model name patterns to auto-detect provider type
+    _MODEL_PATTERNS = {
+        "clip": ["clip", "CLIP"],
+        "sentence-transformer": [
+            "sentence-transformers/",
+            "all-MiniLM",
+            "all-mpnet",
+            "all-roberta",
+            "paraphrase-",
+            "multi-qa-",
+            "msmarco-",
+            "gtr-",
+            "bge-",
+            "gte-",
+            "e5-",
+            "jina-",
+            "nomic-",
+        ]
+    }
+    
+    @classmethod
+    def create(
+        cls,
+        model_name: str,
+        model_type: Optional[str] = None,
+        **kwargs
+    ) -> EmbeddingProvider:
+        """Create an embedding provider for the given model.
+        
+        Args:
+            model_name: Model identifier (HF ID, path, or API name)
+            model_type: Explicit provider type (sentence-transformer, clip, openai, etc.)
+                       If None, will attempt auto-detection based on model name
+            **kwargs: Additional arguments passed to provider constructor
+            
+        Returns:
+            Appropriate EmbeddingProvider instance
+            
+        Raises:
+            ValueError: If model type is unknown or cannot be auto-detected
+        """
+        # Auto-detect provider type if not specified
+        if model_type is None:
+            model_type = cls._detect_provider_type(model_name)
+        
+        # Normalize model type
+        model_type = model_type.lower()
+        
+        # Get provider class from registry
+        provider_class = cls._PROVIDER_REGISTRY.get(model_type)
+        
+        if provider_class is None:
+            # Check if it's a cloud provider (not yet implemented)
+            if model_type in ["openai", "cohere", "vertex-ai", "voyage"]:
+                raise NotImplementedError(
+                    f"Cloud provider '{model_type}' not yet implemented. "
+                    f"Currently supported: {', '.join(cls._PROVIDER_REGISTRY.keys())}"
+                )
+            else:
+                raise ValueError(
+                    f"Unknown provider type: {model_type}. "
+                    f"Supported types: {', '.join(cls._PROVIDER_REGISTRY.keys())}"
+                )
+        
+        # Create and return provider instance
+        return provider_class(model_name, **kwargs)
+    
+    @classmethod
+    def _detect_provider_type(cls, model_name: str) -> str:
+        """Auto-detect provider type based on model name patterns.
+        
+        First checks the known model registry, then falls back to pattern matching.
+        
+        Args:
+            model_name: Model identifier
+            
+        Returns:
+            Detected provider type
+            
+        Raises:
+            ValueError: If provider type cannot be detected
+        """
+        # First, check if model is in registry
+        registry = get_model_registry()
+        model_info = registry.get_model_by_name(model_name)
+        if model_info:
+            return model_info.type
+        
+        # Fall back to pattern matching
+        model_name_lower = model_name.lower()
+        
+        # Check each pattern category
+        for provider_type, patterns in cls._MODEL_PATTERNS.items():
+            for pattern in patterns:
+                if pattern.lower() in model_name_lower:
+                    return provider_type
+        
+        # Default to sentence-transformer for HuggingFace models
+        if "/" in model_name and not model_name.startswith("http"):
+            return "sentence-transformer"
+        
+        raise ValueError(
+            f"Cannot auto-detect provider type for model: {model_name}. "
+            "Please specify model_type explicitly."
+        )
+    
+    @classmethod
+    def register_provider(cls, model_type: str, provider_class: Type[EmbeddingProvider]):
+        """Register a new provider type.
+        
+        Args:
+            model_type: Provider type identifier
+            provider_class: Provider class (must inherit from EmbeddingProvider)
+        """
+        if not issubclass(provider_class, EmbeddingProvider):
+            raise TypeError(f"{provider_class} must inherit from EmbeddingProvider")
+        
+        cls._PROVIDER_REGISTRY[model_type.lower()] = provider_class
+    
+    @classmethod
+    def list_supported_types(cls) -> list:
+        """Get list of supported provider types.
+        
+        Returns:
+            List of registered provider type names
+        """
+        return list(cls._PROVIDER_REGISTRY.keys())
+    
+    @classmethod
+    def supports_type(cls, model_type: str) -> bool:
+        """Check if a provider type is supported.
+        
+        Args:
+            model_type: Provider type to check
+            
+        Returns:
+            True if supported, False otherwise
+        """
+        return model_type.lower() in cls._PROVIDER_REGISTRY
+
+
+# Convenience function for creating providers
+def create_provider(
+    model_name: str,
+    model_type: Optional[str] = None,
+    **kwargs
+) -> EmbeddingProvider:
+    """Create an embedding provider (convenience wrapper around ProviderFactory).
+    
+    Args:
+        model_name: Model identifier
+        model_type: Optional explicit provider type
+        **kwargs: Additional arguments for provider
+        
+    Returns:
+        EmbeddingProvider instance
+    """
+    return ProviderFactory.create(model_name, model_type, **kwargs)