hammad-python 0.0.29__py3-none-any.whl → 0.0.31__py3-none-any.whl

hammad/genai/models/embeddings/model.py

@@ -1,226 +0,0 @@
-"""hammad.genai.embedding_models.embedding_model"""
-
-import asyncio
-from dataclasses import dataclass, field
-from typing import Any, List, Optional
-import sys
-
-if sys.version_info >= (3, 12):
-    from typing import TypedDict
-else:
-    from typing_extensions import TypedDict
-
-from ..model_provider import litellm
-
-from .types import (
-    EmbeddingModelName,
-    EmbeddingModelRunParams,
-    EmbeddingModelSettings,
-    Embedding,
-    EmbeddingUsage,
-    EmbeddingModelResponse,
-)
-from ....formatting.text import convert_to_text
-
-
-__all__ = (
-    "EmbeddingModel",
-    "EmbeddingModelError",
-    "create_embedding_model",
-)
-
-
-class EmbeddingModelError(Exception):
-    """Exception raised when an error occurs while generating embeddings
-    using an embedding model."""
-
-    def __init__(self, message: str, response: Any):
-        self.message = message
-        self.response = response
-        super().__init__(self.message)
-
-
-def _parse_litellm_response_to_embedding_model_response(
-    response: "litellm.EmbeddingResponse",
-) -> EmbeddingModelResponse:
-    """Parse the response from `litellm` to an `EmbeddingModelResponse` 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 EmbeddingModelResponse(
-            output=embedding_data,
-            model=response.model,
-            object="list",
-            usage=usage,
-            type="embedding_model",
-        )
-    except Exception as e:
-        raise EmbeddingModelError(
-            f"Failed to parse litellm response to embedding response: {e}",
-            response,
-        )
-
-
-@dataclass
-class EmbeddingModel:
-    """Embeddings provider client that utilizes the `litellm` module
-    when generating embeddings."""
-
-    model: EmbeddingModelName | str = "openai/text-embedding-3-small"
-
-    base_url: Optional[str] = None
-    """Optional base URL for a custom embedding provider."""
-
-    api_key: Optional[str] = None
-    """Optional API key for a custom embedding provider."""
-
-    api_type: Optional[str] = None
-    """Optional API type for a custom embedding provider."""
-
-    api_version: Optional[str] = None
-    """Optional API version for a custom embedding provider."""
-
-    settings: EmbeddingModelSettings = field(default_factory=EmbeddingModelSettings)
-    """Optional settings for the embedding model."""
-
-    async def async_run(
-        self,
-        input: List[Any] | Any,
-        dimensions: Optional[int] = None,
-        encoding_format: Optional[str] = None,
-        timeout=600,
-        caching: bool = False,
-        user: Optional[str] = None,
-        format: bool = False,
-    ) -> EmbeddingModelResponse:
-        """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.
-            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:
-            EmbeddingModelResponse : The embedding response 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 EmbeddingModelError(
-                        f"Failed to format input to text: {e}",
-                        i,
-                    )
-
-        async_embedding_fn = litellm.aembedding
-
-        try:
-            response = await async_embedding_fn(
-                model=self.model,
-                input=input,
-                dimensions=dimensions or self.settings.dimensions,
-                encoding_format=encoding_format or self.settings.encoding_format,
-                timeout=timeout or self.settings.timeout,
-                api_base=self.base_url or self.settings.api_base,
-                api_version=self.api_version or self.settings.api_version,
-                api_key=self.api_key or self.settings.api_key,
-                api_type=self.api_type or self.settings.api_type,
-                caching=caching or self.settings.caching,
-                user=user or self.settings.user,
-            )
-        except Exception as e:
-            raise EmbeddingModelError(
-                f"Error in embedding model request: {e}", response=None
-            ) from e
-
-        return _parse_litellm_response_to_embedding_model_response(response)
-
-    def run(
-        self,
-        input: List[Any] | Any,
-        dimensions: Optional[int] = None,
-        encoding_format: Optional[str] = None,
-        timeout=600,
-        caching: bool = False,
-        user: Optional[str] = None,
-        format: bool = False,
-    ) -> EmbeddingModelResponse:
-        """Generate embeddings for the given input using
-        a valid `litellm` model.
-
-        Args:
-            input (List[Any] | Any) : The input text / content to generate embeddings for.
-            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:
-            EmbeddingModelResponse : The embedding response generated for the given input.
-        """
-        return asyncio.run(
-            self.async_run(
-                input=input,
-                dimensions=dimensions,
-                encoding_format=encoding_format,
-                timeout=timeout,
-                caching=caching,
-                user=user,
-                format=format,
-            )
-        )
-
-
-def create_embedding_model(
-    model: str | EmbeddingModelName = "openai/text-embedding-3-small",
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_type: Optional[str] = None,
-    settings: Optional[EmbeddingModelSettings] = None,
-) -> EmbeddingModel:
-    """Create an embedding model instance.
-
-    Args:
-        model (str | EmbeddingModelName) : The model to use for the embedding.
-        base_url (Optional[str]) : The base URL for the API.
-        api_key (Optional[str]) : The API key to use for the request.
-        api_version (Optional[str]) : The version of the API.
-        api_type (Optional[str]) : The API type to use for the request.
-        settings (Optional[EmbeddingModelSettings]) : The settings for the embedding model.
-    """
-    return EmbeddingModel(
-        model=model,
-        base_url=base_url,
-        api_key=api_key,
-        api_version=api_version,
-        api_type=api_type,
-        settings=settings or EmbeddingModelSettings(),
-    )

