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

hammad/genai/language_models/language_model_request.py

@@ -0,0 +1,135 @@
+"""hammad.genai.language_models.language_model_request"""
+
+from typing import (
+    Any,
+    Dict,
+    List,
+    Union,
+    Type,
+    TypeVar,
+    TYPE_CHECKING,
+    TypeAlias,
+    Callable,
+)
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import TypedDict, Required, NotRequired
+else:
+    from typing_extensions import TypedDict, Required, NotRequired
+
+if TYPE_CHECKING:
+    from httpx import Timeout
+    try:
+        from openai.types.chat import (
+            ChatCompletionMessageParam,
+            ChatCompletionModality,
+            ChatCompletionPredictionContentParam,
+            ChatCompletionAudioParam,
+        )
+    except ImportError:
+        ChatCompletionMessageParam = Any
+        ChatCompletionModality = Any
+        ChatCompletionPredictionContentParam = Any
+        ChatCompletionAudioParam = Any
+        
+from ._types import LanguageModelName, LanguageModelInstructorMode
+
+__all__ = [
+    "LanguageModelMessagesParam",
+    "LanguageModelRequest",
+]
+
+T = TypeVar("T")
+
+LanguageModelMessagesParam : TypeAlias = Union[
+    str,
+    "ChatCompletionMessageParam",
+    "List[ChatCompletionMessageParam]",
+    Any,
+]
+"""Type alias for the input parameters of a language model request."""
+
+
+class LanguageModelRequestProviderSettings(TypedDict, total=False):
+    """Provider-specific settings for language model requests."""
+    model: Required[LanguageModelName]
+    base_url: NotRequired[str]
+    api_key: NotRequired[str]
+    api_version: NotRequired[str]
+    organization: NotRequired[str]
+    deployment_id: NotRequired[str]
+    model_list: NotRequired[List[Any]]
+    extra_headers: NotRequired[Dict[str, str]]
+
+
+class LanguageModelRequestStructuredOutputSettings(TypedDict, total=False):
+    """Settings for structured output generation."""
+    type: Required[Type[T]]
+    instructor_mode: NotRequired[LanguageModelInstructorMode]
+    response_field_name: NotRequired[str]
+    response_field_instruction: NotRequired[str]
+    max_retries: NotRequired[int]
+    strict: NotRequired[bool]
+    validation_context: NotRequired[Dict[str, Any]]
+    context: NotRequired[Dict[str, Any]]
+
+
+class LanguageModelRequestToolsSettings(TypedDict, total=False):
+    """Settings for tool usage in language model requests."""
+    tools: NotRequired[List[Any]]
+    tool_choice: NotRequired[Union[str, Dict[str, Any]]]
+    parallel_tool_calls: NotRequired[bool]
+    functions: NotRequired[List[Any]]
+    function_call: NotRequired[str]
+
+
+class LanguageModelRequestStreamingSettings(TypedDict, total=False):
+    """Settings for streaming responses."""
+    stream: Required[bool]
+    stream_options: NotRequired[Dict[str, Any]]
+
+
+class LanguageModelRequestHooksSettings(TypedDict, total=False):
+    """Settings for instructor hooks."""
+    completion_kwargs_hooks: NotRequired[List[Callable[..., None]]]
+    completion_response_hooks: NotRequired[List[Callable[..., None]]]
+    completion_error_hooks: NotRequired[List[Callable[..., None]]]
+    completion_last_attempt_hooks: NotRequired[List[Callable[..., None]]]
+    parse_error_hooks: NotRequired[List[Callable[..., None]]]
+
+
+class LanguageModelRequestExtendedSettings(TypedDict, total=False):
+    """Extended settings for language model requests."""
+    timeout: NotRequired[Union[float, str, "Timeout"]]
+    temperature: NotRequired[float]
+    top_p: NotRequired[float]
+    n: NotRequired[int]
+    stop: NotRequired[str]
+    max_completion_tokens: NotRequired[int]
+    max_tokens: NotRequired[int]
+    modalities: NotRequired[List["ChatCompletionModality"]]
+    prediction: NotRequired["ChatCompletionPredictionContentParam"]
+    audio: NotRequired["ChatCompletionAudioParam"]
+    presence_penalty: NotRequired[float]
+    frequency_penalty: NotRequired[float]
+    logit_bias: NotRequired[Dict[str, float]]
+    user: NotRequired[str]
+    reasoning_effort: NotRequired[str]
+    seed: NotRequired[int]
+    logprobs: NotRequired[bool]
+    top_logprobs: NotRequired[int]
+    thinking: NotRequired[Dict[str, Any]]
+    web_search_options: NotRequired[Dict[str, Any]]
+
+
+class LanguageModelRequest(
+    LanguageModelRequestProviderSettings,
+    LanguageModelRequestStructuredOutputSettings,
+    LanguageModelRequestToolsSettings,
+    LanguageModelRequestStreamingSettings,
+    LanguageModelRequestHooksSettings,
+    LanguageModelRequestExtendedSettings,
+):
+    """Complete settings for language model requests."""
+    pass

