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

hammad/ai/completions/utils.py

@@ -1,374 +0,0 @@
-"""hammad.ai.completions.utils"""
-
-import json
-from typing import (
-    Optional,
-    List,
-    Iterator,
-    AsyncIterator,
-    TypeVar,
-    Type,
-    Any,
-)
-
-try:
-    from pydantic import BaseModel
-except ImportError:
-    raise ImportError(
-        "Using completion stream parsing requires the `openai` and `instructor` packages."
-        "Please install with: pip install 'hammad-python[ai]'"
-    )
-
-from ...cache import cached
-from .types import (
-    CompletionsInputParam,
-    ChatCompletionMessageParam,
-    CompletionStream,
-    AsyncCompletionStream,
-    Completion,
-)
-
-T = TypeVar("T", bound=BaseModel)
-
-__all__ = (
-    "parse_completions_input",
-    "create_completion_stream",
-    "create_async_completion_stream",
-    "format_tool_calls",
-    "convert_response_to_completion",
-)
-
-
-@cached
-def parse_completions_input(
-    input: CompletionsInputParam,
-    instructions: Optional[str] = None,
-) -> List[ChatCompletionMessageParam]:
-    """Parse various input formats into a list of ChatCompletionMessageParam.
-
-    This function handles:
-    - Plain strings (converted to user messages)
-    - Strings with message blocks like [system], [user], [assistant]
-    - Single ChatCompletionMessageParam objects
-    - Lists of ChatCompletionMessageParam objects
-    - Objects with model_dump() method
-
-    Args:
-        input: The input to parse
-        instructions: Optional system instructions to prepend
-
-    Returns:
-        List of ChatCompletionMessageParam objects
-    """
-    messages: List[ChatCompletionMessageParam] = []
-
-    # Handle string inputs
-    if isinstance(input, str):
-        # Check if string contains message blocks like [system], [user], [assistant]
-        import re
-
-        # Pattern to match only allowed message blocks (system, user, assistant)
-        pattern = (
-            r"\[(system|user|assistant)\]\s*(.*?)(?=\[(?:system|user|assistant)\]|$)"
-        )
-        matches = re.findall(pattern, input, re.DOTALL | re.IGNORECASE)
-
-        if matches:
-            # Validate that we only have allowed roles
-            allowed_roles = {"system", "user", "assistant"}
-            found_roles = {role.lower() for role, _ in matches}
-
-            if not found_roles.issubset(allowed_roles):
-                invalid_roles = found_roles - allowed_roles
-                raise ValueError(
-                    f"Invalid message roles found: {invalid_roles}. Only 'system', 'user', and 'assistant' are allowed."
-                )
-
-            # Parse message blocks
-            system_contents = []
-
-            for role, content in matches:
-                content = content.strip()
-                if content:
-                    if role.lower() == "system":
-                        system_contents.append(content)
-                    else:
-                        messages.append({"role": role.lower(), "content": content})
-
-            # Combine system contents if any exist
-            if system_contents:
-                combined_system = "\n\n".join(system_contents)
-                if instructions:
-                    combined_system = f"{combined_system}\n\n{instructions}"
-                messages.insert(0, {"role": "system", "content": combined_system})
-            elif instructions:
-                messages.insert(0, {"role": "system", "content": instructions})
-        else:
-            # Plain string - create user message
-            if instructions:
-                messages.append({"role": "system", "content": instructions})
-            messages.append({"role": "user", "content": input})
-
-    # Handle single message object
-    elif hasattr(input, "model_dump"):
-        message_dict = input.model_dump()
-        if instructions:
-            messages.append({"role": "system", "content": instructions})
-        messages.append(message_dict)
-
-    # Handle list of messages
-    elif isinstance(input, list):
-        system_contents = []
-        other_messages = []
-
-        for item in input:
-            if hasattr(item, "model_dump"):
-                msg_dict = item.model_dump()
-            else:
-                msg_dict = item
-
-            if msg_dict.get("role") == "system":
-                system_contents.append(msg_dict.get("content", ""))
-            else:
-                other_messages.append(msg_dict)
-
-        # Combine system messages and instructions
-        if system_contents or instructions:
-            combined_system_parts = []
-            if system_contents:
-                combined_system_parts.extend(system_contents)
-            if instructions:
-                combined_system_parts.append(instructions)
-
-            messages.append(
-                {"role": "system", "content": "\n\n".join(combined_system_parts)}
-            )
-
-        messages.extend(other_messages)
-
-    # Handle single dictionary or other object
-    else:
-        if hasattr(input, "model_dump"):
-            message_dict = input.model_dump()
-        else:
-            message_dict = input
-
-        if instructions:
-            messages.append({"role": "system", "content": instructions})
-        messages.append(message_dict)
-
-    return messages
-
-
-def create_completion_stream(
-    stream: Iterator[Any], output_type: Type[T] = str, model: str | None = None
-) -> CompletionStream[T]:
-    """Create a unified completion stream from a raw stream.
-
-    This function wraps raw streams from both LiteLLM and Instructor
-    into a unified CompletionStream interface. It automatically detects
-    the stream type based on the output_type parameter.
-
-    Args:
-        stream: The raw stream from LiteLLM or Instructor
-        output_type: The expected output type (str for LiteLLM, model class for Instructor)
-        model: The model name for metadata
-
-    Returns:
-        CompletionStream: Unified stream interface
-
-    Examples:
-        # For LiteLLM string completions
-        litellm_stream = litellm.completion(model="gpt-4", messages=messages, stream=True)
-        unified_stream = create_completion_stream(litellm_stream, str, "gpt-4")
-
-        # For Instructor structured outputs
-        instructor_stream = instructor_client.completion(response_model=User, messages=messages, stream=True)
-        unified_stream = create_completion_stream(instructor_stream, User, "gpt-4")
-    """
-    return CompletionStream(stream, output_type, model)
-
-
-def create_async_completion_stream(
-    stream: AsyncIterator[Any], output_type: Type[T] = str, model: str | None = None
-) -> AsyncCompletionStream[T]:
-    """Create a unified async completion stream from a raw async stream.
-
-    This function wraps raw async streams from both LiteLLM and Instructor
-    into a unified AsyncCompletionStream interface. It automatically detects
-    the stream type based on the output_type parameter.
-
-    Args:
-        stream: The raw async stream from LiteLLM or Instructor
-        output_type: The expected output type (str for LiteLLM, model class for Instructor)
-        model: The model name for metadata
-
-    Returns:
-        AsyncCompletionStream: Unified async stream interface
-
-    Examples:
-        ```python
-        # For LiteLLM async string completions
-        litellm_stream = await litellm.acompletion(model="gpt-4", messages=messages, stream=True)
-        unified_stream = create_async_completion_stream(litellm_stream, str, "gpt-4")
-
-        # For Instructor async structured outputs
-        instructor_stream = await instructor_client.acompletion(response_model=User, messages=messages, stream=True)
-        unified_stream = create_async_completion_stream(instructor_stream, User, "gpt-4")
-        ```
-    """
-    return AsyncCompletionStream(stream, output_type, model)
-
-
-def format_tool_calls(
-    messages: List[ChatCompletionMessageParam],
-) -> List[ChatCompletionMessageParam]:
-    """Format message thread by replacing tool call blocks with readable assistant messages.
-
-    This function processes a message thread and replaces sequences of:
-    assistant(with tool_calls) + tool + tool + ... with a single clean assistant message
-    that describes what tools were called and their results.
-
-    Args:
-        messages: List of messages in the conversation thread
-
-    Returns:
-        List[ChatCompletionMessageParam]: Cleaned message thread with tool calls formatted
-
-    Example:
-        ```python
-        messages = [
-            {"role": "user", "content": "What's the weather in NYC?"},
-            {"role": "assistant", "tool_calls": [...]},
-            {"role": "tool", "tool_call_id": "call_1", "content": "Sunny, 72°F"},
-            {"role": "user", "content": "Thanks!"}
-        ]
-
-        formatted = format_tool_calls(messages)
-        # Returns: [
-        #     {"role": "user", "content": "What's the weather in NYC?"},
-        #     {"role": "assistant", "content": "I called get_weather tool with parameters (city=NYC), and got result: Sunny, 72°F"},
-        #     {"role": "user", "content": "Thanks!"}
-        # ]
-        ```
-    """
-    if not messages:
-        return messages
-
-    formatted_messages = []
-    i = 0
-
-    while i < len(messages):
-        current_msg = messages[i]
-
-        # Check if this is an assistant message with tool calls
-        if current_msg.get("role") == "assistant" and current_msg.get("tool_calls"):
-            # Collect all following tool messages
-            tool_results = {}
-            j = i + 1
-
-            # Gather tool results that follow this assistant message
-            while j < len(messages) and messages[j].get("role") == "tool":
-                tool_msg = messages[j]
-                tool_call_id = tool_msg.get("tool_call_id")
-                if tool_call_id:
-                    tool_results[tool_call_id] = tool_msg.get("content", "No result")
-                j += 1
-
-            # Format the tool calls with their results
-            tool_calls = current_msg.get("tool_calls", [])
-            formatted_calls = []
-
-            for tool_call in tool_calls:
-                tool_name = tool_call.function.name
-                tool_args = tool_call.function.arguments
-                tool_id = tool_call.id
-
-                # Parse arguments for cleaner display
-                try:
-                    args_dict = json.loads(tool_args) if tool_args else {}
-                    args_str = ", ".join([f"{k}={v}" for k, v in args_dict.items()])
-                except json.JSONDecodeError:
-                    args_str = tool_args or "no parameters"
-
-                # Get the result for this tool call
-                result = tool_results.get(tool_id, "No result available")
-
-                # Format the tool call description
-                call_description = f"I called {tool_name} tool with parameters ({args_str}), and got result: {result}"
-                formatted_calls.append(call_description)
-
-            # Create the formatted assistant message
-            if len(formatted_calls) == 1:
-                content = formatted_calls[0]
-            elif len(formatted_calls) > 1:
-                content = "I made the following tool calls:\n" + "\n".join(
-                    [f"- {call}" for call in formatted_calls]
-                )
-            else:
-                content = "I made tool calls but no results were available."
-
-            # Add the formatted message
-            formatted_messages.append({"role": "assistant", "content": content})
-
-            # Skip past all the tool messages we processed
-            i = j
-        else:
-            # Regular message, add as-is
-            formatted_messages.append(current_msg)
-            i += 1
-
-    return formatted_messages
-
-
-def convert_response_to_completion(response: Any) -> Completion[str]:
-    """Convert a LiteLLM ModelResponse to a Completion object.
-
-    This function converts LiteLLM's ModelResponse (which is based on OpenAI's
-    ChatCompletion format) into our unified Completion type for standard
-    string completions.
-
-    Args:
-        response: The ModelResponse from LiteLLM
-
-    Returns:
-        Completion[str]: Unified completion object with string output
-
-    Example:
-        ```python
-        # For LiteLLM completions
-        response = await litellm.acompletion(model="gpt-4", messages=messages)
-        completion = convert_response_to_completion(response)
-        ```
-    """
-    # Handle empty or invalid response
-    if not hasattr(response, "choices") or not response.choices:
-        return Completion(
-            output="",
-            model=getattr(response, "model", "unknown"),
-            content=None,
-            completion=response,
-        )
-
-    choice = response.choices[0]
-
-    # Extract message data
-    if hasattr(choice, "message"):
-        message = choice.message
-        content = getattr(message, "content", None)
-        tool_calls = getattr(message, "tool_calls", None)
-        refusal = getattr(message, "refusal", None)
-    else:
-        # Fallback for different response structures
-        content = None
-        tool_calls = None
-        refusal = None
-
-    return Completion(
-        output=content or "",
-        model=getattr(response, "model", "unknown"),
-        content=content,
-        tool_calls=tool_calls,
-        refusal=refusal,
-        completion=response,
-    )

