soe-ai 0.2.0b1__py3-none-any.whl

soe/nodes/agent/lib/loop_handlers.py

@@ -0,0 +1,150 @@
+"""
+Agent loop action handlers
+
+Focused functions for handling each router action type.
+Extracted from factory.py to keep the main loop clean.
+"""
+
+from typing import Dict, Any, Callable, TYPE_CHECKING
+from ..stages import (
+    execute_response_stage,
+    execute_parameter_stage,
+    FinalResponse,
+)
+from ...lib.tools import create_tool_schema
+from ...lib.output import get_signal_options, get_output_model
+
+if TYPE_CHECKING:
+    from ..types import CallLlm
+    from .loop_state import AgentLoopState
+    from ..state import AgentContext, AgentOperationalState
+    from ....types import Backends
+
+
+def handle_finish_action(
+    call_llm: "CallLlm",
+    agent_context: "AgentContext",
+    loop_state: "AgentLoopState",
+    node_config: Dict[str, Any],
+    backends: "Backends",
+    operational_state: "AgentOperationalState",
+) -> FinalResponse:
+    """Handle the 'finish' action from the router."""
+    signal_options = get_signal_options(operational_state.event_emissions)
+    output_model = get_output_model(
+        backends, operational_state.main_execution_id, operational_state.output_field
+    )
+
+    return execute_response_stage(
+        call_llm=call_llm,
+        agent_context=agent_context,
+        loop_state=loop_state,
+        config=node_config,
+        output_field=operational_state.output_field,
+        output_schema=output_model,
+        signal_options=signal_options,
+        max_retries=operational_state.max_retries,
+    )
+
+
+def handle_tool_call_action(
+    call_llm: "CallLlm",
+    tool_name: str,
+    tools_registry: Dict[str, Dict[str, Any]],
+    agent_context: "AgentContext",
+    loop_state: "AgentLoopState",
+    node_config: Dict[str, Any],
+    operational_state: "AgentOperationalState",
+    backends: "Backends",
+    execution_id: str,
+) -> bool:
+    """Handle the 'call_tool' action from the router."""
+    from ....lib.register_event import register_event
+    from ....types import EventTypes
+
+    if not tool_name or tool_name not in tools_registry:
+        register_event(
+            backends=backends,
+            execution_id=execution_id,
+            event_type=EventTypes.AGENT_TOOL_NOT_FOUND,
+            data={
+                "node_name": node_config.get("name", "unknown"),
+                "tool_name": tool_name,
+                "available_tools": list(tools_registry.keys()),
+            }
+        )
+        loop_state.add_system_error(f"Tool '{tool_name}' not found or not available.")
+        return False
+
+    tool_config = tools_registry[tool_name]
+    tool_func = tool_config["function"]
+    tool_exec_retries = tool_config.get("max_retries", 0)
+    tool_schema = create_tool_schema(tool_func)
+
+    try:
+        tool_args = execute_parameter_stage(
+            call_llm=call_llm,
+            agent_context=agent_context,
+            loop_state=loop_state,
+            tool_name=tool_name,
+            tool_schema=tool_schema,
+            config=node_config,
+            max_retries=operational_state.max_retries,
+        )
+
+        tool_args_dict = tool_args.model_dump() if hasattr(tool_args, 'model_dump') else dict(tool_args)
+
+        register_event(
+            backends=backends,
+            execution_id=execution_id,
+            event_type=EventTypes.AGENT_TOOL_CALL,
+            data={
+                "node_name": node_config.get("name", "unknown"),
+                "tool_name": tool_name,
+                "tool_args": tool_args_dict,
+            }
+        )
+
+        result = _execute_tool_with_retries(tool_func, tool_args, tool_exec_retries)
+
+        result_str = str(result)
+        result_preview = result_str[:1000] + "..." if len(result_str) > 1000 else result_str
+
+        register_event(
+            backends=backends,
+            execution_id=execution_id,
+            event_type=EventTypes.AGENT_TOOL_RESULT,
+            data={
+                "node_name": node_config.get("name", "unknown"),
+                "tool_name": tool_name,
+                "result_preview": result_preview,
+                "result_length": len(result_str),
+            }
+        )
+
+        loop_state.add_tool_response(tool_name, result)
+
+    except Exception as e:
+        loop_state.add_tool_error(tool_name, str(e))
+
+    return True
+
+
+def _execute_tool_with_retries(
+    tool_func: Callable,
+    tool_args: Any,
+    max_retries: int,
+) -> Any:
+    """Execute a tool with retry logic."""
+    last_error = None
+
+    for attempt in range(max_retries + 1):
+        try:
+            return tool_func(**tool_args.model_dump())
+        except Exception as e:
+            last_error = e
+            if attempt < max_retries:
+                continue
+
+    if last_error:
+        raise last_error

