connectonion 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

connectonion/core/tool_factory.py

@@ -1,28 +1,63 @@
 """
 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
+  Dependencies: imports from [inspect, functools, typing] | imported by [agent.py, __init__.py] | tested by [tests/unit/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 get_json_schema_type() → 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 _)
+  Integration: exposes get_json_schema_type(param_type), 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
+  Type Support: handles Optional[X], List[X], Dict[K,V] via get_json_schema_type() | extracts inner types from Union/Optional | generates proper JSON Schema with "items" for arrays
 """
 
 import inspect
 import functools
-from typing import Callable, Dict, Any, get_type_hints, List
+from typing import Callable, Dict, Any, get_type_hints, List, get_origin, get_args, Union
 
 # Map Python types to JSON Schema types
 TYPE_MAP = {
     str: "string",
-    int: "integer", 
+    int: "integer",
     float: "number",
     bool: "boolean",
     list: "array",
     dict: "object",
 }
 
+
+def get_json_schema_type(param_type) -> dict:
+    """Convert a Python type hint to JSON Schema type, handling generics."""
+    origin = get_origin(param_type)
+
+    # Handle Optional[X] which is Union[X, None]
+    if origin is Union:
+        args = get_args(param_type)
+        # Filter out NoneType to get the actual type
+        non_none_args = [a for a in args if a is not type(None)]
+        if non_none_args:
+            return get_json_schema_type(non_none_args[0])
+        return {"type": "string"}
+
+    # Handle List[X]
+    if origin is list:
+        args = get_args(param_type)
+        schema = {"type": "array"}
+        if args:
+            item_schema = get_json_schema_type(args[0])
+            schema["items"] = item_schema
+        return schema
+
+    # Handle Dict[K, V]
+    if origin is dict:
+        return {"type": "object"}
+
+    # Handle basic types
+    if param_type in TYPE_MAP:
+        return {"type": TYPE_MAP[param_type]}
+
+    # Default to string
+    return {"type": "string"}
+
 def create_tool_from_function(func: Callable) -> Callable:
     """
     Converts a Python function into a tool that is compatible with the Agent,
@@ -42,16 +77,18 @@ def create_tool_from_function(func: Callable) -> Callable:
 
     for param in sig.parameters.values():
         param_name = param.name
-        
+
         # Skip 'self' parameter for bound methods
         if param_name == 'self':
             continue
-            
+
+        # Skip 'agent' parameter - injected by tool_executor
+        if param_name == 'agent':
+            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}
+        properties[param_name] = get_json_schema_type(param_type)
 
         if param.default is inspect.Parameter.empty:
             required.append(param_name)

connectonion/debug/__init__.py

@@ -1,4 +1,13 @@
-"""Debug tools for agent development and troubleshooting.
+"""
+Purpose: Debug tools package re-exporting xray, decorators, auto_debug, runtime_inspector, debug_explainer
+LLM-Note:
+  Dependencies: imports from [xray.py, decorators.py, auto_debug.py (lazy), auto_debug_exception.py, runtime_inspector/ (lazy), debug_explainer/ (lazy)] | imported by [__init__.py main package, user code] | tested via submodule tests
+  Data flow: pure re-export module with lazy loading for circular dependency avoidance
+  State/Effects: no state
+  Integration: exposes xray (decorator), replay/xray_replay (decorators), AutoDebugger/AutoDebugUI (lazy), auto_debug_exception, RuntimeInspector (lazy), explain_tool_choice (lazy) | lazy imports via __getattr__ to avoid circular deps with agent.py
+  Performance: lazy loading delays imports until accessed
+  Errors: none
+Debug tools for agent development and troubleshooting.
 
 This module contains:
 - xray: Runtime context injection for tool inspection

connectonion/debug/debug_explainer/__init__.py

@@ -1,4 +1,13 @@
-"""Debug explainer - AI-powered explanation of tool choices during debugging.
+"""
+Purpose: Debug explainer module for AI-powered tool choice explanations
+LLM-Note:
+  Dependencies: imports from [explain_agent.py, explain_context.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_debug_explainer.py]
+  Data flow: re-exports explain_tool_choice function and RuntimeContext dataclass
+  State/Effects: no state
+  Integration: exposes explain_tool_choice(agent, tool_name, tool_args) → str, RuntimeContext dataclass | used for post-hoc analysis of agent decisions
+  Performance: trivial
+  Errors: none
+Debug explainer - AI-powered explanation of tool choices during debugging.
 
 Provides runtime investigation capabilities to explain why an agent
 chose to call a specific tool with specific arguments.

connectonion/debug/execution_analyzer/__init__.py

@@ -1,4 +1,13 @@
-"""Execution analyzer - Post-execution analysis and improvement suggestions.
+"""
+Purpose: Execution analyzer module for post-run analysis and improvement suggestions
+LLM-Note:
+  Dependencies: imports from [execution_analysis.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_execution_analyzer.py]
+  Data flow: re-exports analyze_execution function and ExecutionAnalysis model
+  State/Effects: no state
+  Integration: exposes analyze_execution(session_file) → ExecutionAnalysis with suggestions for prompt improvements | used after agent runs for optimization
+  Performance: trivial
+  Errors: none
+Execution analyzer - Post-execution analysis and improvement suggestions.
 
 Analyzes completed agent runs and provides suggestions for improving
 system prompts and agent behavior.

connectonion/debug/execution_analyzer/execution_analysis.py

@@ -49,16 +49,19 @@ def analyze_execution(
         Structured analysis with improvement suggestions
     """
     # Build execution summary
+    # Filter for tool_result entries (the current trace format)
     tools_called = [
         entry for entry in execution_trace
-        if entry.get('type') == 'tool_execution'
+        if entry.get('type') == 'tool_result'
     ]
 
     tools_summary = []
     for entry in tools_called:
         status = "✓" if entry.get('status') == 'success' else "✗"
+        # Use 'name' field (current format) with fallback to 'tool_name' (legacy)
+        tool_name = entry.get('name') or entry.get('tool_name')
         tools_summary.append(
-            f"{status} {entry.get('tool_name')}({entry.get('args')}) → {entry.get('result')}"
+            f"{status} {tool_name}({entry.get('args')}) → {entry.get('result')}"
         )
 
     # Create analysis input

connectonion/debug/runtime_inspector/__init__.py

@@ -1,4 +1,13 @@
-"""Runtime inspector for AI-powered crash debugging.
+"""
+Purpose: Runtime inspector module for AI-powered crash debugging with experiment validation
+LLM-Note:
+  Dependencies: imports from [agent.py, runtime_inspector.py] | imported by [debug/__init__.py, user code] | tested by [tests/debug/test_runtime_inspector.py]
+  Data flow: re-exports create_debug_agent factory and RuntimeInspector class
+  State/Effects: no state
+  Integration: exposes create_debug_agent() → Agent, RuntimeInspector class for capturing crash context and experimenting with fixes | used for interactive crash debugging
+  Performance: trivial
+  Errors: none
+Runtime inspector for AI-powered crash debugging.
 
 Provides RuntimeInspector class and factory function to create debug agents
 that can experiment, test, and validate fixes using actual crashed program data.

connectonion/docs/.package-ignore

@@ -0,0 +1,6 @@
+# Folders/files to exclude from pip package
+# These are for internal use only, not shipped with connectonion
+
+archive
+design-decisions
+roadmap.md