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

hammad/genai/agents/types/agent_event.py

@@ -0,0 +1,128 @@
+"""hammad.genai.agents.types.agent_event"""
+
+from typing import Any, Dict, Optional, Literal
+from openai.types.chat import ChatCompletionMessageParam, ChatCompletionContentPartParam
+
+from ...types.base import BaseGenAIModelEvent
+
+
+__all__ = [
+    "AgentEvent",
+]
+
+
+class AgentEvent(BaseGenAIModelEvent[Any]):
+    """Base class for all agent events with universal event checking.
+
+    This class extends BaseGenAIModelEvent to provide agent-specific
+    event handling capabilities.
+    """
+
+    type: Literal["agent"] = "agent"
+    """The type of the model. Always 'agent'."""
+
+    model: str = "agent"
+    """The model that generated this event."""
+
+    output: Any = None
+    """The event data/output."""
+
+    event_type: str
+    """The specific type of event (e.g., 'context_update', 'tool_call', etc.)."""
+
+    metadata: Dict[str, Any] = {}
+    """Additional metadata for the event."""
+
+    def __init__(
+        self,
+        event_type: str,
+        data: Any = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ):
+        """Initialize an AgentEvent.
+
+        Args:
+            event_type: The type of event
+            data: The event data
+            metadata: Additional metadata
+            **kwargs: Additional keyword arguments
+        """
+        super().__init__(
+            output=data, event_type=event_type, metadata=metadata or {}, **kwargs
+        )
+
+    def is_event(self, event_type: str) -> bool:
+        """Universal event type checker."""
+        return self.event_type == event_type
+
+    def is_event_category(self, category: str) -> bool:
+        """Check if event belongs to a category (e.g., 'tool' matches 'tool_call', 'tool_execution')."""
+        return self.event_type.startswith(category)
+
+    def has_metadata(self, key: str) -> bool:
+        """Check if event has specific metadata."""
+        return key in self.metadata
+
+    def get_metadata(self, key: str, default: Any = None) -> Any:
+        """Get metadata value."""
+        return self.metadata.get(key, default)
+
+    # Common event type checks (for convenience)
+    def is_context_update(self) -> bool:
+        return self.is_event("context_update")
+
+    def is_tool_call(self) -> bool:
+        return self.is_event("tool_call")
+
+    def is_tool_execution(self) -> bool:
+        return self.is_event("tool_execution")
+
+    def is_tool_response(self) -> bool:
+        return self.is_event("tool_response")
+
+    def is_final_response(self) -> bool:
+        return self.is_event("final_response")
+
+    def is_step_start(self) -> bool:
+        return self.is_event("step_start")
+
+    def is_step_end(self) -> bool:
+        return self.is_event("step_end")
+
+    def is_error(self) -> bool:
+        return self.is_event("error")
+
+    def is_stream_chunk(self) -> bool:
+        return self.is_event("stream_chunk")
+
+    # Category checks
+    def is_tool_event(self) -> bool:
+        return self.is_event_category("tool")
+
+    def is_context_event(self) -> bool:
+        return self.is_event_category("context")
+
+    def is_stream_event(self) -> bool:
+        return self.is_event_category("stream")
+
+    def to_message(self) -> ChatCompletionMessageParam:
+        """Convert the event to a chat completion message."""
+        content = f"Event: {self.event_type}"
+        if self.output:
+            content += f"\nData: {self.output}"
+        if self.metadata:
+            content += f"\nMetadata: {self.metadata}"
+
+        return {"role": "assistant", "content": content}
+
+    def to_content_part(self) -> ChatCompletionContentPartParam:
+        """Convert the event to a chat completion content part."""
+        content = f"Event: {self.event_type}"
+        if self.output:
+            content += f" - {self.output}"
+
+        return {"type": "text", "text": content}
+
+    def __repr__(self) -> str:
+        return f"AgentEvent(type='{self.event_type}', data={self.output}, metadata={self.metadata})"

hammad/genai/agents/types/agent_hooks.py

