hammad-python 0.0.30__py3-none-any.whl → 0.0.31__py3-none-any.whl

hammad/genai/agents/types/__init__.py

@@ -1,42 +0,0 @@
-"""hammad.genai.agents.types"""
-
-from typing import TYPE_CHECKING
-from ...._internal import create_getattr_importer
-
-
-if TYPE_CHECKING:
-    from .agent_event import AgentEvent
-    from .agent_hooks import HookManager, HookDecorator
-    from .agent_response import (
-        AgentResponse,
-        _create_agent_response_from_language_model_response,
-    )
-    from .agent_stream import AgentStream, AgentResponseChunk
-    from .agent_context import AgentContext
-    from .agent_messages import AgentMessages
-
-
-__all__ = [
-    # hammad.genai.agents.types.agent_event
-    "AgentEvent",
-    # hammad.genai.agents.types.agent_hooks
-    "HookManager",
-    "HookDecorator",
-    # hammad.genai.agents.types.agent_response
-    "AgentResponse",
-    "_create_agent_response_from_language_model_response",
-    # hammad.genai.agents.types.agent_stream
-    "AgentStream",
-    "AgentResponseChunk",
-    # hammad.genai.agents.types.agent_context
-    "AgentContext",
-    # hammad.genai.agents.types.agent_messages
-    "AgentMessages",
-]
-
-
-__getattr__ = create_getattr_importer(__all__)
-
-
-def __dir__() -> list[str]:
-    return __all__

hammad/genai/agents/types/agent_context.py

@@ -1,13 +0,0 @@
-"""hammad.genai.agents.types.agent_context"""
-
-from typing import Dict, Any, TypeVar
-from pydantic import BaseModel
-
-
-__all__ = [
-    "AgentContext",
-]
-
-
-AgentContext = TypeVar("AgentContext", bound=BaseModel | Dict[str, Any])
-"""A context object that can be used to store information about the agent's state."""

hammad/genai/agents/types/agent_event.py

@@ -1,128 +0,0 @@
-"""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

@@ -1,220 +0,0 @@
-"""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

@@ -1,31 +0,0 @@
-"""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

@@ -1,125 +0,0 @@
-"""hammad.genai.agents.types.agent_response"""
-
-from typing import List, Any, TypeVar, Literal, Generic
-from pydantic import Field
-
-from ....cache import cached
-from ....typing import get_type_description
-from ...models.language.types import (
-    LanguageModelResponse,
-)
-
-from .agent_context import AgentContext
-
-__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], Generic[T, AgentContext]):
-    """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]] = Field(default_factory=list)
-    """
-    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: AgentContext | None = 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>>> Output Type: {get_type_description(type(self.output))}"
-
-        # 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}"
-
-        # Show context if available
-        if self.context:
-            output += (
-                f"\n>>> Final Context: {self._format_context_display(self.context)}"
-            )
-
-        return output
-
-    def _format_context_display(self, context: AgentContext) -> str:
-        """Format context for display in string representation."""
-        if context is None:
-            return "None"
-
-        try:
-            # For Pydantic models, show as dict
-            if hasattr(context, "model_dump"):
-                context_dict = context.model_dump()
-            elif isinstance(context, dict):
-                context_dict = context
-            else:
-                return str(context)
-
-            # Format as compact JSON-like string
-            items = []
-            for key, value in context_dict.items():
-                if isinstance(value, str):
-                    items.append(f"{key}='{value}'")
-                else:
-                    items.append(f"{key}={value}")
-
-            return "{" + ", ".join(items) + "}"
-        except Exception:
-            return str(context)