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

hammad/genai/{language_models → models/language}/run.py

@@ -3,47 +3,57 @@
 Standalone functions for running language models with full parameter typing.
 """
 
-from typing import Any, List, TypeVar, Union, Optional, Type, overload, Dict, TYPE_CHECKING, Callable
+from typing import (
+    Any,
+    List,
+    TypeVar,
+    Union,
+    Optional,
+    Type,
+    overload,
+    Dict,
+    TYPE_CHECKING,
+    Callable,
+)
 from typing_extensions import Literal
 
 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
-from .language_model import LanguageModel
-from .language_model_request import LanguageModelMessagesParam
-from .language_model_response import LanguageModelResponse
-from ._streaming import Stream, AsyncStream
+    from openai.types.chat import (
+        ChatCompletionModality,
+        ChatCompletionPredictionContentParam,
+        ChatCompletionAudioParam,
+    )
+
+    from .types import (
+        LanguageModelMessages,
+        LanguageModelInstructorMode,
+        LanguageModelName,
+        LanguageModelResponse,
+        LanguageModelStream,
+    )
+
+from .model import LanguageModel
+
 
 __all__ = [
     "run_language_model",
     "async_run_language_model",
 ]
 
+
 T = TypeVar("T")
 
 
 # Overloads for run_language_model - String output, non-streaming
 @overload
 def run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -51,6 +61,7 @@ def run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Streaming settings
     stream: Literal[False] = False,
     stream_options: Optional[Dict[str, Any]] = None,
@@ -81,17 +92,17 @@ def run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> LanguageModelResponse[str]: ...
+) -> "LanguageModelResponse[str]": ...
 
 
 # Overloads for run_language_model - String output, streaming
 @overload
 def run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -99,6 +110,7 @@ def run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Streaming settings
     stream: Literal[True],
     stream_options: Optional[Dict[str, Any]] = None,
@@ -129,17 +141,17 @@ def run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> Stream[str]: ...
+) -> "LanguageModelStream[str]": ...
 
 
 # Overloads for run_language_model - Structured output, non-streaming
 @overload
 def run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -147,6 +159,7 @@ def run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Structured output settings
     type: Type[T],
     instructor_mode: Optional[LanguageModelInstructorMode] = "tool_call",
@@ -192,17 +205,17 @@ def run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> LanguageModelResponse[T]: ...
+) -> "LanguageModelResponse[T]": ...
 
 
 # Overloads for run_language_model - Structured output, streaming
 @overload
 def run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -210,6 +223,7 @@ def run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Structured output settings
     type: Type[T],
     instructor_mode: Optional[LanguageModelInstructorMode] = "tool_call",
@@ -255,42 +269,45 @@ def run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> Stream[T]: ...
+) -> "LanguageModelStream[T]": ...
 
 
 def run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
+    mock_response: Optional[bool] = None,
     **kwargs: Any,
-) -> Union[LanguageModelResponse[Any], Stream[Any]]:
+) -> Union["LanguageModelResponse[Any]", "LanguageModelStream[Any]"]:
     """Run a language model request with full parameter support.
-    
+
     Args:
         messages: The input messages/content for the request
         instructions: Optional system instructions to prepend
         **kwargs: All request parameters from LanguageModelRequest
-        
+
     Returns:
         LanguageModelResponse or Stream depending on parameters
     """
     # Extract model parameter or use default
     model = kwargs.pop("model", "openai/gpt-4o-mini")
-    
+
     # Create language model instance
     language_model = LanguageModel(model=model)
-    
+
     # Forward to the instance method
-    return language_model.run(messages, instructions, **kwargs)
+    return language_model.run(
+        messages, instructions, mock_response=mock_response, **kwargs
+    )
 
 
 # Async overloads for async_run_language_model - String output, non-streaming
 @overload
 async def async_run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -328,17 +345,17 @@ async def async_run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> LanguageModelResponse[str]: ...
+) -> "LanguageModelResponse[str]": ...
 
 
 # Async overloads for async_run_language_model - String output, streaming
 @overload
 async def async_run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -346,6 +363,7 @@ async def async_run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Streaming settings
     stream: Literal[True],
     stream_options: Optional[Dict[str, Any]] = None,
@@ -376,17 +394,17 @@ async def async_run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> AsyncStream[str]: ...
+) -> "LanguageModelStream[str]": ...
 
 
 # Async overloads for async_run_language_model - Structured output, non-streaming
 @overload
 async def async_run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -394,6 +412,7 @@ async def async_run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Structured output settings
     type: Type[T],
     instructor_mode: Optional[LanguageModelInstructorMode] = "tool_call",
@@ -439,17 +458,17 @@ async def async_run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> LanguageModelResponse[T]: ...
+) -> "LanguageModelResponse[T]": ...
 
 
 # Async overloads for async_run_language_model - Structured output, streaming
 @overload
 async def async_run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
     *,
     # Provider settings
-    model: LanguageModelName = "openai/gpt-4o-mini",
+    model: "LanguageModelName" = "openai/gpt-4o-mini",
     base_url: Optional[str] = None,
     api_key: Optional[str] = None,
     api_version: Optional[str] = None,
@@ -457,6 +476,7 @@ async def async_run_language_model(
     deployment_id: Optional[str] = None,
     model_list: Optional[List[Any]] = None,
     extra_headers: Optional[Dict[str, str]] = None,
+    mock_response: Optional[bool] = None,
     # Structured output settings
     type: Type[T],
     instructor_mode: Optional[LanguageModelInstructorMode] = "tool_call",
@@ -502,29 +522,32 @@ async def async_run_language_model(
     parallel_tool_calls: Optional[bool] = None,
     functions: Optional[List[Any]] = None,
     function_call: Optional[str] = None,
-) -> AsyncStream[T]: ...
+) -> "LanguageModelStream[T]": ...
 
 
 async def async_run_language_model(
-    messages: LanguageModelMessagesParam,
+    messages: "LanguageModelMessages",
     instructions: Optional[str] = None,
+    mock_response: Optional[bool] = None,
     **kwargs: Any,
-) -> Union[LanguageModelResponse[Any], AsyncStream[Any]]:
+) -> Union["LanguageModelResponse[Any]", "LanguageModelStream[Any]"]:
     """Run an async language model request with full parameter support.
