hammad-python 0.0.24__py3-none-any.whl → 0.0.26__py3-none-any.whl

hammad/genai/agents/agent.py

@@ -11,6 +11,7 @@ from typing import (
     Optional,
     Union,
     Dict,
+    TypeAlias,
     overload,
     TYPE_CHECKING,
 )
@@ -49,7 +50,10 @@ from .types.agent_hooks import HookManager, HookDecorator
 from .types.agent_messages import AgentMessages
 
 if TYPE_CHECKING:
-    pass
+    try:
+        from fasta2a import FastA2A
+    except ImportError:
+        FastA2A: TypeAlias = Any
 
 
 T = TypeVar("T")
@@ -1058,7 +1062,8 @@ Please update the appropriate fields based on the conversation. Only update fiel
                         f"Agent '{self.name}' completed execution in {step + 1} steps"
                     )
                     # Now we can make the final call with the output_type if specified
-                    if output_type:
+                    # Only make structured output call for non-str types
+                    if output_type and output_type != str:
                         # Make a final call with the structured output type
                         final_model_kwargs = kwargs.copy()
                         final_model_kwargs["type"] = output_type
@@ -1129,8 +1134,8 @@ Please update the appropriate fields based on the conversation. Only update fiel
             # Max steps reached - return last response
             if steps:
                 final_response = steps[-1]
-                # If we have an output_type, make a final structured call
-                if output_type:
+                # If we have an output_type, make a final structured call (but not for str)
+                if output_type and output_type != str:
                     final_model_kwargs = kwargs.copy()
                     final_model_kwargs["type"] = output_type
                     if self.instructor_mode:
@@ -1168,7 +1173,7 @@ Please update the appropriate fields based on the conversation. Only update fiel
             else:
                 # No steps taken, make a final call
                 final_model_kwargs = kwargs.copy()
-                if output_type:
+                if output_type and output_type != str:
                     final_model_kwargs["type"] = output_type
                 if self.instructor_mode:
                     final_model_kwargs["instructor_mode"] = self.instructor_mode
@@ -1444,7 +1449,8 @@ Please update the appropriate fields based on the conversation. Only update fiel
 
                     # This is the final step (either no end_strategy or end_tool was called)
                     # Now we can make the final call with the output_type if specified
-                    if output_type:
+                    # Only make structured output call for non-str types
+                    if output_type and output_type != str:
                         # Make a final call with the structured output type
                         final_model_kwargs = kwargs.copy()
                         final_model_kwargs["type"] = output_type
@@ -1515,8 +1521,8 @@ Please update the appropriate fields based on the conversation. Only update fiel
             # Max steps reached - return last response
             if steps:
                 final_response = steps[-1]
-                # If we have an output_type, make a final structured call
-                if output_type:
+                # If we have an output_type, make a final structured call (but not for str)
+                if output_type and output_type != str:
                     final_model_kwargs = kwargs.copy()
                     final_model_kwargs["type"] = output_type
                     if self.instructor_mode:
@@ -1554,7 +1560,7 @@ Please update the appropriate fields based on the conversation. Only update fiel
             else:
                 # No steps taken, make a final call
                 final_model_kwargs = kwargs.copy()
-                if output_type:
+                if output_type and output_type != str:
                     final_model_kwargs["type"] = output_type
                 if self.instructor_mode:
                     final_model_kwargs["instructor_mode"] = self.instructor_mode
@@ -1621,6 +1627,106 @@ Please update the appropriate fields based on the conversation. Only update fiel
             **kwargs,
         )
 
