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

hammad/genai/agents/agent.py

@@ -354,22 +354,43 @@ class Agent(BaseGenAIModel, Generic[T]):
     ) -> 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,
+            "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"], context_updates=None
+        self,
+        context: AgentContext,
+        timing: Literal["before", "after"],
+        context_updates=None,
     ) -> bool:
         """Determine if context should be updated based on timing and configuration."""
-        effective_context_updates = context_updates if context_updates is not None else 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
 
@@ -405,7 +426,9 @@ class Agent(BaseGenAIModel, Generic[T]):
             if isinstance(context, BaseModel):
                 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")
+                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"
@@ -415,7 +438,7 @@ class Agent(BaseGenAIModel, Generic[T]):
 
             return create_model(
                 f"Update{field_name.capitalize()}",
-                **{field_name: (field_type, Field(description=description))}
+                **{field_name: (field_type, Field(description=description))},
             )
         else:
             # All fields update - create a model with the exact same fields as the context
@@ -425,9 +448,14 @@ class Agent(BaseGenAIModel, Generic[T]):
                 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))
-                
+                    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
@@ -435,12 +463,21 @@ class Agent(BaseGenAIModel, Generic[T]):
                 for key, value in context.items():
                     field_type = type(value)
                     description = f"Current value: {value}"
-                    field_definitions[key] = (field_type, Field(description=description))
-                
+                    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")))
+                return create_model(
+                    "ContextUpdate",
+                    updates=(
+                        Dict[str, Any],
+                        Field(description="Dictionary of field updates"),
+                    ),
+                )
 
     def _perform_context_update(
         self,
@@ -452,7 +489,7 @@ class Agent(BaseGenAIModel, Generic[T]):
     ) -> AgentContext:
         """Perform context update with retries and error handling."""
         updated_context = context
-        
+
         # Use effective settings or defaults
         if effective_settings is None:
             effective_settings = {
@@ -470,16 +507,18 @@ class Agent(BaseGenAIModel, Generic[T]):
                 # Check if update is needed (if confirmation is enabled)
                 if effective_settings["context_confirm"]:
                     confirm_model = self._create_context_confirm_model()
-                    
+
                     # Create detailed instructions with context structure
-                    context_structure = _format_context_for_instructions(updated_context, effective_settings["context_format"])
+                    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']}"
 
@@ -499,16 +538,18 @@ Should the context be updated based on the new information provided in the conve
                     selection_model = self._create_context_selection_model(
                         updated_context
                     )
-                    
+
                     # Create detailed instructions with context structure
-                    context_structure = _format_context_for_instructions(updated_context, effective_settings["context_format"])
+                    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']}"
 
@@ -526,14 +567,18 @@ Choose only the fields that need to be updated based on the new information prov
                             updated_context, field_name
                         )
                         # Get current field value for context
-                        current_value = getattr(updated_context, field_name) if isinstance(updated_context, BaseModel) else updated_context.get(field_name)
-                        
+                        current_value = (
+                            getattr(updated_context, field_name)
+                            if isinstance(updated_context, BaseModel)
+                            else updated_context.get(field_name)
+                        )
+
                         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']}"
 
@@ -555,16 +600,18 @@ Please provide the new value for {field_name} based on the information from the
                 else:  # strategy == "all"
                     # Update all fields at once
                     update_model = self._create_context_update_model(updated_context)
-                    
+
                     # Create detailed instructions with context structure
-                    context_structure = _format_context_for_instructions(updated_context, effective_settings["context_format"])
+                    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']}"
 
@@ -576,7 +623,7 @@ Please update the appropriate fields based on the conversation. Only update fiel
                     )
 
                     # Apply the updates
-                    if hasattr(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
@@ -584,10 +631,18 @@ Please update the appropriate fields based on the conversation. Only update fiel
                     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()):
+                        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)
+                                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)
@@ -808,7 +863,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
         # 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"]):
