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

hammad/genai/agents/agent.py

@@ -19,6 +19,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 import json
 
+from ...logging.logger import _get_internal_logger
+
 from ..types.base import BaseGenAIModel, BaseGenAIModelSettings
 from ..models.language.model import LanguageModel
 from ..models.language.types import (
@@ -53,6 +55,9 @@ if TYPE_CHECKING:
 T = TypeVar("T")
 
 
+logger = _get_internal_logger(__name__)
+
+
 @dataclass
 class AgentSettings:
     """Settings object that controls the default behavior of an agent's run."""
@@ -253,6 +258,43 @@ class Agent(BaseGenAIModel, Generic[T]):
         context_format: Literal["json", "python", "markdown"] = "json",
         **kwargs: Any,
     ):
+        """Create a new AI agent with specified capabilities and behavior.
+
+        An agent is an intelligent assistant that can use tools, follow instructions,
+        and maintain context across conversations. It combines a language model with
+        additional capabilities like tool execution and structured output generation.
+
+        Args:
+            name: A human-readable name for the agent (default: "agent")
+            instructions: System instructions that define the agent's behavior and personality
+            model: The language model to use - either a LanguageModel instance or model name string
+            description: Optional description of what the agent does
+            tools: List of tools/functions the agent can call, or a single callable
+            settings: AgentSettings object to customize default behavior
+            instructor_mode: Mode for structured output generation
+            context_updates: When to update context - "before", "after", or both
+            context_confirm: Whether to confirm context updates with the user
+            context_strategy: How to select context updates - "selective" or "all"
+            context_max_retries: Maximum attempts for context update operations
+            context_confirm_instructions: Custom instructions for context confirmation
+            context_selection_instructions: Custom instructions for context selection
+            context_update_instructions: Custom instructions for context updates
+            context_format: Format for context display - "json", "python", or "markdown"
+            **kwargs: Additional parameters passed to the underlying language model
+
+        Example:
+            Basic agent:
+            >>> agent = Agent(name="assistant", instructions="You are helpful")
+
+            Agent with tools:
+            >>> def calculator(x: int, y: int) -> int:
+            ...     return x + y
+            >>> agent = Agent(tools=[calculator])
+
+            Agent with custom settings:
+            >>> settings = AgentSettings(max_steps=5)
+            >>> agent = Agent(settings=settings, model="gpt-4")
+        """
         # Initialize BaseGenAIModel with basic parameters
         super().__init__(
             model=model if isinstance(model, str) else model.model, **kwargs
@@ -297,17 +339,65 @@ class Agent(BaseGenAIModel, Generic[T]):
         """Get the underlying language model."""
         return self._language_model
 
+    def _get_effective_context_settings(
+        self,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
+    ) -> dict:
+        """Get effective context settings, using provided parameters or defaults."""
+        return {
+            "context_updates": context_updates
+            if context_updates is not None
+            else self.context_updates,
+            "context_confirm": context_confirm
+            if context_confirm is not None
+            else self.context_confirm,
+            "context_strategy": context_strategy
+            if context_strategy is not None
+            else self.context_strategy,
+            "context_max_retries": context_max_retries
+            if context_max_retries is not None
+            else self.context_max_retries,
+            "context_confirm_instructions": context_confirm_instructions
+            if context_confirm_instructions is not None
+            else self.context_confirm_instructions,
+            "context_selection_instructions": context_selection_instructions
+            if context_selection_instructions is not None
+            else self.context_selection_instructions,
+            "context_update_instructions": context_update_instructions
+            if context_update_instructions is not None
+            else self.context_update_instructions,
+            "context_format": context_format
+            if context_format is not None
+            else self.context_format,
+        }
+
     def _should_update_context(
-        self, context: AgentContext, timing: Literal["before", "after"]
+        self,
+        context: AgentContext,
+        timing: Literal["before", "after"],
+        context_updates=None,
     ) -> bool:
         """Determine if context should be updated based on timing and configuration."""
-        if not self.context_updates:
+        effective_context_updates = (
+            context_updates if context_updates is not None else self.context_updates
+        )
+
+        if not effective_context_updates:
             return False
 
-        if isinstance(self.context_updates, str):
-            return self.context_updates == timing
+        if isinstance(effective_context_updates, str):
+            return effective_context_updates == timing
         else:
-            return timing in self.context_updates
+            return timing in effective_context_updates
 
     def _create_context_confirm_model(self):
         """Create IsUpdateRequired model for context confirmation."""
@@ -334,18 +424,60 @@ class Agent(BaseGenAIModel, Generic[T]):
         if field_name:
             # Single field update
             if isinstance(context, BaseModel):
-                field_type = context.model_fields[field_name].annotation
+                field_type = context.__class__.model_fields[field_name].annotation
+                field_info = context.__class__.model_fields[field_name]
+                description = getattr(
+                    field_info, "description", f"Update the {field_name} field"
+                )
             elif isinstance(context, dict):
                 field_type = type(context[field_name])
+                description = f"Update the {field_name} field"
             else:
                 field_type = Any
+                description = f"Update the {field_name} field"
 
             return create_model(
-                field_name.capitalize(), **{field_name: (field_type, ...)}
+                f"Update{field_name.capitalize()}",
+                **{field_name: (field_type, Field(description=description))},
             )
         else:
-            # All fields update
-            return create_model("Update", updates=(Dict[str, Any], ...))
+            # All fields update - create a model with the exact same fields as the context
+            if isinstance(context, BaseModel):
+                # Create a model with the same fields as the context
+                field_definitions = {}
+                for field_name, field_info in context.model_fields.items():
+                    field_type = field_info.annotation
+                    current_value = getattr(context, field_name)
+                    description = getattr(
+                        field_info, "description", f"Current value: {current_value}"
+                    )
+                    field_definitions[field_name] = (
+                        field_type,
+                        Field(description=description),
+                    )
+
+                return create_model("ContextUpdate", **field_definitions)
+            elif isinstance(context, dict):
+                # Create a model with the same keys as the dict
+                field_definitions = {}
+                for key, value in context.items():
+                    field_type = type(value)
+                    description = f"Current value: {value}"
+                    field_definitions[key] = (
+                        field_type,
+                        Field(description=description),
+                    )
+
+                return create_model("ContextUpdate", **field_definitions)
+            else:
+                # Fallback to generic updates
+                return create_model(
+                    "ContextUpdate",
+                    updates=(
+                        Dict[str, Any],
+                        Field(description="Dictionary of field updates"),
+                    ),
+                )
 
     def _perform_context_update(
         self,
@@ -353,20 +485,42 @@ class Agent(BaseGenAIModel, Generic[T]):
         model: LanguageModel,
         current_messages: List[Dict[str, Any]],
         timing: Literal["before", "after"],
+        effective_settings: Optional[dict] = None,
     ) -> AgentContext:
         """Perform context update with retries and error handling."""
         updated_context = context
 
-        for attempt in range(self.context_max_retries):
+        # Use effective settings or defaults
+        if effective_settings is None:
+            effective_settings = {
+                "context_confirm": self.context_confirm,
+                "context_strategy": self.context_strategy,
+                "context_max_retries": self.context_max_retries,
+                "context_confirm_instructions": self.context_confirm_instructions,
+                "context_selection_instructions": self.context_selection_instructions,
+                "context_update_instructions": self.context_update_instructions,
+                "context_format": self.context_format,
+            }
+
+        for attempt in range(effective_settings["context_max_retries"]):
             try:
                 # Check if update is needed (if confirmation is enabled)
-                if self.context_confirm:
+                if effective_settings["context_confirm"]:
                     confirm_model = self._create_context_confirm_model()
-                    confirm_instructions = f"Based on the conversation, determine if the context should be updated {timing} processing."
-                    if self.context_confirm_instructions:
-                        confirm_instructions += (
-                            f"\n\n{self.context_confirm_instructions}"
-                        )
+
+                    # Create detailed instructions with context structure
+                    context_structure = _format_context_for_instructions(
+                        updated_context, effective_settings["context_format"]
+                    )
+                    confirm_instructions = f"""Based on the conversation, determine if the context should be updated {timing} processing.
+
+Current context structure:
+{context_structure}
+
+Should the context be updated based on the new information provided in the conversation?"""
+
+                    if effective_settings["context_confirm_instructions"]:
+                        confirm_instructions += f"\n\nAdditional instructions: {effective_settings['context_confirm_instructions']}"
 
                     confirm_response = model.run(
                         messages=current_messages
@@ -379,16 +533,25 @@ class Agent(BaseGenAIModel, Generic[T]):
                         return updated_context
 
                 # Perform the update based on strategy
-                if self.context_strategy == "selective":
+                if effective_settings["context_strategy"] == "selective":
                     # Get fields to update
                     selection_model = self._create_context_selection_model(
                         updated_context
                     )
-                    selection_instructions = f"Select which fields in the context should be updated {timing} processing."
-                    if self.context_selection_instructions:
-                        selection_instructions += (
-                            f"\n\n{self.context_selection_instructions}"
-                        )
+
+                    # Create detailed instructions with context structure
+                    context_structure = _format_context_for_instructions(
+                        updated_context, effective_settings["context_format"]
+                    )
+                    selection_instructions = f"""Select which fields in the context should be updated {timing} processing based on the conversation.
+
+Current context structure:
+{context_structure}
+
+Choose only the fields that need to be updated based on the new information provided in the conversation."""
+
+                    if effective_settings["context_selection_instructions"]:
+                        selection_instructions += f"\n\nAdditional instructions: {effective_settings['context_selection_instructions']}"
 
                     selection_response = model.run(
                         messages=current_messages
@@ -403,13 +566,21 @@ class Agent(BaseGenAIModel, Generic[T]):
                         field_model = self._create_context_update_model(
                             updated_context, field_name
                         )
-                        field_instructions = (
-                            f"Update the {field_name} field in the context."
+                        # Get current field value for context
+                        current_value = (
+                            getattr(updated_context, field_name)
+                            if isinstance(updated_context, BaseModel)
+                            else updated_context.get(field_name)
                         )
-                        if self.context_update_instructions:
-                            field_instructions += (
-                                f"\n\n{self.context_update_instructions}"
-                            )
+
+                        field_instructions = f"""Update the {field_name} field in the context based on the conversation.
+
+Current value of {field_name}: {current_value}
+
+Please provide the new value for {field_name} based on the information from the conversation."""
+
+                        if effective_settings["context_update_instructions"]:
+                            field_instructions += f"\n\nAdditional instructions: {effective_settings['context_update_instructions']}"
 
                         field_response = model.run(
                             messages=current_messages
@@ -429,9 +600,20 @@ class Agent(BaseGenAIModel, Generic[T]):
                 else:  # strategy == "all"
                     # Update all fields at once
                     update_model = self._create_context_update_model(updated_context)
-                    update_instructions = f"Update the context {timing} processing."
-                    if self.context_update_instructions:
-                        update_instructions += f"\n\n{self.context_update_instructions}"
+
+                    # Create detailed instructions with context structure
+                    context_structure = _format_context_for_instructions(
+                        updated_context, effective_settings["context_format"]
+                    )
+                    update_instructions = f"""Update the context {timing} processing based on the conversation.
+
+Current context structure:
+{context_structure}
+
+Please update the appropriate fields based on the conversation. Only update fields that need to be changed based on the new information provided."""
+
+                    if effective_settings["context_update_instructions"]:
+                        update_instructions += f"\n\nAdditional instructions: {effective_settings['context_update_instructions']}"
 
                     update_response = model.run(
                         messages=current_messages
@@ -441,9 +623,26 @@ class Agent(BaseGenAIModel, Generic[T]):
                     )
 
                     # Apply the updates
-                    updated_context = _update_context_object(
-                        updated_context, update_response.output.updates
-                    )
+                    if hasattr(update_response.output, "updates"):
+                        # Legacy fallback for generic updates
+                        updated_context = _update_context_object(
+                            updated_context, update_response.output.updates
+                        )
+                    else:
+                        # New approach - extract field values directly from the response
+                        updates_dict = {}
+                        for field_name in (
+                            context.model_fields.keys()
+                            if isinstance(context, BaseModel)
+                            else context.keys()
+                        ):
+                            if hasattr(update_response.output, field_name):
+                                updates_dict[field_name] = getattr(
+                                    update_response.output, field_name
+                                )
+                        updated_context = _update_context_object(
+                            updated_context, updates_dict
+                        )
 
                 # Trigger context update hooks
                 self.hook_manager.trigger_hooks("context_update", updated_context)
@@ -490,10 +689,20 @@ class Agent(BaseGenAIModel, Generic[T]):
         max_steps: Optional[int] = None,
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
         *,
         stream: Literal[False] = False,
         **kwargs: Any,
-    ) -> AgentResponse[T]: ...
+    ) -> AgentResponse[T, AgentContext]: ...
 
     @overload
     def run(
@@ -503,10 +712,20 @@ class Agent(BaseGenAIModel, Generic[T]):
         max_steps: Optional[int] = None,
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
         *,
         stream: Literal[True],
         **kwargs: Any,
-    ) -> AgentStream[T]: ...
+    ) -> AgentStream[T, AgentContext]: ...
 
     def run(
         self,
@@ -515,9 +734,19 @@ class Agent(BaseGenAIModel, Generic[T]):
         max_steps: Optional[int] = None,
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
         stream: bool = False,
         **kwargs: Any,
-    ) -> Union[AgentResponse[T], AgentStream[T]]:
+    ) -> Union[AgentResponse[T, AgentContext], AgentStream[T, AgentContext]]:
         """Runs this agent and returns a final agent response or stream.
 
         You can override defaults assigned to this agent from this function directly.
@@ -614,6 +843,18 @@ class Agent(BaseGenAIModel, Generic[T]):
         if max_steps is None:
             max_steps = self.settings.max_steps
 
+        # Get effective context settings
+        effective_context_settings = self._get_effective_context_settings(
+            context_updates=context_updates,
+            context_confirm=context_confirm,
+            context_strategy=context_strategy,
+            context_max_retries=context_max_retries,
+            context_confirm_instructions=context_confirm_instructions,
+            context_selection_instructions=context_selection_instructions,
+            context_update_instructions=context_update_instructions,
+            context_format=context_format,
+        )
+
         # Parse initial messages
         parsed_messages = parse_messages(messages)
         current_messages = parsed_messages.copy()
@@ -621,6 +862,18 @@ class Agent(BaseGenAIModel, Generic[T]):
 
         # RUN MAIN AGENTIC LOOP
         for step in range(max_steps):
+            # Update context before processing if configured
+            if context and self._should_update_context(
+                context, "before", effective_context_settings["context_updates"]
+            ):
+                context = self._perform_context_update(
+                    context=context,
+                    model=working_model,
+                    current_messages=current_messages,
+                    timing="before",
+                    effective_settings=effective_context_settings,
+                )
+
             # Format messages with instructions and context for first step only
             if step == 0:
                 formatted_messages = self._format_messages_with_context(
@@ -640,9 +893,7 @@ class Agent(BaseGenAIModel, Generic[T]):
             # Get language model response
             response = working_model.run(
                 messages=formatted_messages,
-                tools=[tool.model_dump() for tool in self.tools]
-                if self.tools
-                else None,
+                tools=[tool.to_dict() for tool in self.tools] if self.tools else None,
                 **model_kwargs,
             )
 
@@ -663,6 +914,17 @@ class Agent(BaseGenAIModel, Generic[T]):
                 steps.append(response)
             else:
                 # No tool calls - this is the final step
+                # Update context after processing if configured
+                if context and self._should_update_context(
+                    context, "after", effective_context_settings["context_updates"]
+                ):
+                    context = self._perform_context_update(
+                        context=context,
+                        model=working_model,
+                        current_messages=current_messages,
+                        timing="after",
+                        effective_settings=effective_context_settings,
+                    )
                 return _create_agent_response_from_language_model_response(
                     response=response, steps=steps, context=context
                 )
@@ -680,6 +942,18 @@ class Agent(BaseGenAIModel, Generic[T]):
                 **model_kwargs,
             )
 
+        # Update context after processing if configured
+        if context and self._should_update_context(
+            context, "after", effective_context_settings["context_updates"]
+        ):
+            context = self._perform_context_update(
+                context=context,
+                model=working_model,
+                current_messages=current_messages,
+                timing="after",
+                effective_settings=effective_context_settings,
+            )
+
         return _create_agent_response_from_language_model_response(
             response=final_response, steps=steps, context=context
         )
@@ -691,8 +965,18 @@ class Agent(BaseGenAIModel, Generic[T]):
         max_steps: Optional[int] = None,
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
         **kwargs: Any,
-    ) -> AgentResponse[T]:
+    ) -> AgentResponse[T, AgentContext]:
         """Runs this agent asynchronously and returns a final agent response.
 
         You can override defaults assigned to this agent from this function directly.
@@ -772,6 +1056,18 @@ class Agent(BaseGenAIModel, Generic[T]):
         if max_steps is None:
             max_steps = self.settings.max_steps
 
+        # Get effective context settings
+        effective_context_settings = self._get_effective_context_settings(
+            context_updates=context_updates,
+            context_confirm=context_confirm,
+            context_strategy=context_strategy,
+            context_max_retries=context_max_retries,
+            context_confirm_instructions=context_confirm_instructions,
+            context_selection_instructions=context_selection_instructions,
+            context_update_instructions=context_update_instructions,
+            context_format=context_format,
+        )
+
         # Parse initial messages
         parsed_messages = parse_messages(messages)
         current_messages = parsed_messages.copy()
@@ -779,6 +1075,18 @@ class Agent(BaseGenAIModel, Generic[T]):
 
         # RUN MAIN AGENTIC LOOP
         for step in range(max_steps):
+            # Update context before processing if configured
+            if context and self._should_update_context(
+                context, "before", effective_context_settings["context_updates"]
+            ):
+                context = self._perform_context_update(
+                    context=context,
+                    model=working_model,
+                    current_messages=current_messages,
+                    timing="before",
+                    effective_settings=effective_context_settings,
+                )
+
             # Format messages with instructions and context for first step only
             if step == 0:
                 formatted_messages = self._format_messages_with_context(
@@ -798,9 +1106,7 @@ class Agent(BaseGenAIModel, Generic[T]):
             # Get language model response
             response = await working_model.async_run(
                 messages=formatted_messages,
-                tools=[tool.model_dump() for tool in self.tools]
-                if self.tools
-                else None,
+                tools=[tool.to_dict() for tool in self.tools] if self.tools else None,
                 **model_kwargs,
             )
 
@@ -821,6 +1127,17 @@ class Agent(BaseGenAIModel, Generic[T]):
                 steps.append(response)
             else:
                 # No tool calls - this is the final step
+                # Update context after processing if configured
+                if context and self._should_update_context(
+                    context, "after", effective_context_settings["context_updates"]
+                ):
+                    context = self._perform_context_update(
+                        context=context,
+                        model=working_model,
+                        current_messages=current_messages,
+                        timing="after",
+                        effective_settings=effective_context_settings,
+                    )
                 return _create_agent_response_from_language_model_response(
                     response=response, steps=steps, context=context
                 )
@@ -838,6 +1155,18 @@ class Agent(BaseGenAIModel, Generic[T]):
                 **model_kwargs,
             )
 
+        # Update context after processing if configured
+        if context and self._should_update_context(
+            context, "after", effective_context_settings["context_updates"]
+        ):
+            context = self._perform_context_update(
+                context=context,
+                model=working_model,
+                current_messages=current_messages,
+                timing="after",
+                effective_settings=effective_context_settings,
+            )
+
         return _create_agent_response_from_language_model_response(
             response=final_response, steps=steps, context=context
         )
@@ -850,7 +1179,7 @@ class Agent(BaseGenAIModel, Generic[T]):
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
         **kwargs: Any,
-    ) -> AgentStream[T]:
+    ) -> AgentStream[T, AgentContext]:
         """Create a stream that yields agent steps.
 
         Args:
@@ -882,8 +1211,18 @@ class Agent(BaseGenAIModel, Generic[T]):
         max_steps: Optional[int] = None,
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
+        context_updates: Optional[
+            Union[List[Literal["before", "after"]], Literal["before", "after"]]
+        ] = None,
+        context_confirm: Optional[bool] = None,
+        context_strategy: Optional[Literal["selective", "all"]] = None,
+        context_max_retries: Optional[int] = None,
+        context_confirm_instructions: Optional[str] = None,
+        context_selection_instructions: Optional[str] = None,
+        context_update_instructions: Optional[str] = None,
+        context_format: Optional[Literal["json", "python", "markdown"]] = None,
         **kwargs: Any,
-    ) -> AgentStream[T]:
+    ) -> AgentStream[T, AgentContext]:
         """Iterate over agent steps, yielding each step response.
 
         You can override defaults assigned to this agent from this function directly.
