hammad-python 0.0.14__py3-none-any.whl → 0.0.15__py3-none-any.whl

hammad/ai/embeddings/client/fastembed_text_embeddings_client.py

@@ -1,200 +0,0 @@
-"""hammad.ai.embeddings.client.fastembed_text_embeddings_client"""
-
-from typing import Any, List, Optional, Union, Literal
-import sys
-
-if sys.version_info >= (3, 12):
-    from typing import TypedDict
-else:
-    from typing_extensions import TypedDict
-
-from .base_embeddings_client import BaseEmbeddingsClient
-from ..types import (
-    Embedding,
-    EmbeddingUsage,
-    EmbeddingResponse,
-)
-from ....formatting.text.converters import convert_to_text
-from ..._utils import (
-    get_fastembed_text_embedding_model,
-)
-
-
-__all__ = (
-    "FastEmbedTextEmbeddingsClient",
-    "FastEmbedTextEmbeddingModel",
-    "FastEmbedTextEmbeddingModelSettings",
-)
-
-
-FastEmbedTextEmbeddingModel = Literal[
-    "BAAI/bge-small-en-v1.5",
-    "BAAI/bge-small-zh-v1.5",
-    "snowflake/snowflake-arctic-embed-xs",
-    "sentence-transformers/all-MiniLM-L6-v2",
-    "jinaai/jina-embeddings-v2-small-en",
-    "BAAI/bge-small-en",
-    "snowflake/snowflake-arctic-embed-s",
-    "nomic-ai/nomic-embed-text-v1.5-Q",
-    "BAAI/bge-base-en-v1.5",
-    "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
-    "Qdrant/clip-ViT-B-32-text",
-    "jinaai/jina-embeddings-v2-base-de",
-    "BAAI/bge-base-en",
-    "snowflake/snowflake-arctic-embed-m",
-    "nomic-ai/nomic-embed-text-v1.5",
-    "jinaai/jina-embeddings-v2-base-en",
-    "nomic-ai/nomic-embed-text-v1",
-    "snowflake/snowflake-arctic-embed-m-long",
-    "mixedbread-ai/mxbai-embed-large-v1",
-    "jinaai/jina-embeddings-v2-base-code",
-    "sentence-transformers/paraphrase-multilingual-mpnet-base-v2",
-    "snowflake/snowflake-arctic-embed-l",
-    "thenlper/gte-large",
-    "BAAI/bge-large-en-v1.5",
-    "intfloat/multilingual-e5-large",
-]
-"""All supported text embedding models supported by `fastembed`."""
-
-
-class FastEmbedTextEmbeddingModelSettings(TypedDict):
-    """Valid settings for the `fastembed` text embedding models."""
-
-    model: FastEmbedTextEmbeddingModel | str
-    parallel: Optional[int]
-    batch_size: Optional[int]
-    format: bool
-
-
-class FastEmbedTextEmbeddingError(Exception):
-    """Exception raised when an error occurs while generating embeddings
-    using `fastembed` text embedding models."""
-
-    def __init__(self, message: str, response: Any):
-        self.message = message
-        self.response = response
-
-
-def _parse_fastembed_response_to_embedding_response(
-    response: Any,
-    model: FastEmbedTextEmbeddingModel | str,
-) -> EmbeddingResponse:
-    """Parse the response from the `fastembed` text embedding model to an `EmbeddingResponse` object."""
-    try:
-        embedding_data: List[Embedding] = []
-
-        # Convert generator to list if needed
-        if hasattr(response, "__iter__") and not isinstance(response, (list, tuple)):
-            response = list(response)
-
-        for i, item in enumerate(response):
-            # Ensure item is a list of floats
-            if hasattr(item, "tolist"):
-                item = item.tolist()
-            elif not isinstance(item, list):
-                item = list(item)
-
-            embedding_data.append(
-                Embedding(embedding=item, index=i, object="embedding")
-            )
-
-        return EmbeddingResponse(
-            data=embedding_data,
-            model=str(model),
-            object="list",
-            usage=EmbeddingUsage(prompt_tokens=0, total_tokens=0),
-        )
-    except Exception as e:
-        raise FastEmbedTextEmbeddingError(
-            f"Failed to parse fastembed response to embedding response: {e}",
-            response,
-        )
-
-
-class FastEmbedTextEmbeddingsClient(BaseEmbeddingsClient):
-    """Client for the `fastembed` text embedding models."""
-
-    @staticmethod
-    def embed(
-        input: List[Any] | Any,
-        model: FastEmbedTextEmbeddingModel | str,
-        parallel: Optional[int] = None,
-        batch_size: Optional[int] = None,
-        format: bool = False,
-        **kwargs: Any,
-    ) -> EmbeddingResponse:
-        """Generate embeddings for the given input using
-        a valid `fastembed` text embedding model.
-
-        Args:
-            input (List[Any] | Any) : The input text / content to generate embeddings for.
-            model (FastEmbedTextEmbeddingModel | str) : The model to use for generating embeddings.
-            parallel (Optional[int]) : The number of parallel processes to use for the embedding.
-            batch_size (Optional[int]) : The batch size to use for the embedding.
-            format (bool) : Whether to format each non-string input as a markdown string.
-            **kwargs : Any : Additional keyword arguments to pass to the `fastembed` text embedding model.
-
-        Returns:
-            EmbeddingResponse : The embedding response from the `fastembed` text embedding model.
-        """
-        if not isinstance(input, list):
-            input = [input]
-
-        if format:
-            for i in input:
-                try:
-                    i = convert_to_text(i)
-                except Exception as e:
-                    raise FastEmbedTextEmbeddingError(
-                        f"Failed to format input to text: {e}",
-                        i,
-                    )
-
-        model = get_fastembed_text_embedding_model(model)
-
-        try:
-            response = model.embed(
-                documents=input,
-                parallel=parallel,
-                batch_size=batch_size,
-                **kwargs,
-            )
-        except Exception as e:
-            raise FastEmbedTextEmbeddingError(
-                f"Failed to generate embeddings: {e}",
-                input,
-            )
-
-        return _parse_fastembed_response_to_embedding_response(response, str(model))
-
-    @staticmethod
-    async def async_embed(
-        input: List[Any] | Any,
-        model: FastEmbedTextEmbeddingModel | str,
-        parallel: Optional[int] = None,
-        batch_size: Optional[int] = None,
-        format: bool = False,
-        **kwargs: Any,
-    ) -> EmbeddingResponse:
-        """Async generate embeddings for the given input using
-        a valid `fastembed` text embedding model.
-
-        Args:
-            input (List[Any] | Any) : The input text / content to generate embeddings for.
-            model (FastEmbedTextEmbeddingModel | str) : The model to use for generating embeddings.
-            parallel (Optional[int]) : The number of parallel processes to use for the embedding.
-            batch_size (Optional[int]) : The batch size to use for the embedding.
-            format (bool) : Whether to format each non-string input as a markdown string.
-            **kwargs : Any : Additional keyword arguments to pass to the `fastembed` text embedding model.
-
-        Returns:
-            EmbeddingResponse : The embedding response from the `fastembed` text embedding model.
-        """
-        return FastEmbedTextEmbeddingsClient.embed(
-            input=input,
-            model=model,
-            parallel=parallel,
-            batch_size=batch_size,
-            format=format,
-            **kwargs,
-        )

