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

hammad/data/types/__init__.py

@@ -5,7 +5,7 @@ by users as bases as well as for type hints. These objects define simple
 interfaces for various types of common objects."""
 
 from typing import TYPE_CHECKING
-from ...performance.imports import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
@@ -24,10 +24,8 @@ __all__ = (
     # hammad.data.types.text
     "BaseText",
     "Text",
-
     # hammad.data.types.file
     "File",
-
     # hammad.data.types.multimodal
     "Audio",
     "Image",

hammad/data/types/file.py

@@ -1,4 +1,4 @@
-"""hammad.types.file"""
+"""hammad.data.types.file"""
 
 from pathlib import Path
 import httpx
@@ -6,8 +6,8 @@ from typing import Any, Self
 import mimetypes
 from urllib.parse import urlparse
 
-from ..models.base.model import Model
-from ..models.base.fields import field
+from ..models.model import Model
+from ..models.fields import field
 
 __all__ = ("File", "FileSource")
 

hammad/data/types/multimodal/__init__.py

@@ -1,10 +1,10 @@
-"""hammad.multimodal
+"""hammad.types.multimodal
 
 Contains types and model like objects for working with various
 types of multimodal data."""
 
 from typing import TYPE_CHECKING
-from ....performance.imports import create_getattr_importer
+from ...._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .image import Image

hammad/data/types/multimodal/audio.py

@@ -1,10 +1,10 @@
-"""hammad.data.types.files.audio"""
+"""hammad.data.types.multimodal.audio"""
 
 import httpx
 from typing import Self
 
 from ...types.file import File, FileSource
-from ...models.base.fields import field
+from ...models.fields import field
 
 __all__ = ("Audio",)
 

hammad/data/types/multimodal/image.py

@@ -1,10 +1,10 @@
-"""hammad.data.types.files.image"""
+"""hammad.data.types.multimodal.image"""
 
 import httpx
 from typing import Self
 
 from ...types.file import File, FileSource
-from ...models.base.fields import field
+from ...models.fields import field
 
 __all__ = ("Image",)
 

hammad/formatting/__init__.py

@@ -1,38 +1,20 @@
-"""hammad.formatting
-
-Contains resources for working with various data structures and formats
-such as JSON, YAML, and text / markdown formatting."""
+"""hammad.formatting"""
 
 from typing import TYPE_CHECKING
-from ..performance.imports import create_getattr_importer
-
+from .._internal import create_getattr_importer
 
 if TYPE_CHECKING:
-    from .json import (
-        convert_to_json_schema,
-        encode_json,
-        decode_json,
-    )
-    from .yaml import (
-        encode_yaml,
-        decode_yaml,
-    )
-
+    from . import json
+    from . import text
+    from . import yaml
 
 __all__ = (
-    # hammad.formatting.json
-    "convert_to_json_schema",
-    "encode_json",
-    "decode_json",
-    # hammad.formatting.yaml
-    "encode_yaml",
-    "decode_yaml",
+    "json",
+    "text",
+    "yaml",
 )
 
-
 __getattr__ = create_getattr_importer(__all__)
 
-
 def __dir__() -> list[str]:
-    """Get the attributes of the formatting module."""
-    return list(__all__)
+    return list(__all__)

hammad/formatting/json/__init__.py

@@ -1,16 +1,22 @@
 """hammad.formatting.json"""
 
 from typing import TYPE_CHECKING
-from ...performance.imports import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .converters import (
         convert_to_json_schema,
+        convert_to_json,
         encode_json,
         decode_json,
     )
 
-__all__ = ("convert_to_json_schema", "encode_json", "decode_json")
+__all__ = (
+    "convert_to_json_schema",
+    "convert_to_json",
+    "encode_json",
+    "decode_json",
+)
 
 
 __getattr__ = create_getattr_importer(__all__)

hammad/formatting/json/converters.py