@@ -986,7 +1325,7 @@ class Agent(BaseGenAIModel, Generic[T]):
         context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
         **kwargs: Any,
-    ) -> AgentStream[T]:
+    ) -> AgentStream[T, AgentContext]:
         """Async iterate over agent steps, yielding each step response.
 
         Args:

hammad/genai/agents/types/agent_response.py

@@ -1,12 +1,14 @@
 """hammad.genai.agents.types.agent_response"""
 
-from typing import List, Any, TypeVar, Literal
+from typing import List, Any, TypeVar, Literal, Generic
 
 from ....cache import cached
+from ....typing import get_type_description
 from ...models.language.types import (
     LanguageModelResponse,
 )
 
+from .agent_context import AgentContext
 
 __all__ = [
     "AgentResponse",
@@ -40,7 +42,7 @@ def _create_agent_response_from_language_model_response(
         ) from e
 
 
-class AgentResponse(LanguageModelResponse[T]):
+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."""
 
@@ -55,7 +57,7 @@ class AgentResponse(LanguageModelResponse[T]):
     empty.
     """
 
-    context: Any = None
+    context: AgentContext | None = None
     """
     The final context object after agent execution.
     
@@ -66,7 +68,7 @@ class AgentResponse(LanguageModelResponse[T]):
     @cached
     def __str__(self) -> str:
         """Pretty prints the response object."""