hammad/genai/models/embeddings/run.py

@@ -1,163 +0,0 @@
-"""hammad.genai.embedding_models.run
-
-Standalone functions for running embedding models with full parameter typing.
-"""
-
-from typing import Any, List, Optional, overload, Union
-
-from .types import (
-    EmbeddingModelName,
-    EmbeddingModelResponse,
-)
-from .model import EmbeddingModel
-
-__all__ = [
-    "run_embedding_model",
-    "async_run_embedding_model",
-]
-
-
-# Overloads for run_embedding_model
-@overload
-def run_embedding_model(
-    input: List[Any] | Any,
-    *,
-    # Provider settings
-    model: EmbeddingModelName = "openai/text-embedding-3-small",
-    api_base: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_type: Optional[str] = None,
-    # Extended settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: int = 600,
-    caching: bool = False,
-    user: Optional[str] = None,
-    format: bool = False,
-) -> EmbeddingModelResponse: ...
-
-
-def run_embedding_model(
-    input: List[Any] | Any,
-    *,
-    # Provider settings
-    model: EmbeddingModelName = "openai/text-embedding-3-small",
-    api_base: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_type: Optional[str] = None,
-    # Extended settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: int = 600,
-    caching: bool = False,
-    user: Optional[str] = None,
-    format: bool = False,
-) -> EmbeddingModelResponse:
-    """Run an embedding model with the given input.
-
-    Args:
-        input: The input text/content to generate embeddings for
-        model: The embedding model to use
-        api_base: The base URL for the API
-        api_key: The API key to use for the request
-        api_version: The version of the API
-        api_type: The API type to use for the request
-        dimensions: The number of dimensions for the embedding
-        encoding_format: The format to return the embeddings in
-        timeout: The timeout for the request
-        caching: Whether to cache the request
-        user: The user to use for the request
-        format: Whether to format each non-string input as a markdown string
-
-    Returns:
-        EmbeddingModelResponse: The embedding response
-    """
-    embedding_model = EmbeddingModel(model=model)
-    return embedding_model.run(
-        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,
-        format=format,
-    )
-
-
-# Overloads for async_run_embedding_model
-@overload
-async def async_run_embedding_model(
-    input: List[Any] | Any,
-    *,
-    # Provider settings
-    model: EmbeddingModelName = "openai/text-embedding-3-small",
-    api_base: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_type: Optional[str] = None,
-    # Extended settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: int = 600,
-    caching: bool = False,
-    user: Optional[str] = None,
-    format: bool = False,
-) -> EmbeddingModelResponse: ...
-
-
-async def async_run_embedding_model(
-    input: List[Any] | Any,
-    *,
-    # Provider settings
-    model: EmbeddingModelName = "openai/text-embedding-3-small",
-    api_base: Optional[str] = None,
-    api_key: Optional[str] = None,
-    api_version: Optional[str] = None,
-    api_type: Optional[str] = None,
-    # Extended settings
-    dimensions: Optional[int] = None,
-    encoding_format: Optional[str] = None,
-    timeout: int = 600,
-    caching: bool = False,
-    user: Optional[str] = None,
-    format: bool = False,
-) -> EmbeddingModelResponse:
-    """Asynchronously run an embedding model with the given input.
-
-    Args:
-        input: The input text/content to generate embeddings for
-        model: The embedding model to use
-        api_base: The base URL for the API
-        api_key: The API key to use for the request
-        api_version: The version of the API
-        api_type: The API type to use for the request
-        dimensions: The number of dimensions for the embedding
-        encoding_format: The format to return the embeddings in
-        timeout: The timeout for the request
-        caching: Whether to cache the request
-        user: The user to use for the request
-        format: Whether to format each non-string input as a markdown string
-
-    Returns:
-        EmbeddingModelResponse: The embedding response
-    """
-    embedding_model = EmbeddingModel(model=model)
-    return await embedding_model.async_run(
-        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,
-        format=format,
-    )