@@ -0,0 +1,220 @@
+"""hammad.genai.agents.types.agent_hooks"""
+
+from typing import Any, Dict, List, Callable, Optional
+from .agent_event import AgentEvent
+
+
+__all__ = [
+    "HookManager",
+    "HookDecorator",
+]
+
+
+class HookManager:
+    """Manages hooks for agent events."""
+
+    def __init__(self):
+        self.hooks: Dict[str, List[Callable]] = {}
+        self.specific_hooks: Dict[str, Dict[str, List[Callable]]] = {}
+
+    def register_hook(
+        self, event_type: str, callback: Callable, specific_name: Optional[str] = None
+    ):
+        """Register a hook for an event type.
+
+        Args:
+            event_type: The type of event to hook into
+            callback: The callback function to execute
+            specific_name: Optional specific name for targeted hooks
+        """
+        if specific_name:
+            if event_type not in self.specific_hooks:
+                self.specific_hooks[event_type] = {}
+            if specific_name not in self.specific_hooks[event_type]:
+                self.specific_hooks[event_type][specific_name] = []
+            self.specific_hooks[event_type][specific_name].append(callback)
+        else:
+            if event_type not in self.hooks:
+                self.hooks[event_type] = []
+            self.hooks[event_type].append(callback)
+
+    def trigger_hooks(
+        self, event_type: str, data: Any, specific_name: Optional[str] = None
+    ) -> Any:
+        """Trigger hooks for an event type.
+
+        Args:
+            event_type: The type of event
+            data: The event data
+            specific_name: Optional specific name for targeted hooks
+
+        Returns:
+            The potentially modified data after running through hooks
+        """
+        result = data
+
+        # Trigger general hooks
+        if event_type in self.hooks:
+            for hook in self.hooks[event_type]:
+                hook_result = hook(result)
+                if hook_result is not None:
+                    result = hook_result
+
+        # Trigger specific hooks
+        if specific_name and event_type in self.specific_hooks:
+            if specific_name in self.specific_hooks[event_type]:
+                for hook in self.specific_hooks[event_type][specific_name]:
+                    hook_result = hook(result)
+                    if hook_result is not None:
+                        result = hook_result
+
+        return result
+
+    def trigger_event(
+        self, event: AgentEvent, specific_name: Optional[str] = None
+    ) -> Any:
+        """Trigger hooks for an AgentEvent.
+
+        Args:
+            event: The AgentEvent instance
+            specific_name: Optional specific name for targeted hooks
+
+        Returns:
+            The potentially modified event data after running through hooks
+        """
+        return self.trigger_hooks(event.event_type, event.output, specific_name)
+
+    def clear_hooks(
+        self, event_type: Optional[str] = None, specific_name: Optional[str] = None
+    ):
+        """Clear hooks for a specific event type or all hooks.
+
+        Args:
+            event_type: Optional event type to clear (clears all if None)
+            specific_name: Optional specific name to clear
+        """
+        if event_type is None:
+            self.hooks.clear()
+            self.specific_hooks.clear()
+        else:
+            if event_type in self.hooks:
+                if specific_name is None:
+                    del self.hooks[event_type]
+
+            if event_type in self.specific_hooks:
+                if specific_name is None:
+                    del self.specific_hooks[event_type]
+                elif specific_name in self.specific_hooks[event_type]:
+                    del self.specific_hooks[event_type][specific_name]
+
+    def list_hooks(self) -> Dict[str, Any]:
+        """List all registered hooks.
+
+        Returns:
+            Dictionary containing all hooks information
+        """
+        return {
+            "general_hooks": {k: len(v) for k, v in self.hooks.items()},
+            "specific_hooks": {
+                k: {sk: len(sv) for sk, sv in v.items()}
+                for k, v in self.specific_hooks.items()
+            },
+        }
+
+
+class HookDecorator:
+    """Provides type-hinted hook decorators with extensible event system."""
+
+    def __init__(self, hook_manager: HookManager):
+        self.hook_manager = hook_manager
+        self._event_types = set()
+
+    def __call__(self, event_type: str, specific_name: Optional[str] = None):
+        """Register a hook for any event type.
+
+        Args:
+            event_type: The type of event to hook into
+            specific_name: Optional specific name for targeted hooks
+
+        Returns:
+            Decorator function
+        """
+
+        def decorator(func: Callable):
+            self.hook_manager.register_hook(event_type, func, specific_name)
+            self._event_types.add(event_type)
+            return func
+
+        return decorator
+
+    def get_registered_event_types(self) -> set:
+        """Get all registered event types."""
+        return self._event_types.copy()
+
+    def supports_event(self, event_type: str) -> bool:
+        """Check if an event type is supported."""
+        return event_type in self._event_types
+
+    # Convenience decorators for common events
+    def on_context_update(self, specific_name: Optional[str] = None):
+        """Decorator for context update events."""
+        return self.__call__("context_update", specific_name)
+
+    def on_tool_call(self, specific_name: Optional[str] = None):
+        """Decorator for tool call events."""
+        return self.__call__("tool_call", specific_name)
+
+    def on_tool_execution(self, specific_name: Optional[str] = None):
+        """Decorator for tool execution events."""
+        return self.__call__("tool_execution", specific_name)
+
+    def on_tool_response(self, specific_name: Optional[str] = None):
+        """Decorator for tool response events."""
+        return self.__call__("tool_response", specific_name)
+
+    def on_final_response(self, specific_name: Optional[str] = None):
+        """Decorator for final response events."""
+        return self.__call__("final_response", specific_name)
+
+    def on_step_start(self, specific_name: Optional[str] = None):
+        """Decorator for step start events."""
+        return self.__call__("step_start", specific_name)
+
+    def on_step_end(self, specific_name: Optional[str] = None):
+        """Decorator for step end events."""
+        return self.__call__("step_end", specific_name)
+
+    def on_error(self, specific_name: Optional[str] = None):
+        """Decorator for error events."""
+        return self.__call__("error", specific_name)
+
+    def on_stream_chunk(self, specific_name: Optional[str] = None):
+        """Decorator for stream chunk events."""
+        return self.__call__("stream_chunk", specific_name)
+
+    # Dynamic event type classes - these are created dynamically
+    # based on the actual events that occur in the system
+    def __getattr__(self, name: str):
+        """Dynamically create event type classes for better type hinting."""
+        if name.startswith("_"):
+            raise AttributeError(
+                f"'{self.__class__.__name__}' object has no attribute '{name}'"
+            )
+
+        # Create a dynamic class for this event type
+        class DynamicEventType:
+            def __init__(
+                self, event_data: Any = None, metadata: Optional[Dict[str, Any]] = None
+            ):
+                self.event_data = event_data
+                self.metadata = metadata or {}
+
+            def __repr__(self):
+                return f"{name}(data={self.event_data}, metadata={self.metadata})"
+
+        DynamicEventType.__name__ = name
+        DynamicEventType.__qualname__ = f"{self.__class__.__name__}.{name}"
+
+        # Cache the class
+        setattr(self, name, DynamicEventType)
+        return DynamicEventType