-        output = "AgentResponse:"
+        output = ">>> AgentResponse:"
 
         if self.output or self.content:
             output += f"\n{self.output if self.output else self.content}"
@@ -77,7 +79,7 @@ class AgentResponse(LanguageModelResponse[T]):
         # 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}"
+        output += f"\n>>> Output Type: {get_type_description(type(self.output))}"
 
         # Calculate total tool calls across all steps
         total_tool_calls = 0
@@ -87,4 +89,36 @@ class AgentResponse(LanguageModelResponse[T]):
 
         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)

hammad/genai/agents/types/agent_stream.py

@@ -38,6 +38,7 @@ from .agent_response import (
     AgentResponse,
     _create_agent_response_from_language_model_response,
 )
+from .agent_context import AgentContext
 
 if TYPE_CHECKING:
     from ..agent import Agent
@@ -85,10 +86,21 @@ class AgentResponseChunk(LanguageModelResponseChunk[T], Generic[T]):
 
     def __str__(self) -> str:
         """String representation of the chunk."""
-        return f"AgentResponseChunk(step={self.step_number}, final={self.is_final})"
+        output = f"AgentResponseChunk(step={self.step_number}, final={self.is_final})"
 
+        # Show content if available
+        if self.output or self.content:
+            content_preview = str(self.output if self.output else self.content)
+            if len(content_preview) > 100:
+                content_preview = content_preview[:100] + "..."
+            output += f"\nContent: {content_preview}"
 
