connectonion 0.5.8__py3-none-any.whl

connectonion/tool_executor.py

@@ -0,0 +1,279 @@
+"""
+Purpose: Execute agent tools with xray context injection, timing, error handling, and trace recording
+LLM-Note:
+  Dependencies: imports from [time, json, typing, xray.py] | imported by [agent.py] | tested by [tests/test_tool_executor.py]
+  Data flow: receives from Agent → tool_calls: List[ToolCall], tools: ToolRegistry, agent: Agent, logger: Logger → for each tool: injects xray context via inject_xray_context() → executes tool_func(**tool_args) → records timing and result → appends to agent.current_session['trace'] → clears xray context → adds tool result to messages
+  State/Effects: mutates agent.current_session['messages'] by appending assistant message with tool_calls and tool result messages | mutates agent.current_session['trace'] by appending tool_execution entries | calls logger.log_tool_call() and logger.log_tool_result() for user feedback | injects/clears xray context via thread-local storage
+  Integration: exposes execute_and_record_tools(tool_calls, tools, agent, logger), execute_single_tool(...) | uses logger.log_tool_call(name, args) for natural function-call style output: greet(name='Alice') | creates trace entries with type, tool_name, arguments, call_id, result, status, timing, iteration, timestamp
+  Performance: times each tool execution in milliseconds | executes tools sequentially (not parallel) | trace entry added BEFORE auto-trace so xray.trace() sees it
+  Errors: catches all tool execution exceptions | wraps errors in trace_entry with error, error_type fields | returns error message to LLM for retry | prints error to logger with red ✗
+"""
+
+import time
+import json
+from typing import List, Dict, Any, Optional, Callable
+
+from .xray import (
+    inject_xray_context,
+    clear_xray_context,
+    is_xray_enabled
+)
+
+
+def execute_and_record_tools(
+    tool_calls: List,
+    tools: Any,  # ToolRegistry
+    agent: Any,
+    logger: Any  # Logger instance
+) -> None:
+    """Execute requested tools and update conversation messages.
+
+    Uses agent.current_session as single source of truth for messages and trace.
+
+    Args:
+        tool_calls: List of tool calls from LLM response
+        tools: ToolRegistry containing tools
+        agent: Agent instance with current_session containing messages and trace
+        logger: Logger for output (always provided by Agent)
+    """
+    # Format and add assistant message with tool calls
+    _add_assistant_message(agent.current_session['messages'], tool_calls)
+
+    # before_tools fires ONCE before ALL tools in the batch execute
+    agent._invoke_events('before_tools')
+
+    # Execute each tool
+    for tool_call in tool_calls:
+        # Execute the tool and get trace entry
+        trace_entry = execute_single_tool(
+            tool_name=tool_call.name,
+            tool_args=tool_call.arguments,
+            tool_id=tool_call.id,
+            tools=tools,
+            agent=agent,
+            logger=logger
+        )
+
+        # Add result to conversation messages
+        _add_tool_result_message(
+            agent.current_session['messages'],
+            tool_call.id,
+            trace_entry["result"]
+        )
+
+        # Note: trace_entry already added to session in execute_single_tool
+        # (before auto-trace, so it shows up in xray.trace() output)
+
+        # Fire events AFTER tool result message is added (proper message ordering)
+        # on_error fires first for errors/not_found
+        if trace_entry["status"] in ("error", "not_found"):
+            agent._invoke_events('on_error')
+
+        # after_each_tool fires for EACH tool execution (success, error, not_found)
+        # WARNING: Do NOT add messages here - it breaks Anthropic's message ordering
+        agent._invoke_events('after_each_tool')
+
+    # after_tools fires ONCE after ALL tools in the batch complete
+    # This is the safe place to add messages (e.g., reflection) because all
+    # tool_results have been added and message ordering is correct for all LLMs
+    agent._invoke_events('after_tools')
+
+
+def execute_single_tool(
+    tool_name: str,
+    tool_args: Dict,
+    tool_id: str,
+    tools: Any,  # ToolRegistry
+    agent: Any,
+    logger: Any  # Logger instance
+) -> Dict[str, Any]:
+    """Execute a single tool and return trace entry.
+
+    Uses agent.current_session as single source of truth.
+    Checks for __xray_enabled__ attribute to auto-print Rich tables.
+
+    Args:
+        tool_name: Name of the tool to execute
+        tool_args: Arguments to pass to the tool
+        tool_id: ID of the tool call
+        tools: ToolRegistry containing tools
+        agent: Agent instance with current_session
+        logger: Logger for output (always provided by Agent)
+
+    Returns:
+        Dict trace entry with: type, tool_name, arguments, call_id, result, status, timing, iteration, timestamp
+    """
+    # Log tool call before execution
+    logger.log_tool_call(tool_name, tool_args)
+
+    # Create single trace entry
+    trace_entry = {
+        "type": "tool_execution",
+        "tool_name": tool_name,
+        "arguments": tool_args,
+        "call_id": tool_id,
+        "timing": 0,
+        "status": "pending",
+        "result": None,
+        "iteration": agent.current_session['iteration'],
+        "timestamp": time.time()
+    }
+
+    # Check if tool exists
+    tool_func = tools.get(tool_name)
+    if tool_func is None:
+        error_msg = f"Tool '{tool_name}' not found"
+
+        # Update trace entry
+        trace_entry["result"] = error_msg
+        trace_entry["status"] = "not_found"
+        trace_entry["error"] = error_msg
+
+        # Add trace entry to session (so on_error handlers can see it)
+        agent.current_session['trace'].append(trace_entry)
+
+        # Logger output
+        logger.print(f"[red]✗[/red] {error_msg}")
+
+        # Note: on_error event will fire in execute_and_record_tools after result message added
+
+        return trace_entry
+
+    # Check if tool has @xray decorator
+    xray_enabled = is_xray_enabled(tool_func)
+
+    # Prepare context data for xray
+    previous_tools = [
+        entry.get("tool_name") for entry in agent.current_session['trace']
+        if entry.get("type") == "tool_execution"
+    ]
+
+    # Inject xray context before tool execution
+    inject_xray_context(
+        agent=agent,
+        user_prompt=agent.current_session.get('user_prompt', ''),
+        messages=agent.current_session['messages'].copy(),
+        iteration=agent.current_session['iteration'],
+        previous_tools=previous_tools
+    )
+
+    # Initialize timing (for error case if before_tool fails)
+    tool_start = time.time()
+
+    try:
+        # Set pending_tool for before_tool handlers to access
+        agent.current_session['pending_tool'] = {
+            'name': tool_name,
+            'arguments': tool_args,
+            'id': tool_id
+        }
+
+        # Invoke before_each_tool events
+        agent._invoke_events('before_each_tool')
+
+        # Clear pending_tool after event (it's only valid during before_tool)
+        agent.current_session.pop('pending_tool', None)
+
+        # Execute the tool with timing (restart timer AFTER events for accurate tool timing)
+        tool_start = time.time()
+        result = tool_func(**tool_args)
+        tool_duration = (time.time() - tool_start) * 1000  # milliseconds
+
+        # Update trace entry
+        trace_entry["timing"] = tool_duration
+        trace_entry["result"] = str(result)
+        trace_entry["status"] = "success"
+
+        # Add trace entry to session BEFORE auto-trace
+        # (so it shows up in xray.trace() output)
+        agent.current_session['trace'].append(trace_entry)
+
+        # Logger output - result on separate line
+        logger.log_tool_result(str(result), tool_duration)
+
+        # Auto-print Rich table if @xray enabled
+        if xray_enabled:
+            logger.print_xray_table(
+                tool_name=tool_name,
+                tool_args=tool_args,
+                result=result,
+                timing=tool_duration,
+                agent=agent
+            )
+
+        # Note: after_tool event will fire in execute_and_record_tools after result message added
+
+    except Exception as e:
+        # Calculate timing from initial start (includes before_tool if it succeeded)
+        tool_duration = (time.time() - tool_start) * 1000
+
+        # Update trace entry
+        trace_entry["timing"] = tool_duration
+        trace_entry["status"] = "error"
+        trace_entry["error"] = str(e)
+        trace_entry["error_type"] = type(e).__name__
+
+        error_msg = f"Error executing tool: {str(e)}"
+        trace_entry["result"] = error_msg
+
+        # Add error trace entry to session (so on_error handlers can see it)
+        agent.current_session['trace'].append(trace_entry)
+
+        # Logger output
+        time_str = f"{tool_duration/1000:.4f}s" if tool_duration < 100 else f"{tool_duration/1000:.1f}s"
+        logger.print(f"[red]✗[/red] Error ({time_str}): {str(e)}")
+
+        # Note: on_error event will fire in execute_and_record_tools after result message added
+
+    finally:
+        # Clear xray context after tool execution
+        clear_xray_context()
+
+    return trace_entry
+
+
+def _add_assistant_message(messages: List[Dict], tool_calls: List) -> None:
+    """Format and add assistant message with tool calls.
+
+    Preserves extra_content (e.g., Gemini 3 thought_signature) which must be
+    echoed back to the LLM for certain providers to work correctly.
+    See: https://ai.google.dev/gemini-api/docs/thinking#openai-sdk
+
+    Args:
+        messages: Conversation messages list (will be mutated)
+        tool_calls: Tool calls from LLM response
+    """
+    assistant_tool_calls = []
+    for tool_call in tool_calls:
+        tc_dict = {
+            "id": tool_call.id,
+            "type": "function",
+            "function": {
+                "name": tool_call.name,
+                "arguments": json.dumps(tool_call.arguments)
+            }
+        }
+        # Only include extra_content if present (Gemini rejects null values)
+        if tool_call.extra_content:
+            tc_dict["extra_content"] = tool_call.extra_content
+        assistant_tool_calls.append(tc_dict)
+
+    messages.append({
+        "role": "assistant",
+        "tool_calls": assistant_tool_calls
+    })
+
+
+def _add_tool_result_message(messages: List[Dict], tool_id: str, result: Any) -> None:
+    """Add tool result message to conversation.
+
+    Args:
+        messages: Conversation messages list (will be mutated)
+        tool_id: ID of the tool call
+        result: Result from tool execution
+    """
+    messages.append({
+        "role": "tool",
+        "content": str(result),
+        "tool_call_id": tool_id
+    })

