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

hammad/genai/agents/run.py

@@ -72,6 +72,9 @@ def run_agent(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -81,6 +84,8 @@ def run_agent(
     frequency_penalty: Optional[float] = None,
     seed: Optional[int] = None,
     user: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
 ) -> "AgentResponse[str]": ...
 
 
@@ -111,6 +116,9 @@ def run_agent(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -120,10 +128,14 @@ def run_agent(
     frequency_penalty: Optional[float] = None,
     seed: Optional[int] = None,
     user: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
 ) -> "AgentResponse[T]": ...
 
 
-def run_agent(messages: "AgentMessages", **kwargs: Any) -> "AgentResponse[Any]":
+def run_agent(
+    messages: "AgentMessages", verbose: bool = False, debug: bool = False, **kwargs: Any
+) -> "AgentResponse[Any]":
     """Runs this agent and returns a final agent response or stream.
 
     You can override defaults assigned to this agent from this function directly.
@@ -145,6 +157,8 @@ def run_agent(messages: "AgentMessages", **kwargs: Any) -> "AgentResponse[Any]":
         stream: Whether to return a stream instead of a final response.
             - If True, returns AgentStream for real-time processing
             - If False, returns complete AgentResponse
+        verbose: If True, set logger to INFO level for detailed output
+        debug: If True, set logger to DEBUG level for maximum verbosity
         **kwargs: Additional keyword arguments passed to the language model.
             - Examples: temperature=0.7, top_p=0.9, presence_penalty=0.1
 
@@ -195,8 +209,8 @@ def run_agent(messages: "AgentMessages", **kwargs: Any) -> "AgentResponse[Any]":
         ...     context=context
         ... )
     """
-    agent = Agent(**kwargs)
-    return agent.run(messages, **kwargs)
+    agent = Agent(verbose=verbose, debug=debug, **kwargs)
+    return agent.run(messages, verbose=verbose, debug=debug, **kwargs)
 
 
 # Overloads for async_run_agent
@@ -226,6 +240,9 @@ async def async_run_agent(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -235,6 +252,8 @@ async def async_run_agent(
     frequency_penalty: Optional[float] = None,
     seed: Optional[int] = None,
     user: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
 ) -> "AgentResponse[str]": ...
 
 
@@ -265,6 +284,9 @@ async def async_run_agent(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -274,11 +296,13 @@ async def async_run_agent(
     frequency_penalty: Optional[float] = None,
     seed: Optional[int] = None,
     user: Optional[str] = None,
+    verbose: bool = False,
+    debug: bool = False,
 ) -> "AgentResponse[T]": ...
 
 
 async def async_run_agent(
-    messages: "AgentMessages", **kwargs: Any
+    messages: "AgentMessages", verbose: bool = False, debug: bool = False, **kwargs: Any
 ) -> "AgentResponse[Any]":
     """Runs this agent asynchronously and returns a final agent response.
 
@@ -347,8 +371,8 @@ async def async_run_agent(
         ...     )
         ...     return response.output
     """
-    agent = Agent(**kwargs)
-    return await agent.async_run(messages, **kwargs)
+    agent = Agent(verbose=verbose, debug=debug, **kwargs)
+    return await agent.async_run(messages, verbose=verbose, debug=debug, **kwargs)
 
 
 # Overloads for run_agent_iter
@@ -378,6 +402,9 @@ def run_agent_iter(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -417,6 +444,9 @@ def run_agent_iter(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -429,7 +459,9 @@ def run_agent_iter(
 ) -> "AgentStream[T]": ...
 
 
-def run_agent_iter(messages: "AgentMessages", **kwargs: Any) -> "AgentStream[Any]":
+def run_agent_iter(
+    messages: "AgentMessages", verbose: bool = False, debug: bool = False, **kwargs: Any
+) -> "AgentStream[Any]":
     """Iterate over agent steps, yielding each step response.
 
     You can override defaults assigned to this agent from this function directly.
@@ -513,8 +545,8 @@ def run_agent_iter(messages: "AgentMessages", **kwargs: Any) -> "AgentStream[Any
         ... except Exception as e:
         ...     print(f"Stream error: {e}")
     """
-    agent = Agent(**kwargs)
-    return agent.run(messages, stream=True, **kwargs)
+    agent = Agent(verbose=verbose, debug=debug, **kwargs)
+    return agent.run(messages, stream=True, verbose=verbose, debug=debug, **kwargs)
 
 
 # Overloads for async_run_agent_iter
@@ -544,6 +576,9 @@ def async_run_agent_iter(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -583,6 +618,9 @@ def async_run_agent_iter(
     model: Optional[Union["LanguageModel", "LanguageModelName"]] = None,
     max_steps: Optional[int] = None,
     instructor_mode: Optional["LanguageModelInstructorMode"] = None,
+    # 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,
@@ -596,7 +634,7 @@ def async_run_agent_iter(
 
 
 def async_run_agent_iter(
-    messages: "AgentMessages", **kwargs: Any
+    messages: "AgentMessages", verbose: bool = False, debug: bool = False, **kwargs: Any
 ) -> "AgentStream[Any]":
     """Async iterate over agent steps, yielding each step response.
 
@@ -611,5 +649,5 @@ def async_run_agent_iter(
     Returns:
         An AgentStream that can be iterated over asynchronously
     """
-    agent = Agent(**kwargs)
-    return agent.run(messages, stream=True, **kwargs)
+    agent = Agent(verbose=verbose, debug=debug, **kwargs)
+    return agent.run(messages, stream=True, verbose=verbose, debug=debug, **kwargs)

hammad/genai/agents/types/agent_response.py

@@ -1,6 +1,7 @@
 """hammad.genai.agents.types.agent_response"""
 
 from typing import List, Any, TypeVar, Literal, Generic
+from pydantic import Field
 
 from ....cache import cached
 from ....typing import get_type_description
@@ -49,7 +50,7 @@ class AgentResponse(LanguageModelResponse[T], Generic[T, AgentContext]):
     type: Literal["agent"] = "agent"
     """The type of the response. Always `agent`."""
 
-    steps: List[LanguageModelResponse[str]]
+    steps: List[LanguageModelResponse[str]] = Field(default_factory=list)
     """
     A list of steps taken by the agent **BEFORE** its final output.
 

hammad/genai/graphs/__init__.py

@@ -0,0 +1,113 @@
+"""hammad.genai.graphs - Graph-based workflow framework built on pydantic-graph
+
+This module provides a high-level interface for creating graph-based workflows
+that integrate seamlessly with hammad's Agent and LanguageModel infrastructure.
+
+Key Features:
+- Action decorator system for defining graph nodes
+- Automatic integration with Agent and LanguageModel
+- IDE-friendly type hints and parameter unpacking
+- Plugin system for extensibility
+- Built on pydantic-graph for robust execution
+
+Basic Usage:
+    from hammad.genai.graphs import BaseGraph, action
+    from pydantic import BaseModel
+
+    class MyState(BaseModel):
+        count: int = 0
+
+    class CountingGraph(BaseGraph[MyState, str]):
+        @action.start()
+        def start_counting(self, ctx, agent, target: int):
+            # Use agent for AI operations
+            response = agent.run(f"Count from 1 to {target}")
+            return response.output
+
+    # Usage
+    graph = CountingGraph()
+    result = graph.run(target=5)
+    print(result.output)
+
+Advanced Usage with Plugins:
+    from hammad.genai.graphs import plugin
+
+    @plugin.history(summarize=True)
+    @plugin.memory(collection_name="counting")
+    class AdvancedGraph(BaseGraph[MyState, str]):
+        @action.start(instructions="You are a helpful counting assistant")
+        def count_with_memory(self, ctx, agent, target: int):
+            # Agent will have instructions and plugins automatically applied
+            return agent.run(f"Count to {target} and remember this session")
+"""
+
+from typing import TYPE_CHECKING
+from ..._internal import create_getattr_importer
+
+
+if TYPE_CHECKING:
+    from .base import BaseGraph, action, ActionNode, GraphBuilder
+    from .types import (
+        GraphContext,
+        GraphResponse,
+        GraphState,
+        BasePlugin,
+        ActionSettings,
+        ActionInfo,
+        GraphEvent,
+        GraphHistoryEntry,
+        GraphStream,
+        GraphResponseChunk,
+        GraphNode,
+        GraphEnd,
+        PydanticGraphContext,
+    )
+    from .plugins import (
+        plugin,
+        PluginDecorator,
+        HistoryPlugin,
+        MemoryPlugin,
+        AudioPlugin,
+        ServePlugin,
+        SettingsPlugin,
+    )
+
+
+__all__ = (
+    # Core graph classes
+    "BaseGraph",
+    "GraphBuilder",
+    # Action system
+    "action",
+    "ActionNode",
+    "ActionSettings",
+    "ActionInfo",
+    # Plugin system
+    "plugin",
+    "BasePlugin",
+    "PluginDecorator",
+    "HistoryPlugin",
+    "MemoryPlugin",
+    "AudioPlugin",
+    "ServePlugin",
+    "SettingsPlugin",
+    # Types and context
+    "GraphContext",
+    "GraphResponse",
+    "GraphState",
+    "GraphEvent",
+    "GraphHistoryEntry",
+    "GraphStream",
+    "GraphResponseChunk",
+    # Re-exports from pydantic-graph
+    "GraphNode",
+    "GraphEnd",
+    "PydanticGraphContext",
+)
+
+
+__getattr__ = create_getattr_importer(__all__)
+
+
+def __dir__() -> list[str]:
+    return list(__all__)