+    def as_a2a(
+        self,
+        *,
+        # Worker configuration
+        context: Optional[AgentContext] = None,
+        # Storage and broker configuration
+        storage: Optional[Any] = None,
+        broker: Optional[Any] = None,
+        # Server configuration
+        host: str = "0.0.0.0",
+        port: int = 8000,
+        reload: bool = False,
+        workers: int = 1,
+        log_level: str = "info",
+        # A2A configuration
+        name: Optional[str] = None,
+        url: Optional[str] = None,
+        version: str = "1.0.0",
+        description: Optional[str] = None,
+        # Advanced configuration
+        lifespan_timeout: int = 30,
+        **uvicorn_kwargs: Any,
+    ) -> "FastA2A":  # type: ignore
+        """
+        Convert this agent to an A2A server application.
+
+        This method creates a FastA2A server that can handle A2A requests
+        for this agent instance. It sets up the necessary Worker, Storage,
+        and Broker components automatically.
+
+        Args:
+            context: Initial context for the agent
+            storage: Custom storage backend (defaults to InMemoryStorage)
+            broker: Custom broker backend (defaults to InMemoryBroker)
+            host: Host to bind the server to
+            port: Port to bind the server to
+            reload: Enable auto-reload for development
+            workers: Number of worker processes
+            log_level: Logging level
+            name: Agent name for the A2A server (defaults to agent's name)
+            url: URL where the agent is hosted
+            version: API version
+            description: API description for the A2A server (defaults to agent's description)
+            lifespan_timeout: Timeout for lifespan events
+            **uvicorn_kwargs: Additional arguments passed to uvicorn
+
+        Returns:
+            FastA2A application instance that can be run with uvicorn
+
+        Examples:
+            Convert agent to A2A server:
+            ```python
+            agent = Agent(
+                name="assistant",
+                instructions="You are a helpful assistant",
+                model="openai/gpt-4o-mini"
+            )
+
+            app = agent.as_a2a(port=8080)
+
+            # Run with uvicorn
+            import uvicorn
+            uvicorn.run(app, host="0.0.0.0", port=8080)
+            ```
+
+            Or use the CLI:
+            ```bash
+            uvicorn mymodule:agent.as_a2a() --reload
+            ```
+
+            With custom configuration:
+            ```python
+            app = agent.as_a2a(
+                name="My Assistant API",
+                description="A helpful AI assistant",
+                host="localhost",
+                port=3000
+            )
+            ```
+        """
+        from ..a2a import as_a2a_app
+
+        return as_a2a_app(
+            self,
+            context=context,
+            storage=storage,
+            broker=broker,
+            host=host,
+            port=port,
+            reload=reload,
+            workers=workers,
+            log_level=log_level,
+            name=name or self.name,
+            url=url,
+            version=version,
+            description=description or self.description,
+            lifespan_timeout=lifespan_timeout,
+            **uvicorn_kwargs,
+        )
+
     def iter(
         self,
         messages: AgentMessages,

hammad/genai/agents/run.py

@@ -3,6 +3,7 @@
 Standalone functions for running agents with full parameter typing.
 """
 
+import functools
 from typing import (
     Any,
     Callable,
@@ -40,6 +41,7 @@ __all__ = [
     "async_run_agent",
     "run_agent_iter",
     "async_run_agent_iter",
+    "agent_decorator",
 ]
 
 T = TypeVar("T")
@@ -209,8 +211,20 @@ def run_agent(
         ...     context=context
         ... )
     """
-    agent = Agent(verbose=verbose, debug=debug, **kwargs)
-    return agent.run(messages, verbose=verbose, debug=debug, **kwargs)
+    # Separate agent constructor parameters from run parameters
+    agent_constructor_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k in ["name", "instructions", "description", "tools", "settings", "model"]
+    }
+    agent_run_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k not in ["name", "instructions", "description", "tools", "settings"]
+    }
+
+    agent = Agent(verbose=verbose, debug=debug, **agent_constructor_params)
+    return agent.run(messages, verbose=verbose, debug=debug, **agent_run_params)
 
 
 # Overloads for async_run_agent
@@ -371,8 +385,22 @@ async def async_run_agent(
         ...     )
         ...     return response.output
     """
-    agent = Agent(verbose=verbose, debug=debug, **kwargs)
-    return await agent.async_run(messages, verbose=verbose, debug=debug, **kwargs)
+    # Separate agent constructor parameters from run parameters
+    agent_constructor_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k in ["name", "instructions", "description", "tools", "settings", "model"]
+    }
+    agent_run_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k not in ["name", "instructions", "description", "tools", "settings"]
+    }
+
+    agent = Agent(verbose=verbose, debug=debug, **agent_constructor_params)
+    return await agent.async_run(
+        messages, verbose=verbose, debug=debug, **agent_run_params
+    )
 
 
 # Overloads for run_agent_iter
@@ -545,8 +573,22 @@ def run_agent_iter(
         ... except Exception as e:
         ...     print(f"Stream error: {e}")
     """
-    agent = Agent(verbose=verbose, debug=debug, **kwargs)
-    return agent.run(messages, stream=True, verbose=verbose, debug=debug, **kwargs)
+    # Separate agent constructor parameters from run parameters
+    agent_constructor_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k in ["name", "instructions", "description", "tools", "settings", "model"]
+    }
+    agent_run_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k not in ["name", "instructions", "description", "tools", "settings"]
+    }
+
+    agent = Agent(verbose=verbose, debug=debug, **agent_constructor_params)
+    return agent.run(
+        messages, stream=True, verbose=verbose, debug=debug, **agent_run_params
+    )
 
 
 # Overloads for async_run_agent_iter