-class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
+        return output
+
+
+class AgentStream(
+    BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentContext]
+):
     """Stream of agent responses that can be used in sync and async contexts."""
 
     def __init__(
@@ -97,7 +109,7 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
         messages: LanguageModelMessages,
         model: Optional[Union[LanguageModel, str]] = None,
         max_steps: Optional[int] = None,
-        context: Optional[Any] = None,
+        context: Optional[AgentContext] = None,
         output_type: Optional[Type[T]] = None,
         stream: bool = False,
         **kwargs: Any,
@@ -127,6 +139,7 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
 
         # Context handling
         self.current_context = context
+        self.initial_context = context
 
         # Model kwargs setup
         self.model_kwargs = kwargs.copy()
@@ -139,7 +152,19 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
 
     def _format_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         if self.agent.instructions:
-            system_message = {"role": "system", "content": self.agent.instructions}
+            system_content = self.agent.instructions
+
+            # Add context if available
+            if self.current_context is not None:
+                from ..agent import _format_context_for_instructions
+
+                context_str = _format_context_for_instructions(
+                    self.current_context, self.agent.context_format
+                )
+                if context_str:
+                    system_content += f"\n\nContext:\n{context_str}"
+
+            system_message = {"role": "system", "content": system_content}
             messages = [system_message] + messages
         return consolidate_system_messages(messages)
 
@@ -162,6 +187,18 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
         else:
             self.is_done = True
             self._final_response = response
+
+            # Update context after processing if configured
+            if self.current_context and self.agent._should_update_context(
+                self.current_context, "after"
+            ):
+                self.current_context = self.agent._perform_context_update(
+                    context=self.current_context,
+                    model=self.model,
+                    current_messages=self.current_messages,
+                    timing="after",
+                )
+
             return AgentResponseChunk(
                 step_number=self.current_step, response=response, is_final=True
             )
@@ -171,6 +208,17 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
         while not self.is_done and self.current_step < self.max_steps:
             self.current_step += 1
 
+            # Update context before processing if configured
+            if self.current_context and self.agent._should_update_context(
+                self.current_context, "before"
+            ):
+                self.current_context = self.agent._perform_context_update(
+                    context=self.current_context,
+                    model=self.model,
+                    current_messages=self.current_messages,
+                    timing="before",
+                )
+
             formatted_messages = self.current_messages
             if self.current_step == 1:
                 formatted_messages = self._format_messages(self.current_messages)
@@ -198,6 +246,17 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
         # The context manager handling should be managed by the agent's run method
         self.current_step += 1
 
+        # Update context before processing if configured
+        if self.current_context and self.agent._should_update_context(
+            self.current_context, "before"
+        ):
+            self.current_context = self.agent._perform_context_update(
+                context=self.current_context,
+                model=self.model,
+                current_messages=self.current_messages,
+                timing="before",
+            )
+
         formatted_messages = self.current_messages
         if self.current_step == 1:
             formatted_messages = self._format_messages(self.current_messages)
@@ -215,7 +274,7 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
             self.is_done = True
         return chunk
 
-    def _build_response(self) -> AgentResponse[T]:
+    def _build_response(self) -> AgentResponse[T, AgentContext]:
         if self._final_response:
             final_response = self._final_response
         elif self.steps:
@@ -229,13 +288,39 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T]):
             context=self.current_context,
         )
 