hammad/ai/embeddings/__init__.py

@@ -1,35 +0,0 @@
-"""hammad.ai.embeddings"""
-
-from typing import TYPE_CHECKING
-from ..._core._utils._import_utils import _auto_create_getattr_loader
-
-if TYPE_CHECKING:
-    from .client.base_embeddings_client import BaseEmbeddingsClient
-    from .client.fastembed_text_embeddings_client import FastEmbedTextEmbeddingsClient
-    from .client.litellm_embeddings_client import LiteLlmEmbeddingsClient
-    from .types import Embedding, EmbeddingResponse, EmbeddingUsage
-    from .create import create_embeddings, async_create_embeddings
-
-
-__all__ = (
-    # hammad.ai.embeddings.client.base_embeddings_client
-    "BaseEmbeddingsClient",
-    # hammad.ai.embeddings.client.fastembed_text_embeddings_client
-    "FastEmbedTextEmbeddingsClient",
-    # hammad.ai.embeddings.client.litellm_embeddings_client
-    "LiteLlmEmbeddingsClient",
-    # hammad.ai.embeddings.types
-    "Embedding",
-    "EmbeddingResponse",
-    "EmbeddingUsage",
-    # hammad.ai.embeddings.create
-    "create_embeddings",
-    "async_create_embeddings",
-)
-
-
-__getattr__ = _auto_create_getattr_loader(__all__)
-
-
-def __dir__() -> list[str]:
-    return list(__all__)

hammad/ai/embeddings/client/__init__.py

@@ -1 +0,0 @@
-"""hammad.ai.embeddings.client"""

hammad/ai/embeddings/client/base_embeddings_client.py

@@ -1,26 +0,0 @@
-"""hammad.ai.embeddings.client.base_embeddings_client"""
-
-from abc import ABC, abstractmethod
-
-from ..types import (
-    EmbeddingResponse,
-)
-
-__all__ = ("BaseEmbeddingsClient",)
-
-
-class BaseEmbeddingsClient(ABC):
-    """Base class for the various supported embeddings clients within
-    the `hammad.ai` extension."""
-
-    @staticmethod
-    @abstractmethod
-    def async_embed(input: list, model: str, **kwargs) -> EmbeddingResponse:
-        """"""
-        pass
-
-    @staticmethod
-    @abstractmethod
-    def embed(input: list, model: str, **kwargs) -> EmbeddingResponse:
-        """"""
-        pass

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 ....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,
-        )