hammad-python 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

hammad/genai/{language_models/_utils → models/language/utils}/__init__.py

@@ -1,22 +1,19 @@
-"""hammad.genai.language_models.utils"""
+"""hammad.genai.models.language.utils"""
 
-from ._completions import (
+from .requests import (
+    format_tool_calls,
+    consolidate_system_messages,
     parse_messages_input,
     handle_completion_request_params,
     handle_completion_response,
+    LanguageModelRequestBuilder,
 )
-from ._structured_outputs import (
+from .structured_outputs import (
     handle_structured_output_request_params,
     prepare_response_model,
     handle_structured_output_response,
 )
-from ._messages import (
-    format_tool_calls,
-    consolidate_system_messages,
-)
-from ._requests import (
-    LanguageModelRequestBuilder,
-)
+
 
 __all__ = [
     "parse_messages_input",
@@ -28,4 +25,4 @@ __all__ = [
     "format_tool_calls",
     "consolidate_system_messages",
     "LanguageModelRequestBuilder",
-]
+]

hammad/genai/models/language/utils/requests.py

@@ -0,0 +1,421 @@
+"""hammad.ai.llms.utils._completions"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Type, Generic, TypeVar
+
+from .....cache import cached
+from .....data.models import (
+    convert_to_pydantic_model,
+    is_pydantic_model_class,
+)
+
+try:
+    from openai.types.chat import ChatCompletionMessageParam
+except ImportError:
+    ChatCompletionMessageParam = Any
+
+from ..types.language_model_messages import LanguageModelMessages
+from ..types.language_model_response import LanguageModelResponse
+from ..types.language_model_request import LanguageModelRequest
+from ..types.language_model_name import LanguageModelName
+from ..types.language_model_instructor_mode import LanguageModelInstructorMode
+
+__all__ = [
+    "format_tool_calls",
+    "consolidate_system_messages",
+    "parse_messages_input",
+    "handle_completion_request_params",
+    "handle_completion_response",
+    "LanguageModelRequestBuilder",
+]
+
+
+T = TypeVar("T")
+
+
+@cached
+def format_tool_calls(
+    messages: List["ChatCompletionMessageParam"],
+) -> List["ChatCompletionMessageParam"]:
+    """Format tool calls in messages for better conversation context.
+
+    Args:
+        messages: List of chat completion messages
+
+    Returns:
+        Messages with formatted tool calls
+    """
+    formatted_messages = []
+
+    for message in messages:
+        if message.get("role") == "assistant" and message.get("tool_calls"):
+            # Create a copy of the message
+            formatted_message = dict(message)
+
+            # Format tool calls into readable content
+            content_parts = []
+            if message.get("content"):
+                content_parts.append(message["content"])
+
+            for tool_call in message["tool_calls"]:
+                formatted_call = (
+                    f"I called the function `{tool_call['function']['name']}` "
+                    f"with the following arguments:\n{tool_call['function']['arguments']}"
+                )
+                content_parts.append(formatted_call)
+
+            formatted_message["content"] = "\n\n".join(content_parts)
+            # Remove tool_calls from the formatted message
+            formatted_message.pop("tool_calls", None)
+
+            formatted_messages.append(formatted_message)
+        else:
+            formatted_messages.append(message)
+
+    return formatted_messages
+
+
+@cached
+def consolidate_system_messages(
+    messages: List["ChatCompletionMessageParam"],
+) -> List["ChatCompletionMessageParam"]:
+    """Consolidate multiple system messages into a single system message.
+
+    Args:
+        messages: List of chat completion messages
+
+    Returns:
+        Messages with consolidated system messages
+    """
+    system_parts = []
+    other_messages = []
+
+    for message in messages:
+        if message.get("role") == "system":
+            if message.get("content"):
+                system_parts.append(message["content"])
+        else:
+            other_messages.append(message)
+
+    # Create consolidated messages
+    consolidated_messages = []
+
+    if system_parts:
+        consolidated_messages.append(
+            {"role": "system", "content": "\n\n".join(system_parts)}
+        )
+
+    consolidated_messages.extend(other_messages)
+
+    return consolidated_messages
+
+
+@cached
+def parse_messages_input(
+    messages: LanguageModelMessages,
+    instructions: Optional[str] = None,
+) -> List["ChatCompletionMessageParam"]:
+    """Parse various message input formats into standardized ChatCompletionMessageParam format.
+
+    Args:
+        messages: Input messages in various formats
+        instructions: Optional system instructions to prepend
+
+    Returns:
+        List of ChatCompletionMessageParam objects
+    """
+    parsed_messages: List["ChatCompletionMessageParam"] = []
+
+    # Add system instructions if provided
+    if instructions:
+        parsed_messages.append({"role": "system", "content": instructions})
+
+    # Handle different input formats
+    if isinstance(messages, str):
+        # Simple string input
+        parsed_messages.append({"role": "user", "content": messages})
+    elif isinstance(messages, dict):
+        # Single message dict
+        parsed_messages.append(messages)
+    elif isinstance(messages, list):
+        # List of messages
+        for msg in messages:
+            if isinstance(msg, dict):
+                parsed_messages.append(msg)
+            elif isinstance(msg, str):
+                parsed_messages.append({"role": "user", "content": msg})
+    else:
+        # Fallback - try to convert to string
+        parsed_messages.append({"role": "user", "content": str(messages)})
+
+    return parsed_messages
+
+
+@cached
+def handle_completion_request_params(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter and process parameters for standard completion requests.
+
+    Args:
+        params: Raw request parameters
+
+    Returns:
+        Filtered parameters suitable for LiteLLM completion
+    """
+    # Remove structured output specific parameters
+    excluded_keys = {
+        "type",
+        "instructor_mode",
+        "response_field_name",
+        "response_field_instruction",
+        "max_retries",
+        "strict",
+    }
+
+    filtered_params = {
+        key: value
+        for key, value in params.items()
+        if key not in excluded_keys and value is not None
+    }
+
+    return filtered_params
+
+
+def handle_completion_response(response: Any, model: str) -> LanguageModelResponse[str]:
+    """Convert a LiteLLM completion response to LanguageModelResponse.
+
+    Args:
+        response: LiteLLM ModelResponse object
+        model: Model name used for the request
+
+    Returns:
+        LanguageModelResponse object with string output
+    """
+    # Extract content from the response
+    content = None
+    tool_calls = None
+    refusal = None
+
+    if hasattr(response, "choices") and response.choices:
+        choice = response.choices[0]
+        if hasattr(choice, "message"):
+            message = choice.message
+            content = getattr(message, "content", None)
+            tool_calls = getattr(message, "tool_calls", None)
+            refusal = getattr(message, "refusal", None)
+
+    return LanguageModelResponse(
+        type="language_model",
+        model=model,
+        output=content or "",
+        completion=response,
+        content=content,
+        tool_calls=tool_calls,
+        refusal=refusal,
+    )
+
+
+class LanguageModelRequestBuilder(Generic[T]):
+    """A request to a language model with comprehensive parameter handling."""
+
+    def __init__(
+        self,
+        messages: LanguageModelMessages,
+        instructions: Optional[str] = None,
+        model: LanguageModelName = "openai/gpt-4o-mini",
+        **kwargs: Any,
+    ):
+        """Initialize a language model request.
+
+        Args:
+            messages: The input messages/content for the request
+            instructions: Optional system instructions to prepend
+            model: The model to use for the request
+            **kwargs: Additional request settings
+        """
+        self.messages = messages
+        self.instructions = instructions
+        self.model = model
+        self.settings = self._build_settings(**kwargs)
+
+        # Validate settings
+        self._validate_settings()
+
+    def _build_settings(self, **kwargs: Any) -> LanguageModelRequest:
+        """Build the complete settings dictionary from kwargs."""
+        settings: LanguageModelRequest = {"model": self.model}
+
+        # Add all provided kwargs to settings
+        for key, value in kwargs.items():
+            if value is not None:
+                settings[key] = value
+
+        return settings
+
+    def _validate_settings(self) -> None:
+        """Validate that the settings are compatible."""
+        # Check if both tools and structured outputs are specified
+        has_tools = any(
+            key in self.settings
+            for key in [
+                "tools",
+                "tool_choice",
+                "parallel_tool_calls",
+                "functions",
+                "function_call",
+            ]
+        )
+
+        has_structured_output = (
+            "type" in self.settings and self.settings["type"] is not str
+        )
+
+        if has_tools and has_structured_output:
+            raise ValueError(
+                "Tools and structured outputs cannot be used together. "
+                "Please specify either tools OR a structured output type, not both."
+            )
+
+    def is_structured_output(self) -> bool:
+        """Check if this request is for structured output."""
+        return "type" in self.settings and self.settings["type"] is not str
+
+    def is_streaming(self) -> bool:
+        """Check if this request is for streaming."""
+        return self.settings.get("stream", False)
+
+    def has_tools(self) -> bool:
+        """Check if this request has tools."""
+        return any(
+            key in self.settings
+            for key in [
+                "tools",
+                "tool_choice",
+                "parallel_tool_calls",
+                "functions",
+                "function_call",
+            ]
+        )
+
+    def get_completion_settings(self) -> Dict[str, Any]:
+        """Get settings filtered for standard completion requests."""
+        excluded_keys = {
+            "type",
+            "instructor_mode",
+            "response_field_name",
+            "response_field_instruction",
+            "response_model_name",
+            "max_retries",
+            "strict",
+            "validation_context",
+            "context",
+            "completion_kwargs_hooks",
+            "completion_response_hooks",
+            "completion_error_hooks",
+            "completion_last_attempt_hooks",
+            "parse_error_hooks",
+        }
+
+        return {
+            key: value
+            for key, value in self.settings.items()
+            if key not in excluded_keys
+        }
+
+    def get_structured_output_settings(self) -> Dict[str, Any]:
+        """Get settings filtered for structured output requests."""
+        excluded_keys = {
+            "tools",
+            "tool_choice",
+            "parallel_tool_calls",
+            "functions",
+            "function_call",
+            "type",
+            "instructor_mode",
+            "response_field_name",
+            "response_field_instruction",
+            "response_model_name",
+            "max_retries",
+            "strict",
+            "validation_context",
+            "context",
+            "completion_kwargs_hooks",
+            "completion_response_hooks",
+            "completion_error_hooks",
+            "completion_last_attempt_hooks",
+            "parse_error_hooks",
+        }
+
+        return {
+            key: value
+            for key, value in self.settings.items()
+            if key not in excluded_keys
+        }
+
+    def get_output_type(self) -> Type[T]:
+        """Get the requested output type."""
+        return self.settings.get("type", str)
+
+    def get_instructor_mode(self) -> LanguageModelInstructorMode:
+        """Get the instructor mode for structured outputs."""
+        return self.settings.get("instructor_mode", "tool_call")
+
+    def get_response_field_name(self) -> str:
+        """Get the response field name for structured outputs."""
+        return self.settings.get("response_field_name", "content")
+
+    def get_response_field_instruction(self) -> str:
+        """Get the response field instruction for structured outputs."""
+        return self.settings.get(
+            "response_field_instruction",
+            "A response in the correct type as requested by the user, or relevant content.",
+        )
+
+    def get_response_model_name(self) -> str:
+        """Get the response model name for structured outputs."""
+        return self.settings.get("response_model_name", "Response")
+
+    def get_max_retries(self) -> int:
+        """Get the maximum retries for structured outputs."""
+        return self.settings.get("max_retries", 3)
+
+    def get_strict_mode(self) -> bool:
+        """Get the strict mode for structured outputs."""
+        return self.settings.get("strict", True)
+
+    def get_validation_context(self) -> Optional[Dict[str, Any]]:
+        """Get the validation context for structured outputs."""
+        return self.settings.get("validation_context")
+
+    def get_context(self) -> Optional[Dict[str, Any]]:
+        """Get the context for structured outputs."""
+        return self.settings.get("context")
+
+    def prepare_pydantic_model(self) -> Optional[Type[Any]]:
+        """Prepare a Pydantic model for structured outputs if needed."""
+        if not self.is_structured_output():
+            return None
+
+        output_type = self.get_output_type()
+
+        if is_pydantic_model_class(output_type):
+            return output_type
+
+        # Convert to Pydantic model
+        return convert_to_pydantic_model(
+            target=output_type,
+            name="Response",
+            field_name=self.get_response_field_name(),
+            description=self.get_response_field_instruction(),
+        )
+
+    def __repr__(self) -> str:
+        """String representation of the request."""
+        return (
+            f"LanguageModelRequest("
+            f"model={self.model}, "
+            f"structured_output={self.is_structured_output()}, "
+            f"streaming={self.is_streaming()}, "
+            f"has_tools={self.has_tools()}"
+            f")"
+        )

hammad/genai/{language_models/_utils/_structured_outputs.py → models/language/utils/structured_outputs.py}

@@ -2,12 +2,12 @@
 
 from typing import Any, Dict, Type, TypeVar
 
-from ....cache import cached
-from ....data.models import (
+from .....cache import cached
+from .....data.models import (
     convert_to_pydantic_model,
     is_pydantic_model_class,
 )
-from ..language_model_response import LanguageModelResponse
+from ..types.language_model_response import LanguageModelResponse
 
 __all__ = [
     "handle_structured_output_request_params",
@@ -21,27 +21,36 @@ T = TypeVar("T")
 @cached
 def handle_structured_output_request_params(params: Dict[str, Any]) -> Dict[str, Any]:
     """Filter and process parameters for structured output requests.
-    
+
     Args:
         params: Raw request parameters
-        
+
     Returns:
         Filtered parameters suitable for Instructor
     """
     # Remove tool-related parameters (not supported with structured outputs)
     # and structured output specific parameters
     excluded_keys = {
-        "tools", "tool_choice", "parallel_tool_calls", 
-        "functions", "function_call",
-        "type", "instructor_mode", "response_field_name", "response_field_instruction",
-        "response_model_name", "max_retries", "strict"
+        "tools",
+        "tool_choice",
+        "parallel_tool_calls",
+        "functions",
+        "function_call",
+        "type",
+        "instructor_mode",
+        "response_field_name",
+        "response_field_instruction",
+        "response_model_name",
+        "max_retries",
+        "strict",
     }
-    
+
     filtered_params = {
-        key: value for key, value in params.items()
+        key: value
+        for key, value in params.items()
         if key not in excluded_keys and value is not None
     }
-    
+
     return filtered_params
 
 
@@ -53,20 +62,20 @@ def prepare_response_model(
     response_model_name: str = "Response",
 ) -> Type[Any]:
     """Prepare a Pydantic model for structured outputs.
-    
+
     Args:
         output_type: The desired output type
         response_field_name: Name of the response field
         response_field_instruction: Description of the response field
         response_model_name: Name of the response model
-        
+
     Returns:
         Pydantic model class suitable for Instructor
     """
     # Check if it's already a Pydantic model
     if is_pydantic_model_class(output_type):
         return output_type
-    
+
     # Convert to Pydantic model
     return convert_to_pydantic_model(
         target=output_type,
@@ -84,19 +93,21 @@ def handle_structured_output_response(
     response_field_name: str = "content",
 ) -> LanguageModelResponse[T]:
     """Convert an Instructor response to LanguageModelResponse.
-    
+
     Args:
         response: The structured response from Instructor
         completion: The raw completion object
         model: Model name used for the request
         output_type: The expected output type
         response_field_name: Name of the response field
-        
+
     Returns:
         LanguageModelResponse object with structured output
     """
     # Extract the actual value if using converted pydantic model
-    if not is_pydantic_model_class(output_type) and hasattr(response, response_field_name):
+    if not is_pydantic_model_class(output_type) and hasattr(
+        response, response_field_name
+    ):
         actual_output = getattr(response, response_field_name)
     else:
         actual_output = response
@@ -105,7 +116,7 @@ def handle_structured_output_response(
     content = None
     tool_calls = None
     refusal = None
-    
+
     if hasattr(completion, "choices") and completion.choices:
         choice = completion.choices[0]
         if hasattr(choice, "message"):
@@ -121,4 +132,4 @@ def handle_structured_output_response(
         content=content,
         tool_calls=tool_calls,
         refusal=refusal,
-    )
+    )

hammad/genai/models/model_provider.py

@@ -0,0 +1,4 @@
+"""hammad.genai.models.model_provider"""
+
+import litellm
+import instructor

hammad/genai/{multimodal_models.py → models/multimodal.py}

@@ -1,10 +1,10 @@
-"""hammad.genai.multimodal_models"""
+"""hammad.genai.models.multimodal"""
 
 # simple litellm refs
 # thanks litellm :)
 
 from typing import TYPE_CHECKING
-from .._internal import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
@@ -16,7 +16,6 @@ if TYPE_CHECKING:
         aimage_edit as async_run_image_edit_model,
         image_variation as run_image_variation_model,
         aimage_variation as async_run_image_variation_model,
-        
         # audio / speech
         speech as run_tts_model,
         aspeech as async_run_tts_model,
@@ -33,7 +32,6 @@ __all__ = (
     "async_run_image_edit_model",
     "run_image_variation_model",
     "async_run_image_variation_model",
-    
     # audio / speech
     "run_tts_model",
     "async_run_tts_model",
@@ -44,5 +42,6 @@ __all__ = (
 
 __getattr__ = create_getattr_importer(__all__)
 
+
 def __dir__() -> list[str]:
-    return list(__all__)    
+    return list(__all__)

hammad/genai/models/reranking.py

@@ -0,0 +1,26 @@
+"""hammad.genai.models.reranking"""
+
+# yay litellm
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from litellm import (
+        rerank as run_reranking_model,
+        arerank as async_run_reranking_model,
+    )
+
+
+__all__ = (
+    "run_reranking_model",
+    "async_run_reranking_model",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)

hammad/genai/types/__init__.py

@@ -0,0 +1 @@
+"""hammad.genai.types"""