@@ -649,5 +691,334 @@ def async_run_agent_iter(
     Returns:
         An AgentStream that can be iterated over asynchronously
     """
-    agent = Agent(verbose=verbose, debug=debug, **kwargs)
-    return agent.run(messages, stream=True, verbose=verbose, debug=debug, **kwargs)
+    # Separate agent constructor parameters from run parameters
+    agent_constructor_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k in ["name", "instructions", "description", "tools", "settings", "model"]
+    }
+    agent_run_params = {
+        k: v
+        for k, v in kwargs.items()
+        if k not in ["name", "instructions", "description", "tools", "settings"]
+    }
+
+    agent = Agent(verbose=verbose, debug=debug, **agent_constructor_params)
+    return agent.run(
+        messages, stream=True, verbose=verbose, debug=debug, **agent_run_params
+    )
+
+
+def agent_decorator(
+    fn: Union[str, Callable, None] = None,
+    *,
+    # Agent settings
+    name: Optional[str] = None,
+    instructions: Optional[str] = None,
+    description: Optional[str] = None,
+    tools: Union[List["Tool"], Callable, None] = None,
+    settings: Optional[AgentSettings] = None,
+    # Context management
+    context: Optional["AgentContext"] = None,
+    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",
+    # Model settings
+    model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
+    max_steps: Optional[int] = None,
+    instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    return_output: bool = True,
+    # End strategy
+    end_strategy: Optional[Literal["tool"]] = None,
+    end_tool: Optional[Callable] = None,
+    # LM settings
+    timeout: Optional[Union[float, str, "Timeout"]] = None,
+    temperature: Optional[float] = None,
+    top_p: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+    presence_penalty: Optional[float] = None,
+    frequency_penalty: Optional[float] = None,
+    seed: Optional[int] = None,
+    user: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
+):
+    """Decorator that converts a function into an agent.
+
+    The function's parameters become the input to the LLM (converted to a string),
+    the function's return type annotation becomes the agent's output type,
+    and the function's docstring becomes the agent's instructions.
+
+    Works with both sync and async functions.
+
+    Can be used in multiple ways:
+
+    1. As a decorator with parameters:
+       @agent_decorator(name="steve", temperature=0.7)
+       def my_agent():
+           pass
+
+    2. As a decorator without parameters:
+       @agent_decorator
+       def my_agent():
+           pass
+
+    3. As an inline function with name as first argument:
+       agent = agent_decorator("steve")
+       # Then use: decorated_func = agent(my_function)
+
+    4. As an inline function with all parameters:
+       agent = agent_decorator(name="steve", temperature=0.7)
+       # Then use: decorated_func = agent(my_function)
+    """
+    # Handle different calling patterns
+    if callable(fn):
+        # Case: @agent_decorator (no parentheses)
+        func = fn
+        actual_name = name or "agent"
+        return _create_agent_wrapper(
+            func,
+            actual_name,
+            instructions,
+            description,
+            tools,
+            settings,
+            context,
+            context_updates,
+            context_confirm,
+            context_strategy,
+            context_max_retries,
+            context_confirm_instructions,
+            context_selection_instructions,
+            context_update_instructions,
+            context_format,
+            model,
+            max_steps,
+            instructor_mode,
+            return_output,
+            end_strategy,
+            end_tool,
+            timeout,
+            temperature,
+            top_p,
+            max_tokens,
+            presence_penalty,
+            frequency_penalty,
+            seed,
+            user,
+            verbose,
+            debug,
+        )
+    elif isinstance(fn, str):
+        # Case: agent_decorator("steve") - first arg is name
+        actual_name = fn
+    else:
+        # Case: agent_decorator() or agent_decorator(name="steve")
+        actual_name = name or "agent"
+
+    def decorator(func: Callable) -> Callable:
+        return _create_agent_wrapper(
+            func,
+            actual_name,
+            instructions,
+            description,
+            tools,
+            settings,
+            context,
+            context_updates,
+            context_confirm,
+            context_strategy,
+            context_max_retries,
+            context_confirm_instructions,
+            context_selection_instructions,
+            context_update_instructions,
+            context_format,
+            model,
+            max_steps,
+            instructor_mode,
+            return_output,
+            end_strategy,
+            end_tool,
+            timeout,
+            temperature,
+            top_p,
+            max_tokens,
+            presence_penalty,
+            frequency_penalty,
+            seed,
+            user,
+            verbose,
+            debug,
+        )
+
+    return decorator
+
+
+def _create_agent_wrapper(
+    func: Callable,
+    name: str,
+    instructions: Optional[str],
+    description: Optional[str],
+    tools: Union[List["Tool"], Callable, None],
+    settings: Optional[AgentSettings],
+    context: Optional["AgentContext"],
+    context_updates: Optional[
+        Union[List[Literal["before", "after"]], Literal["before", "after"]]
+    ],
+    context_confirm: bool,
+    context_strategy: Literal["selective", "all"],
+    context_max_retries: int,
+    context_confirm_instructions: Optional[str],
+    context_selection_instructions: Optional[str],
+    context_update_instructions: Optional[str],
+    context_format: Literal["json", "python", "markdown"],
+    model: Optional[Union["LanguageModel", "LanguageModelName"]],
+    max_steps: Optional[int],
+    instructor_mode: Optional["LanguageModelInstructorMode"],
+    return_output: bool,
+    end_strategy: Optional[Literal["tool"]],
+    end_tool: Optional[Callable],
+    timeout: Optional[Union[float, str, "Timeout"]],
+    temperature: Optional[float],
+    top_p: Optional[float],
+    max_tokens: Optional[int],
+    presence_penalty: Optional[float],
+    frequency_penalty: Optional[float],
+    seed: Optional[int],
+    user: Optional[str],
+    verbose: bool,
+    debug: bool,
+) -> Callable:
+    """Helper function to create the actual agent wrapper."""
+    import inspect
+    import asyncio
+    from typing import get_type_hints
+
+    # Get function metadata
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+    return_type = type_hints.get("return", str)
+    func_instructions = instructions or func.__doc__ or ""
+
+    # Check if function is async
+    is_async = asyncio.iscoroutinefunction(func)
+
+    if is_async:
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            # Convert function parameters to message string
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Create message from parameters
+            param_parts = []
+            for param_name, param_value in bound_args.arguments.items():
+                param_parts.append(f"{param_name}: {param_value}")
+            message = "\n".join(param_parts)
+
+            # Run agent with extracted parameters
+            response = await async_run_agent(
+                messages=message,
+                output_type=return_type,
+                name=name,
+                instructions=func_instructions,
+                description=description,
+                tools=tools,
+                settings=settings,
+                context=context,
+                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,
+                model=model or "openai/gpt-4o-mini",
+                max_steps=max_steps,
+                instructor_mode=instructor_mode,
+                end_strategy=end_strategy,
+                end_tool=end_tool,
+                timeout=timeout,
+                temperature=temperature,
+                top_p=top_p,
+                max_tokens=max_tokens,
+                presence_penalty=presence_penalty,
+                frequency_penalty=frequency_penalty,
+                seed=seed,
+                user=user,
+                verbose=verbose,
+                debug=debug,
+            )
+
+            # Return just the output if return_output is True (default behavior)
+            if return_output:
+                return response.output
+            else:
+                return response
+
+        return async_wrapper
+    else:
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            # Convert function parameters to message string
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            # Create message from parameters
+            param_parts = []
+            for param_name, param_value in bound_args.arguments.items():
+                param_parts.append(f"{param_name}: {param_value}")
+            message = "\n".join(param_parts)
+
+            # Run agent with extracted parameters
+            response = run_agent(
+                messages=message,
+                output_type=return_type,
+                name=name,
+                instructions=func_instructions,
+                description=description,
+                tools=tools,
+                settings=settings,
+                context=context,
+                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,
+                model=model or "openai/gpt-4o-mini",
+                max_steps=max_steps,
+                instructor_mode=instructor_mode,
+                end_strategy=end_strategy,
+                end_tool=end_tool,
+                timeout=timeout,
+                temperature=temperature,
+                top_p=top_p,
+                max_tokens=max_tokens,
+                presence_penalty=presence_penalty,
+                frequency_penalty=frequency_penalty,
+                seed=seed,
+                user=user,
+                verbose=verbose,
+                debug=debug,
+            )
+
+            # Return just the output if return_output is True (default behavior)
+            if return_output:
+                return response.output
+            else:
+                return response
+
+        return sync_wrapper

hammad/genai/graphs/__init__.py

@@ -46,7 +46,16 @@ from ..._internal import create_getattr_importer
 
 
 if TYPE_CHECKING:
-    from .base import BaseGraph, action, ActionNode, GraphBuilder
+    from .base import (
+        ActionDecorator,
+        ActionNode,
+        ActionSettings,
+        BaseGraph,
+        GraphBuilder,
+        action,
+        select,
+        SelectionStrategy,
+    )
     from .types import (
         GraphContext,
         GraphResponse,
@@ -77,11 +86,14 @@ __all__ = (
     # Core graph classes
     "BaseGraph",
     "GraphBuilder",
+    "ActionDecorator",
     # Action system
     "action",
     "ActionNode",
     "ActionSettings",
     "ActionInfo",
+    "select",
+    "SelectionStrategy",
     # Plugin system
     "plugin",
     "BasePlugin",