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

connectonion/docs/debug/exceptions.md

@@ -0,0 +1,307 @@
+# Auto Debug Exception - AI-Powered Exception Debugger
+
+**Debugs ONLY uncaught exceptions** - crashes, raised exceptions, and failed assertions.
+
+When your Python program **encounters an uncaught exception**, ConnectOnion's `auto_debug_exception()` gives the AI **live access to your program's runtime state**. The AI can execute code, inspect objects, and test fixes using the actual data. No more guessing - get verified solutions that actually work.
+
+> **Important:** This only works for uncaught exceptions. For logic errors that don't crash, use `raise` or `assert` to convert them to exceptions!
+
+## Quick Start
+
+```python
+from connectonion import auto_debug_exception
+
+# Enable AI debugging with runtime inspection
+auto_debug_exception()
+
+# Your code - any crash triggers deep AI analysis
+data = {"users": []}
+average = sum(u["age"] for u in data["users"]) / len(data["users"])  # Crashes!
+```
+
+When this crashes, the AI will:
+1. Show the normal Python traceback first
+2. Execute code in the crashed context to understand what happened
+3. Test potential fixes with your actual data
+4. Provide a working solution you can copy-paste
+
+## What Makes This Special
+
+### 🔬 Live Runtime Access
+The AI isn't just reading your code - it has access to the actual runtime state when the crash occurred. It can:
+- Execute any Python expression using your variables
+- See the real values that caused the problem
+- Test fixes before suggesting them
+
+### ✅ Verified Solutions
+Every fix is tested with your actual data before being suggested. No more "this might work" - only proven solutions.
+
+### 🎯 Precise Analysis
+The AI can explore your data structures, check types, validate assumptions, and trace variables through the call stack.
+
+## Real-World Examples
+
+### Example 1: Empty Collection Crash
+
+```python
+from connectonion import auto_debug_exception
+auto_debug_exception()
+
+def calculate_metrics(scores):
+    return {
+        'average': sum(scores) / len(scores),  # Crashes if empty!
+        'maximum': max(scores),
+        'minimum': min(scores)
+    }
+
+result = calculate_metrics([])  # 💥 Multiple issues!
+```
+
+**AI Runtime Debug Analysis:**
+
+What I found:
+- Executed: len(scores) → 0
+- Executed: sum(scores) → 0
+- The division 0/0 causes ZeroDivisionError
+- Also tested: max([]) raises ValueError
+
+Why it failed:
+Empty list causes division by zero and max()/min() to fail
+
+Verified fix (tested with your data):
+```python
+def calculate_metrics(scores):
+    if not scores:
+        return {
+            'average': 0,
+            'maximum': None,
+            'minimum': None
+        }
+    return {
+        'average': sum(scores) / len(scores),
+        'maximum': max(scores),
+        'minimum': min(scores)
+    }
+
+```
+
+### Example 2: Nested Dictionary Access
+
+```python
+from connectonion import auto_debug_exception
+auto_debug_exception()
+
+# API response with unexpected structure
+response = {
+    'data': {
+        'user': {
+            'profile': {'name': 'Alice'}
+            # Missing 'settings' key!
+        }
+    }
+}
+
+# Your code expects different structure
+theme = response['data']['user']['profile']['settings']['theme']  # 💥
+```
+
+**AI Runtime Debug Analysis:**
+```
+What I found:
+- Executed: list(response['data']['user']['profile'].keys()) → ['name']
+- No 'settings' key exists in profile
+- Tested: response['data']['user']['profile'].get('settings') → None
+
+Why it failed:
+KeyError because 'settings' doesn't exist in the profile dictionary
+
+Verified fix (tested with your data):
+```python
+# Safe navigation with defaults
+profile = response['data']['user']['profile']
+theme = profile.get('settings', {}).get('theme', 'light')
+
+# Or check before accessing
+if 'settings' in profile and 'theme' in profile['settings']:
+    theme = profile['settings']['theme']
+else:
+    theme = 'light'  # default
+```
+```
+
+### Example 3: Type Mismatch
+
+```python
+from connectonion import auto_debug_exception
+auto_debug_exception()
+
+def process_items(items):
+    # Expects list, might get dict or string
+    for item in items:
+        print(f"Processing: {item['id']}")
+
+# API returned dict instead of list
+api_data = {'item1': {...}, 'item2': {...}}
+process_items(api_data)  # 💥
+```
+
+**AI Runtime Debug Analysis:**
+```
+What I found:
+- Executed: type(items) → <class 'dict'>
+- Iterating over dict gives keys, not items
+- Executed: list(items.keys()) → ['item1', 'item2']
+- item (the key) is a string, not dict with 'id'
+
+Why it failed:
+TypeError because you're iterating over dict keys (strings), not dict values
+
+Verified fix (tested with your data):
+```python
+def process_items(items):
+    # Handle both list and dict
+    if isinstance(items, dict):
+        items = items.values()
+
+    for item in items:
+        print(f"Processing: {item['id']}")
+```
+```
+
+## Power Features
+
+### 1. Execute Code in Crashed Context
+The AI can run any Python code using your actual variables:
+```python
+# AI explores your data:
+execute_in_frame("type(data)")  # → <class 'dict'>
+execute_in_frame("list(data.keys())")  # → ['users', 'config']
+execute_in_frame("len(data['users'])")  # → 0
+```
+
+### 2. Deep Object Inspection
+See everything about an object - type, attributes, methods, values:
+```python
+# AI inspects complex objects:
+inspect_object("response")
+# → Type: dict
+# → Keys: ['data', 'meta', 'errors']
+# → Methods: get, items, keys, values...
+```
+
+### 3. Test Fixes Before Suggesting
+The AI tests solutions with your actual data:
+```python
+# AI tests potential fixes:
+test_fix(
+    "data['missing']",  # Original (fails)
+    "data.get('missing', 'default')"  # Fixed (works)
+)
+# → Original: ✗ KeyError
+# → Fixed: ✓ Returns 'default'
+```
+
+### 4. Validate Assumptions
+Test any hypothesis about your data:
+```python
+# AI validates assumptions:
+validate_assumption("isinstance(data, dict)")  # → ✓ TRUE
+validate_assumption("len(users) > 0")  # → ✗ FALSE
+validate_assumption("'id' in user")  # → Shows available keys
+```
+
+### 5. Trace Variables Through Stack
+See how variables changed across function calls:
+```python
+# AI traces variable through call stack:
+trace_variable("user_data")
+# → Frame 1: process() - user_data = {...}
+# → Frame 2: validate() - user_data = {...}
+# → Frame 3: save() - user_data = None (modified!)
+```
+
+## Configuration
+
+### Choose Your Model
+
+```python
+# Use a specific model
+auto_debug(model="gpt-4")  # More thorough analysis
+auto_debug(model="o4-mini")  # Faster, default
+```
+
+### Disable via Environment
+
+In your `.env` file:
+```bash
+# Disable auto_debug completely
+CONNECTONION_AUTO_DEBUG=false
+```
+
+Or temporarily:
+```bash
+CONNECTONION_AUTO_DEBUG=false python your_script.py
+```
+
+## Best Practices
+
+### When to Use
+
+✅ **Perfect for:**
+- Development and debugging
+- Understanding unfamiliar codebases
+- Complex data structure issues
+- Learning from mistakes
+- Debugging production issues locally
+
+❌ **Not recommended for:**
+- Production environments (exposes runtime data)
+- Performance-critical code (adds overhead)
+- Simple syntax errors (overkill)
+
+### Tips for Best Results
+
+1. **Let it crash** - Don't wrap in try/except, let auto_debug catch it
+2. **Use descriptive variable names** - Helps AI understand context
+3. **Keep sensitive data out** - AI sees all variables in crashed scope
+
+## How It Works
+
+1. **Exception Hook**: Intercepts uncaught exceptions via `sys.excepthook`
+2. **Frame Capture**: Captures the exception frame with all variables
+3. **Runtime Inspector**: Creates a `RuntimeInspector` with crashed state
+4. **AI Analysis**: Provides tools for the AI to explore and test
+5. **Solution Verification**: Tests fixes before suggesting them
+
+## Limitations
+
+- **Only uncaught exceptions** - Caught exceptions aren't analyzed
+- **Frame access** - Some built-in objects may not be fully inspectable
+- **API dependency** - Requires OpenAI/Anthropic API access
+- **Performance** - Adds overhead, not for production
+
+## Security Notes
+
+⚠️ **The AI can see all variables in the crashed scope**, including:
+- API keys in variables (use environment variables instead)
+- User data
+- Database credentials
+- Any sensitive information in memory
+
+For production, always set `CONNECTONION_AUTO_DEBUG=false`.
+
+## Coming Soon
+
+Based on user feedback, we're considering:
+- **Automatic fix application** - Apply the verified fix automatically
+- **Historical analysis** - Learn from past crashes
+- **Team sharing** - Share crash analysis with team
+- **Custom prompts** - Tailor analysis to your needs
+- **Offline mode** - Save crash state for later analysis
+
+## See Also
+
+- [Getting Started](quickstart.md) - ConnectOnion basics
+- [RuntimeInspector](runtime_inspector.md) - Technical details of runtime tools
+- [Debug Agent](debug_agent.md) - How the debug agent works
+- [Examples](examples.md#auto-debug) - More auto_debug examples

connectonion/docs/debug/log.md

@@ -0,0 +1,117 @@
+# Logging
+
+ConnectOnion automatically logs agent activity to files for debugging and analysis.
+
+## Quick Start
+
+```python
+# Default: logs to .co/logs/{name}.log + .co/evals/{name}_{timestamp}.yaml
+agent = Agent("assistant")
+
+# Quiet mode: no console output, but sessions still recorded
+agent = Agent("assistant", quiet=True)
+
+# Disable all logging
+agent = Agent("assistant", log=False)
+
+# Custom log file path
+agent = Agent("assistant", log="debug.log")
+```
+
+## Logging Modes
+
+| quiet | log | Console | Plain Text | Sessions | Use Case |
+|-------|-----|---------|------------|----------|----------|
+| False | True/None | ✓ | ✓ | ✓ | Development (default) |
+| True | True/None | ✗ | ✗ | ✓ | Eval/testing |
+| False | False | ✓ | ✗ | ✗ | Benchmarking |
+| False | "path" | ✓ | custom | ✓ | Custom log path |
+
+## Log Locations
+
+```
+.co/
+├── logs/
+│   └── assistant.log        # Plain text logs
+└── sessions/
+    └── assistant_2024-12-02_10-30-00.yaml  # Session YAML
+```
+
+## Plain Text Format (.co/logs/)
+
+```
+============================================================
+Session started: 2024-12-02 10:32:14
+============================================================
+
+[10:32:14] INPUT: Generate a Python function...
+[10:32:14] -> LLM Request (co/o4-mini) • 2 msgs • 3 tools
+[10:32:15] <- LLM Response (1.1s) • 1 tools • 1.2k tokens • $0.0012
+[10:32:15] -> Tool: generate_code({"language": "python"})
+[10:32:15] <- Result (0.05s): def hello(): print("Hi")...
+[10:32:16] [OK] Complete (2.3s)
+```
+
+## Session YAML Format (.co/evals/)
+
+Sessions are saved as YAML for replay and eval:
+
+```yaml
+name: assistant
+timestamp: 2024-12-02 10:32:14
+
+turns:
+  - input: "Generate a Python function"
+    model: "co/o4-mini"
+    duration_ms: 2300
+    tokens: 1234
+    cost: 0.0012
+    tools_called: [generate_code]
+    result: "Here's a Python function..."
+    messages: '[{"role":"system",...}]'
+```
+
+Use cases:
+- **Session replay**: Restore context from saved sessions
+- **Regression testing**: Compare expected vs actual results
+- **Development comparison**: See what changed after prompt edits
+
+## View Logs
+
+```bash
+# Watch plain text logs in real-time
+tail -f .co/logs/assistant.log
+
+# Search for errors
+grep ERROR .co/logs/assistant.log
+
+# See all tool calls
+grep "Tool:" .co/logs/assistant.log
+
+# List sessions
+ls -la .co/evals/
+```
+
+## Environment Variable
+
+```bash
+# Override log file via environment (highest priority)
+CONNECTONION_LOG=debug.log python agent.py
+```
+
+## Git Ignore
+
+Add to `.gitignore`:
+```
+.co/logs/
+.co/evals/
+*.log
+```
+
+## Parameters
+
+- **`quiet`** (bool): Suppress console output. Sessions still recorded. Default: `False`
+- **`log`** (bool|str|Path): Control file logging
+  - `None`/`True`: Default `.co/logs/{name}.log`
+  - `False`: Disable all logging
+  - `"path/to/file.log"`: Custom log path

connectonion/docs/debug/xray.md

@@ -0,0 +1,215 @@
+# Debug with @xray
+
+See what your AI agent is thinking.
+
+## Quick Start
+
+```python
+from connectonion import xray
+
+@xray
+def my_tool(text: str) -> str:
+    """Process some text."""
+    
+    # Now you can see inside the agent's mind!
+    print(xray.agent.name)    # "my_assistant"
+    print(xray.task)          # "Process this document"
+    print(xray.iteration)     # 1, 2, 3...
+    
+    return f"Processed: {text}"
+```
+
+That's it! Add `@xray` to any tool to unlock debugging superpowers.
+
+## What You Can Access
+
+Inside any `@xray` decorated function:
+
+```python
+xray.agent         # The Agent instance calling this tool
+xray.task          # Original request from user  
+xray.messages      # Full conversation history
+xray.iteration     # Which round of tool calls (1-10)
+xray.previous_tools # Tools called before this one
+```
+
+## Real Example
+
+```python
+@xray
+def search_database(query: str) -> str:
+    """Search our database."""
+    
+    # See what led to this search
+    print(f"User asked: {xray.task}")
+    print(f"This is iteration {xray.iteration}")
+    
+    if xray.previous_tools:
+        print(f"Already tried: {xray.previous_tools}")
+    
+    # Adjust behavior based on context
+    if xray.iteration > 2:
+        return "No results found, please refine your search"
+    
+    return f"Found 5 results for '{query}'"
+```
+
+## Visual Execution Trace
+
+See the complete flow of your agent's work from inside a tool:
+
+```python
+@xray
+def analyze_data(text: str) -> str:
+    """Analyze data and show execution trace."""
+    
+    # Show what happened so far
+    xray.trace()
+    
+    return "Analysis complete"
+```
+
+**Output:**
+```
+Task: "Find Python tutorials and summarize them"
+
+[1] • 89ms  search_database(query="Python tutorials")
+      IN  → query: "Python tutorials"
+      OUT ← "Found 5 results for 'Python tutorials'"
+
+[2] • 234ms summarize_text(text="Found 5 results...", max_words=50)
+      IN  → text: "Found 5 results for 'Python tutorials'"
+      IN  → max_words: 50
+      OUT ← "5 Python tutorials found covering basics to advanced topics"
+
+Total: 323ms • 2 steps • 1 iterations
+```
+
+## Debug in Your IDE
+
+Set a breakpoint and explore:
+
+```python
+@xray
+def analyze_sentiment(text: str) -> str:
+    # 🎯 Set breakpoint on next line
+    sentiment = "positive"  # When stopped here in debugger:
+                           # >>> xray
+                           # <XrayContext active>
+                           #   agent: 'my_bot'
+                           #   task: 'How do people feel about Python?'
+                           # >>> xray.messages
+                           # [{'role': 'user', 'content': '...'}, ...]
+    
+    return sentiment
+```
+
+## Practical Use Cases
+
+### 1. Understand Why a Tool Was Called
+```python
+@xray
+def emergency_shutdown():
+    """Shutdown the system."""
+    
+    # Check why this drastic action was requested
+    print(f"Shutdown requested because: {xray.task}")
+    print(f"After trying: {xray.previous_tools}")
+    
+    # Maybe don't shutdown if it's the first try
+    if xray.iteration == 1:
+        return "Try restarting first"
+    
+    return "System shutdown complete"
+```
+
+### 2. Adaptive Tool Behavior
+```python
+@xray
+def fetch_data(source: str) -> str:
+    """Fetch data from a source."""
+    
+    # Use cache on repeated calls
+    if "fetch_data" in xray.previous_tools:
+        return "Using cached data"
+    
+    # Fresh fetch on first call
+    return f"Fresh data from {source}"
+```
+
+### 3. Debug Complex Flows
+```python
+@xray
+def process_order(order_id: str) -> str:
+    """Process an order."""
+    
+    # See the full context when debugging
+    if xray.agent:
+        print(f"Processing for agent: {xray.agent.name}")
+        print(f"Original request: {xray.task}")
+        print(f"Conversation length: {len(xray.messages)}")
+    
+    return f"Order {order_id} processed"
+```
+
+## Tips
+
+1. **Development Only** - Remove @xray in production for best performance
+2. **Combine with IDE** - Set breakpoints for interactive debugging
+3. **Use trace()** - Call `xray.trace(agent)` after runs to see full flow
+4. **Check context** - Always verify `xray.agent` exists before using
+
+## Production Notes
+
+**Thread Safety:** xray uses global state that is NOT thread-safe. This is fine for:
+- Single-threaded async servers (uvicorn, asyncio) ✅
+- Multi-process workers (gunicorn with workers) ✅
+
+But NOT safe for:
+- Multi-threaded servers with shared agent instances ❌
+- Parallel tool execution in threads ❌
+
+If you need multi-threading, either:
+1. Don't use `@xray` in production (recommended)
+2. Use separate agent instances per thread
+
+**For production:** If you need to access agent context in tools, use the [Events system](../events.md) instead. Events provide a cleaner, safer pattern for injecting agent context without global state.
+
+If you have a use case that requires thread-local xray context, please [open a GitHub issue](https://github.com/openonion/connectonion/issues) to discuss.
+
+## Common Patterns
+
+### Logging What Matters
+```python
+@xray
+def important_action(data: str) -> str:
+    # Log with context
+    if xray.agent:
+        logger.info(f"Agent {xray.agent.name} performing action")
+        logger.info(f"Original task: {xray.task}")
+        logger.info(f"Iteration: {xray.iteration}")
+    
+    return "Action completed"
+```
+
+### Conditional Logic
+```python
+@xray
+def smart_search(query: str) -> str:
+    # Different strategies based on context
+    if xray.iteration > 1:
+        # Broaden search on retry
+        query = f"{query} OR related"
+    
+    if "analyze" in xray.previous_tools:
+        # We already analyzed, search differently
+        query = f"summary of {query}"
+    
+    return f"Results for: {query}"
+```
+
+## Next Steps
+
+- Try [@replay](replay.md) for re-running tools with different parameters
+- See [Examples](examples.md) for complete debugging workflows
+- Check [API Reference](api.md) for all xray properties