realtimex-deeptutor 0.5.0.post1__py3-none-any.whl

src/services/embedding/adapters/base.py

@@ -0,0 +1,106 @@
+"""
+Base Embedding Adapter
+=======================
+
+Abstract base class for all embedding adapters.
+Defines the contract that all embedding providers must implement.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class EmbeddingRequest:
+    """
+    Standard embedding request structure.
+
+    Provider-agnostic request format. Different providers interpret fields differently:
+
+    Args:
+        texts: List of texts to embed
+        model: Model name to use
+        dimensions: Embedding vector dimensions (optional)
+        input_type: Input type hint for task-aware embeddings (optional)
+            - Cohere: Maps to 'input_type' ("search_document", "search_query", "classification", "clustering")
+            - Jina: Maps to 'task' ("retrieval.passage", "retrieval.query", etc.)
+            - OpenAI/Ollama: Ignored
+        encoding_format: Output format ("float" or "base64", default: "float")
+        truncate: Whether to truncate texts that exceed max tokens (default: True)
+        normalized: Whether to return L2-normalized embeddings (Jina/Ollama only)
+        late_chunking: Enable late chunking for long context (Jina v3 only)
+    """
+
+    texts: List[str]
+    model: str
+    dimensions: Optional[int] = None
+    input_type: Optional[str] = None
+    encoding_format: Optional[str] = "float"
+    truncate: Optional[bool] = True
+    normalized: Optional[bool] = True
+    late_chunking: Optional[bool] = False
+
+
+@dataclass
+class EmbeddingResponse:
+    """Standard embedding response structure."""
+
+    embeddings: List[List[float]]
+    model: str
+    dimensions: int
+    usage: Dict[str, Any]
+
+
+class BaseEmbeddingAdapter(ABC):
+    """
+    Base class for all embedding adapters.
+
+    Each adapter implements the specific API interface for a provider
+    (OpenAI, Cohere, Ollama, etc.) while exposing a unified interface.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize the adapter with configuration.
+
+        Args:
+            config: Dictionary containing:
+                - api_key: API authentication key (optional for local)
+                - base_url: API endpoint URL
+                - model: Model name to use
+                - dimensions: Embedding vector dimensions
+                - request_timeout: Request timeout in seconds
+        """
+        self.api_key = config.get("api_key")
+        self.base_url = config.get("base_url")
+        self.api_version = config.get("api_version")
+        self.model = config.get("model")
+        self.dimensions = config.get("dimensions")
+        self.request_timeout = config.get("request_timeout", 30)
+
+    @abstractmethod
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        """
+        Generate embeddings for a list of texts.
+
+        Args:
+            request: EmbeddingRequest with texts and parameters
+
+        Returns:
+            EmbeddingResponse with embeddings and metadata
+
+        Raises:
+            httpx.HTTPError: If the API request fails
+        """
+        pass
+
+    @abstractmethod
+    def get_model_info(self) -> Dict[str, Any]:
+        """
+        Return information about the configured model.
+
+        Returns:
+            Dictionary with model metadata (name, dimensions, etc.)
+        """
+        pass

src/services/embedding/adapters/cohere.py

@@ -0,0 +1,127 @@
+"""Cohere Embedding Adapter for v1 and v2 API."""
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CohereEmbeddingAdapter(BaseEmbeddingAdapter):
+    """Adapter for Cohere Embed API (v1 and v2)."""
+
+    MODELS_INFO = {
+        "embed-v4.0": {
+            "dimensions": [256, 512, 1024, 1536],
+            "default": 1024,
+            "api_version": "v2",
+        },
+        "embed-english-v3.0": {
+            "dimensions": [1024],
+            "default": 1024,
+            "api_version": "v1",
+        },
+        "embed-multilingual-v3.0": {
+            "dimensions": [1024],
+            "default": 1024,
+            "api_version": "v1",
+        },
+        "embed-multilingual-light-v3.0": {
+            "dimensions": [384],
+            "default": 384,
+            "api_version": "v1",
+        },
+        "embed-english-light-v3.0": {
+            "dimensions": [384],
+            "default": 384,
+            "api_version": "v1",
+        },
+    }
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        model_name = request.model or self.model
+        model_info = self.MODELS_INFO.get(model_name, {})
+        api_version = model_info.get("api_version", "v2")
+        dimension = request.dimensions or self.dimensions
+
+        input_type = request.input_type or "search_document"
+
+        if api_version == "v1":
+            payload = {
+                "texts": request.texts,
+                "model": model_name,
+                "input_type": input_type,
+            }
+
+            if not request.truncate:
+                payload["truncate"] = "NONE"
+        else:
+            payload = {
+                "texts": request.texts,
+                "model": model_name,
+                "embedding_types": ["float"],
+                "input_type": input_type,
+            }
+
+            supported_dims = model_info.get("dimensions", [])
+            if isinstance(supported_dims, list) and len(supported_dims) > 1:
+                payload["output_dimension"] = dimension or model_info.get("default")
+
+            if not request.truncate:
+                payload["truncate"] = "NONE"
+
+        url = f"{self.base_url}/{api_version}/embed"
+
+        logger.debug(f"Sending embedding request to {url} with {len(request.texts)} texts")
+
+        async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+            response = await client.post(url, json=payload, headers=headers)
+
+            if response.status_code >= 400:
+                logger.error(f"HTTP {response.status_code} response body: {response.text}")
+
+            response.raise_for_status()
+            data = response.json()
+
+        if api_version == "v1":
+            embeddings = data["embeddings"]
+        else:
+            embeddings = data["embeddings"]["float"]
+
+        actual_dims = len(embeddings[0]) if embeddings else 0
+        expected_dims = request.dimensions or self.dimensions
+
+        if expected_dims and actual_dims != expected_dims:
+            logger.warning(f"Dimension mismatch: expected {expected_dims}, got {actual_dims}")
+
+        logger.info(
+            f"Successfully generated {len(embeddings)} embeddings "
+            f"(model: {data.get('model', self.model)}, dimensions: {actual_dims})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=data.get("model", self.model),
+            dimensions=actual_dims,
+            usage=data.get("meta", {}).get("billed_units", {}),
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        model_info = self.MODELS_INFO.get(self.model, {})
+        dimensions_list = model_info.get("dimensions", [])
+        return {
+            "model": self.model,
+            "dimensions": model_info.get("default", self.dimensions),
+            "supports_variable_dimensions": len(dimensions_list) > 1
+            if isinstance(dimensions_list, list)
+            else False,
+            "provider": "cohere",
+        }

src/services/embedding/adapters/jina.py

@@ -0,0 +1,99 @@
+"""Jina AI embedding adapter with task-aware embeddings and late chunking."""
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class JinaEmbeddingAdapter(BaseEmbeddingAdapter):
+    MODELS_INFO = {
+        "jina-embeddings-v3": {"default": 1024, "dimensions": [32, 64, 128, 256, 512, 768, 1024]},
+        "jina-embeddings-v4": {"default": 1024, "dimensions": [32, 64, 128, 256, 512, 768, 1024]},
+    }
+
+    INPUT_TYPE_TO_TASK = {
+        "search_document": "retrieval.passage",
+        "search_query": "retrieval.query",
+        "classification": "classification",
+        "clustering": "separation",
+        "text-matching": "text-matching",
+    }
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+        payload = {
+            "input": request.texts,
+            "model": request.model or self.model,
+        }
+
+        if request.dimensions:
+            payload["dimensions"] = request.dimensions
+        elif self.dimensions:
+            payload["dimensions"] = self.dimensions
+
+        if request.input_type:
+            task = self.INPUT_TYPE_TO_TASK.get(request.input_type, request.input_type)
+            payload["task"] = task
+            logger.debug(f"Using Jina task: {task}")
+
+        if request.normalized is not None:
+            payload["normalized"] = request.normalized
+
+        if request.late_chunking:
+            payload["late_chunking"] = True
+
+        url = f"{self.base_url}/embeddings"
+
+        logger.debug(f"Sending embedding request to {url} with {len(request.texts)} texts")
+
+        async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+            response = await client.post(url, json=payload, headers=headers)
+
+            if response.status_code >= 400:
+                logger.error(f"HTTP {response.status_code} response body: {response.text}")
+
+            response.raise_for_status()
+            data = response.json()
+
+        embeddings = [item["embedding"] for item in data["data"]]
+        actual_dims = len(embeddings[0]) if embeddings else 0
+
+        logger.info(
+            f"Successfully generated {len(embeddings)} embeddings "
+            f"(model: {data['model']}, dimensions: {actual_dims})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=data["model"],
+            dimensions=actual_dims,
+            usage=data.get("usage", {}),
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        model_info = self.MODELS_INFO.get(self.model, self.dimensions)
+
+        if isinstance(model_info, dict):
+            return {
+                "model": self.model,
+                "dimensions": model_info.get("default", self.dimensions),
+                "supported_dimensions": model_info.get("dimensions", []),
+                "supports_variable_dimensions": True,
+                "provider": "jina",
+            }
+        else:
+            return {
+                "model": self.model,
+                "dimensions": model_info or self.dimensions,
+                "supports_variable_dimensions": False,
+                "provider": "jina",
+            }

src/services/embedding/adapters/ollama.py

@@ -0,0 +1,116 @@
+"""Ollama Embedding Adapter for local embeddings."""
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class OllamaEmbeddingAdapter(BaseEmbeddingAdapter):
+    MODELS_INFO = {
+        "all-minilm": 384,
+        "all-mpnet-base-v2": 768,
+        "nomic-embed-text": 768,
+        "mxbai-embed-large": 1024,
+        "snowflake-arctic-embed": 1024,
+    }
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        payload = {
+            "model": request.model or self.model,
+            "input": request.texts,
+        }
+
+        if request.dimensions or self.dimensions:
+            payload["dimensions"] = request.dimensions or self.dimensions
+
+        if request.truncate is not None:
+            payload["truncate"] = request.truncate
+
+        payload["keep_alive"] = "5m"
+
+        url = f"{self.base_url}/api/embed"
+
+        logger.debug(f"Sending embedding request to {url} with {len(request.texts)} texts")
+
+        try:
+            async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+                response = await client.post(url, json=payload)
+
+                if response.status_code == 404:
+                    try:
+                        health_check = await client.get(f"{self.base_url}/api/tags")
+                        if health_check.status_code == 200:
+                            available_models = [
+                                m.get("name", "") for m in health_check.json().get("models", [])
+                            ]
+                            raise ValueError(
+                                f"Model '{payload['model']}' not found in Ollama. "
+                                f"Available models: {', '.join(available_models[:10])}. "
+                                f"Download it with: ollama pull {payload['model']}"
+                            )
+                    except httpx.HTTPError:
+                        pass
+
+                    raise ValueError(
+                        f"Model '{payload['model']}' not found. "
+                        f"Download it with: ollama pull {payload['model']}"
+                    )
+
+                response.raise_for_status()
+                data = response.json()
+
+        except httpx.ConnectError as e:
+            raise ConnectionError(
+                f"Cannot connect to Ollama at {self.base_url}. "
+                f"Make sure Ollama is running. Start it with: ollama serve"
+            ) from e
+
+        except httpx.TimeoutException as e:
+            raise TimeoutError(
+                f"Request to Ollama timed out after {self.request_timeout}s. "
+                f"The model might be too large or the server is overloaded."
+            ) from e
+
+        except httpx.HTTPError as e:
+            logger.error(f"Ollama API error: {e}")
+            raise
+
+        embeddings = data["embeddings"]
+
+        actual_dims = len(embeddings[0]) if embeddings else 0
+        expected_dims = request.dimensions or self.dimensions
+
+        if expected_dims and actual_dims != expected_dims:
+            logger.warning(
+                f"Dimension mismatch: expected {expected_dims}, got {actual_dims}. "
+                f"Model '{payload['model']}' may not support custom dimensions."
+            )
+
+        logger.info(
+            f"Successfully generated {len(embeddings)} embeddings "
+            f"(model: {data.get('model', self.model)}, dimensions: {actual_dims})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=data.get("model", self.model),
+            dimensions=actual_dims,
+            usage={
+                "prompt_eval_count": data.get("prompt_eval_count", 0),
+                "total_duration": data.get("total_duration", 0),
+            },
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "dimensions": self.MODELS_INFO.get(self.model, self.dimensions),
+            "local": True,
+            "supports_variable_dimensions": False,
+            "provider": "ollama",
+        }

src/services/embedding/adapters/openai_compatible.py

@@ -0,0 +1,96 @@
+"""OpenAI-compatible embedding adapter for OpenAI, Azure, HuggingFace, LM Studio, etc."""
+
+import logging
+from typing import Any, Dict
+
+import httpx
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAICompatibleEmbeddingAdapter(BaseEmbeddingAdapter):
+    MODELS_INFO = {
+        "text-embedding-3-large": {"default": 3072, "dimensions": [256, 512, 1024, 3072]},
+        "text-embedding-3-small": {"default": 1536, "dimensions": [512, 1536]},
+        "text-embedding-ada-002": 1536,
+    }
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        headers = {
+            "Content-Type": "application/json",
+        }
+        if self.api_version:
+            headers["api-key"] = self.api_key
+        else:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        payload = {
+            "input": request.texts,
+            "model": request.model or self.model,
+            "encoding_format": request.encoding_format or "float",
+        }
+
+        if request.dimensions or self.dimensions:
+            payload["dimensions"] = request.dimensions or self.dimensions
+
+        url = f"{self.base_url.rstrip('/')}/embeddings"
+        if self.api_version:
+            if "?" not in url:
+                url += f"?api-version={self.api_version}"
+            else:
+                url += f"&api-version={self.api_version}"
+
+        logger.debug(f"Sending embedding request to {url} with {len(request.texts)} texts")
+
+        async with httpx.AsyncClient(timeout=self.request_timeout) as client:
+            response = await client.post(url, json=payload, headers=headers)
+
+            if response.status_code >= 400:
+                logger.error(f"HTTP {response.status_code} response body: {response.text}")
+
+            response.raise_for_status()
+            data = response.json()
+
+        embeddings = [item["embedding"] for item in data["data"]]
+
+        actual_dims = len(embeddings[0]) if embeddings else 0
+        expected_dims = request.dimensions or self.dimensions
+
+        if expected_dims and actual_dims != expected_dims:
+            logger.warning(
+                f"Dimension mismatch: expected {expected_dims}, got {actual_dims}. "
+                f"Model '{data['model']}' may not support custom dimensions."
+            )
+
+        logger.info(
+            f"Successfully generated {len(embeddings)} embeddings "
+            f"(model: {data['model']}, dimensions: {actual_dims})"
+        )
+
+        return EmbeddingResponse(
+            embeddings=embeddings,
+            model=data["model"],
+            dimensions=actual_dims,
+            usage=data.get("usage", {}),
+        )
+
+    def get_model_info(self) -> Dict[str, Any]:
+        model_info = self.MODELS_INFO.get(self.model, self.dimensions)
+
+        if isinstance(model_info, dict):
+            return {
+                "model": self.model,
+                "dimensions": model_info.get("default", self.dimensions),
+                "supported_dimensions": model_info.get("dimensions", []),
+                "supports_variable_dimensions": len(model_info.get("dimensions", [])) > 1,
+                "provider": "openai_compatible",
+            }
+        else:
+            return {
+                "model": self.model,
+                "dimensions": model_info or self.dimensions,
+                "supports_variable_dimensions": False,
+                "provider": "openai_compatible",
+            }