hammad/genai/models/embeddings/types/__init__.py

@@ -1,37 +0,0 @@
-"""hammad.genai.models.embeddings.types"""
-
-from typing import TYPE_CHECKING
-from ....._internal import create_getattr_importer
-
-
-if TYPE_CHECKING:
-    from .embedding_model_name import EmbeddingModelName
-    from .embedding_model_run_params import EmbeddingModelRunParams
-    from .embedding_model_response import (
-        Embedding,
-        EmbeddingUsage,
-        EmbeddingModelResponse,
-    )
-    from .embedding_model_settings import EmbeddingModelSettings
-
-
-__all__ = [
-    # hammad.genai.models.embeddings.types.embedding_model_name
-    "EmbeddingModelName",
-    # hammad.genai.models.embeddings.types.embedding_model_run_params
-    "EmbeddingModelRunParams",
-    # hammad.genai.models.embeddings.types.embedding_model_response
-    "Embedding",
-    "EmbeddingUsage",
-    "EmbeddingModelResponse",
-    # hammad.genai.models.embeddings.types.embedding_model_settings
-    "EmbeddingModelSettings",
-]
-
-
-__getattr__ = create_getattr_importer(__all__)
-
-
-def __dir__() -> list[str]:
-    """Return the list of attributes to be shown in the REPL."""
-    return __all__

hammad/genai/models/embeddings/types/embedding_model_name.py

