connectonion 0.5.8__py3-none-any.whl

connectonion/decorators.py

@@ -0,0 +1,208 @@
+"""
+Purpose: Provide @replay decorator for re-executing tools with modified parameters during debugging
+LLM-Note:
+  Dependencies: imports from [functools, builtins, typing] | imported by [agent.py, __init__.py] | tested by [tests/test_decorators.py]
+  Data flow: @replay wraps function → stores func, args, kwargs in ReplayFunction during execution → user calls replay(param=new_value) in debugger → re-executes function with merged kwargs → prints result
+  State/Effects: modifies builtins namespace by injecting global 'replay' object | stores ReplayFunction state in _func, _args, _kwargs, _original_func | clears context after execution | no persistence
+  Integration: exposes @replay decorator, replay global callable, xray_replay() combined decorator, _is_replay_enabled() helper | marked functions have __replay_enabled__ attribute | ReplayDecorator acts as both decorator and callable
+  Performance: lightweight wrapper with functools.wraps | no performance overhead (just attribute marking) | context cleared immediately after execution
+  Errors: replay() with no active context prints helpful error message | re-execution errors are re-raised after printing
+"""
+
+import functools
+import builtins
+from typing import Any, Callable
+
+
+# =============================================================================
+# Replay Function and Decorator
+# =============================================================================
+
+class ReplayFunction:
+    """
+    Container for replay functionality.
+
+    Holds the current function and its arguments to enable re-execution
+    with modified parameters during debugging.
+    """
+
+    def __init__(self):
+        """Initialize with no active function."""
+        self._func = None
+        self._args = None
+        self._kwargs = None
+        self._original_func = None
+
+    def _setup(self, func: Callable, args: tuple, kwargs: dict) -> None:
+        """
+        Set up replay context (internal use).
+
+        Args:
+            func: The function to replay
+            args: Original positional arguments
+            kwargs: Original keyword arguments
+        """
+        self._func = func
+        self._args = args
+        self._kwargs = kwargs
+        self._original_func = func
+
+    def _clear(self) -> None:
+        """Clear replay context after execution (internal use)."""
+        self._func = None
+        self._args = None
+        self._kwargs = None
+        self._original_func = None
+
+    def __call__(self, **new_kwargs) -> Any:
+        """
+        Replay the function with modified parameters.
+
+        Args:
+            **new_kwargs: Keyword arguments to override
+
+        Returns:
+            Result of re-executing the function
+
+        Example:
+            # In debugger at breakpoint:
+            >>> replay(threshold=0.8)  # Re-run with new threshold
+            🔄 Replaying my_function()
+               Modified parameters: {'threshold': 0.8}
+            ✅ Result: 0.95
+        """
+        if self._func is None:
+            print("❌ No function to replay. Make sure you're in a breakpoint "
+                  "inside a @replay decorated function.")
+            return None
+
+        # Merge original kwargs with new ones (new ones override)
+        merged_kwargs = self._kwargs.copy() if self._kwargs else {}
+        merged_kwargs.update(new_kwargs)
+
+        print(f"🔄 Replaying {self._original_func.__name__}()")
+        if new_kwargs:
+            print(f"   Modified parameters: {new_kwargs}")
+
+        try:
+            result = self._func(*self._args, **merged_kwargs)
+            print(f"✅ Result: {result}")
+            return result
+        except Exception as e:
+            print(f"❌ Error during replay: {e}")
+            raise
+
+    def __repr__(self):
+        """Show current replay state."""
+        if self._original_func:
+            return f"<replay function for {self._original_func.__name__}>"
+        return "<replay function (not active)>"
+
+
+class ReplayDecorator:
+    """
+    Hybrid object that acts as both a decorator and replay function.
+
+    Dual-purpose design:
+    1. When decorating a function, enables replay functionality
+    2. When called with kwargs, replays the current function
+    """
+
+    def __init__(self, replay_func: ReplayFunction):
+        """
+        Initialize with a replay function container.
+
+        Args:
+            replay_func: ReplayFunction instance to manage replay state
+        """
+        self._replay_func = replay_func
+        # Make this available globally as 'replay' for easy access
+        builtins.replay = self
+
+    def __call__(self, *args, **kwargs) -> Any:
+        """
+        Act as decorator or replay function based on arguments.
+
+        If called with a single callable argument and no kwargs, acts as decorator.
+        Otherwise, forwards the call to replay the current function.
+
+        Args:
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            Decorated function or replay result
+        """
+        # Check if being used as decorator
+        if len(args) == 1 and len(kwargs) == 0 and callable(args[0]):
+            func = args[0]
+
+            @functools.wraps(func)
+            def wrapper(*inner_args, **inner_kwargs):
+                # Set up replay context with current execution
+                self._replay_func._setup(func, inner_args, inner_kwargs)
+
+                try:
+                    # Execute the original function
+                    return func(*inner_args, **inner_kwargs)
+                finally:
+                    # Clean up replay context
+                    self._replay_func._clear()
+
+            # Mark function as replay-enabled
+            wrapper.__replay_enabled__ = True
+            return wrapper
+
+        # Otherwise, act as the replay function
+        else:
+            return self._replay_func(*args, **kwargs)
+
+    def __repr__(self):
+        """Delegate representation to replay function."""
+        return repr(self._replay_func)
+
+
+# Create the global replay instance
+replay_function = ReplayFunction()
+replay = ReplayDecorator(replay_function)
+
+
+# =============================================================================
+# Combined Decorator
+# =============================================================================
+
+def xray_replay(func: Callable) -> Callable:
+    """
+    Convenience decorator that combines @xray and @replay.
+
+    Equivalent to:
+        @xray
+        @replay
+        def my_tool(...):
+            ...
+
+    Args:
+        func: Function to decorate
+
+    Returns:
+        Function with both xray and replay capabilities
+    """
+    from .xray import xray
+    return xray(replay(func))
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def _is_replay_enabled(func: Callable) -> bool:
+    """
+    Check if a function has the @replay decorator.
+
+    Args:
+        func: Function to check
+
+    Returns:
+        True if function is decorated with @replay
+    """
+    return getattr(func, '__replay_enabled__', False)

