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

hammad/genai/types/base.py

@@ -0,0 +1,215 @@
+"""hammad.genai.types.base"""
+
+from abc import ABC, abstractmethod
+from typing import (
+    Any,
+    AsyncIterator,
+    Callable,
+    Dict,
+    Iterator,
+    Generic,
+    ParamSpec,
+    TypeVar,
+    TYPE_CHECKING,
+    Union,
+)
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from openai.types.chat import (
+        ChatCompletionMessageParam,
+        ChatCompletionContentPartParam,
+        ChatCompletionMessageParam,
+    )
+
+
+__all__ = [
+    "T",
+    "P",
+    "R",
+    "BaseGenAIModelEvent",
+    "BaseGenAIModelStream",
+    "BaseTool",
+    "BaseGenAIModelResponse",
+    "BaseGenAIModelSettings",
+    "BaseGenAIModel",
+]
+
+
+T = TypeVar("T")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class BaseGenAIModelEvent(BaseModel, Generic[T]):
+    """Base class for all events that a Generative AI model can
+    emit / return.
+
+    This is a base class used only for type hinting and incorporates
+    no fields.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    def to_message(self) -> "ChatCompletionMessageParam":
+        """Converts the event into a message dictionary that is compatible
+        with any message interface within the `hammad.genai` module."""
+        raise NotImplementedError(
+            f"to_message() is not implemented for {self.__class__.__name__}"
+        )
+
+    def to_content_part(self) -> "ChatCompletionContentPartParam":
+        """Converts the event into a content part dictionary that can be added
+        within chat messages."""
+        raise NotImplementedError(
+            f"to_content_part() is not implemented for {self.__class__.__name__}"
+        )
+
+
+class BaseGenAIModelStream(BaseGenAIModelEvent[T]):
+    """Base class for all streams from Generative AI models within the
+    `hammad.genai` module.
+
+    This class manages both sync and async streaming.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    type: str
+    """The type of the model, can be `language_model`, `embedding_model`, 
+    `image_model`..."""
+
+    model: str
+    """The model that was used to generate the stream."""
+
+    stream: Union[Iterator[T], AsyncIterator[T]] | None = None
+    """The streamed content generated by the model."""
+
+    def __iter__(self) -> Iterator[T]:
+        raise NotImplementedError(
+            f"__iter__() is not implemented for {self.__class__.__name__}"
+        )
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        raise NotImplementedError(
+            f"__aiter__() is not implemented for {self.__class__.__name__}"
+        )
+
+
+class BaseTool(BaseModel, Generic[P, R]):
+    """Base class for tools. All generative AI models within the
+    `hammad.genai` module can be converted into tools usable by
+    agents and language models.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    name: str
+    """The name of the tool."""
+
+    description: str
+    """Description of what the tool does."""
+
+    function: Callable[P, R]
+    """The Python function to execute."""
+
+    parameters_json_schema: Dict[str, Any]
+    """JSON schema for the tool's parameters."""
+
+    takes_context: bool = False
+    """Whether the function expects a context as first parameter."""
+
+    strict: bool = True
+    """Whether to enforce strict JSON schema validation."""
+
+
+class BaseGenAIModelResponse(BaseGenAIModelEvent[T]):
+    """Base class for all responses from Generative AI models within the
+    `hammad.genai` module.
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+    )
+
+    type: str
+    """The type of the model, can be `language_model`, `embedding_model`, 
+    `image_model`..."""
+
+    model: str
+    """The model that was used to generate the response."""
+
+    output: T
+    """The final response or output generated by the model. This can be
+    anything from chat messages, embeddings, ..."""
+
+
+class BaseGenAIModelSettings(BaseModel):
+    """Represents the defaults & base for additional settings that
+    can be applied to any model within the `hammad.genai` module.
+    """
+
+
+class BaseGenAIModel(BaseModel, ABC):
+    """Base class for all Generative AI models available within the
+    `hammad.genai` module.
+
+    NOTE:
+    All models within this library use `litellm` directly as the
+    client, if you dont have a need for any of the opinionation
+    given by this package, I would recommend just using
+    `litellm` directly.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="allow")
+
+    model: str | None = None
+    """The model to use. This is always in the `litellm` format:
+    
+    `<provider>/<model>`
+
+    `openai/gpt-4o-mini`
+    `openai/text-embedding-3-small`
+    """
+
+    base_url: str | None = None
+    """A custom base URL to use for the model.
+    """
+
+    api_key: str | None = None
+    """The API key to use for the model.
+    """
+
+    settings: BaseGenAIModelSettings | None = None
+    """The default (additional) settings to use when generating outputs
+    with this model."""
+
+    @abstractmethod
+    def run(
+        self,
+        *args,
+        **kwargs,
+    ) -> Any: ...
+
+    @abstractmethod
+    async def async_run(
+        self,
+        *args,
+        **kwargs,
+    ) -> Any: ...
+
+    def as_tool(
+        self,
+        *args,
+        **kwargs,
+    ) -> BaseTool[P, R]:
+        raise NotImplementedError(
+            f"as_tool() is not implemented for {self.__class__.__name__}"
+        )