@@ -1,75 +0,0 @@
-"""hammad.genai.embedding_models.embedding_model_name"""
-
-from typing import Literal
-
-
-__all__ = ("EmbeddingModelName",)
-
-
-EmbeddingModelName = 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`."""

hammad/genai/models/embeddings/types/embedding_model_response.py

@@ -1,76 +0,0 @@
-"""hammad.genai.embedding_models.embedding_model_response"""
-
-from typing import List, Literal
-
-from pydantic import BaseModel
-
-from ....types.base import BaseGenAIModelResponse
-
-__all__ = (
-    "Embedding",
-    "EmbeddingUsage",
-    "EmbeddingResponse",
-)
-
-
-class Embedding(BaseModel):
-    embedding: List[float]
-    """The embedding vector, which is a list of floats.
-
-    The length of vector depends on the model as listed in the
-    [embedding guide](https://platform.openai.com/docs/guides/embeddings).
-    """
-
-    index: int
-    """The index of the embedding in the list of embeddings."""
-
-    object: Literal["embedding"]
-    """The object type, which is always "embedding"."""
-
-    @property
-    def dimensions(self) -> int:
-        """The dimensions of the embedding."""
-        return len(self.embedding)
-
-
-class EmbeddingUsage(BaseModel):
-    """Usage statistics for embedding requests."""
-
-    prompt_tokens: int
-    """The number of tokens used by the prompt."""
-
-    total_tokens: int
-    """The total number of tokens used by the request."""
-
-
-class EmbeddingModelResponse(BaseGenAIModelResponse[List[Embedding]]):
-    output: List[Embedding]
-    """The list of embeddings generated by the model."""
-
-    model: str
-    """The name of the model used to generate the embedding."""
-
-    object: Literal["list"]
-    """The object type, which is always "list"."""
-
-    usage: EmbeddingUsage
-    """The usage information for the request."""
-
-    @property
-    def data(self) -> List[Embedding]:
-        """The list of embeddings generated by the model."""
-        return self.output
-
-    @property
-    def dimensions(self) -> int:
-        """The dimensions of the embedding."""
-        return len(self.output[0].embedding)
-
-    def __str__(self) -> str:
-        return (
-            "EmbeddingModelResponse:\n"
-            f">>> Model: {self.model}\n"
-            f">>> Dimensions: {self.dimensions}\n"
-            f">>> Usage: {self.usage}\n"
-            f">>> Number of Generated Embeddings: {len(self.output)}\n"
-        )

hammad/genai/models/embeddings/types/embedding_model_run_params.py

@@ -1,66 +0,0 @@
-"""hammad.genai.embedding_models.embedding_model_run_params"""
-
-import sys
-
-if sys.version_info >= (3, 12):
-    from typing import TypedDict, Required, NotRequired
-else:
-    from typing_extensions import TypedDict, Required, NotRequired
-
-from typing import (
-    Any,
-    Dict,
-    List,
-    Optional,
-    Type,
-    TypeVar,
-    Union,
-    Literal,
-)
-
-from .embedding_model_name import EmbeddingModelName
-
-__all__ = [
-    "EmbeddingModelRunParams",
-]
-
-
-class EmbeddingModelRunParams(TypedDict, total=False):
-    """A request to an embedding model."""
-
-    input: List[Any] | Any
-    """The input items to embed."""
-
-    model: EmbeddingModelName | str
-    """The embedding model to use."""
-
-    format: bool = False
-    """Whether to format each non-string input as a markdown string."""
-
-    # LiteLLM Settings
-    dimensions: Optional[int] = None
-    """The dimensions of the embedding."""
-
-    encoding_format: Optional[str] = None
-    """The encoding format of the embedding."""
-
-    timeout: Optional[int] = None
-    """The timeout for the embedding request."""
-
-    api_base: Optional[str] = None
-    """The API base for the embedding request."""
-
-    api_version: Optional[str] = None
-    """The API version for the embedding request."""
-
-    api_key: Optional[str] = None
-    """The API key for the embedding request."""
-
-    api_type: Optional[str] = None
-    """The API type for the embedding request."""
-
-    caching: bool = False
-    """Whether to cache the embedding request."""
-
-    user: Optional[str] = None
-    """The user for the embedding request."""

hammad/genai/models/embeddings/types/embedding_model_settings.py

@@ -1,47 +0,0 @@
-"""hammad.genai.models.embeddings.types.embedding_model_settings"""
-
-from pydantic import BaseModel
-from typing import Any, List, Optional
-
-from .embedding_model_name import EmbeddingModelName
-from ....types.base import BaseGenAIModelSettings
-
-
-__all__ = [
-    "EmbeddingModelSettings",
-]
-
-
-class EmbeddingModelSettings(BaseGenAIModelSettings):
-    """A request to an embedding model."""
-
-    format: bool = False
-    """Whether to format each non-string input as a markdown string."""
-
-    # LiteLLM Settings
-    dimensions: Optional[int] = None
-    """The dimensions of the embedding."""
-
-    encoding_format: Optional[str] = None
-    """The encoding format of the embedding."""
-
-    timeout: Optional[int] = None
-    """The timeout for the embedding request."""
-
-    api_base: Optional[str] = None
-    """The API base for the embedding request."""
-
-    api_version: Optional[str] = None
-    """The API version for the embedding request."""
-
-    api_key: Optional[str] = None
-    """The API key for the embedding request."""
-
-    api_type: Optional[str] = None
-    """The API type for the embedding request."""
-
-    caching: bool = False
-    """Whether to cache the embedding request."""
-
-    user: Optional[str] = None
-    """The user for the embedding request."""