-    def collect(self) -> AgentResponse[T]:
+    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)
+
+    def collect(self) -> AgentResponse[T, AgentContext]:
         """Collect all steps and return final response."""
         for _ in self:
             pass
         return self._build_response()
 
-    async def async_collect(self) -> AgentResponse[T]:
+    async def async_collect(self) -> AgentResponse[T, AgentContext]:
         """Collect all steps and return final response."""
         async for _ in self:
             pass

hammad/genai/models/language/model.py

@@ -21,6 +21,7 @@ from typing_extensions import Literal
 if TYPE_CHECKING:
     from httpx import Timeout
 
+from ....logging.logger import _get_internal_logger
 from ..model_provider import litellm, instructor
 
 from ...types.base import BaseGenAIModel
@@ -50,6 +51,9 @@ __all__ = [
 T = TypeVar("T")
 
 
+logger = _get_internal_logger(__name__)
+
+
 class LanguageModelError(Exception):
     """Error raised when an error occurs during a language model operation."""
 
@@ -112,6 +116,9 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         # Initialize LanguageModel-specific attributes
         self._instructor_client = None
 
+        logger.info(f"Initialized LanguageModel w/ model: {self.model}")
+        logger.debug(f"LanguageModel settings: {self.settings}")
+
     def _get_instructor_client(
         self, mode: Optional[LanguageModelInstructorMode] = None
     ):
@@ -123,6 +130,10 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
             self._instructor_client is None
             or getattr(self._instructor_client, "_mode", None) != effective_mode
         ):
