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

hammad/genai/language_models/_utils/_requests.py

@@ -0,0 +1,202 @@
+"""hammad.genai.language_models._utils._requests"""
+
+from typing import (
+    Any,
+    Dict,
+    List,
+    Generic,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    TYPE_CHECKING,
+)
+
+from ....data.models import (
+    convert_to_pydantic_model,
+    is_pydantic_model_class,
+)
+
+from .._types import LanguageModelName, LanguageModelInstructorMode
+from ..language_model_request import (
+    LanguageModelMessagesParam,
+    LanguageModelRequest,
+)
+
+__all__ = [
+    "LanguageModelRequestBuilder"
+]
+
+
+T = TypeVar("T")
+
+
+class LanguageModelRequestBuilder(Generic[T]):
+    """A request to a language model with comprehensive parameter handling."""
+    
+    def __init__(
+        self,
+        messages: LanguageModelMessagesParam,
+        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

@@ -0,0 +1,124 @@
+"""hammad.genai.language_models._utils._structured_outputs"""
+
+from typing import Any, Dict, Type, TypeVar
+
+from ....cache import cached
+from ....data.models import (
+    convert_to_pydantic_model,
+    is_pydantic_model_class,
+)
+from ..language_model_response import LanguageModelResponse
+
+__all__ = [
+    "handle_structured_output_request_params",
+    "prepare_response_model",
+    "handle_structured_output_response",
+]
+
+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"
+    }
+    
+    filtered_params = {
+        key: value for key, value in params.items()
+        if key not in excluded_keys and value is not None
+    }
+    
+    return filtered_params
+
+
+@cached
+def prepare_response_model(
+    output_type: Type[T],
+    response_field_name: str = "content",
+    response_field_instruction: str = "A response in the correct type as requested by the user, or relevant content.",
+    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,
+        name=response_model_name,
+        field_name=response_field_name,
+        description=response_field_instruction,
+    )
+
+
+def handle_structured_output_response(
+    response: Any,
+    completion: Any,
+    model: str,
+    output_type: Type[T],
+    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):
+        actual_output = getattr(response, response_field_name)
+    else:
+        actual_output = response
+
+    # Extract content and tool calls from the completion
+    content = None
+    tool_calls = None
+    refusal = None
+    
+    if hasattr(completion, "choices") and completion.choices:
+        choice = completion.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(
+        model=model,
+        output=actual_output,
+        completion=completion,
+        content=content,
+        tool_calls=tool_calls,
+        refusal=refusal,
+    )