-    
+
     Args:
         messages: The input messages/content for the request
         instructions: Optional system instructions to prepend
         **kwargs: All request parameters from LanguageModelRequest
-        
+
     Returns:
         LanguageModelResponse or AsyncStream depending on parameters
     """
     # Extract model parameter or use default
     model = kwargs.pop("model", "openai/gpt-4o-mini")
-    
+
     # Create language model instance
     language_model = LanguageModel(model=model)
-    
+
     # Forward to the instance method
-    return await language_model.async_run(messages, instructions, **kwargs)
+    return await language_model.async_run(
+        messages, instructions, mock_response=mock_response, **kwargs
+    )

hammad/genai/models/language/types/__init__.py

@@ -0,0 +1,40 @@
+"""hammad.genai.models.language.types"""
+
+from typing import TYPE_CHECKING
+from ....._internal import create_getattr_importer
+
+if TYPE_CHECKING:
+    from .language_model_instructor_mode import LanguageModelInstructorMode
+    from .language_model_messages import LanguageModelMessages
+    from .language_model_name import LanguageModelName
+    from .language_model_request import LanguageModelRequest
+    from .language_model_response import LanguageModelResponse
+    from .language_model_response_chunk import LanguageModelResponseChunk
+    from .language_model_settings import LanguageModelSettings
+    from .language_model_stream import LanguageModelStream
+
+__all__ = [
+    # hammad.genai.models.language.types.language_model_instructor_mode
+    "LanguageModelInstructorMode",
+    # hammad.genai.models.language.types.language_model_messages
+    "LanguageModelMessages",
+    # hammad.genai.models.language.types.language_model_name
+    "LanguageModelName",
+    # hammad.genai.models.language.types.language_model_request
+    "LanguageModelRequest",
+    # hammad.genai.models.language.types.language_model_response
+    "LanguageModelResponse",
+    # hammad.genai.models.language.types.language_model_response_chunk
+    "LanguageModelResponseChunk",
+    # hammad.genai.models.language.types.language_model_settings
+    "LanguageModelSettings",
+    # hammad.genai.models.language.types.language_model_stream
+    "LanguageModelStream",
+]
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return __all__

hammad/genai/models/language/types/language_model_instructor_mode.py

@@ -0,0 +1,47 @@
+"""hammad.genai.models.language.types.language_model_instructor_mode"""
+
+from typing import (
+    TypeAlias,
+    Literal,
+)
+
+
+__all__ = [
+    "LanguageModelInstructorMode",
+]
+
+
+LanguageModelInstructorMode: TypeAlias = Literal[
+    "function_call",
+    "parallel_tool_call",
+    "tool_call",
+    "tools_strict",
+    "json_mode",
+    "json_o1",
+    "markdown_json_mode",
+    "json_schema_mode",
+    "anthropic_tools",
+    "anthropic_reasoning_tools",
+    "anthropic_json",
+    "mistral_tools",
+    "mistral_structured_outputs",
+    "vertexai_tools",
+    "vertexai_json",
+    "vertexai_parallel_tools",
+    "gemini_json",
+    "gemini_tools",
+    "genai_tools",
+    "genai_structured_outputs",
+    "cohere_tools",
+    "cohere_json_object",
+    "cerebras_tools",
+    "cerebras_json",
+    "fireworks_tools",
+    "fireworks_json",
+    "writer_tools",
+    "bedrock_tools",
+    "bedrock_json",
+    "perplexity_json",
+    "openrouter_structured_outputs",
+]
+"""Instructor prompt/parsing mode for structured outputs."""

hammad/genai/models/language/types/language_model_messages.py

@@ -0,0 +1,28 @@
+"""hammad.genai.models.language.types.language_model_messages"""
+
+from typing import (
+    TypeAlias,
+    Union,
+    Any,
+    List,
+    TYPE_CHECKING,
+)
+
+if TYPE_CHECKING:
+    from openai.types.chat import (
+        ChatCompletionMessageParam,
+    )
+
+
+__all__ = [
+    "LanguageModelMessages",
+]
+
+
+LanguageModelMessages: TypeAlias = Union[
+    str,
+    "ChatCompletionMessageParam",
+    "List[ChatCompletionMessageParam]",
+    Any,
+]
+"""Type alias for the input parameters of a language model request."""

hammad/genai/{language_models/_types.py → models/language/types/language_model_name.py}

@@ -1,4 +1,4 @@
-"""hammad.genai.language_models._types"""
+"""hammad.genai.models.language.types.language_model_name"""
 
 from typing import (
     TypeAlias,
@@ -7,48 +7,11 @@ from typing import (
 
 
 __all__ = [
-    "LanguageModelInstructorMode",
     "LanguageModelName",
 ]
 
 
-LanguageModelInstructorMode : TypeAlias = Literal[
-    "function_call",
-    "parallel_tool_call",
-    "tool_call",
-    "tools_strict",
-    "json_mode",
-    "json_o1",
-    "markdown_json_mode",
-    "json_schema_mode",
-    "anthropic_tools",
-    "anthropic_reasoning_tools",
-    "anthropic_json",
-    "mistral_tools",
-    "mistral_structured_outputs",
-    "vertexai_tools",
-    "vertexai_json",
-    "vertexai_parallel_tools",
-    "gemini_json",
-    "gemini_tools",
-    "genai_tools",
-    "genai_structured_outputs",
-    "cohere_tools",
-    "cohere_json_object",
-    "cerebras_tools",
-    "cerebras_json",
-    "fireworks_tools",
-    "fireworks_json",
-    "writer_tools",
-    "bedrock_tools",
-    "bedrock_json",
-    "perplexity_json",
-    "openrouter_structured_outputs",
-]
-"""Instructor prompt/parsing mode for structured outputs."""
-
-
-LanguageModelName : TypeAlias = Literal[
+LanguageModelName: TypeAlias = Literal[
     "anthropic/claude-3-7-sonnet-latest",
     "anthropic/claude-3-5-haiku-latest",
     "anthropic/claude-3-5-sonnet-latest",
@@ -273,4 +236,4 @@ LanguageModelName : TypeAlias = Literal[
     "xai/grok-3-latest",
 ]
 """Helper alias for various compatible models usable with litellm