soe/nodes/agent/lib/loop_state.py

@@ -0,0 +1,157 @@
+"""
+Agent loop state management
+
+This module defines the internal state that persists across the agent's
+execution loop. When an `identity` is configured, the conversation history
+is persisted to the backend, allowing it to be shared across different
+node executions.
+"""
+
+from typing import Dict, Any, List, Optional, TYPE_CHECKING
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
+
+if TYPE_CHECKING:
+    from ....types import Backends
+
+
+class AgentLoopState(BaseModel):
+    """
+    Internal state for the agent execution loop.
+
+    When `identity` is None, this state is local to a single agent node
+    execution. When `identity` is set, conversation history is loaded from
+    and saved to the conversation_history backend, enabling persistence
+    across different node executions.
+    """
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    tool_responses: Dict[str, Any] = Field(default_factory=dict)
+    conversation_history: List[Dict[str, str]] = Field(default_factory=list)
+    errors: List[str] = Field(default_factory=list)
+    retry_count: int = 0
+    max_retries: int = 10
+    history_key: Optional[str] = None
+    _backends: Optional["Backends"] = PrivateAttr(default=None)
+
+    @classmethod
+    def create(
+        cls,
+        history_key: Optional[str] = None,
+        backends: Optional["Backends"] = None,
+        max_retries: int = 10,
+    ) -> "AgentLoopState":
+        """
+        Factory method to create AgentLoopState, optionally loading
+        existing conversation history from backend.
+
+        Args:
+            history_key: Optional key for persistent conversation history (main_execution_id)
+            backends: Backends container (required if history_key is set)
+            max_retries: Maximum retry count
+
+        Returns:
+            AgentLoopState instance, with history loaded if history_key exists
+        """
+        state = cls(max_retries=max_retries, history_key=history_key)
+        state._backends = backends
+
+        if history_key and backends and backends.conversation_history:
+            state.conversation_history = backends.conversation_history.get_conversation_history(history_key)
+
+        return state
+
+    def add_tool_response(self, tool_name: str, result: Any) -> None:
+        """Record a successful tool response."""
+        self.tool_responses[tool_name] = result
+        entry = {
+            "role": "tool",
+            "tool_name": tool_name,
+            "content": str(result),
+        }
+        self.conversation_history.append(entry)
+        self._persist_entry(entry)
+
+    def add_tool_error(self, tool_name: str, error: str) -> None:
+        """Record a tool execution error."""
+        error_msg = f"Error executing {tool_name}: {error}"
+        self.tool_responses[tool_name] = error_msg
+        self.errors.append(error_msg)
+        entry = {
+            "role": "tool_error",
+            "tool_name": tool_name,
+            "content": error_msg,
+        }
+        self.conversation_history.append(entry)
+        self._persist_entry(entry)
+        self.retry_count += 1
+
+    def add_system_error(self, error: str) -> None:
+        """Record a system-level error (e.g., invalid tool name)."""
+        self.errors.append(error)
+        entry = {
+            "role": "system_error",
+            "content": error,
+        }
+        self.conversation_history.append(entry)
+        self._persist_entry(entry)
+        self.retry_count += 1
+
+    def _persist_entry(self, entry: Dict[str, str]) -> None:
+        """Persist a single entry to the backend if history_key is set."""
+        if self.history_key and self._backends and self._backends.conversation_history:
+            self._backends.conversation_history.append_to_conversation_history(
+                self.history_key, entry
+            )
+
+    def can_retry(self) -> bool:
+        """Check if we can still retry."""
+        return self.retry_count < self.max_retries
+
+    def get_execution_state(self) -> str:
+        """
+        Determine current execution state for prompt selection.
+
+        Returns one of:
+        - 'initial': No tool calls yet
+        - 'tool_response': Has successful tool responses
+        - 'tool_error': Has tool errors
+        - 'retry': Has system errors (e.g., invalid tool name)
+        """
+        if not self.conversation_history:
+            return "initial"
+
+        last_entry = self.conversation_history[-1]
+        role = last_entry.get("role", "")
+
+        if role == "tool_error":
+            return "tool_error"
+        elif role == "system_error":
+            return "retry"
+        elif role == "tool":
+            return "tool_response"
+
+        return "initial"
+
+    def get_context_for_llm(self) -> str:
+        """
+        Format the conversation history for inclusion in LLM prompts.
+        """
+        if not self.conversation_history:
+            return ""
+
+        parts = []
+        for entry in self.conversation_history:
+            role = entry.get("role", "unknown")
+            content = entry.get("content", "")
+            tool_name = entry.get("tool_name", "")
+
+            if role == "tool":
+                parts.append(f"[Tool: {tool_name}]\n{content}")
+            elif role == "tool_error":
+                parts.append(f"[Tool Error: {tool_name}]\n{content}")
+            elif role == "system_error":
+                parts.append(f"[System Error]\n{content}")
+            else:
+                parts.append(content)
+
+        return "\n\n".join(parts)

