hammad-python 0.0.15__py3-none-any.whl → 0.0.17__py3-none-any.whl

hammad/formatting/text/markdown.py

@@ -0,0 +1,131 @@
+"""hammad.formatting.text.markdown"""
+
+from typing import (
+    List,
+    Literal,
+    Optional,
+)
+
+__all__ = (
+    "markdown_bold",
+    "markdown_italic",
+    "markdown_code",
+    "markdown_code_block",
+    "markdown_heading",
+    "markdown_link",
+    "markdown_list_item",
+    "markdown_table_row",
+    "markdown_blockquote",
+    "markdown_horizontal_rule",
+    "markdown_table",
+)
+
+
+def markdown_bold(text: str) -> str:
+    """Format text as bold in Markdown."""
+    return f"**{text}**"
+
+
+def markdown_italic(text: str) -> str:
+    """Format text as italic in Markdown."""
+    return f"*{text}*"
+
+
+def markdown_code(text: str) -> str:
+    """Format text as inline code in Markdown."""
+    return f"`{text}`"
+
+
+def markdown_code_block(text: str, language: str = "") -> str:
+    """Format text as a code block in Markdown."""
+    return f"```{language}\n{text}\n```"
+
+
+def markdown_heading(text: str, level: int = 1) -> str:
+    """Format text as a heading in Markdown."""
+    if not 1 <= level <= 6:
+        level = 1
+    return f"{'#' * level} {text}"
+
+
+def markdown_link(text: str, url: str) -> str:
+    """Format text as a link in Markdown."""
+    return f"[{text}]({url})"
+
+
+def markdown_list_item(
+    text: str, level: int = 0, ordered: bool = False, index: int = 1
+) -> str:
+    """Format text as a list item in Markdown."""
+    indent = "  " * level
+    marker = f"{index}." if ordered else "-"
+    return f"{indent}{marker} {text}"
+
+
+def markdown_table_row(cells: List[str], is_header: bool = False) -> str:
+    """Format a table row in Markdown."""
+    row = "| " + " | ".join(cells) + " |"
+    if is_header:
+        separator = "|" + "|".join([" --- " for _ in cells]) + "|"
+        return f"{row}\n{separator}"
+    return row
+
+
+def markdown_blockquote(text: str, level: int = 1) -> str:
+    """Format text as a blockquote in Markdown."""
+    prefix = ">" * level + " "
+    lines = text.split("\n")
+    return "\n".join(f"{prefix}{line}" for line in lines)
+
+
+def markdown_horizontal_rule() -> str:
+    """Create a horizontal rule in Markdown."""
+    return "---"
+
+
+def markdown_table(
+    headers: List[str],
+    rows: List[List[str]],
+    alignment: Optional[List[Literal["left", "center", "right"]]] = None,
+) -> str:
+    """
+    Create a Markdown table from headers and rows.
+
+    Args:
+        headers: List of header strings
+        rows: List of row data (each row is a list of strings)
+        alignment: Optional list of alignments for each column
+
+    Returns:
+        Formatted Markdown table
+    """
+    if not headers:
+        return ""
+
+    parts = []
+
+    # Add header
+    parts.append("| " + " | ".join(headers) + " |")
+
+    # Add separator with alignment
+    separators = []
+    for i, header in enumerate(headers):
+        if alignment and i < len(alignment):
+            align = alignment[i]
+            if align == "center":
+                separators.append(" :---: ")
+            elif align == "right":
+                separators.append(" ---: ")
+            else:
+                separators.append(" --- ")
+        else:
+            separators.append(" --- ")
+    parts.append("|" + "|".join(separators) + "|")
+
+    # Add rows
+    for row in rows:
+        # Ensure row has same number of columns as headers
+        padded_row = row + [""] * (len(headers) - len(row))
+        parts.append("| " + " | ".join(padded_row[: len(headers)]) + " |")
+
+    return "\n".join(parts)

hammad/formatting/yaml/__init__.py

@@ -0,0 +1,26 @@
+"""hammad.formatting.yaml
+
+Simply extends the `msgspec.yaml` submodule."""
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+if TYPE_CHECKING:
+    from .converters import (
+        encode_yaml,
+        decode_yaml,
+    )
+
+
+__all__ = (
+    "encode_yaml",
+    "decode_yaml",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    """Get the attributes of the yaml module."""
+    return list(__all__)

hammad/formatting/yaml/converters.py

@@ -0,0 +1,5 @@
+"""hammad.formatting.yaml.converters"""
+
+from msgspec.yaml import encode as encode_yaml, decode as decode_yaml
+
+__all__ = ("encode_yaml", "decode_yaml")

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)})"