hammad/ai/embeddings/client/litellm_embeddings_client.py

@@ -1,288 +0,0 @@
-"""hammad.ai.embeddings.client.litellm_embeddings_client"""
-
-from typing import Any, List, Literal, Optional
-import sys
-
-if sys.version_info >= (3, 12):
-    from typing import TypedDict
-else:
-    from typing_extensions import TypedDict
-
-
-from .base_embeddings_client import BaseEmbeddingsClient
-from ..types import (
-    Embedding,
-    EmbeddingUsage,
-    EmbeddingResponse,
-)
-from ....formatting.text.converters import convert_to_text
-from ..._utils import get_litellm
-
-__all__ = (
-    "LiteLlmEmbeddingsClient",
-    "LiteLlmEmbeddingModel",
-    "LiteLlmEmbeddingModelSettings",
-)
-
-
-LiteLlmEmbeddingModel = Literal[
-    # OpenAI Embedding Models
-    "text-embedding-3-small",
-    "text-embedding-3-large",
-    "text-embedding-ada-002",
-    # OpenAI Compatible Embedding Models
-    "openai/text-embedding-3-small",
-    "openai/text-embedding-3-large",
-    "openai/text-embedding-ada-002",
-    # Bedrock Embedding Models
-    "amazon.titan-embed-text-v1",
-    "cohere.embed-english-v3",
-    "cohere.embed-multilingual-v3",
-    # Cohere Embedding Models
-    "embed-english-v3.0",
-    "embed-english-light-v3.0",
-    "embed-multilingual-v3.0",
-    "embed-multilingual-light-v3.0",
-    "embed-english-v2.0",
-    "embed-english-light-v2.0",
-    "embed-multilingual-v2.0",
-    # NVIDIA NIM Embedding Models
-    "nvidia_nim/NV-Embed-QA",
-    "nvidia_nim/nvidia/nv-embed-v1",
-    "nvidia_nim/nvidia/nv-embedqa-mistral-7b-v2",
-    "nvidia_nim/nvidia/nv-embedqa-e5-v5",
-    "nvidia_nim/nvidia/embed-qa-4",
-    "nvidia_nim/nvidia/llama-3.2-nv-embedqa-1b-v1",
-    "nvidia_nim/nvidia/llama-3.2-nv-embedqa-1b-v2",
-    "nvidia_nim/snowflake/arctic-embed-l",
-    "nvidia_nim/baai/bge-m3",
-    # HuggingFace Embedding Models
-    "huggingface/microsoft/codebert-base",
-    "huggingface/BAAI/bge-large-zh",
-    # Mistral AI Embedding Models
-    "mistral/mistral-embed",
-    # Gemini AI Embedding Models
-    "gemini/text-embedding-004",
-    # Vertex AI Embedding Models
-    "vertex_ai/textembedding-gecko",
-    "vertex_ai/textembedding-gecko-multilingual",
-    "vertex_ai/textembedding-gecko-multilingual@001",
-    "vertex_ai/textembedding-gecko@001",
-    "vertex_ai/textembedding-gecko@003",
-    "vertex_ai/text-embedding-preview-0409",
-    "vertex_ai/text-multilingual-embedding-preview-0409",
-    # Voyage AI Embedding Models
-    "voyage/voyage-01",
-    "voyage/voyage-lite-01",
-    "voyage/voyage-lite-01-instruct",
-    # Nebius AI Studio Embedding Models
-    "nebius/BAAI/bge-en-icl",
-    "nebius/BAAI/bge-multilingual-gemma2",
-    "nebius/intfloat/e5-mistral-7b-instruct",
-    # Ollama Embedding Models
-    "ollama/granite-embedding:30m",
-    "ollama/granite-embedding:278m",
-    "ollama/snowflake-arctic-embed2",
-    "ollama/bge-large",
-    "ollama/paraphrase-multilingual",
-    "ollama/bge-m3",
-    "ollama/snowflake-arctic-embed",
-    "ollama/mxbai-embed-large",
-    "ollama/all-minilm",
-    "ollama/nomic-embed-text",
-]
-"""Common embedding models supported by `litellm`."""
-
-
-class LiteLlmEmbeddingModelSettings(TypedDict):
-    """Valid settings for the `litellm` embedding models."""
-
-    model: LiteLlmEmbeddingModel | str
-    dimensions: Optional[int]
-    encoding_format: Optional[str]
-    timeout: Optional[int]
-    api_base: Optional[str]
-    api_version: Optional[str]
-    api_key: Optional[str]
-    api_type: Optional[str]
-    caching: bool
-    user: Optional[str]
-
-
-class LiteLlmEmbeddingError(Exception):
-    """Exception raised when an error occurs while generating embeddings
-    using `litellm`."""
-
-    def __init__(self, message: str, response: Any):
-        self.message = message
-        self.response = response
-        super().__init__(self.message)
-
-
-def _parse_litellm_response_to_embedding_response(response: Any) -> EmbeddingResponse:
-    """Parse the response from `litellm` to an `EmbeddingResponse` object."""
-    try:
-        embedding_data: List[Embedding] = []
-
-        for i, item in enumerate(response.data):
-            embedding_data.append(
-                Embedding(embedding=item["embedding"], index=i, object="embedding")
-            )
-        usage = EmbeddingUsage(
-            prompt_tokens=response.usage.prompt_tokens,
-            total_tokens=response.usage.total_tokens,
-        )
-        return EmbeddingResponse(
-            data=embedding_data,
-            model=response.model,
-            object="list",
-            usage=usage,
-        )
-    except Exception as e:
-        raise LiteLlmEmbeddingError(
-            f"Failed to parse litellm response to embedding response: {e}",
-            response,
-        )
-
-
-class LiteLlmEmbeddingsClient(BaseEmbeddingsClient):
-    """Embeddings provider client that utilizes the `litellm` module
-    when generating embeddings."""
-
-    @staticmethod
-    async def async_embed(
-        input: List[Any] | Any,
-        model: LiteLlmEmbeddingModel | str,
-        dimensions: Optional[int] = None,
-        encoding_format: Optional[str] = None,
-        timeout=600,
-        api_base: Optional[str] = None,
-        api_version: Optional[str] = None,
-        api_key: Optional[str] = None,
-        api_type: Optional[str] = None,
-        caching: bool = False,
-        user: Optional[str] = None,
-        format: bool = False,
-    ) -> Embedding:
-        """Asynchronously generate embeddings for the given input using
-        a valid `litellm` model.
-
-        Args:
-            input (List[Any] | Any) : The input text / content to generate embeddings for.
-            model (LiteLlmEmbeddingModel | str) : The model to use for generating embeddings.
-            dimensions (Optional[int]) : The number of dimensions for the embedding.
-            encoding_format (Optional[str]) : The format to return the embeddings in. (e.g. "float", "base64")
-            timeout (int) : The timeout for the request.
-            api_base (Optional[str]) : The base URL for the API.
-            api_version (Optional[str]) : The version of the API.
-            api_key (Optional[str]) : The API key to use for the request.
-            api_type (Optional[str]) : The API type to use for the request.
-            caching (bool) : Whether to cache the request.
-            user (Optional[str]) : The user to use for the request.
-            format (bool) : Whether to format each non-string input as a markdown string.
-
-        Returns:
-            Embedding : The embedding generated for the given input.
-        """
-        if not isinstance(input, list):
-            input = [input]
-
-        if format:
-            for i in input:
-                try:
-                    i = convert_to_text(i)
-                except Exception as e:
-                    raise LiteLlmEmbeddingError(
-                        f"Failed to format input to text: {e}",
-                        i,
-                    )
-
-        async_embedding_fn = get_litellm().aembedding
-
-        try:
-            response = await async_embedding_fn(
-                model=model,
-                input=input,
-                dimensions=dimensions,
-                encoding_format=encoding_format,
-                timeout=timeout,
-                api_base=api_base,
-                api_version=api_version,
-                api_key=api_key,
-                api_type=api_type,
-                caching=caching,
-                user=user,
-            )
-        except Exception as e:
-            raise e
-
-        return _parse_litellm_response_to_embedding_response(response)
-
-    @staticmethod
-    def embed(
-        input: List[Any] | Any,
-        model: LiteLlmEmbeddingModel | str,
-        dimensions: Optional[int] = None,
-        encoding_format: Optional[str] = None,
-        timeout=600,
-        api_base: Optional[str] = None,
-        api_version: Optional[str] = None,
-        api_key: Optional[str] = None,
-        api_type: Optional[str] = None,
-        caching: bool = False,
-        user: Optional[str] = None,
-        format: bool = False,
-    ) -> Embedding:
-        """Generate embeddings for the given input using
-        a valid `litellm` model.
-
-        Args:
-            input (List[Any] | Any) : The input text / content to generate embeddings for.
-            model (LiteLlmEmbeddingModel | str) : The model to use for generating embeddings.
-            dimensions (Optional[int]) : The number of dimensions for the embedding.
-            encoding_format (Optional[str]) : The format to return the embeddings in. (e.g. "float", "base64")
-            timeout (int) : The timeout for the request.
-            api_base (Optional[str]) : The base URL for the API.
-            api_version (Optional[str]) : The version of the API.
-            api_key (Optional[str]) : The API key to use for the request.
-            api_type (Optional[str]) : The API type to use for the request.
-            caching (bool) : Whether to cache the request.
-            user (Optional[str]) : The user to use for the request.
-            format (bool) : Whether to format each non-string input as a markdown string.
-
-        Returns:
-            Embedding : The embedding generated for the given input.
-        """
-        if not isinstance(input, list):
-            input = [input]
-
-        if format:
-            for i in input:
-                try:
-                    i = convert_to_text(i)
-                except Exception as e:
-                    raise LiteLlmEmbeddingError(
-                        f"Failed to format input to text: {e}",
-                        i,
-                    )
-
-        sync_embedding_fn = get_litellm().embedding
-
-        try:
-            response = sync_embedding_fn(
-                model=model,
-                input=input,
-                dimensions=dimensions,
-                encoding_format=encoding_format,
-                timeout=timeout,
-                api_base=api_base,
-                api_version=api_version,
-                api_key=api_key,
-                api_type=api_type,
-                caching=caching,
-                user=user,
-            )
-        except Exception as e:
-            raise e
-
-        return _parse_litellm_response_to_embedding_response(response)