soe/nodes/agent/lib/prompts.py

@@ -0,0 +1,65 @@
+"""
+Agent node prompt building utilities
+
+Provides state-specific instructions for the agent's router stage.
+"""
+
+
+def get_state_instructions(execution_state: str) -> str:
+    """
+    Get state-specific instructions for the router stage.
+
+    The router decides between 'call_tool' and 'finish' actions.
+    Instructions vary based on what happened in previous iterations.
+    """
+
+    base_decision = "Decide the next action: 'call_tool' to use a tool, or 'finish' if task is complete."
+
+    if execution_state == "initial":
+        return f"""{base_decision}
+
+INITIAL EXECUTION:
+1. Analyze the task and available context
+2. Determine if you need additional information from tools
+3. If tools are needed, choose 'call_tool' and specify which tool
+4. If you have enough information to complete the task, choose 'finish'
+
+IMPORTANT: Only call tools that are NECESSARY. Be selective."""
+
+    elif execution_state == "tool_response":
+        return f"""{base_decision}
+
+TOOL RESPONSE RECEIVED:
+Your previous tool call was successful. Review the results in conversation history.
+
+NEXT STEPS:
+1. Analyze if the tool response provides what you need
+2. If more information is needed, call another tool
+3. If task can now be completed, choose 'finish'
+
+Do NOT re-call tools that already succeeded."""
+
+    elif execution_state == "tool_error":
+        return f"""{base_decision}
+
+TOOL ERROR OCCURRED:
+Your previous tool call failed. Review the error in conversation history.
+
+RECOVERY:
+1. Understand what went wrong
+2. Fix parameters and retry the failed tool, OR
+3. Try a different approach with another tool
+4. If task can be completed despite the error, choose 'finish'"""
+
+    elif execution_state == "retry":
+        return f"""{base_decision}
+
+RETRY NEEDED:
+A system error occurred (e.g., invalid tool name). Review the error.
+
+RECOVERY:
+1. Check that tool names match available tools exactly
+2. Use a valid tool name and try again
+3. If no tools are needed, choose 'finish'"""
+
+    return base_decision

soe/nodes/agent/lib/tools.py

@@ -0,0 +1,35 @@
+"""
+Agent node tool loading utilities.
+"""
+
+from typing import Dict, Any, List
+
+from ...lib.tools import get_tool_signature, get_tool_from_registry
+
+
+def load_tools_and_build_signatures(
+    tool_names: List[str],
+    tools_registry: Dict[str, Dict[str, Any]],
+    execution_id: str,
+    backends,
+) -> str:
+    """Load tools and build signature string for agent prompt.
+
+    Args:
+        tool_names: List of tool names to load
+        tools_registry: Dict mapping tool name -> {function: callable, max_retries: int}
+        execution_id: Current workflow execution ID
+        backends: Backend services
+
+    Returns:
+        Formatted string with all tool signatures for the prompt
+    """
+    tools_info = []
+
+    for tool_name in tool_names:
+        tool_func, _, _, _ = get_tool_from_registry(
+            tool_name, tools_registry, execution_id, backends
+        )
+        tools_info.append(get_tool_signature(tool_func))
+
+    return "\n\n".join(tools_info) if tools_info else ""

