hammad-python 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

hammad/ai/embeddings/client/litellm_embeddings_client.py

@@ -0,0 +1,288 @@
+"""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 ....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

@@ -0,0 +1,159 @@
+"""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,
+        )

hammad/ai/embeddings/types.py

@@ -0,0 +1,69 @@
+"""hammad.ai.embeddings.types"""
+
+from typing import List, Literal
+
+from ...base.model import Model
+
+__all__ = (
+    "Embedding",
+    "EmbeddingUsage",
+    "EmbeddingResponse",
+)
+
+
+class Embedding(Model):
+    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(Model):
+    """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 EmbeddingResponse(Model):
+    data: 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 dimensions(self) -> int:
+        """The dimensions of the embedding."""
+        return len(self.data[0].embedding)
+
+    def __str__(self) -> str:
+        return (
+            "Embedding Response:\n"
+            f">>> Model: {self.model}\n"
+            f">>> Dimensions: {self.dimensions}\n"
+            f">>> Usage: {self.usage}\n"
+            f">>> Number of Generated Embeddings: {len(self.data)}\n"
+        )

hammad/base/__init__.py

@@ -0,0 +1,35 @@
+"""hammad.base
+
+Contains the `Model` and `field` system along with an assortment
+of various utilities for interacting and managing these objects.
+"""
+
+from typing import TYPE_CHECKING
+from .._core._utils._import_utils import _auto_create_getattr_loader
+
+if TYPE_CHECKING:
+    from .model import Model, model_settings
+    from .fields import field, Field, FieldInfo
+    from .utils import create_model, validator, is_field, is_model, get_field_info
+
+__all__ = (
+    # hammad.models.model
+    "Model",
+    "model_settings",
+    # hammad.models.fields
+    "field",
+    "Field",
+    "FieldInfo",
+    # hammad.models.utils
+    "create_model",
+    "validator",
+    "is_field",
+    "is_model",
+    "get_field_info",
+)
+
+__getattr__ = _auto_create_getattr_loader(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/{based → base}/fields.py

@@ -1,4 +1,4 @@
-"""hammad.core.base.fields"""
+"""hammad.base.fields"""
 
 import re
 from dataclasses import dataclass
@@ -9,18 +9,18 @@ import msgspec
 from msgspec import field as msgspec_field
 
 __all__ = (
-    "BasedFieldInfo",
-    "basedfield",
-    "BasedField",
-    "str_basedfield",
-    "int_basedfield",
-    "float_basedfield",
-    "list_basedfield",
+    "FieldInfo",
+    "field",
+    "Field",
+    "str_field",
+    "int_field",
+    "float_field",
+    "list_field",
 )
 
 
 @dataclass(frozen=True, slots=True)
-class BasedFieldInfo:
+class FieldInfo:
     """Immutable field information container optimized for performance.
 
     Uses frozen dataclass with slots for memory efficiency and faster attribute access.
@@ -294,14 +294,14 @@ class BasedFieldInfo:
         return schema
 
 
-class BasedField:
+class Field:
     """Field descriptor that combines msgspec.field with FieldInfo metadata.
 
     This class wraps msgspec's field functionality while preserving our
     extended metadata for validation and serialization.
     """
 
-    def __init__(self, field_info: BasedFieldInfo):
+    def __init__(self, field_info: FieldInfo):
         self.field_info = field_info
         self._msgspec_field = None
 
@@ -330,7 +330,7 @@ class BasedField:
         return f"Field({self.field_info})"
 
 
-def basedfield(
+def field(
     default: Any = msgspec.UNSET,
     *,
     default_factory: Optional[Callable[[], Any]] = None,
@@ -370,7 +370,7 @@ def basedfield(
     pre_validators: Optional[List[Callable[[Any], Any]]] = None,
     post_validators: Optional[List[Callable[[Any], Any]]] = None,
 ) -> Any:
-    """Create a field descriptor for BasedModel with Pydantic-like configuration.
+    """Create a field descriptor for Model with Pydantic-like configuration.
 
     This function creates a field with validation, serialization, and schema
     generation capabilities while maintaining msgspec's performance benefits.
@@ -415,10 +415,10 @@ def basedfield(
         post_validators: List of post-processing validators
 
     Returns:
-        Field descriptor or Annotated type with metadata for use with BasedModel
+        Field descriptor or Annotated type with metadata for use with Model
     """
     # Store field info for potential future use (validation, schema generation, etc.)
-    info = BasedFieldInfo(
+    info = FieldInfo(
         default=default,
         default_factory=default_factory,
         alias=alias,
@@ -472,7 +472,7 @@ def basedfield(
     return msgspec_field_instance
 
 
-def str_basedfield(
+def str_field(
     *,
     min_length: Optional[int] = None,
     max_length: Optional[int] = None,
@@ -483,7 +483,7 @@ def str_basedfield(
     **kwargs,
 ) -> Any:
     """Create a string field with common string-specific options."""
-    return basedfield(
+    return field(
         min_length=min_length,
         max_length=max_length,
         pattern=pattern,
@@ -494,7 +494,7 @@ def str_basedfield(
     )
 
 
-def int_basedfield(
+def int_field(
     *,
     gt: Optional[int] = None,
     ge: Optional[int] = None,
@@ -504,10 +504,10 @@ def int_basedfield(
     **kwargs,
 ) -> Any:
     """Create an integer field with numeric constraints."""
-    return basedfield(gt=gt, ge=ge, lt=lt, le=le, multiple_of=multiple_of, **kwargs)
+    return field(gt=gt, ge=ge, lt=lt, le=le, multiple_of=multiple_of, **kwargs)
 
 
-def float_basedfield(
+def float_field(
     *,
     gt: Optional[float] = None,
     ge: Optional[float] = None,
@@ -518,7 +518,7 @@ def float_basedfield(
     **kwargs,
 ) -> Any:
     """Create a float field with numeric constraints."""
-    return basedfield(
+    return field(
         gt=gt,
         ge=ge,
         lt=lt,
@@ -529,7 +529,7 @@ def float_basedfield(
     )
 
 
-def list_basedfield(
+def list_field(
     *,
     min_length: Optional[int] = None,
     max_length: Optional[int] = None,
@@ -537,7 +537,7 @@ def list_basedfield(
     **kwargs,
 ) -> Any:
     """Create a list field with collection constraints."""
-    return basedfield(
+    return field(
         default_factory=list,
         min_length=min_length,
         max_length=max_length,