hammad/genai/agents/types/agent_messages.py

@@ -0,0 +1,31 @@
+"""hammad.genai.agents.types.agent_messages"""
+
+from typing import TypeAlias, Union, List, Any, TYPE_CHECKING
+
+from ...models.language.types import LanguageModelMessages
+
+if TYPE_CHECKING:
+    from openai.types.chat import ChatCompletionMessageParam
+    from ...types.history import History
+
+
+__all__ = [
+    "AgentMessages",
+]
+
+
+AgentMessages: TypeAlias = Union[
+    str,
+    "ChatCompletionMessageParam",
+    "List[ChatCompletionMessageParam]",
+    "History",
+    LanguageModelMessages,
+    Any,
+]
+"""Type alias for agent message inputs that extends LanguageModelMessages to include History objects.
+
+This type alias allows agents to accept:
+- All standard LanguageModelMessages types (str, ChatCompletionMessageParam, List[ChatCompletionMessageParam])
+- History objects for conversation history management
+- Any other type for flexibility
+"""

hammad/genai/agents/types/agent_response.py

@@ -0,0 +1,90 @@
+"""hammad.genai.agents.types.agent_response"""
+
+from typing import List, Any, TypeVar, Literal
+
+from ....cache import cached
+from ...models.language.types import (
+    LanguageModelResponse,
+)
+
+
+__all__ = [
+    "AgentResponse",
+    "_create_agent_response_from_language_model_response",
+]
+
+
+T = TypeVar("T")
+
+
+def _create_agent_response_from_language_model_response(
+    response: LanguageModelResponse[T],
+    steps: List[LanguageModelResponse[str]] | None = None,
+    context: Any = None,
+) -> "AgentResponse[T]":
+    """Create a AgentResponse from a LanguageModelResponse."""
+    try:
+        return AgentResponse(
+            type="agent",
+            model=response.model,
+            output=response.output,
+            content=response.content,
+            completion=response.completion,
+            refusal=response.refusal,
+            steps=steps or [],
+            context=context,
+        )
+    except Exception as e:
+        raise ValueError(
+            "Failed to create AgentResponse from LanguageModelResponse."
+        ) from e
+
+
+class AgentResponse(LanguageModelResponse[T]):
+    """A response generated by an agent, that includes the steps and final
+    output during the agent's execution."""
+
+    type: Literal["agent"] = "agent"
+    """The type of the response. Always `agent`."""
+
+    steps: List[LanguageModelResponse[str]]
+    """
+    A list of steps taken by the agent **BEFORE** its final output.
+
+    NOTE: If the final output was also the first step, this will be
+    empty.
+    """
+
+    context: Any = None
+    """
+    The final context object after agent execution.
+    
+    This is always the final version of the context after any updates
+    have been applied during the agent's execution.
+    """
+
+    @cached
+    def __str__(self) -> str:
+        """Pretty prints the response object."""
+        output = "AgentResponse:"
+
+        if self.output or self.content:
+            output += f"\n{self.output if self.output else self.content}"
+        else:
+            output += f"\n{self.completion}"
+
+        output += f"\n\n>>> Model: {self.model}"
+        # NOTE:
+        # added +1 to include final step in the output
+        output += f"\n>>> Steps: {len(self.steps) + 1}"
+        output += f"\n>>> Tool Calls: {len(self.tool_calls) if self.tool_calls else 0}"
+
+        # Calculate total tool calls across all steps
+        total_tool_calls = 0
+        for step in self.steps:
+            if step.has_tool_calls():
+                total_tool_calls += len(step.tool_calls)
+
+        output += f"\n>>> Total Tool Calls: {total_tool_calls}"
+
+        return output