hammad/ai/embeddings/create.py

@@ -1,159 +0,0 @@
-"""hammad.ai.embeddings.create"""
-
-from typing import Any, List, Optional
-
-from .types import (
-    EmbeddingResponse,
-)
-from .client.fastembed_text_embeddings_client import (
-    FastEmbedTextEmbeddingsClient,
-    FastEmbedTextEmbeddingModel,
-    FastEmbedTextEmbeddingModelSettings,
-)
-from .client.litellm_embeddings_client import (
-    LiteLlmEmbeddingsClient,
-    LiteLlmEmbeddingModel,
-)
-
-
-__all__ = ("async_create_embeddings", "create_embeddings")
-
-
-async def async_create_embeddings(
-    input: List[Any] | Any,
-    model: FastEmbedTextEmbeddingModel | LiteLlmEmbeddingModel | str,
-    format: bool = False,
-    # LiteLLM Settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: Optional[int] = None,
-    api_base: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_type: Optional[str] = None,
-    caching: bool = False,
-    user: Optional[str] = None,
-    # FastEmbed Settings
-    parallel: Optional[int] = None,
-    batch_size: Optional[int] = None,
-    **kwargs: Any,
-) -> EmbeddingResponse:
-    """Asynchronously create embeddings for the given input using the specified model.
-
-    Args:
-        input (List[Any] | Any) : The input text / content to generate embeddings for.
-        model (FastEmbedTextEmbeddingModel | LiteLlmEmbeddingModel | str) : The model to use for generating embeddings.
-        format (bool) : Whether to format each non-string input as a markdown string.
-        dimensions (Optional[int]) : The dimensions of the embedding. NOTE: LiteLLM models only
-        encoding_format (Optional[str]) : The encoding format of the embedding. NOTE: LiteLLM models only
-        timeout (Optional[int]) : The timeout for the embedding. NOTE: LiteLLM models only
-        api_base (Optional[str]) : The base URL for the embedding API. NOTE: LiteLLM models only
-        api_version (Optional[str]) : The version of the embedding API. NOTE: LiteLLM models only
-        api_key (Optional[str]) : The API key for the embedding API. NOTE: LiteLLM models only
-        api_type (Optional[str]) : The type of the embedding API. NOTE: LiteLLM models only
-        caching (bool) : Whether to cache the embedding. NOTE: LiteLLM models only
-        user (Optional[str]) : The user for the embedding. NOTE: LiteLLM models only
-        parallel (Optional[int]) : The number of parallel processes to use for the embedding. NOTE: FastEmbed models only
-        batch_size (Optional[int]) : The batch size to use for the embedding. NOTE: FastEmbed models only
-        **kwargs : Any : Additional keyword arguments to pass to the embedding client.
-
-    Returns:
-        EmbeddingResponse : The embedding response from the embedding client.
-    """
-
-    if model.startswith("fastembed/"):
-        model = model.split("fastembed/")[1]
-        return await FastEmbedTextEmbeddingsClient.async_embed(
-            input=input,
-            model=model,
-            parallel=parallel,
-            batch_size=batch_size,
-            format=format,
-            **kwargs,
-        )
-    else:
-        return await LiteLlmEmbeddingsClient.async_embed(
-            input=input,
-            model=model,
-            dimensions=dimensions,
-            encoding_format=encoding_format,
-            timeout=timeout,
-            api_base=api_base,
-            api_version=api_version,
-            api_key=api_key,
-            api_type=api_type,
-            caching=caching,
-            user=user,
-            format=format,
-            **kwargs,
-        )
-
-
-def create_embeddings(
-    input: List[Any] | Any,
-    model: FastEmbedTextEmbeddingModel | LiteLlmEmbeddingModel | str,
-    format: bool = False,
-    # LiteLLM Settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: Optional[int] = None,
-    api_base: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_type: Optional[str] = None,
-    caching: bool = False,
-    user: Optional[str] = None,
-    # FastEmbed Settings
-    parallel: Optional[int] = None,
-    batch_size: Optional[int] = None,
-    **kwargs: Any,
-) -> EmbeddingResponse:
-    """Asynchronously create embeddings for the given input using the specified model.
-
-    Args:
-        input (List[Any] | Any) : The input text / content to generate embeddings for.
-        model (FastEmbedTextEmbeddingModel | LiteLlmEmbeddingModel | str) : The model to use for generating embeddings.
-        format (bool) : Whether to format each non-string input as a markdown string.
-        dimensions (Optional[int]) : The dimensions of the embedding. NOTE: LiteLLM models only
-        encoding_format (Optional[str]) : The encoding format of the embedding. NOTE: LiteLLM models only
-        timeout (Optional[int]) : The timeout for the embedding. NOTE: LiteLLM models only
-        api_base (Optional[str]) : The base URL for the embedding API. NOTE: LiteLLM models only
-        api_version (Optional[str]) : The version of the embedding API. NOTE: LiteLLM models only
-        api_key (Optional[str]) : The API key for the embedding API. NOTE: LiteLLM models only
-        api_type (Optional[str]) : The type of the embedding API. NOTE: LiteLLM models only
-        caching (bool) : Whether to cache the embedding. NOTE: LiteLLM models only
-        user (Optional[str]) : The user for the embedding. NOTE: LiteLLM models only
-        parallel (Optional[int]) : The number of parallel processes to use for the embedding. NOTE: FastEmbed models only
-        batch_size (Optional[int]) : The batch size to use for the embedding. NOTE: FastEmbed models only
-        **kwargs : Any : Additional keyword arguments to pass to the embedding client.
-
-    Returns:
-        EmbeddingResponse : The embedding response from the embedding client.
-    """
-
-    if model.startswith("fastembed/"):
-        model = model.split("fastembed/")[1]
-        return FastEmbedTextEmbeddingsClient.embed(
-            input=input,
-            model=model,
-            parallel=parallel,
-            batch_size=batch_size,
-            format=format,
-            **kwargs,
-        )
-    else:
-        return LiteLlmEmbeddingsClient.embed(
-            input=input,
-            model=model,
-            dimensions=dimensions,
-            encoding_format=encoding_format,
-            timeout=timeout,
-            api_base=api_base,
-            api_version=api_version,
-            api_key=api_key,
-            api_type=api_type,
-            caching=caching,
-            user=user,
-            format=format,
-            **kwargs,
-        )