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

hammad/genai/agents/types/agent_stream.py

@@ -1,327 +0,0 @@
-"""hammad.genai.agents.types.agent_stream"""
-
-from typing import (
-    Generic,
-    TypeVar,
-    Iterator,
-    AsyncIterator,
-    List,
-    Any,
-    Dict,
-    Optional,
-    TYPE_CHECKING,
-    Type,
-    Union,
-    Literal,
-)
-from contextlib import contextmanager, asynccontextmanager
-
-from ...types.base import BaseGenAIModelStream
-from ...types.tools import (
-    Tool,
-    execute_tools_from_language_model_response,
-)
-from ...models.language.model import LanguageModel
-from ...models.language.types import (
-    LanguageModelMessages,
-    LanguageModelResponse,
-    LanguageModelResponseChunk,
-    LanguageModelStream,
-    LanguageModelSettings,
-)
-from ...models.language.utils.requests import (
-    parse_messages_input as parse_messages,
-    consolidate_system_messages,
-)
-
-from .agent_response import (
-    AgentResponse,
-    _create_agent_response_from_language_model_response,
-)
-from .agent_context import AgentContext
-
-if TYPE_CHECKING:
-    from ..agent import Agent
-
-T = TypeVar("T")
-
-
-class AgentResponseChunk(LanguageModelResponseChunk[T], Generic[T]):
-    """A chunk from an agent response stream representing a single step."""
-
-    def __init__(
-        self,
-        step_number: int,
-        response: LanguageModelResponse[str],
-        output: T | None = None,
-        content: str | None = None,
-        model: str | None = None,
-        is_final: bool = False,
-        **kwargs: Any,
-    ):
-        """Initialize a AgentResponseChunk.
-
-        Args:
-            step_number: The step number of this chunk
-            response: The language model response for this step
-            output: The output value
-            content: The content string
-            model: The model name
-            is_final: Whether this is the final chunk
-            **kwargs: Additional keyword arguments
-        """
-        super().__init__(
-            output=output if output is not None else response.output,
-            content=content if content is not None else response.content,
-            model=model if model is not None else response.model,
-            is_final=is_final,
-            **kwargs,
-        )
-        self.step_number = step_number
-        self.response = response
-
-    def __bool__(self) -> bool:
-        """Check if this chunk has meaningful content."""
-        return bool(self.response)
-
-    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]
-):
-    """Stream of agent responses that can be used in sync and async contexts."""
-
-    def __init__(
-        self,
-        agent: "Agent[T]",
-        messages: LanguageModelMessages,
-        model: Optional[Union[LanguageModel, str]] = None,
-        max_steps: Optional[int] = None,
-        context: Optional[AgentContext] = None,
-        output_type: Optional[Type[T]] = None,
-        stream: bool = False,
-        **kwargs: Any,
-    ):
-        self.agent = agent
-        self.messages = messages
-        self.context = context
-        self.output_type = output_type
-        self.stream = stream
-        self.kwargs = kwargs
-        self.current_step = 0
-        self.steps: List[LanguageModelResponse[str]] = []
-        self.current_messages = parse_messages(messages)
-        self.is_done = False
-        self._final_response: Optional[LanguageModelResponse[str]] = None
-
-        # Model setup
-        if model is None:
-            self.model = agent.model
-        elif isinstance(model, str):
-            self.model = LanguageModel(model=model)
-        else:
-            self.model = model
-
-        # Max steps setup
-        self.max_steps = max_steps or agent.settings.max_steps
-
-        # Context handling
-        self.current_context = context
-        self.initial_context = context
-
-        # Model kwargs setup
-        self.model_kwargs = kwargs.copy()
-        if output_type:
-            self.model_kwargs["type"] = output_type
-        if agent.instructor_mode:
-            self.model_kwargs["instructor_mode"] = agent.instructor_mode
-        if stream:
-            self.model_kwargs["stream"] = stream
-
-    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)
-
-    def _process_response(
-        self, response: LanguageModelResponse
-    ) -> AgentResponseChunk[T]:
-        self.current_messages.append(response.to_message())
-
-        if response.has_tool_calls:
-            tool_responses = execute_tools_from_language_model_response(
-                tools=self.agent.tools, response=response
-            )
-            for tool_resp in tool_responses:
-                self.current_messages.append(tool_resp.to_dict())
-
-            self.steps.append(response)
-            return AgentResponseChunk(
-                step_number=self.current_step, response=response, is_final=False
-            )
-        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
-            )
-
-    def __iter__(self) -> Iterator[AgentResponseChunk[T]]:
-        # The context manager handling should be managed by the agent's run method
-        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)
-
-            response = self.model.run(
-                messages=formatted_messages,
-                tools=[tool.model_dump() for tool in self.agent.tools]
-                if self.agent.tools
-                else None,
-                **self.model_kwargs,
-            )
-
-            chunk = self._process_response(response)
-            yield chunk
-            if chunk.is_final:
-                break
-
-    def __aiter__(self) -> AsyncIterator[AgentResponseChunk[T]]:
-        return self
-
-    async def __anext__(self) -> AgentResponseChunk[T]:
-        if self.is_done or self.current_step >= self.max_steps:
-            raise StopAsyncIteration
-
-        # 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)
-
-        response = await self.model.async_run(
-            messages=formatted_messages,
-            tools=[tool.model_dump() for tool in self.agent.tools]
-            if self.agent.tools
-            else None,
-            **self.model_kwargs,
-        )
-
-        chunk = self._process_response(response)
-        if chunk.is_final:
-            self.is_done = True
-        return chunk
-
-    def _build_response(self) -> AgentResponse[T, AgentContext]:
-        if self._final_response:
-            final_response = self._final_response
-        elif self.steps:
-            final_response = self.steps[-1]
-        else:
-            raise RuntimeError("No response generated by the agent.")
-
-        return _create_agent_response_from_language_model_response(
-            response=final_response,
-            steps=self.steps,
-            context=self.current_context,
-        )
-
-    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, AgentContext]:
-        """Collect all steps and return final response."""
-        async for _ in self:
-            pass
-        return self._build_response()