connectonion/events.py

@@ -0,0 +1,248 @@
+"""
+Purpose: Event system for hooking into agent lifecycle
+LLM-Note:
+  Dependencies: None (standalone module) | imported by [agent.py, __init__.py] | tested by [tests/test_events.py]
+  Data flow: Wrapper functions tag event handlers with _event_type attribute → Agent organizes handlers by type → Agent invokes handlers at specific lifecycle points passing agent instance
+  State/Effects: Event handlers receive agent instance and can modify agent.current_session (messages, trace, etc.)
+  Integration: exposes after_user_input(), before_llm(), after_llm(), before_each_tool(), before_tools(), after_each_tool(), after_tools(), on_error(), on_complete()
+  Performance: Minimal overhead - just function attribute checking and iteration over handler lists
+  Errors: Event handler exceptions propagate and stop agent execution (fail fast)
+"""
+
+from typing import Callable, List, Union, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+# Event handler type: function that takes Agent and returns None
+EventHandler = Callable[['Agent'], None]
+
+
+def after_user_input(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_user_input event handlers.
+
+    Fires once per turn, after user input is added to session.
+    Use for: adding context, timestamps, initializing turn state.
+
+    Supports both decorator and wrapper syntax:
+        # As decorator
+        @after_user_input
+        def add_timestamp(agent):
+            ...
+
+        # As wrapper (single or multiple)
+        on_events=[after_user_input(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'after_user_input'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def before_llm(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as before_llm event handlers.
+
+    Fires before each LLM call (multiple times per turn).
+    Use for: modifying messages for specific LLM calls.
+
+    Supports both decorator and wrapper syntax:
+        @before_llm
+        def inject_context(agent):
+            ...
+
+        on_events=[before_llm(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'before_llm'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def after_llm(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_llm event handlers.
+
+    Fires after each LLM response (multiple times per turn).
+    Use for: logging LLM calls, analyzing responses.
+
+    Supports both decorator and wrapper syntax:
+        @after_llm
+        def log_llm(agent):
+            trace = agent.current_session['trace'][-1]
+            if trace['type'] == 'llm_call':
+                print(f"LLM took {trace['duration_ms']:.0f}ms")
+
+        on_events=[after_llm(log_llm)]
+    """
+    for fn in funcs:
+        fn._event_type = 'after_llm'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def before_each_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as before_each_tool event handlers.
+
+    Fires before EACH individual tool execution.
+    Use for: validating arguments, approval prompts, logging.
+
+    Access pending tool via agent.current_session['pending_tool']:
+        - name: Tool name (e.g., "bash")
+        - arguments: Tool arguments dict
+        - id: Tool call ID
+
+    Raise an exception to cancel the tool execution.
+
+    Supports both decorator and wrapper syntax:
+        @before_each_tool
+        def approve_dangerous(agent):
+            ...
+
+        # Multiple handlers
+        on_events=[before_each_tool(check_shell, check_email)]
+    """
+    for fn in funcs:
+        fn._event_type = 'before_each_tool'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def before_tools(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as before_tools event handlers.
+
+    Fires ONCE before ALL tools in a batch execute.
+
+    What is a "tools batch"?
+    When the LLM responds, it can request multiple tools at once. For example:
+        LLM Response: tool_calls = [search("python"), read_file("docs.md"), calculate(2+2)]
+
+    This group of tools from ONE LLM response is called a "tools batch".
+    - before_tools fires ONCE before the batch starts
+    - after_tools fires ONCE after ALL tools in the batch complete
+
+    Use for: batch validation, user approval before execution, setup.
+
+    Supports both decorator and wrapper syntax:
+        @before_tools
+        def log_batch_start(agent):
+            ...
+
+        on_events=[before_tools(handler)]
+    """
+    for fn in funcs:
+        fn._event_type = 'before_tools'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def after_each_tool(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_each_tool event handlers.
+
+    Fires after EACH individual tool execution (success, error, or not_found).
+    Use for: logging individual tool performance, debugging.
+
+    ⚠️  WARNING: Do NOT add messages to agent.current_session['messages'] here!
+    When LLM returns multiple tool_calls, this fires after EACH tool, which would
+    interleave messages between tool results. This breaks Anthropic Claude's API
+    which requires all tool_results to immediately follow the tool_use message.
+
+    If you need to add messages after tools complete, use `after_tools` instead.
+
+    Supports both decorator and wrapper syntax:
+        @after_each_tool
+        def log_tool(agent):
+            trace = agent.current_session['trace'][-1]
+            if trace['type'] == 'tool_execution':
+                print(f"Tool: {trace['tool_name']} in {trace['timing']:.0f}ms")
+
+        on_events=[after_each_tool(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'after_each_tool'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def after_tools(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as after_tools event handlers.
+
+    Fires ONCE after ALL tools in a batch complete.
+
+    What is a "tools batch"?
+    When the LLM responds, it can request multiple tools at once. For example:
+        LLM Response: tool_calls = [search("python"), read_file("docs.md"), calculate(2+2)]
+
+    This group of tools from ONE LLM response is called a "tools batch".
+    - before_tools fires ONCE before the batch starts
+    - after_tools fires ONCE after ALL tools in the batch complete
+
+    This is the SAFE place to add messages to agent.current_session['messages']
+    after tool execution, because all tool_results have been added and message
+    ordering is correct for all LLM providers (including Anthropic Claude).
+
+    Message ordering when this event fires:
+        - assistant (with tool_calls)
+        - tool result 1
+        - tool result 2
+        - tool result N
+        - [YOUR MESSAGE HERE - safe to add]
+
+    Use for: reflection/reasoning injection, ReAct pattern, batch cleanup.
+
+    Supports both decorator and wrapper syntax:
+        @after_tools
+        def add_reflection(agent):
+            trace = agent.current_session['trace']
+            recent = [t for t in trace if t['type'] == 'tool_execution'][-3:]
+            agent.current_session['messages'].append({
+                'role': 'assistant',
+                'content': f"Completed {len(recent)} tools"
+            })
+
+        on_events=[after_tools(add_reflection)]
+    """
+    for fn in funcs:
+        fn._event_type = 'after_tools'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def on_error(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as on_error event handlers.
+
+    Fires when tool execution fails.
+    Use for: custom error handling, retries, fallback values.
+
+    Supports both decorator and wrapper syntax:
+        @on_error
+        def handle_error(agent):
+            trace = agent.current_session['trace'][-1]
+            if trace.get('status') == 'error':
+                print(f"Tool failed: {trace['error']}")
+
+        on_events=[on_error(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'on_error'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)
+
+
+def on_complete(*funcs: EventHandler) -> Union[EventHandler, List[EventHandler]]:
+    """
+    Mark function(s) as on_complete event handlers.
+
+    Fires once per input() call, after final response is generated.
+    Use for: metrics, logging, cleanup, final summary.
+
+    Supports both decorator and wrapper syntax:
+        @on_complete
+        def log_done(agent):
+            trace = agent.current_session['trace']
+            tools_used = [t['tool_name'] for t in trace if t['type'] == 'tool_execution']
+            print(f"Task done. Tools: {tools_used}")
+
+        on_events=[on_complete(handler1, handler2)]
+    """
+    for fn in funcs:
+        fn._event_type = 'on_complete'  # type: ignore
+    return funcs[0] if len(funcs) == 1 else list(funcs)

connectonion/execution_analyzer/__init__.py

@@ -0,0 +1,9 @@
+"""Execution analyzer - Post-execution analysis and improvement suggestions.
+
+Analyzes completed agent runs and provides suggestions for improving
+system prompts and agent behavior.
+"""
+
+from .execution_analysis import analyze_execution, ExecutionAnalysis
+
+__all__ = ["analyze_execution", "ExecutionAnalysis"]

connectonion/execution_analyzer/execution_analysis.py

@@ -0,0 +1,93 @@
+"""
+Purpose: Post-execution analysis of agent runs with AI-powered improvement suggestions
+LLM-Note:
+  Dependencies: imports from [pathlib, pydantic, typing, llm_do.py] | imported by [agent.py via execution_analyzer/__init__.py] | tested by [tests/test_execution_analyzer.py]
+  Data flow: receives from Agent.input() after completion → analyze_execution(user_prompt, agent_instance, final_result, execution_trace, max_iterations_reached) → builds execution summary with tool calls → loads prompt from execution_analysis_prompt.md → calls llm_do() with ExecutionAnalysis Pydantic schema → returns structured analysis with task_completed, problems_identified, system_prompt_suggestions, overall_quality, key_insights
+  State/Effects: reads execution_analysis_prompt.md file | makes single LLM API call via llm_do() | no writes or global state | stateless
+  Integration: exposes analyze_execution(), ExecutionAnalysis Pydantic model | used by Agent after .input() completes to provide feedback | uses same model as agent instance for analysis | ExecutionAnalysis schema validated by Pydantic
+  Performance: single LLM call per execution (only when enabled) | execution_trace serialization can be large for long runs | no caching
+  Errors: llm_do() errors bubble up (API failures, timeout) | Pydantic ValidationError if LLM output doesn't match schema | handles empty tools list gracefully
+
+Post-execution analysis for completed agent runs.
+
+Analyzes the entire execution trace and provides suggestions for improvement.
+"""
+
+from pathlib import Path
+from pydantic import BaseModel
+from typing import List
+from ..llm_do import llm_do
+
+
+class ExecutionAnalysis(BaseModel):
+    """Structured output for post-execution analysis."""
+    task_completed: bool
+    completion_explanation: str
+    problems_identified: List[str]
+    system_prompt_suggestions: List[str]
+    overall_quality: str  # "excellent" | "good" | "fair" | "poor"
+    key_insights: List[str]
+
+
+def analyze_execution(
+    user_prompt: str,
+    agent_instance,
+    final_result: str,
+    execution_trace: List,
+    max_iterations_reached: bool
+) -> ExecutionAnalysis:
+    """Analyze completed execution and suggest improvements.
+
+    Args:
+        user_prompt: The original user request
+        agent_instance: The Agent that executed
+        final_result: Final response from agent
+        execution_trace: Complete trace of execution
+        max_iterations_reached: Whether agent hit iteration limit
+
+    Returns:
+        Structured analysis with improvement suggestions
+    """
+    # Build execution summary
+    tools_called = [
+        entry for entry in execution_trace
+        if entry.get('type') == 'tool_execution'
+    ]
+
+    tools_summary = []
+    for entry in tools_called:
+        status = "✓" if entry.get('status') == 'success' else "✗"
+        tools_summary.append(
+            f"{status} {entry.get('tool_name')}({entry.get('args')}) → {entry.get('result')}"
+        )
+
+    # Create analysis input
+    data = f"""**User Request:**
+{user_prompt}
+
+**Agent System Prompt:**
+{agent_instance.system_prompt}
+
+**Available Tools:**
+{', '.join([t.name for t in agent_instance.tools]) if agent_instance.tools else 'None'}
+
+**Execution Summary:**
+- Max iterations reached: {max_iterations_reached}
+- Tools called ({len(tools_called)}):
+{chr(10).join(f"  {i+1}. {s}" for i, s in enumerate(tools_summary))}
+
+**Final Result:**
+{final_result}
+
+**Complete Trace:**
+{execution_trace}"""
+
+    prompt_file = Path(__file__).parent / "execution_analysis_prompt.md"
+
+    # Use same model as agent
+    return llm_do(
+        data,
+        output=ExecutionAnalysis,
+        system_prompt=prompt_file,
+        model=agent_instance.llm.model
+    )

connectonion/execution_analyzer/execution_analysis_prompt.md

@@ -0,0 +1,47 @@
+# Post-Execution Analysis Expert
+
+You are an expert at analyzing AI agent execution and suggesting improvements.
+
+## Your Task
+
+Analyze a completed agent execution and provide actionable insights.
+
+You will be given:
+- User's original request
+- Agent's system prompt
+- Complete execution trace (all tools called, results, errors)
+- Final result or max iteration limit
+- Available tools
+
+## Analysis Framework
+
+Provide structured analysis:
+
+1. **task_completed**: Did the agent successfully complete the user's task? (true/false)
+
+2. **completion_explanation**: Why was it completed or not? Be specific about what happened.
+
+3. **problems_identified**: What went wrong or could improve? List specific issues:
+   - Wrong tool choices
+   - Inefficient sequences
+   - Errors encountered
+   - Missing capabilities
+   - Unclear goals or confusion
+
+4. **system_prompt_suggestions**: Concrete changes to improve the system prompt:
+   - Quote problematic parts and suggest replacements
+   - Suggest new directives to add
+   - Identify contradictions or ambiguities
+   - Be specific with actual suggested text
+
+5. **overall_quality**: Rate execution: "excellent" | "good" | "fair" | "poor"
+
+6. **key_insights**: 2-3 most important lessons for improving this agent
+
+## Guidelines
+
+- Be specific and actionable (not generic)
+- Quote actual moments from execution
+- Suggest concrete system prompt modifications
+- Focus on root causes
+- Prioritize high-impact improvements