soe/nodes/agent/stages/__init__.py

@@ -0,0 +1,12 @@
+from .router import execute_router_stage
+from .response import execute_response_stage
+from .parameter import execute_parameter_stage
+from ..types import RouterResponse, FinalResponse
+
+__all__ = [
+    "execute_router_stage",
+    "RouterResponse",
+    "execute_response_stage",
+    "FinalResponse",
+    "execute_parameter_stage",
+]

soe/nodes/agent/stages/parameter.py

@@ -0,0 +1,37 @@
+from typing import Type, TypeVar, TYPE_CHECKING
+from pydantic import BaseModel
+from ...lib.llm_resolver import resolve_llm_call
+from ..types import ParameterInput
+from ....types import CallLlm
+
+if TYPE_CHECKING:
+    from ..state import AgentContext
+    from ..lib.loop_state import AgentLoopState
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def execute_parameter_stage(
+    call_llm: CallLlm,
+    agent_context: "AgentContext",
+    loop_state: "AgentLoopState",
+    tool_name: str,
+    tool_schema: Type[T],
+    config: dict,
+    max_retries: int = 3,
+) -> T:
+    """Execute the Parameter Generation stage to generate arguments for a tool."""
+    input_data = ParameterInput(
+        task_description=agent_context.agent_prompt,
+        context=agent_context.context_string,
+        tool_name=tool_name,
+        conversation_history=loop_state.get_context_for_llm(),
+    )
+
+    return resolve_llm_call(
+        call_llm=call_llm,
+        input_data=input_data,
+        config=config,
+        response_model=tool_schema,
+        max_retries=max_retries,
+    )

soe/nodes/agent/stages/response.py

@@ -0,0 +1,54 @@
+from typing import List, Optional, Type, Any, TYPE_CHECKING
+from pydantic import BaseModel, Field
+from ...lib.llm_resolver import resolve_llm_call
+from ...lib.response_builder import (
+    build_response_model,
+    extract_output_from_response,
+    extract_signal_from_response,
+)
+from ....types import CallLlm
+from ..types import ResponseStageInput, FinalResponse
+
+if TYPE_CHECKING:
+    from ..state import AgentContext
+    from ..lib.loop_state import AgentLoopState
+
+
+def execute_response_stage(
+    call_llm: CallLlm,
+    agent_context: "AgentContext",
+    loop_state: "AgentLoopState",
+    config: dict,
+    output_field: Optional[str] = None,
+    output_schema: Optional[Type[BaseModel]] = None,
+    signal_options: Optional[List[str]] = None,
+    max_retries: int = 3,
+) -> FinalResponse:
+    """Execute the Response stage to generate the final output."""
+    input_data = ResponseStageInput(
+        task_description=agent_context.agent_prompt,
+        context=agent_context.context_string,
+        conversation_history=loop_state.get_context_for_llm(),
+    )
+
+    response_model = build_response_model(
+        output_field=output_field,
+        output_schema=output_schema,
+        signal_options=signal_options,
+    )
+
+    raw_response = resolve_llm_call(
+        call_llm=call_llm,
+        input_data=input_data,
+        config=config,
+        response_model=response_model,
+        max_retries=max_retries,
+    )
+
+    output_value = extract_output_from_response(raw_response, output_field)
+    selected_signal = extract_signal_from_response(raw_response)
+
+    return FinalResponse(
+        output=output_value,
+        selected_signal=selected_signal,
+    )

soe/nodes/agent/stages/router.py