-completions."""
+completions."""

hammad/genai/{language_models → models/language/types}/language_model_request.py

@@ -8,7 +8,6 @@ from typing import (
     Type,
     TypeVar,
     TYPE_CHECKING,
-    TypeAlias,
     Callable,
 )
 import sys
@@ -20,39 +19,26 @@ else:
 
 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
+    from openai.types.chat import (
+        ChatCompletionModality,
+        ChatCompletionPredictionContentParam,
+        ChatCompletionAudioParam,
+    )
+
+from .language_model_name import LanguageModelName
+from .language_model_instructor_mode import 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."""
+T = TypeVar("T")
 
 
 class LanguageModelRequestProviderSettings(TypedDict, total=False):
     """Provider-specific settings for language model requests."""
+
     model: Required[LanguageModelName]
     base_url: NotRequired[str]
     api_key: NotRequired[str]
@@ -65,6 +51,7 @@ class LanguageModelRequestProviderSettings(TypedDict, total=False):
 
 class LanguageModelRequestStructuredOutputSettings(TypedDict, total=False):
     """Settings for structured output generation."""
+
     type: Required[Type[T]]
     instructor_mode: NotRequired[LanguageModelInstructorMode]
     response_field_name: NotRequired[str]
@@ -77,6 +64,7 @@ class LanguageModelRequestStructuredOutputSettings(TypedDict, total=False):
 
 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]
@@ -86,12 +74,14 @@ class LanguageModelRequestToolsSettings(TypedDict, total=False):
 
 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]]]
@@ -101,6 +91,7 @@ class LanguageModelRequestHooksSettings(TypedDict, total=False):
 
 class LanguageModelRequestExtendedSettings(TypedDict, total=False):
     """Extended settings for language model requests."""
+
     timeout: NotRequired[Union[float, str, "Timeout"]]
     temperature: NotRequired[float]
     top_p: NotRequired[float]
@@ -132,4 +123,5 @@ class LanguageModelRequest(
     LanguageModelRequestExtendedSettings,
 ):
     """Complete settings for language model requests."""
-    pass
+
+    pass