+            if context and self._should_update_context(
+                context, "before", effective_context_settings["context_updates"]
+            ):
                 context = self._perform_context_update(
                     context=context,
                     model=working_model,
@@ -836,9 +893,7 @@ Please update the appropriate fields based on the conversation. Only update fiel
             # Get language model response
             response = working_model.run(
                 messages=formatted_messages,
-                tools=[tool.to_dict() 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,
             )
 
@@ -860,7 +915,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
             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"]):
+                if context and self._should_update_context(
+                    context, "after", effective_context_settings["context_updates"]
+                ):
                     context = self._perform_context_update(
                         context=context,
                         model=working_model,
@@ -886,7 +943,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
             )
 
         # Update context after processing if configured
-        if context and self._should_update_context(context, "after", effective_context_settings["context_updates"]):
+        if context and self._should_update_context(
+            context, "after", effective_context_settings["context_updates"]
+        ):
             context = self._perform_context_update(
                 context=context,
                 model=working_model,
@@ -1017,7 +1076,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
         # 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"]):
+            if context and self._should_update_context(
+                context, "before", effective_context_settings["context_updates"]
+            ):
                 context = self._perform_context_update(
                     context=context,
                     model=working_model,
@@ -1045,9 +1106,7 @@ Please update the appropriate fields based on the conversation. Only update fiel
             # Get language model response
             response = await working_model.async_run(
                 messages=formatted_messages,
-                tools=[tool.to_dict() 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,
             )
 
@@ -1069,7 +1128,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
             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"]):
+                if context and self._should_update_context(
+                    context, "after", effective_context_settings["context_updates"]
+                ):
                     context = self._perform_context_update(
                         context=context,
                         model=working_model,
@@ -1095,7 +1156,9 @@ Please update the appropriate fields based on the conversation. Only update fiel
             )
 
         # Update context after processing if configured
-        if context and self._should_update_context(context, "after", effective_context_settings["context_updates"]):
+        if context and self._should_update_context(
+            context, "after", effective_context_settings["context_updates"]
+        ):
             context = self._perform_context_update(
                 context=context,
                 model=working_model,
@@ -1288,6 +1351,84 @@ Please update the appropriate fields based on the conversation. Only update fiel
         )
 
 
+def create_agent(
+    name: str = "agent",
+    instructions: Optional[str] = None,
+    model: Union[LanguageModel, LanguageModelName] = "openai/gpt-4o-mini",
+    description: Optional[str] = None,
+    tools: Union[List[Tool], Callable, None] = None,
+    settings: Optional[AgentSettings] = None,
+    instructor_mode: Optional[LanguageModelInstructorMode] = None,
+    # Context management parameters
+    context_updates: Optional[
+        Union[List[Literal["before", "after"]], Literal["before", "after"]]
+    ] = None,
+    context_confirm: bool = False,
+    context_strategy: Literal["selective", "all"] = "all",
+    context_max_retries: int = 3,
+    context_confirm_instructions: Optional[str] = None,
+    context_selection_instructions: Optional[str] = None,
+    context_update_instructions: Optional[str] = None,
+    context_format: Literal["json", "python", "markdown"] = "json",
+    **kwargs: Any,
+) -> Agent[T]:
+    """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 = create_agent(name="assistant", instructions="You are helpful")
+
+        Agent with tools:
+        >>> def calculator(x: int, y: int) -> int:
+        ...     return x + y
+        >>> agent = create_agent(tools=[calculator])
+
+        Agent with custom settings:
+        >>> settings = AgentSettings(max_steps=5)
+        >>> agent = create_agent(settings=settings, model="gpt-4")
+    """
+    return Agent(
+        name=name,
+        instructions=instructions,
+        model=model,
+        description=description,
+        tools=tools,
+        settings=settings,
+        instructor_mode=instructor_mode,
+        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,
+        **kwargs,
+    )
+
+
 __all__ = [
     "Agent",
     "AgentSettings",
@@ -1295,4 +1436,5 @@ __all__ = [
     "AgentEvent",
     "HookManager",
     "HookDecorator",
+    "create_agent",
 ]

hammad/genai/agents/types/agent_response.py

@@ -57,7 +57,7 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
     empty.
     """
 
-    context: AgentContext = None
+    context: AgentContext | None = None
     """
     The final context object after agent execution.
     
@@ -68,7 +68,7 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
     @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}"
@@ -91,7 +91,9 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
 
         # Show context if available
         if self.context:
-            output += f"\n>>> Final Context: {self._format_context_display(self.context)}"
+            output += (
+                f"\n>>> Final Context: {self._format_context_display(self.context)}"
+            )
 
         return output
 
@@ -99,16 +101,16 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
         """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'):
+            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():
@@ -116,7 +118,7 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
                     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

@@ -87,18 +87,20 @@ class AgentResponseChunk(LanguageModelResponseChunk[T], Generic[T]):
     def __str__(self) -> str:
         """String representation of the chunk."""
         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}"
-        
+
         return output
 
 
-class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentContext]):
+class AgentStream(
+    BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentContext]
+):
     """Stream of agent responses that can be used in sync and async contexts."""
 
     def __init__(
@@ -151,16 +153,17 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
     def _format_messages(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         if 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)
@@ -184,16 +187,18 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
         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"):
+            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
             )
@@ -204,7 +209,9 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
             self.current_step += 1
 
             # Update context before processing if configured
-            if self.current_context and self.agent._should_update_context(self.current_context, "before"):
+            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,
@@ -240,7 +247,9 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
         self.current_step += 1
 
         # Update context before processing if configured
-        if self.current_context and self.agent._should_update_context(self.current_context, "before"):
+        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,
@@ -283,16 +292,16 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
         """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'):
+            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():
@@ -300,7 +309,7 @@ class AgentStream(BaseGenAIModelStream[AgentResponseChunk[T]], Generic[T, AgentC
                     items.append(f"{key}='{value}'")
                 else:
                     items.append(f"{key}={value}")
-            
+
             return "{" + ", ".join(items) + "}"
         except Exception:
             return str(context)

hammad/genai/models/embeddings/__init__.py

@@ -5,7 +5,10 @@ from ...._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .model import EmbeddingModel
+    from .model import (
+        EmbeddingModel,
+        create_embedding_model,
+    )
     from .run import (
         run_embedding_model,
         async_run_embedding_model,
@@ -19,6 +22,7 @@ if TYPE_CHECKING:
 
 __all__ = [
     "EmbeddingModel",
+    "create_embedding_model",
     # hammad.genai.models.embeddings.run
     "run_embedding_model",
     "async_run_embedding_model",

hammad/genai/models/embeddings/model.py

@@ -1,7 +1,7 @@
 """hammad.genai.embedding_models.embedding_model"""
 
 import asyncio
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any, List, Optional
 import sys
 
@@ -26,6 +26,7 @@ from ....formatting.text import convert_to_text
 __all__ = (
     "EmbeddingModel",
     "EmbeddingModelError",
+    "create_embedding_model",
 )
 
 
@@ -87,7 +88,7 @@ class EmbeddingModel:
     api_version: Optional[str] = None
     """Optional API version for a custom embedding provider."""
 
-    settings: EmbeddingModelSettings = EmbeddingModelSettings()
+    settings: EmbeddingModelSettings = field(default_factory=EmbeddingModelSettings)
     """Optional settings for the embedding model."""
 
     async def async_run(
@@ -195,3 +196,31 @@ class EmbeddingModel:
                 format=format,
             )
         )
+
+
+def create_embedding_model(
+    model: str | EmbeddingModelName = "openai/text-embedding-3-small",
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_version: Optional[str] = None,
+    api_type: Optional[str] = None,
+    settings: Optional[EmbeddingModelSettings] = None,
+) -> EmbeddingModel:
+    """Create an embedding model instance.
+
+    Args:
+        model (str | EmbeddingModelName) : The model to use for the embedding.
+        base_url (Optional[str]) : The base URL for the API.
+        api_key (Optional[str]) : The API key to use for the request.
+        api_version (Optional[str]) : The version of the API.
+        api_type (Optional[str]) : The API type to use for the request.
+        settings (Optional[EmbeddingModelSettings]) : The settings for the embedding model.
+    """
+    return EmbeddingModel(
+        model=model,
+        base_url=base_url,
+        api_key=api_key,
+        api_version=api_version,
+        api_type=api_type,
+        settings=settings or EmbeddingModelSettings(),
+    )