hammad/genai/graphs/__init__.py

@@ -1,125 +0,0 @@
-"""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 (
-        ActionDecorator,
-        ActionNode,
-        ActionSettings,
-        BaseGraph,
-        GraphBuilder,
-        action,
-        select,
-        SelectionStrategy,
-    )
-    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",
-    "ActionDecorator",
-    # Action system
-    "action",
-    "ActionNode",
-    "ActionSettings",
-    "ActionInfo",
-    "select",
-    "SelectionStrategy",
-    # 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__)

hammad/genai/graphs/_utils.py

@@ -1,190 +0,0 @@
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .base import BaseGraph
-
-
-def visualize_base_graph(graph: "BaseGraph", filename: str) -> None:
-    """Generate a visualization of the graph with clean, readable flow."""
-    if not graph._action_nodes or not graph._start_action_name:
-        raise ValueError("No actions defined in graph")
-    
-    # Build our own mermaid code for better control over layout
-    mermaid_lines = ["graph TD"]  # Top-Down layout
-    
-    # Track which nodes we've already added
-    added_nodes = set()
-    
-    # Style definitions
-    mermaid_lines.append("    %% Styles")
-    mermaid_lines.append("    classDef startNode fill:#4CAF50,stroke:#333,stroke-width:2px,color:#fff")
-    mermaid_lines.append("    classDef endNode fill:#f44336,stroke:#333,stroke-width:2px,color:#fff")
-    mermaid_lines.append("    classDef defaultNode fill:#2196F3,stroke:#333,stroke-width:2px,color:#fff")
-    mermaid_lines.append("")
-    
-    # Helper to get clean node ID
-    def get_node_id(action_name: str) -> str:
-        return action_name.replace(" ", "_").replace("-", "_")
-    
-    # Helper to add a node if not already added
-    def add_node(action_name: str, is_start: bool = False, is_end: bool = False) -> None:
-        if action_name not in added_nodes:
-            node_id = get_node_id(action_name)
-            # Use the action name as the display label
-            display_name = action_name
-            
-            if is_start:
-                mermaid_lines.append(f"    {node_id}[{display_name}]:::startNode")
-            elif is_end:
-                mermaid_lines.append(f"    {node_id}[{display_name}]:::endNode")
-            else:
-                mermaid_lines.append(f"    {node_id}[{display_name}]:::defaultNode")
-            added_nodes.add(action_name)
-    
-    # Add all nodes and connections
-    mermaid_lines.append("    %% Nodes and connections")
-    
-    # Start with the start node
-    add_node(graph._start_action_name, is_start=True)
-    
-    # Process all actions to find connections
-    for action_name in graph._action_nodes:
-        action_func = getattr(graph, action_name, None)
-        if action_func and hasattr(action_func, '_action_settings'):
-            settings = action_func._action_settings
-            
-            # Add the node
-            add_node(action_name, is_end=settings.terminates)
-            
-            # Add connections based on 'next' settings
-            if settings.next:
-                source_id = get_node_id(action_name)
-                
-                if isinstance(settings.next, str):
-                    # Simple string case
-                    target_id = get_node_id(settings.next)
-                    add_node(settings.next)
-                    mermaid_lines.append(f"    {source_id} --> {target_id}")
-                    
-                elif isinstance(settings.next, list):
-                    # List case - branches to multiple nodes
-                    for next_action in settings.next:
-                        if isinstance(next_action, str):
-                            target_id = get_node_id(next_action)
-                            add_node(next_action)
-                            mermaid_lines.append(f"    {source_id} --> {target_id}")
-                            
-                elif hasattr(settings.next, '__class__') and settings.next.__class__.__name__ == 'SelectionStrategy':
-                    # SelectionStrategy case
-                    if settings.next.actions:
-                        # Show all possible paths with a decision diamond
-                        decision_id = f"{source_id}_decision"
-                        mermaid_lines.append(f"    {source_id} --> {decision_id}{{LLM Selection}}")
-                        
-                        for next_action in settings.next.actions:
-                            target_id = get_node_id(next_action)
-                            add_node(next_action)
-                            mermaid_lines.append(f"    {decision_id} --> {target_id}")
-                    else:
-                        # If no specific actions, it can go to any node
-                        # For visualization, show connections to all non-start nodes
-                        decision_id = f"{source_id}_decision"
-                        mermaid_lines.append(f"    {source_id} --> {decision_id}{{LLM Selection}}")
-                        
-                        for other_action in graph._action_nodes:
-                            if other_action != action_name and other_action != graph._start_action_name:
-                                target_id = get_node_id(other_action)
-                                add_node(other_action)
-                                mermaid_lines.append(f"    {decision_id} -.-> {target_id}")
-    
-    # If start node has no explicit next, but there are other nodes, show possible connections
-    start_func = getattr(graph, graph._start_action_name, None)
-    if start_func and hasattr(start_func, '_action_settings'):
-        if not start_func._action_settings.next and len(graph._action_nodes) > 1:
-            source_id = get_node_id(graph._start_action_name)
-            # Find end nodes (terminates=True) to connect to
-            for action_name in graph._action_nodes:
-                if action_name != graph._start_action_name:
-                    action_func = getattr(graph, action_name, None)
-                    if action_func and hasattr(action_func, '_action_settings'):
-                        if action_func._action_settings.terminates:
-                            target_id = get_node_id(action_name)
-                            add_node(action_name, is_end=True)
-                            mermaid_lines.append(f"    {source_id} --> {target_id}")
-    
-    # Join all lines
-    mermaid_code = "\n".join(mermaid_lines)
-    
-    # Render the mermaid diagram and save it
-    try:
-        import subprocess
-        import tempfile
-        import os
-        import shutil
-        
-        # Check if mmdc (mermaid CLI) is available
-        if shutil.which('mmdc') is None:
-            raise FileNotFoundError("mermaid-cli (mmdc) not found. Install with: npm install -g @mermaid-js/mermaid-cli")
-        
-        # Create a temporary mermaid file
-        with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as temp_file:
-            temp_file.write(mermaid_code)
-            temp_mmd_path = temp_file.name
-        
-        try:
-            # Determine output format from filename extension
-            output_format = 'png'  # default
-            if filename.lower().endswith('.svg'):
-                output_format = 'svg'
-            elif filename.lower().endswith('.pdf'):
-                output_format = 'pdf'
-            
-            # Use mermaid CLI to render the diagram
-            cmd = ['mmdc', '-i', temp_mmd_path, '-o', filename]
-            
-            # Add format flag only if not PNG (PNG is default)
-            if output_format != 'png':
-                cmd.extend(['-f', output_format])
-            
-            # Add theme and background color
-            cmd.extend(['-t', 'default', '-b', 'transparent'])
-            
-            result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-            
-            if result.returncode == 0:
-                print(f"Graph visualization saved to: {filename}")
-            else:
-                raise subprocess.CalledProcessError(result.returncode, result.args, result.stderr)
-                
-        finally:
-            # Clean up temporary file
-            if os.path.exists(temp_mmd_path):
-                os.unlink(temp_mmd_path)
-                
-    except FileNotFoundError as e:
-        # Provide helpful error message for missing mermaid CLI
-        print(f"Warning: {e}")
-        # Save as .mmd file instead
-        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
-        with open(mmd_filename, "w") as f:
-            f.write(mermaid_code)
-        print(f"Mermaid code saved to: {mmd_filename}")
-        print("To render as PNG, install mermaid-cli: npm install -g @mermaid-js/mermaid-cli")
-        
-    except subprocess.CalledProcessError as e:
-        # Handle mermaid CLI errors
-        print(f"Error rendering mermaid diagram: {e.stderr if e.stderr else str(e)}")
-        # Save as .mmd file as fallback
-        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
-        with open(mmd_filename, "w") as f:
-            f.write(mermaid_code)
-        print(f"Mermaid code saved to: {mmd_filename} (rendering failed)")
-        
-    except Exception as e:
-        # General fallback: save the mermaid code
-        print(f"Unexpected error: {e}")
-        mmd_filename = filename.rsplit('.', 1)[0] + '.mmd'
-        with open(mmd_filename, "w") as f:
-            f.write(mermaid_code)
-        print(f"Mermaid code saved to: {mmd_filename}")