hammad/genai/language_models/language_model_response.py

@@ -0,0 +1,219 @@
+"""hammad.genai.language_models.language_model_response"""
+
+from typing import List, TypeVar, Generic, TYPE_CHECKING, Optional, Any, Dict, Union
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    try:
+        import litellm
+        from openai.types.chat import (
+            ChatCompletionContentPartParam,
+            ChatCompletionMessageParam,
+        )
+    except ImportError:
+        ChatCompletionContentPartParam = Any
+        ChatCompletionMessageParam = Any
+
+
+__all__ = [
+    "LanguageModelResponse",
+]
+
+T = TypeVar("T")
+
+
+class LanguageModelResponse(BaseModel, Generic[T]):
+    """A response generated by a language model. This response is unified
+    to represent both standard completions as well as structured outputs."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model: str
+    """The model that generated this response."""
+
+    output: T
+    """The 'final' or primary response content from the language model, this is
+    in the type requested by the user.
+    
+    NOTE:
+    In many cases with tool calling, message content is not present, in these cases
+    this field will **NOT** represent tool calls, and will be returned as `None`."""
+
+    completion: "litellm.ModelResponse"
+    """The raw Chat Completion (`litellm.ModelResponse`) object returned by the
+    language model."""
+
+    content: Optional[str] = None
+    """The actual response content of the completion. This is the string that
+    was generated by the model."""
+
+    tool_calls: Optional[List["litellm.ChatCompletionMessageToolCall"]] = None
+    """The tool calls that were made by the model. This is a list of tool calls
+    that were made by the model."""
+
+    refusal: Optional[str] = None
+    """The refusal message generated by the model. This is the string that
+    was generated by the model when it refused to generate the completion."""
+
+    def get_content(
+        self,
+        choice: int = 0
+    ) -> Union[str, List["ChatCompletionContentPartParam"], None]:
+        """The 'raw' message content generated by the language model, this
+        can be either a string, a list of content parts, or `None`."""
+
+        if not self.completion or not self.completion.choices:
+            return None
+        
+        if choice >= len(self.completion.choices):
+            return None
+            
+        return self.completion.choices[choice].message.content
+
+    def get_tool_calls(
+        self,
+        *,
+        name: Optional[str] = None,
+        id: Optional[str] = None,
+        choice: int = 0
+    ) -> Optional[List["litellm.ChatCompletionMessageToolCall"]]:
+        """The tool calls generated by the language model, this is a list of
+        `ChatCompletionMessageToolCall` objects. Optionally can be filtered
+        by name or ID to return specific tool calls.
+        
+        NOTE: Only one of `name` or `id` can be provided."""
+        if not self.completion or not self.completion.choices:
+            return None
+        
+        if choice >= len(self.completion.choices):
+            return None
+        
+        tool_calls = self.completion.choices[choice].message.tool_calls
+        if not tool_calls:
+            return None
+        
+        # Filter by name or id if provided
+        if name is not None and id is not None:
+            raise ValueError("Only one of 'name' or 'id' can be provided, not both")
+        
+        if name is not None:
+            return [call for call in tool_calls if call.function.name == name]
+        
+        if id is not None:
+            return [call for call in tool_calls if call.id == id]
+        
+        return tool_calls
+
+    def has_tool_calls(
+        self,
+        name: Optional[str] = None,
+        choice: int = 0
+    ) -> bool:
+        """Checks if the response has tool calls, optionally filtered by name.
+        If `name` is provided, it will check if the tool call with that name
+        exists in the response."""
+        if not self.completion or not self.completion.choices:
+            return False
+        
+        tool_calls = self.get_tool_calls(name=name, choice=choice)
+        return tool_calls is not None and len(tool_calls) > 0
+
+    def get_tool_call_parameters(
+        self, 
+        tool: Optional[str] = None,
+        choice: int = 0
+    ) -> Optional[Dict[str, Any]]:
+        """Returns the generated parameters for a tool call within a response. 
+        If the response has multiple tool calls, and no tool is specified, 
+        an error will be raised.
+
+        Args:
+            tool: The name of the tool to get the parameters for.
+            choice: The choice index to get tool calls from.
+
+        Returns:
+            Dict[str, Any]: The generated parameters for the tool call.
+        """
+        tool_calls = self.get_tool_calls(choice=choice)
+        if not tool_calls:
+            return None
+
+        if tool is None:
+            if len(tool_calls) > 1:
+                raise ValueError(
+                    "Multiple tool calls found in response, and no tool specified."
+                )
+            tool = tool_calls[0].function.name
+
+        for tool_call in tool_calls:
+            if tool_call.function.name == tool:
+                import json
+                return json.loads(tool_call.function.arguments)
+        return None
+
+    def to_message(
+        self,
+        format_tool_calls: bool = False,
+        choice: int = 0
+    ) -> "ChatCompletionMessageParam":
+        """Converts the LanguageModelResponse to a Chat Completions
+        message object.
+        
+        If the `format_tool_calls` parameter is True, the tool calls
+        will be cleanly formatted and added to the message content
+        with something similar to:
+            
+        'I called the function `get_weather` with the following arguments:
+        {arguments}'
+        """
+        if not self.completion or not self.completion.choices:
+            return {
+                "role": "assistant",
+                "content": ""
+            }
+        
+        if choice >= len(self.completion.choices):
+            return {
+                "role": "assistant", 
+                "content": ""
+            }
+        
+        choice_message = self.completion.choices[choice].message
+        
+        # Base message structure
+        message: "ChatCompletionMessageParam" = {
+            "role": "assistant",
+            "content": choice_message.content or ""
+        }
+        
+        # Add tool calls if they exist and format_tool_calls is False
+        if choice_message.tool_calls and not format_tool_calls:
+            message["tool_calls"] = choice_message.tool_calls
+        
+        # Format tool calls into content if format_tool_calls is True
+        elif choice_message.tool_calls and format_tool_calls:
+            content_parts = []
+            if choice_message.content:
+                content_parts.append(choice_message.content)
+            
+            for tool_call in choice_message.tool_calls:
+                formatted_call = f"I called the function `{tool_call.function.name}` with the following arguments:\n{tool_call.function.arguments}"
+                content_parts.append(formatted_call)
+            
+            message["content"] = "\n\n".join(content_parts)
+        
+        return message
+
+    def __str__(self) -> str:
+        """Pretty prints the response object."""
+        output = "LanguageModelResponse:"
+
+        if self.output or self.content:
+            output += f"\n{self.output if self.output else self.content}"
+        else:
+            output += f"\n{self.completion}"
+
+        output += f"\n\n>>> Model: {self.model}"
+        output += f"\n>>> Tool Calls: {len(self.tool_calls) if self.tool_calls else 0}"
+
+        return output

hammad/genai/language_models/language_model_response_chunk.py

@@ -0,0 +1,53 @@
+"""hammad.genai.language_models.language_model_response_chunk"""
+
+from typing import TypeVar, Generic, Optional, Any
+from pydantic import BaseModel, ConfigDict
+
+__all__ = [
+    "LanguageModelResponseChunk",
+]
+
+T = TypeVar("T")
+
+
+class LanguageModelResponseChunk(BaseModel, Generic[T]):
+    """Represents a chunk of data from a language model response stream.
+
+    This class unifies chunks from both LiteLLM and Instructor streaming,
+    providing a consistent interface for processing streaming responses.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    content: Optional[str] = None
+    """The content delta for this chunk."""
+
+    output: Optional[T] = None
+    """The structured output for this chunk (from instructor)."""
+
+    model: Optional[str] = None
+    """The model that generated this chunk."""
+
+    finish_reason: Optional[str] = None
+    """The reason the stream finished (if applicable)."""
+
+    chunk: Optional[Any] = None
+    """The original chunk object from the provider."""
+
+    is_final: bool = False
+    """Whether this is the final chunk in the stream."""
+
+    def __bool__(self) -> bool:
+        """Check if this chunk has meaningful content."""
+        return bool(self.content or self.output or self.finish_reason)
+
+    def __str__(self) -> str:
+        """String representation of the chunk."""
+        if self.output:
+            return f"LanguageModelResponseChunk(output={self.output})"
+        elif self.content:
+            return f"LanguageModelResponseChunk(content={repr(self.content)})"
+        elif self.finish_reason:
+            return f"LanguageModelResponseChunk(finish_reason={self.finish_reason})"
+        else:
+            return "LanguageModelResponseChunk(empty)"