@@ -1,4 +1,4 @@
-"""hammad.formatting.json.utils
+"""hammad.formatting.json.converters
 
 Contains various utility functions used when working with JSON data."""
 
@@ -150,3 +150,9 @@ def convert_to_json_schema(t: Any) -> dict:
 
     # Default to string representation of type
     return {"type": get_type_description(t)}
+
+
+def convert_to_json(
+    target : Any,
+) -> str:
+    return encode_json(target).decode()

hammad/formatting/text/__init__.py

@@ -3,7 +3,7 @@
 Contains resources for working with text / markdown formatting."""
 
 from typing import TYPE_CHECKING
-from ...performance.imports import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .converters import (

hammad/formatting/yaml/__init__.py

@@ -3,7 +3,7 @@
 Simply extends the `msgspec.yaml` submodule."""
 
 from typing import TYPE_CHECKING
-from ...performance.imports import create_getattr_importer
+from ..._internal import create_getattr_importer
 
 if TYPE_CHECKING:
     from .converters import (

hammad/genai/__init__.py

@@ -0,0 +1,78 @@
+"""hammad.genai"""
+
+from typing import TYPE_CHECKING
+from .._internal import create_getattr_importer
+
+if TYPE_CHECKING:
+    from .embedding_models import (
+        EmbeddingModel,
+        EmbeddingModelRequest,
+        EmbeddingModelResponse,
+        run_embedding_model,
+        async_run_embedding_model
+    )
+    from .language_models import (
+        LanguageModel,
+        LanguageModelRequest,
+        LanguageModelResponse,
+        run_language_model,
+        async_run_language_model,
+    )
+    from .rerank_models import (
+        run_rerank_model,
+        async_run_rerank_model,
+    )
+    from .multimodal_models import (
+        run_image_generation_model,
+        async_run_image_generation_model,
+        run_image_edit_model,
+        async_run_image_edit_model,
+        run_image_variation_model,
+        async_run_image_variation_model,
+
+        run_tts_model,
+        async_run_tts_model,
+        run_transcription_model,
+        async_run_transcription_model,
+    )
+
+
+__all__ = (
+    # hammad.genai.embedding_models
+    "EmbeddingModel",
+    "EmbeddingModelRequest",
+    "EmbeddingModelResponse",
+    "run_embedding_model",
+    "async_run_embedding_model",
+
+    # hammad.genai.language_models
+    "LanguageModel",
+    "LanguageModelRequest",
+    "LanguageModelResponse",
+    "run_language_model",
+    "async_run_language_model",
+
+    # hammad.genai.rerank_models
+    "run_rerank_model",
+    "async_run_rerank_model",
+
+    # hammad.genai.multimodal_models
+    "run_image_generation_model",
+    "async_run_image_generation_model",
+    "run_image_edit_model",
+    "async_run_image_edit_model",
+    "run_image_variation_model",
+    "async_run_image_variation_model",
+    "run_tts_model",
+    "async_run_tts_model",
+    "run_transcription_model",
+    "async_run_transcription_model",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    """Get the attributes of the genai module."""
+    return list(__all__)

hammad/genai/agents/__init__.py

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

hammad/genai/agents/types/__init__.py

@@ -0,0 +1,35 @@
+"""hammad.genai.types
+
+Contains functional types usable with various components within
+the `hammad.genai` module."""
+
+from typing import TYPE_CHECKING
+from ...._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .history import (
+        History,
+    )
+    from .tool import (
+        Tool,
+        ToolResponseMessage,
+        function_tool,
+    )
+
+
+__all__ = (
+    # hammad.genai.types.history
+    "History",
+    # hammad.genai.types.tool
+    "Tool",
+    "function_tool",
+    "ToolResponseMessage",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return __all__

hammad/genai/agents/types/history.py

@@ -0,0 +1,277 @@
+"""hammad.genai.types.history"""
+
+from typing import List, Union, overload, TYPE_CHECKING, Any, Dict
+from typing_extensions import Literal
+import json
+
+if TYPE_CHECKING:
+    try:
+        from openai.types.chat import ChatCompletionMessageParam
+    except ImportError:
+        ChatCompletionMessageParam = Any
+
+from ...language_models import LanguageModelResponse
+from ...language_models._streaming import Stream, AsyncStream
+
+__all__ = ["History"]
+
+
+class History:
+    """A conversation history manager that handles messages and responses.
+    
+    This class provides a clean interface for managing conversation history,
+    including adding messages, responses, and rendering the complete history
+    with optional tool call formatting.
+    """
+    
+    def __init__(self):
+        """Initialize an empty conversation history."""
+        self.messages: List["ChatCompletionMessageParam"] = []
+    
+    @overload
+    def add(self, content: str, *, role: Literal["user", "assistant", "system", "tool"] = "user") -> None:
+        """Add a simple text message to the history.
+        
+        Args:
+            content: The message content
+            role: The role of the message sender
+        """
+        ...
+    
+    @overload
+    def add(self, content: List["ChatCompletionMessageParam"]) -> None:
+        """Add a list of messages to the history.
+        
+        Args:
+            content: List of ChatCompletionMessageParam messages
+        """
+        ...
+    
+    def add(
+        self, 
+        content: Union[str, List["ChatCompletionMessageParam"]], 
+        *, 
+        role: Literal["user", "assistant", "system", "tool"] = "user"
+    ) -> None:
+        """Add content to the conversation history.
+        
+        Args:
+            content: Either a string message or a list of messages
+            role: The role for string messages (ignored for message lists)
+        """
+        if isinstance(content, str):
+            self.messages.append({
+                "role": role,
+                "content": content
+            })
+        elif isinstance(content, list):
+            self.messages.extend(content)
+        else:
+            raise TypeError(f"Expected str or List[ChatCompletionMessageParam], got {type(content)}")
+    
+    def add_message(self, message: "ChatCompletionMessageParam") -> None:
+        """Add a single message to the history.
+        
+        Args:
+            message: A ChatCompletionMessageParam to add
+        """
+        self.messages.append(message)
+    
+    @overload
+    def add_response(
+        self, 
+        response: LanguageModelResponse, 
+        *, 
+        format_tool_calls: bool = False
+    ) -> None:
+        """Add a LanguageModelResponse to the history.
+        
+        Args:
+            response: The language model response to add
+            format_tool_calls: Whether to format tool calls in the message
+        """
+        ...
+    
+    @overload
+    def add_response(
+        self, 
+        response: Stream, 
+        *, 
+        format_tool_calls: bool = False
+    ) -> None:
+        """Add a Stream response to the history after collecting it.
+        
+        Args:
+            response: The stream to collect and add
+            format_tool_calls: Whether to format tool calls in the message
+        """
+        ...
+    
+    @overload
+    def add_response(
+        self, 
+        response: AsyncStream, 
+        *, 
+        format_tool_calls: bool = False
+    ) -> None:
+        """Add an AsyncStream response to the history after collecting it.
+        
+        Args:
+            response: The async stream to collect and add
+            format_tool_calls: Whether to format tool calls in the message
+        """
+        ...
+    
+    def add_response(
+        self, 
+        response: Union[LanguageModelResponse, Stream, AsyncStream],
+        *,
+        format_tool_calls: bool = False
+    ) -> None:
+        """Add a language model response to the history.
+        
+        Args:
+            response: The response, stream, or async stream to add
+            format_tool_calls: Whether to format tool calls in the message content
+        """
+        if isinstance(response, LanguageModelResponse):
+            # Direct response - convert to message
+            message = response.to_message(format_tool_calls=format_tool_calls)
+            self.messages.append(message)
+        elif isinstance(response, (Stream, AsyncStream)):
+            raise RuntimeError(
+                "Cannot add uncollected streams to history. "
+                "Please collect the stream first using stream.collect() or stream.to_response(), "
+                "then add the resulting LanguageModelResponse to history."
+            )
+        else:
+            raise TypeError(
+                f"Expected LanguageModelResponse, Stream, or AsyncStream, got {type(response)}"
+            )
+    
+    def _summarize_content(self, content: str, max_length: int = 100) -> str:
+        """Summarize content by truncating with ellipsis if too long.
+        
+        Args:
+            content: The content to summarize
+            max_length: Maximum length before truncation
+            
+        Returns:
+            Summarized content
+        """
+        if len(content) <= max_length:
+            return content
+        return content[:max_length - 3] + "..."
+    
+    def _format_and_merge_tool_calls(
+        self, 
+        messages: List["ChatCompletionMessageParam"],
+        summarize_tool_calls: bool = True
+    ) -> List["ChatCompletionMessageParam"]:
+        """Format tool calls and merge tool responses into assistant messages.
+        
+        Args:
+            messages: List of messages to process
+            summarize_tool_calls: Whether to summarize tool call content
+            
+        Returns:
+            Formatted messages with tool calls and responses merged
+        """
+        # Create a mapping of tool_call_id to tool response content
+        tool_responses: Dict[str, str] = {}
+        tool_message_indices: List[int] = []
+        
+        for i, message in enumerate(messages):
+            if message.get("role") == "tool":
+                tool_call_id = message.get("tool_call_id")
+                if tool_call_id:
+                    tool_responses[tool_call_id] = message.get("content", "")
+                    tool_message_indices.append(i)
+        
+        # Process messages and format tool calls
+        formatted_messages = []
+        indices_to_skip = set(tool_message_indices)
+        
+        for i, message in enumerate(messages):
+            if i in indices_to_skip:
+                continue
+                
+            if message.get("role") == "assistant" and message.get("tool_calls"):
+                # Create a copy of the message
+                formatted_message = dict(message)
+                
+                # Format tool calls and merge responses
+                content_parts = []
+                if message.get("content"):
+                    content_parts.append(message["content"])
+                
+                for tool_call in message["tool_calls"]:
+                    tool_id = tool_call.get("id")
+                    tool_name = tool_call["function"]["name"]
+                    tool_args = tool_call["function"]["arguments"]
+                    
+                    # Format arguments nicely
+                    try:
+                        args_dict = json.loads(tool_args) if isinstance(tool_args, str) else tool_args
+                        args_str = json.dumps(args_dict, indent=2)
+                    except:
+                        args_str = str(tool_args)
+                    
+                    # Create the tool call section
+                    tool_section = f"I called the function `{tool_name}` with arguments:\n{args_str}"
+                    
+                    # Add tool response if available
+                    if tool_id and tool_id in tool_responses:
+                        response_content = tool_responses[tool_id]
+                        if summarize_tool_calls and len(response_content) > 100:
+                            response_content = self._summarize_content(response_content)
+                        tool_section += f"\n\nResponse: {response_content}"
+                    
+                    content_parts.append(tool_section)
+                
+                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
+    
+    def render(
+        self, 
+        *, 
+        format_tool_calls: bool = False,
+        summarize_tool_calls: bool = True
+    ) -> List["ChatCompletionMessageParam"]:
+        """Render the conversation history as a list of messages.
+        
+        Args:
+            format_tool_calls: Whether to format tool calls in assistant messages
+                             for better readability and merge tool responses
+            summarize_tool_calls: Whether to summarize tool call responses when
+                                format_tool_calls is True (defaults to True)
+        
+        Returns:
+            List of ChatCompletionMessageParam messages
+        """
+        if format_tool_calls:
+            return self._format_and_merge_tool_calls(self.messages, summarize_tool_calls)
+        return self.messages.copy()
+    
+    def clear(self) -> None:
+        """Clear all messages from the history."""
+        self.messages.clear()
+    
+    def __len__(self) -> int:
+        """Return the number of messages in the history."""
+        return len(self.messages)
+    
+    def __bool__(self) -> bool:
+        """Return True if there are messages in the history."""
+        return bool(self.messages)
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the history."""
+        return f"History(messages={len(self.messages)})"