hammad/genai/{agents/types → types}/history.py

@@ -10,268 +10,281 @@ if TYPE_CHECKING:
     except ImportError:
         ChatCompletionMessageParam = Any
 
-from ...language_models import LanguageModelResponse
-from ...language_models._streaming import Stream, AsyncStream
+from ..models.language.types import LanguageModelResponse, LanguageModelStream
+from ..agents.types.agent_response import AgentResponse
+from ..agents.types.agent_stream import AgentStream
 
 __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:
+    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"
+        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
-            })
+            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)}")
-    
+            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
+        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
+        self, response: LanguageModelStream, *, 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
+        self, response: AgentResponse, *, format_tool_calls: bool = False
     ) -> None:
-        """Add an AsyncStream response to the history after collecting it.
-        
+        """Add an AgentResponse to the history.
+
+        Args:
+            response: The agent response to add
+            format_tool_calls: Whether to format tool calls in the message
+        """
+        ...
+
+    @overload
+    def add_response(
+        self, response: AgentStream, *, format_tool_calls: bool = False
+    ) -> None:
+        """Add an AgentStream to the history after collecting it.
+
         Args:
-            response: The async stream to collect and add
+            response: The agent 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],
+        self,
+        response: Union[
+            LanguageModelResponse, LanguageModelStream, AgentResponse, AgentStream
+        ],
         *,
-        format_tool_calls: bool = False
+        format_tool_calls: bool = False,
     ) -> None:
-        """Add a language model response to the history.
-        
+        """Add a language model or agent response to the history.
+
         Args:
-            response: The response, stream, or async stream to add
+            response: The response or stream to add
             format_tool_calls: Whether to format tool calls in the message content
         """
-        if isinstance(response, LanguageModelResponse):
+        if isinstance(response, (LanguageModelResponse, AgentResponse)):
             # Direct response - convert to message
             message = response.to_message(format_tool_calls=format_tool_calls)
             self.messages.append(message)
-        elif isinstance(response, (Stream, AsyncStream)):
+        elif isinstance(response, (LanguageModelStream, AgentStream)):
             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."
+                "then add the resulting response to history."
             )
         else:
             raise TypeError(
-                f"Expected LanguageModelResponse, Stream, or AsyncStream, got {type(response)}"
+                f"Expected LanguageModelResponse, AgentResponse, Stream, or AgentStream, 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] + "..."
-    
+        return content[: max_length - 3] + "..."
+
     def _format_and_merge_tool_calls(
-        self, 
+        self,
         messages: List["ChatCompletionMessageParam"],
-        summarize_tool_calls: bool = True
+        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_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
+        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._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)})"