+            logger.debug(
+                f"Creating new instructor client for mode: {effective_mode} from old mode: {getattr(self._instructor_client, '_mode', None)}"
+            )
+
             self._instructor_client = instructor.from_litellm(
                 completion=litellm.completion, mode=instructor.Mode(effective_mode)
             )
@@ -338,6 +349,9 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         Returns:
             LanguageModelResponse or LanguageModelStream depending on parameters
         """
+        logger.info(f"Running LanguageModel request with model: {self.model}")
+        logger.debug(f"LanguageModel request kwargs: {kwargs}")
+
         try:
             # Extract model, base_url, api_key, and mock_response from kwargs, using instance defaults
             model = kwargs.pop("model", None) or self.model
@@ -572,6 +586,9 @@ class LanguageModel(BaseGenAIModel, Generic[T]):
         Returns:
             LanguageModelResponse or LanguageModelAsyncStream depending on parameters
         """
+        logger.info(f"Running async LanguageModel request with model: {self.model}")
+        logger.debug(f"LanguageModel request kwargs: {kwargs}")
+
         try:
             # Extract model, base_url, api_key, and mock_response from kwargs, using instance defaults
             model = kwargs.pop("model", None) or self.model

hammad/genai/models/language/types/language_model_response.py

@@ -12,6 +12,8 @@ from typing import (
     Literal,
 )
 
