Occupying-Mars
5 months ago
parent
599776736b
commit
ca95cdbbba
@ -0,0 +1,181 @@
|
||||
# Self-Healing Agent Documentation
|
||||
|
||||
The Self-Healing Agent is a specialized agent designed to automatically detect, analyze, and fix runtime errors in your code using LLM-based analysis. It provides structured error analysis and generates fixes in JSON format.
|
||||
|
||||
## Overview
|
||||
|
||||
The Self-Healing Agent uses advanced language models to:
|
||||
1. Analyze runtime errors and exceptions
|
||||
2. Understand the error context and root cause
|
||||
3. Generate potential fixes in a structured format
|
||||
4. Apply fixes automatically when possible
|
||||
|
||||
## Installation
|
||||
|
||||
The Self-Healing Agent is included in the main swarms package:
|
||||
|
||||
```bash
|
||||
pip install -U swarms
|
||||
```
|
||||
|
||||
## Basic Usage
|
||||
|
||||
```python
|
||||
from swarms.agents import SelfHealingAgent
|
||||
|
||||
# Initialize the agent
|
||||
agent = SelfHealingAgent(
|
||||
model_name="gpt-4", # The LLM model to use
|
||||
max_retries=3, # Maximum number of fix attempts
|
||||
verbose=True # Enable detailed logging
|
||||
)
|
||||
|
||||
# Example usage with error handling
|
||||
try:
|
||||
result = some_function_that_might_fail()
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
print(f"Error Analysis: {fix['analysis']}")
|
||||
print(f"Proposed Fix: {fix['solution']}")
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### SelfHealingAgent Class
|
||||
|
||||
#### Constructor Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| model_name | str | "gpt-4" | The name of the LLM model to use |
|
||||
| max_retries | int | 3 | Maximum number of fix attempts |
|
||||
| verbose | bool | False | Enable detailed logging |
|
||||
| system_prompt | str | None | Custom system prompt for the LLM |
|
||||
| temperature | float | 0.7 | Temperature for LLM responses |
|
||||
|
||||
#### Methods
|
||||
|
||||
##### analyze_and_fix(error: Exception) -> dict
|
||||
Analyzes an error and generates potential fixes.
|
||||
|
||||
**Parameters:**
|
||||
- error (Exception): The caught exception to analyze
|
||||
|
||||
**Returns:**
|
||||
A dictionary containing:
|
||||
```json
|
||||
{
|
||||
"error_type": "str", // Type of the error
|
||||
"analysis": "str", // Detailed error analysis
|
||||
"context": "str", // Error context
|
||||
"solution": "str", // Proposed fix in code form
|
||||
"confidence": float, // Confidence score (0-1)
|
||||
"metadata": {} // Additional error metadata
|
||||
}
|
||||
```
|
||||
|
||||
##### apply_fix(fix: dict) -> bool
|
||||
Attempts to apply a generated fix.
|
||||
|
||||
**Parameters:**
|
||||
- fix (dict): The fix dictionary returned by analyze_and_fix()
|
||||
|
||||
**Returns:**
|
||||
- bool: True if fix was successfully applied, False otherwise
|
||||
|
||||
## Error Output Format
|
||||
|
||||
The agent provides structured error analysis in JSON format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error_type": "ZeroDivisionError",
|
||||
"analysis": "Attempted division by zero in calculation",
|
||||
"context": "Error occurred in calculate_average() at line 45",
|
||||
"solution": "Add a check for zero denominator:\nif denominator != 0:\n result = numerator/denominator\nelse:\n raise ValueError('Denominator cannot be zero')",
|
||||
"confidence": 0.95,
|
||||
"metadata": {
|
||||
"file": "calculator.py",
|
||||
"line": 45,
|
||||
"function": "calculate_average"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Error Context**: Always provide as much context as possible when catching errors
|
||||
2. **Validation**: Review proposed fixes before applying them automatically
|
||||
3. **Logging**: Enable verbose mode during development for detailed insights
|
||||
4. **Model Selection**: Use GPT-4 for complex errors, GPT-3.5-turbo for simpler cases
|
||||
5. **Retry Strategy**: Configure max_retries based on your use case
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Error Handling
|
||||
|
||||
```python
|
||||
from swarms.agents import SelfHealingAgent
|
||||
|
||||
agent = SelfHealingAgent()
|
||||
|
||||
def process_data(data):
|
||||
try:
|
||||
result = data['key']['nested_key']
|
||||
return result
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
if fix['confidence'] > 0.8:
|
||||
print(f"Applying fix: {fix['solution']}")
|
||||
return agent.apply_fix(fix)
|
||||
else:
|
||||
print(f"Low confidence fix, manual review needed: {fix['analysis']}")
|
||||
return None
|
||||
```
|
||||
|
||||
### Custom System Prompt
|
||||
|
||||
```python
|
||||
agent = SelfHealingAgent(
|
||||
system_prompt="""You are an expert Python developer specializing in
|
||||
fixing data processing errors. Focus on data validation and type checking
|
||||
in your solutions."""
|
||||
)
|
||||
```
|
||||
|
||||
### Batch Error Processing
|
||||
|
||||
```python
|
||||
def process_batch(items):
|
||||
results = []
|
||||
errors = []
|
||||
|
||||
for item in items:
|
||||
try:
|
||||
result = process_item(item)
|
||||
results.append(result)
|
||||
except Exception as e:
|
||||
errors.append((item, e))
|
||||
|
||||
# Process all errors at once
|
||||
if errors:
|
||||
fixes = [agent.analyze_and_fix(e) for _, e in errors]
|
||||
return results, fixes
|
||||
```
|
||||
|
||||
## Error Types Handled
|
||||
|
||||
The Self-Healing Agent can handle various types of runtime errors including:
|
||||
|
||||
- Syntax Errors
|
||||
- Type Errors
|
||||
- Index Errors
|
||||
- Key Errors
|
||||
- Attribute Errors
|
||||
- Value Errors
|
||||
- Import Errors
|
||||
- And more...
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions to improve the Self-Healing Agent! Please see our [Contributing Guidelines](../../CONTRIBUTING.md) for more information.
|
||||
@ -0,0 +1,319 @@
|
||||
# Self-Healing Agent Tutorial
|
||||
|
||||
This tutorial will guide you through using the Self-Healing Agent to automatically detect and fix runtime errors in your Python code.
|
||||
|
||||
## Introduction
|
||||
|
||||
The Self-Healing Agent is a powerful tool that uses LLM-based analysis to:
|
||||
- Detect runtime errors
|
||||
- Analyze their root causes
|
||||
- Generate and apply fixes automatically
|
||||
- Provide detailed error analysis in structured JSON format
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.7+
|
||||
- swarms package installed (`pip install -U swarms`)
|
||||
- OpenAI API key set in environment variables
|
||||
|
||||
## Basic Setup
|
||||
|
||||
First, let's set up a basic project with some error-prone code:
|
||||
|
||||
```python
|
||||
# error_prone.py
|
||||
def divide_numbers(a, b):
|
||||
return a / b
|
||||
|
||||
def access_nested_dict(data):
|
||||
return data['user']['name']
|
||||
|
||||
def process_list(items):
|
||||
return [item.upper() for item in items]
|
||||
```
|
||||
|
||||
Now let's add error handling with the Self-Healing Agent:
|
||||
|
||||
```python
|
||||
# main.py
|
||||
from swarms.agents import SelfHealingAgent
|
||||
from error_prone import divide_numbers, access_nested_dict, process_list
|
||||
|
||||
# Initialize the agent
|
||||
agent = SelfHealingAgent(
|
||||
model_name="gpt-4",
|
||||
max_retries=3,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Test cases that will cause errors
|
||||
def run_tests():
|
||||
test_cases = [
|
||||
lambda: divide_numbers(10, 0),
|
||||
lambda: access_nested_dict({}),
|
||||
lambda: process_list([1, 2, "three"])
|
||||
]
|
||||
|
||||
for test in test_cases:
|
||||
try:
|
||||
result = test()
|
||||
print(f"Success: {result}")
|
||||
except Exception as e:
|
||||
print(f"\nError caught: {type(e).__name__}")
|
||||
fix = agent.analyze_and_fix(e)
|
||||
|
||||
print("\nError Analysis:")
|
||||
print(f"Type: {fix['error_type']}")
|
||||
print(f"Analysis: {fix['analysis']}")
|
||||
print(f"Proposed Fix: {fix['solution']}")
|
||||
print(f"Confidence: {fix['confidence']}")
|
||||
|
||||
if fix['confidence'] > 0.8:
|
||||
print("\nApplying fix automatically...")
|
||||
success = agent.apply_fix(fix)
|
||||
if success:
|
||||
print("Fix applied successfully!")
|
||||
else:
|
||||
print("\nLow confidence fix - manual review needed")
|
||||
|
||||
if __name__ == "__main__":
|
||||
run_tests()
|
||||
```
|
||||
|
||||
## Step-by-Step Examples
|
||||
|
||||
### 1. Handling Division by Zero
|
||||
|
||||
```python
|
||||
def safe_division():
|
||||
try:
|
||||
result = divide_numbers(10, 0)
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
print(f"Original error: {e}")
|
||||
print(f"Fix suggestion: {fix['solution']}")
|
||||
|
||||
# The agent might suggest something like:
|
||||
"""
|
||||
def divide_numbers(a, b):
|
||||
if b == 0:
|
||||
raise ValueError("Cannot divide by zero")
|
||||
return a / b
|
||||
"""
|
||||
```
|
||||
|
||||
### 2. Handling Dictionary Access
|
||||
|
||||
```python
|
||||
def safe_dict_access():
|
||||
data = {}
|
||||
try:
|
||||
name = access_nested_dict(data)
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
print(f"Original error: {e}")
|
||||
print(f"Fix suggestion: {fix['solution']}")
|
||||
|
||||
# The agent might suggest something like:
|
||||
"""
|
||||
def access_nested_dict(data):
|
||||
return data.get('user', {}).get('name', None)
|
||||
"""
|
||||
```
|
||||
|
||||
### 3. Type Error Handling
|
||||
|
||||
```python
|
||||
def safe_list_processing():
|
||||
items = [1, 2, "three"]
|
||||
try:
|
||||
result = process_list(items)
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
print(f"Original error: {e}")
|
||||
print(f"Fix suggestion: {fix['solution']}")
|
||||
|
||||
# The agent might suggest something like:
|
||||
"""
|
||||
def process_list(items):
|
||||
return [str(item).upper() for item in items]
|
||||
"""
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Error Handlers
|
||||
|
||||
```python
|
||||
class CustomErrorHandler:
|
||||
def __init__(self, agent):
|
||||
self.agent = agent
|
||||
self.fix_history = []
|
||||
|
||||
def handle_error(self, error, context=None):
|
||||
fix = self.agent.analyze_and_fix(error)
|
||||
self.fix_history.append(fix)
|
||||
|
||||
if fix['confidence'] > 0.9:
|
||||
return self.agent.apply_fix(fix)
|
||||
elif fix['confidence'] > 0.7:
|
||||
return self.request_human_review(fix)
|
||||
else:
|
||||
return self.fallback_handler(error)
|
||||
|
||||
def request_human_review(self, fix):
|
||||
print("Please review the following fix:")
|
||||
print(f"Error: {fix['error_type']}")
|
||||
print(f"Solution: {fix['solution']}")
|
||||
response = input("Apply fix? (y/n): ")
|
||||
return response.lower() == 'y'
|
||||
|
||||
def fallback_handler(self, error):
|
||||
print(f"Unable to fix error: {error}")
|
||||
return False
|
||||
|
||||
# Usage
|
||||
handler = CustomErrorHandler(agent)
|
||||
try:
|
||||
result = some_risky_operation()
|
||||
except Exception as e:
|
||||
handler.handle_error(e)
|
||||
```
|
||||
|
||||
### Batch Processing with Progress Tracking
|
||||
|
||||
```python
|
||||
from tqdm import tqdm
|
||||
|
||||
def batch_process_with_healing(items, process_func):
|
||||
results = []
|
||||
errors = []
|
||||
fixes_applied = 0
|
||||
|
||||
for item in tqdm(items, desc="Processing items"):
|
||||
try:
|
||||
result = process_func(item)
|
||||
results.append(result)
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
if fix['confidence'] > 0.8:
|
||||
if agent.apply_fix(fix):
|
||||
fixes_applied += 1
|
||||
# Retry with fix applied
|
||||
try:
|
||||
result = process_func(item)
|
||||
results.append(result)
|
||||
continue
|
||||
except Exception as retry_e:
|
||||
errors.append((item, retry_e))
|
||||
errors.append((item, e))
|
||||
|
||||
print(f"\nProcessing complete:")
|
||||
print(f"- Successful items: {len(results)}")
|
||||
print(f"- Failed items: {len(errors)}")
|
||||
print(f"- Fixes applied: {fixes_applied}")
|
||||
|
||||
return results, errors
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Error Context**
|
||||
```python
|
||||
try:
|
||||
result = risky_operation()
|
||||
except Exception as e:
|
||||
# Provide additional context
|
||||
fix = agent.analyze_and_fix(e, context={
|
||||
'function': 'risky_operation',
|
||||
'input_data': str(input_data)[:100], # First 100 chars
|
||||
'expected_output': 'list of strings'
|
||||
})
|
||||
```
|
||||
|
||||
2. **Confidence Thresholds**
|
||||
```python
|
||||
def apply_fix_with_threshold(fix, threshold=0.8):
|
||||
if fix['confidence'] >= threshold:
|
||||
return agent.apply_fix(fix)
|
||||
return False
|
||||
```
|
||||
|
||||
3. **Logging and Monitoring**
|
||||
```python
|
||||
import logging
|
||||
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
logger = logging.getLogger('self_healing')
|
||||
|
||||
def monitored_execution(func):
|
||||
try:
|
||||
return func()
|
||||
except Exception as e:
|
||||
logger.error(f"Error in {func.__name__}: {e}")
|
||||
fix = agent.analyze_and_fix(e)
|
||||
logger.info(f"Fix generated: {fix['solution']}")
|
||||
if agent.apply_fix(fix):
|
||||
logger.info("Fix applied successfully")
|
||||
return func() # Retry
|
||||
logger.warning("Fix application failed")
|
||||
raise
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Avoid Infinite Loops**
|
||||
```python
|
||||
max_retries = 3
|
||||
retry_count = 0
|
||||
|
||||
while retry_count < max_retries:
|
||||
try:
|
||||
result = risky_operation()
|
||||
break
|
||||
except Exception as e:
|
||||
retry_count += 1
|
||||
fix = agent.analyze_and_fix(e)
|
||||
if not agent.apply_fix(fix):
|
||||
break
|
||||
```
|
||||
|
||||
2. **Handle Nested Errors**
|
||||
```python
|
||||
def safe_execute(func):
|
||||
try:
|
||||
return func()
|
||||
except Exception as outer_e:
|
||||
try:
|
||||
fix = agent.analyze_and_fix(outer_e)
|
||||
except Exception as inner_e:
|
||||
logger.error(f"Error in error handler: {inner_e}")
|
||||
raise outer_e
|
||||
```
|
||||
|
||||
3. **Resource Cleanup**
|
||||
```python
|
||||
def safe_file_operation(filename):
|
||||
file = None
|
||||
try:
|
||||
file = open(filename, 'r')
|
||||
return process_file(file)
|
||||
except Exception as e:
|
||||
fix = agent.analyze_and_fix(e)
|
||||
# Handle fix
|
||||
finally:
|
||||
if file:
|
||||
file.close()
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Self-Healing Agent is a powerful tool for automating error handling and fixes in your Python code. By following this tutorial and best practices, you can significantly reduce the time spent debugging common runtime errors and improve your code's resilience.
|
||||
|
||||
Remember to:
|
||||
- Always validate fixes before applying them in production
|
||||
- Set appropriate confidence thresholds
|
||||
- Maintain good logging and monitoring
|
||||
- Handle edge cases and cleanup properly
|
||||
|
||||
For more information, see the [API Documentation](../swarms/agents/self_healing_agent.md).
|
||||
Loading…
Reference in new issue