connectonion/tool_factory.py

@@ -0,0 +1,186 @@
+"""
+Purpose: Convert Python functions and class methods into agent-compatible tool schemas
+LLM-Note:
+  Dependencies: imports from [inspect, functools, typing] | imported by [agent.py, __init__.py] | tested by [tests/test_tool_factory.py]
+  Data flow: receives func: Callable → inspects signature with inspect.signature() → extracts type hints with get_type_hints() → maps Python types to JSON Schema via TYPE_MAP → creates tool with .name, .description, .to_function_schema(), .run() attributes → returns wrapped Callable
+  State/Effects: no side effects | pure function transformations | preserves @xray and @replay decorator flags via hasattr checks | creates wrapper functions for bound methods to maintain self reference
+  Integration: exposes create_tool_from_function(func), extract_methods_from_instance(obj), is_class_instance(obj) | used by Agent.__init__ to auto-convert tools | supports both standalone functions and bound methods | skips private methods (starting with _)
+  Performance: uses inspect module (relatively fast) | TYPE_MAP provides O(1) type lookups | caches nothing (recreates on each call)
+  Errors: skips methods without type annotations | skips methods without return type hint | handles inspection failures gracefully | wraps functions with functools.wraps to preserve metadata
+"""
+
+import inspect
+import functools
+from typing import Callable, Dict, Any, get_type_hints, List
+
+# Map Python types to JSON Schema types
+TYPE_MAP = {
+    str: "string",
+    int: "integer", 
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+def create_tool_from_function(func: Callable) -> Callable:
+    """
+    Converts a Python function into a tool that is compatible with the Agent,
+    by inspecting its signature and docstring.
+    """
+    name = func.__name__
+    description = inspect.getdoc(func) or f"Execute the {name} tool."
+
+    # Build the parameters schema from the function signature
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+    
+    properties = {}
+    required = []
+
+    for param in sig.parameters.values():
+        param_name = param.name
+        
+        # Skip 'self' parameter for bound methods
+        if param_name == 'self':
+            continue
+            
+        # Use 'str' as a fallback if no type hint is available
+        param_type = type_hints.get(param_name, str)
+        schema_type = TYPE_MAP.get(param_type, "string")
+        
+        properties[param_name] = {"type": schema_type}
+
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+
+    parameters_schema = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        parameters_schema["required"] = required
+    
+    # For bound methods, create a wrapper function that preserves the method
+    if inspect.ismethod(func):
+        base_func = getattr(func, "__func__", func)
+
+        @functools.wraps(base_func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve decorator flags from the underlying function (for backward compatibility)
+        # Note: xray context is now injected for ALL tools automatically,
+        # so @xray decorator is optional
+        for attr in ("__xray_enabled__", "__replay_enabled__"):
+            if hasattr(base_func, attr):
+                try:
+                    setattr(wrapper, attr, getattr(base_func, attr))
+                except Exception:
+                    pass
+
+        # Ensure tool naming/docs are consistent for the Agent
+        wrapper.__name__ = name
+        wrapper.__doc__ = description
+        tool_func = wrapper
+    else:
+        tool_func = func
+    
+    # Attach the necessary attributes for Agent compatibility
+    tool_func.name = name
+    tool_func.description = description
+    tool_func.get_parameters_schema = lambda: parameters_schema
+    tool_func.to_function_schema = lambda: {
+        "name": name,
+        "description": description,
+        "parameters": parameters_schema,
+    }
+    tool_func.run = tool_func  # The agent calls .run() - this should be the decorated function
+    
+    return tool_func
+
+
+def extract_methods_from_instance(instance) -> List[Callable]:
+    """
+    Extract public methods from a class instance that can be used as tools.
+    
+    Args:
+        instance: A class instance to extract methods from
+        
+    Returns:
+        List of method functions that have proper type annotations
+    """
+    methods = []
+    
+    for name in dir(instance):
+        # Skip private methods (starting with _)
+        if name.startswith('_'):
+            continue
+            
+        attr = getattr(instance, name)
+        
+        # Check if it's a callable method (not a property or static value)
+        if not callable(attr):
+            continue
+            
+        # Skip built-in methods like __class__, etc.
+        if isinstance(attr, type):
+            continue
+            
+        # Check if it's actually a bound method (has __self__)
+        if not hasattr(attr, '__self__'):
+            continue
+            
+        # Check if method has proper type annotations
+        try:
+            sig = inspect.signature(attr)
+            type_hints = get_type_hints(attr)
+            
+            # Must have return type annotation to be a valid tool
+            if 'return' not in type_hints:
+                continue
+                
+            # Process method as tool, preserving self reference
+            tool = create_tool_from_function(attr)
+            methods.append(tool)
+            
+        except (ValueError, TypeError):
+            # Skip methods that can't be inspected
+            continue
+    
+    return methods
+
+
+def is_class_instance(obj) -> bool:
+    """
+    Check if an object is a class instance (not a function, class, or module).
+    
+    Args:
+        obj: Object to check
+        
+    Returns:
+        True if obj is a class instance with callable methods
+    """
+    # Must be an object with a class
+    if not hasattr(obj, '__class__'):
+        return False
+        
+    # Should not be a function, method, or class itself
+    if inspect.isfunction(obj) or inspect.ismethod(obj) or inspect.isclass(obj):
+        return False
+        
+    # Should not be a module
+    if inspect.ismodule(obj):
+        return False
+        
+    # Should not be built-in types
+    if isinstance(obj, (list, dict, tuple, set, str, int, float, bool, type(None))):
+        return False
+        
+    # Should have some callable attributes (methods)
+    has_methods = any(
+        callable(getattr(obj, name, None)) and not name.startswith('_')
+        for name in dir(obj)
+    )
+    
+    return has_methods

connectonion/tool_registry.py

@@ -0,0 +1,105 @@
+"""
+Purpose: Store and manage agent tools and class instances with O(1) lookup and conflict detection
+LLM-Note:
+  Dependencies: None (standalone module) | imported by [agent.py] | tested by [tests/unit/test_tool_registry.py]
+  Data flow: Agent.__init__() creates ToolRegistry → .add(tool) stores tool with tool.name key → .add_instance(name, instance) stores class instances → .get(name) returns tool or None → __getattr__ enables agent.tools.send() attribute access → __iter__ yields tools for LLM schema generation
+  State/Effects: stores tools in _tools dict and instances in _instances dict | no file I/O or external effects | raises ValueError on duplicate names or conflicts between tool/instance names
+  Integration: exposes ToolRegistry class with add(), add_instance(), get(), get_instance(), remove(), names() | supports iteration (for tool in registry) | supports len() and bool | supports 'in' operator | attribute access checks instances first, then tools
+  Performance: O(1) dict-based lookup for all operations | iteration yields tools only (not instances) | memory proportional to number of tools/instances
+  Errors: raises ValueError for duplicate tool names | raises ValueError if tool name conflicts with instance name | raises AttributeError for unknown tool/instance names via __getattr__
+
+Agent tools and instances with attribute access and conflict detection.
+
+Usage:
+    # Call tools
+    agent.tools.send(to, subject, body)
+    agent.tools.search(query)
+
+    # Access class instances (for properties)
+    agent.tools.gmail.my_id
+    agent.tools.calendar.timezone
+
+    # API
+    agent.tools.add(tool)
+    agent.tools.add_instance('gmail', gmail_obj)
+    agent.tools.get('send')
+    agent.tools.get_instance('gmail')
+
+    # Iteration (tools only)
+    for tool in agent.tools:
+        print(tool.name)
+"""
+
+
+class ToolRegistry:
+    """Agent tools and class instances with attribute access and conflict detection."""
+
+    def __init__(self):
+        self._tools = {}
+        self._instances = {}
+
+    def add(self, tool):
+        """Add a tool. Raises ValueError if name conflicts with existing tool or instance."""
+        name = tool.name
+        if name in self._tools:
+            raise ValueError(f"Duplicate tool: '{name}'")
+        if name in self._instances:
+            raise ValueError(f"Tool name '{name}' conflicts with instance name")
+        self._tools[name] = tool
+
+    def add_instance(self, name: str, instance):
+        """Add a class instance. Raises ValueError if name conflicts."""
+        if name in self._instances:
+            raise ValueError(f"Duplicate instance: '{name}'")
+        if name in self._tools:
+            raise ValueError(f"Instance name '{name}' conflicts with tool name")
+        self._instances[name] = instance
+
+    def get(self, name, default=None):
+        """Get tool by name."""
+        return self._tools.get(name, default)
+
+    def get_instance(self, name, default=None):
+        """
+        this will be called like agent.tools.get_instance('deep_research_agent').tools.get_instance('web')
+        Get instance by name."""
+        return self._instances.get(name, default)
+
+    def remove(self, name) -> bool:
+        """Remove tool by name."""
+        if name in self._tools:
+            del self._tools[name]
+            return True
+        return False
+
+    def names(self):
+        """List all tool names."""
+        return list(self._tools.keys())
+
+    def __getattr__(self, name):
+        """Attribute access: agent.tools.send() or agent.tools.gmail.my_id"""
+        if name.startswith('_'):
+            raise AttributeError(name)
+        # Check instances first (gmail, calendar)
+        if name in self._instances:
+            return self._instances[name]
+        # Then check tools (send, reply)
+        tool = self._tools.get(name)
+        if tool is None:
+            raise AttributeError(f"No tool or instance: '{name}'")
+        return tool
+
+    def __iter__(self):
+        """Iterate over tools only (for LLM schemas)."""
+        return iter(self._tools.values())
+
+    def __len__(self):
+        """Count of tools (not instances)."""
+        return len(self._tools)
+
+    def __bool__(self):
+        return len(self._tools) > 0
+
+    def __contains__(self, name):
+        """Check if tool or instance exists."""
+        return name in self._tools or name in self._instances