+from .....cache import cached
+
 from ...model_provider import litellm
 from ....types.base import BaseGenAIModelResponse
 from openai.types.chat import (
@@ -53,7 +55,7 @@ class LanguageModelResponse(BaseGenAIModelResponse[T]):
     """The actual response content of the completion. This is the string that
     was generated by the model."""
 
-    tool_calls: Optional[List["ChatCompletionMessageToolCall"]] = None
+    tool_calls: Optional[List["litellm.ChatCompletionMessageToolCall"]] = None
     """The tool calls that were made by the model. This is a list of tool calls
     that were made by the model."""
 
@@ -197,9 +199,10 @@ class LanguageModelResponse(BaseGenAIModelResponse[T]):
         content part object."""
         return {"type": "text", "text": self.content}
 
+    @cached
     def __str__(self) -> str:
         """Pretty prints the response object."""
-        output = "LanguageModelResponse:"
+        output = ">>> LanguageModelResponse:"
 
         if self.output or self.content:
             output += f"\n{self.output if self.output else self.content}"

hammad/genai/types/tools.py

@@ -5,6 +5,7 @@ Tool system for agent function calling with JSON schema generation.
 
 import asyncio
 import concurrent.futures
+from dataclasses import dataclass
 import inspect
 import json
 from typing import (
@@ -44,6 +45,7 @@ __all__ = (
 )
 
 
+@dataclass
 class ToolResponseMessage:
     """Represents a tool response message for chat completion."""
 

hammad/logging/logger.py

@@ -953,3 +953,11 @@ def create_logger(
         console=console,
         handlers=handlers,
     )
+
+
+# internal logger and helper
+_logger = Logger("hammad", level="warning")
+
+
+def _get_internal_logger(name: str) -> Logger:
+    return Logger(name=name, level="warning")

{hammad_python-0.0.20.dist-info → hammad_python-0.0.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hammad-python
-Version: 0.0.20
+Version: 0.0.22
 Author-email: Hammad Saeed <hammadaidev@gmail.com>
 License: MIT License
         

{hammad_python-0.0.20.dist-info → hammad_python-0.0.22.dist-info}/RECORD

@@ -55,15 +55,15 @@ hammad/formatting/yaml/__init__.py,sha256=4dBeXPi0jx7ELT2_sC2fUYaiY8b8wFiUScLODc
 hammad/formatting/yaml/converters.py,sha256=zvSB8QGb56uvwO0KjXllfTj9g1FmNINOKR06DTjvXw8,153
 hammad/genai/__init__.py,sha256=16L9z0U73uUhBB7JHSL0tHWie2-rI7GAUtQSY94IeZk,3579
 hammad/genai/agents/__init__.py,sha256=R_wW_fbZqMXZZYSErAb81UDRMTaNDlAFzNKfTOm4XYg,1235
-hammad/genai/agents/agent.py,sha256=r9iKJoks2dFc0ifLYhQnYjVN31ULkpBWy_IwrAMKwr0,38899
+hammad/genai/agents/agent.py,sha256=xtb-xexCA7XzoHCR20zCTAEsgjTo0C-i701WQGzIXgA,55884
 hammad/genai/agents/run.py,sha256=G3NLJgg8nXFHfOrh_XR1NpVjGzAgjnA_Ojc_rrMHz9E,23278
 hammad/genai/agents/types/__init__.py,sha256=6X6_P82qe15dyqs-vAcXUk4na4tB-7oMdMf484v87io,1119
 hammad/genai/agents/types/agent_context.py,sha256=u4evwx9B-UKEHMtNcsNlN9q8i12bsW9HhtyvmU0NNTw,313
 hammad/genai/agents/types/agent_event.py,sha256=zNKXXPKKOsIO9MAhE-YNCOxeNg00O7j1mE0R1pA_Xr8,3925
 hammad/genai/agents/types/agent_hooks.py,sha256=wgys4ixiHjX5oux4zVSr9OPXyAZ-iJGk_MhaOKEgMxo,7853
 hammad/genai/agents/types/agent_messages.py,sha256=csjEq42bElaTZYZW2dE6nlFZc142-HgT3bB6h1KMg_w,846
-hammad/genai/agents/types/agent_response.py,sha256=3WTIKP123amnuRzaQ0Jjlipqvug7aRstlqiPnHD9m4Q,2598
-hammad/genai/agents/types/agent_stream.py,sha256=n8RrWfLylfpW0xYj4ZrrUgq-0Z-DVAFl9lfBiSYANb8,7842
+hammad/genai/agents/types/agent_response.py,sha256=vRR9bWwzSA6Y6a_cpf7KrrmJqoAwh5OuuNThTERNVwY,3806
+hammad/genai/agents/types/agent_stream.py,sha256=VIfqZp55wq6jQh_OtPzZjiL_K4cEoVCkeEZS3s_MIXI,11069
 hammad/genai/models/__init__.py,sha256=e4TbEsiKIoXENOEsdIdQcWWt0RnFdTEqCz0nICHQHtM,26
 hammad/genai/models/model_provider.py,sha256=2RdOeqr7KpjyrMqq4YH4OYy1pk6sjzf2CPu1ZHa1Pdk,75
 hammad/genai/models/multimodal.py,sha256=KXUyLXqM1eBgBGZFEbMw3dYbakZFAXoko2xYprronxY,1276
@@ -77,14 +77,14 @@ hammad/genai/models/embeddings/types/embedding_model_response.py,sha256=V2H_VTl1
 hammad/genai/models/embeddings/types/embedding_model_run_params.py,sha256=ZGhCXrEEzMF5y-V8neF2a73Gh1emzrYUHVxWkybg5uE,1570
 hammad/genai/models/embeddings/types/embedding_model_settings.py,sha256=KEwvoElXhPMSVCKW2uKwqqT2lSAAthQXmGXaV7Qk5cU,1268
 hammad/genai/models/language/__init__.py,sha256=B92q9f5UIQBMIFoYUja9V61bn5Lzdrk12_bf3DHw6Is,1838
-hammad/genai/models/language/model.py,sha256=sXXAcW7tWX9vxAKT9jPOtIren-IkGXyG-P-ib4EeoQg,38698
+hammad/genai/models/language/model.py,sha256=h3V-Z_AUlVRn_pFbC0wchMajk7tyJjK0dIpZxq3lYy8,39408
 hammad/genai/models/language/run.py,sha256=nqqQYi3iBpkNxW3_JHyyZBNpn79LVWLpnebCBYOaEbA,21468
 hammad/genai/models/language/types/__init__.py,sha256=cdLnoCiVmK6T86-5CZrUJg2rxXKoSk-svyCSviUdgao,1534
 hammad/genai/models/language/types/language_model_instructor_mode.py,sha256=7ywBaY24m-UKRynnX6XsfVf_hsQrM2xHAHugTgV0Vho,1008
 hammad/genai/models/language/types/language_model_messages.py,sha256=e-HZ_YKXq17gwmMlpOmYUYUpBFm7Mu3aRawtjSslWXs,504
 hammad/genai/models/language/types/language_model_name.py,sha256=2V70cZ47L9yIcug6LCcMHcvEJaee7gRN6DUPhLUBlsE,8056
 hammad/genai/models/language/types/language_model_request.py,sha256=ZtzhCx8o6zkEBS3uTFXFLf_poDD7MnIp1y7MbKckOmI,3911
-hammad/genai/models/language/types/language_model_response.py,sha256=pViE4lRNwlXAlNPNNPemKH8Z2tTjeEuU2C5yJnLV2nI,7485
+hammad/genai/models/language/types/language_model_response.py,sha256=YHDEDJuhQ_ULs9qse2b-h5cx1ELWgfPc2BHk34OPVxE,7540
 hammad/genai/models/language/types/language_model_response_chunk.py,sha256=wIzGZw732KsI-a1-uASjATA6qvBuq-7rupWoFjsAgQo,1796
 hammad/genai/models/language/types/language_model_settings.py,sha256=C0EvLXZoOLgPZ4bX7mVFs_CWP-jam27qkseJRGsBAfQ,2794
 hammad/genai/models/language/types/language_model_stream.py,sha256=XgJ83JSbtTdf7jeLQMrDhMfI7zp0pRrdY7JWYbZV_h0,22043
@@ -94,10 +94,10 @@ hammad/genai/models/language/utils/structured_outputs.py,sha256=Va7pie9AOvLbJOaD
 hammad/genai/types/__init__.py,sha256=W0fzUnKhDynt4TkwZX8LCRYfgRTAVomSuWqPmhGu8sg,25
 hammad/genai/types/base.py,sha256=VnGL45w8oR-6rWl2GfGgWX4SjMC-23RGWuN0_H2bH_I,5437
 hammad/genai/types/history.py,sha256=zsfBvGMoFTHZCT7Igae-5_jszu409dVJ_wEmNw7alCk,10208
-hammad/genai/types/tools.py,sha256=2VTH1LhKKtrIOqvq7JitYgtOvApLAoWTZH-4ogNtL9E,16509
+hammad/genai/types/tools.py,sha256=3p7qhZcilP_NOCOnufCkubTeYN0yC7Ij5bqrUy-FYow,16554
 hammad/logging/__init__.py,sha256=VtskZx0bKEAJ9FHTMflhB1CzeFUxLpDT5HPgcecAXUo,701
 hammad/logging/decorators.py,sha256=VbI1x3P4ft0-0BGjXq7nQgiuNqcXAA51CGmoSn47iSw,30122
-hammad/logging/logger.py,sha256=bHmA1osHwbA7B4noyQp1GmlLmNkQvAXQigr-OC4XVH8,31536
+hammad/logging/logger.py,sha256=5Y41gCtH7APxNjIXtsZg1E9nwpi2xTgRAoC2l-QKil4,31706
 hammad/mcp/__init__.py,sha256=5oTU-BLYjfz6fBHDH9cyWg3DpQ6Qar-jodbCR05SuWo,1123
 hammad/mcp/client/__init__.py,sha256=_SfnKvd5Za-FfFoE5GcXkBY9WcwprZND9SyZ6RY--no,795
 hammad/mcp/client/client.py,sha256=auKCiIJfcZkuVFRapTpqYP4PxoyIfx40gVbMYLBdTzI,20565
@@ -121,7 +121,7 @@ hammad/web/openapi/__init__.py,sha256=JhJQ6_laBmB2djIYFc0vgGha2GsdUe4FP1LDdZCQ5J
 hammad/web/openapi/client.py,sha256=1pXz7KAO_0pN4kQZoWKWskXDYGiJ535TsPO1GGCiC0E,26816
 hammad/web/search/__init__.py,sha256=e9A6znPIiZCz-4secyHbUs0uUGf5yAqW6wGacgx961U,24
 hammad/web/search/client.py,sha256=LIx2MsHhn6cRTuq5i1mWowRTdIhPobY4GQV3S3bk9lk,36694
-hammad_python-0.0.20.dist-info/METADATA,sha256=H-iyFt1AuR4ys_APfIVmnyp8t4Kkhl2xUehhSbw-EfQ,6570
-hammad_python-0.0.20.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hammad_python-0.0.20.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
-hammad_python-0.0.20.dist-info/RECORD,,
+hammad_python-0.0.22.dist-info/METADATA,sha256=OFmPfD3CcZq0Et0hWl2dBUjRNm4IcYZKL1EX8aTJPsU,6570
+hammad_python-0.0.22.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hammad_python-0.0.22.dist-info/licenses/LICENSE,sha256=h74yFUWjbBaodcWG5wNmm30npjl8obVcxD-1nQfUp2I,1069
+hammad_python-0.0.22.dist-info/RECORD,,