@@ -0,0 +1,37 @@
+from typing import TYPE_CHECKING
+from ...lib.llm_resolver import resolve_llm_call
+from ..lib.prompts import get_state_instructions
+from ..types import RouterInput, RouterResponse
+from ....types import CallLlm
+
+if TYPE_CHECKING:
+    from ..state import AgentContext
+    from ..lib.loop_state import AgentLoopState
+
+
+def execute_router_stage(
+    call_llm: CallLlm,
+    agent_context: "AgentContext",
+    loop_state: "AgentLoopState",
+    tools_signature: str,
+    config: dict,
+    max_retries: int = 3,
+) -> RouterResponse:
+    """Execute the Router stage to decide the next action."""
+    state_instructions = get_state_instructions(loop_state.get_execution_state())
+
+    input_data = RouterInput(
+        instructions=state_instructions,
+        task_description=agent_context.agent_prompt,
+        context=agent_context.context_string,
+        available_tools=tools_signature,
+        conversation_history=loop_state.get_context_for_llm(),
+    )
+
+    return resolve_llm_call(
+        call_llm=call_llm,
+        input_data=input_data,
+        config=config,
+        response_model=RouterResponse,
+        max_retries=max_retries,
+    )

soe/nodes/agent/state.py

@@ -0,0 +1,111 @@
+"""Agent node state retrieval."""
+
+import json
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, ConfigDict
+from ...types import Backends
+from ..lib.conversation_history import get_conversation_history
+from ...lib.jinja_render import render_prompt, get_context_for_prompt
+
+
+class AgentOperationalState(BaseModel):
+    """All data needed for agent node execution."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    main_execution_id: str
+    prompt: str
+    identity: Optional[str]
+    output_field: Optional[str]
+    event_emissions: List[Dict[str, Any]]
+    max_retries: int
+    tools: List[str]
+    llm_failure_signal: Optional[str]
+    current_workflow_name: str
+    history_key: Optional[str]
+    conversation_history: List[Dict[str, Any]]
+
+
+class AgentContext(BaseModel):
+    """Context data prepared for each agent loop iteration."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    filtered_context: Dict[str, Any]
+    context_string: str
+    workflows_registry: Dict[str, Any]
+    workflow_name: str
+    error_note: str
+    agent_prompt: str
+    tool_names: List[str]
+    event_emissions: List[Dict[str, Any]]
+
+
+def get_operational_state(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends: Backends,
+) -> AgentOperationalState:
+    """Retrieve all state needed for agent node execution."""
+    context = backends.context.get_context(execution_id)
+    operational = context["__operational__"]
+    identity = node_config.get("identity")
+    current_workflow_name = backends.workflow.get_current_workflow_name(execution_id)
+    history_key, conversation_history = get_conversation_history(
+        execution_id, identity, backends
+    )
+
+    return AgentOperationalState(
+        context=context,
+        main_execution_id=operational["main_execution_id"],
+        prompt=node_config["prompt"],
+        identity=identity,
+        output_field=node_config.get("output_field"),
+        event_emissions=node_config.get("event_emissions", []),
+        max_retries=node_config.get("retries", 3),
+        tools=node_config.get("tools", []),
+        llm_failure_signal=node_config.get("llm_failure_signal"),
+        current_workflow_name=current_workflow_name,
+        history_key=history_key,
+        conversation_history=conversation_history,
+    )
+
+
+def prepare_agent_context(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends,
+    tool_responses: Dict[str, Any],
+) -> AgentContext:
+    """Prepare all context data for agent execution."""
+    context = backends.context.get_context(execution_id)
+    workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+    workflow_name = backends.workflow.get_current_workflow_name(execution_id)
+
+    prompt_template = node_config["prompt"]
+    rendered_prompt, _ = render_prompt(prompt_template, context)
+
+    filtered_context, _ = get_context_for_prompt(context, prompt_template)
+
+    has_errors = (
+        any("Error:" in str(v) for v in tool_responses.values())
+        if tool_responses
+        else False
+    )
+    error_note = (
+        "\n⚠️  Previous tool calls had errors. Please fix the parameters and try again."
+        if has_errors
+        else ""
+    )
+
+    return AgentContext(
+        context=context,
+        filtered_context=filtered_context,
+        context_string=json.dumps(filtered_context, indent=2),
+        workflows_registry=workflows_registry,
+        workflow_name=workflow_name,
+        error_note=error_note,
+        agent_prompt=rendered_prompt,
+        tool_names=node_config.get("tools", []),
+        event_emissions=node_config.get("event_emissions", []),
+    )