rpa_vision_v3/docs/guides/SELF_HEALING_QUICKSTART.md

# Self-Healing Workflows - Quick Start Guide 🚀

## Installation

The self-healing system is already integrated into RPA Vision V3. No additional installation required!

## Basic Usage

### 1. Enable Self-Healing

```python
from core.healing.execution_integration import get_self_healing_integration
from pathlib import Path

# Initialize with default settings
healing = get_self_healing_integration(
    storage_path=Path('data/healing'),
    log_path=Path('logs/healing'),
    enabled=True
)
```

### 2. Integrate with Execution Loop

The self-healing system automatically handles failures during workflow execution:

```python
# In your execution loop, when an action fails:
if execution_result.status != ExecutionStatus.SUCCESS:
    # Attempt recovery
    recovery = healing.handle_execution_failure(
        action_info={
            'action': 'click',
            'target': 'Submit Button',
            'element_type': 'button'
        },
        execution_result=execution_result,
        workflow_id='my_workflow',
        node_id='node_123',
        screenshot_path='/tmp/screenshot.png',
        attempt_count=1
    )
    
    if recovery and recovery.success:
        print(f"✅ Recovered using {recovery.strategy_used}")
        print(f"   Confidence: {recovery.confidence_score:.2f}")
        print(f"   New element: {recovery.new_element}")
        
        # Update workflow with learned pattern
        healing.update_workflow_from_recovery(
            workflow_id='my_workflow',
            node_id='node_123',
            edge_id='edge_456',
            recovery_result=recovery
        )
    else:
        print("❌ Recovery failed, manual intervention needed")
```

### 3. Monitor Performance

```python
# Get statistics
stats = healing.get_statistics()
print(f"Total attempts: {stats['total_attempts']}")
print(f"Success rate: {stats['successful_recoveries'] / stats['total_attempts'] * 100:.1f}%")
print(f"Time saved: {stats['time_saved_hours']:.1f} hours")

# Get insights
insights = healing.get_insights()
for insight in insights:
    print(f"💡 {insight}")

# Check for alerts
alerts = healing.check_alerts()
for alert in alerts:
    if alert['severity'] == 'high':
        print(f"⚠️  {alert['message']}")
```

## Recovery Strategies

The system uses 4 intelligent strategies:

### 1. Semantic Variants
Finds alternative text for UI elements:
- "Submit" → "Send" → "OK" → "Confirm"
- Supports English and French
- Best for: Button text changes

### 2. Spatial Fallback
Searches in expanded areas around original position:
- Progressively expands: 50px → 100px → 200px → 400px
- Best for: Elements that moved slightly

### 3. Timing Adaptation
Adjusts wait times based on performance:
- Increases timeout by 1.5x on failure
- Learns optimal timing per element
- Best for: Slow-loading pages

### 4. Format Transformation
Adapts input formats:
- Date formats (8 variations)
- Phone number formats
- Text truncation
- Best for: Validation errors

## Configuration

### Adjust Recovery Time Limits

```python
# Default is 30 seconds
healing.healing_engine.max_recovery_time = 60.0
```

### Set Confidence Thresholds

```python
# When creating recovery context
context = RecoveryContext(
    # ... other params ...
    confidence_threshold=0.8,  # Higher = more conservative
)
```

### Configure Pattern Pruning

```python
# Prune old patterns monthly
healing.prune_patterns(
    max_age_days=90,      # Keep patterns for 90 days
    min_confidence=0.3    # Remove low-confidence patterns
)
```

## Testing

### Run Unit Tests
```bash
pytest tests/unit/test_self_healing.py -v
```

### Run Property Tests
```bash
pytest tests/property/test_self_healing_properties.py -v
```

### Test Specific Strategy
```python
from core.healing.strategies import SemanticVariantStrategy
from core.healing.models import RecoveryContext

strategy = SemanticVariantStrategy()
context = RecoveryContext(
    original_action='click',
    target_element='Submit',
    failure_reason='element_not_found',
    screenshot_path='/tmp/test.png',
    workflow_id='test',
    node_id='node1',
    attempt_count=1
)

result = strategy.attempt_recovery(context)
print(f"Success: {result.success}")
print(f"New element: {result.new_element}")
```

## Advanced Features

### Get Recovery Suggestions

```python
# Get suggestions before attempting recovery
suggestions = healing.get_recovery_suggestions(
    action_info={'action': 'click', 'target': 'Submit'},
    workflow_id='my_workflow',
    node_id='node_123',
    screenshot_path='/tmp/screenshot.png'
)

for suggestion in suggestions:
    print(f"{suggestion.strategy}: {suggestion.confidence:.2f}")
    print(f"  {suggestion.description}")
    print(f"  Estimated time: {suggestion.estimated_time}s")
```

### Manual Pattern Creation

```python
from core.healing.models import RecoveryPattern
from datetime import datetime

# Create a pattern manually
pattern = RecoveryPattern(
    pattern_id='custom_001',
    original_failure='element_not_found',
    recovery_strategy='semantic_variant',
    success_count=10,
    failure_count=1,
    confidence_score=0.9,
    context_metadata={
        'original_action': 'click',
        'element_type': 'button'
    },
    created_at=datetime.now(),
    last_used=datetime.now()
)

healing.healing_engine.learning_repo.patterns[pattern.pattern_id] = pattern
```

### Export/Import Patterns

```python
# Export patterns
patterns = healing.healing_engine.learning_repo.get_all_patterns()
import json
with open('patterns_backup.json', 'w') as f:
    json.dump([p.to_dict() for p in patterns], f, indent=2)

# Import patterns
with open('patterns_backup.json', 'r') as f:
    pattern_dicts = json.load(f)
    for p_dict in pattern_dicts:
        pattern = RecoveryPattern.from_dict(p_dict)
        healing.healing_engine.learning_repo.patterns[pattern.pattern_id] = pattern
```

## Best Practices

### 1. Start with Supervised Mode
- Enable self-healing but review recoveries
- Build confidence in the system
- Gradually move to automatic mode

### 2. Monitor Regularly
- Check statistics weekly
- Review alerts daily
- Prune patterns monthly

### 3. Provide Good Context
- Include element_type in metadata
- Provide accurate failure reasons
- Include input values when relevant

### 4. Handle Low Confidence
```python
if recovery and recovery.requires_user_input:
    # Ask user for guidance
    user_choice = ask_user_for_recovery_choice(recovery)
    # Learn from user's choice
    # ...
```

### 5. Update Workflows
- Always update workflows after successful recovery
- This prevents the same failure in the future
- Keeps workflows up-to-date with UI changes

## Troubleshooting

### Recovery Always Fails
- Check confidence threshold (might be too high)
- Verify screenshot quality
- Check if strategies can handle the failure type

### Patterns Not Reused
- Verify pattern matching criteria
- Check if patterns are being pruned too aggressively
- Ensure metadata is consistent

### Slow Recovery
- Reduce max_recovery_time
- Disable slow strategies for specific contexts
- Use parallel execution (coming soon)

## Examples

### Example 1: Button Text Changed
```python
# Original: "Submit"
# New: "Send"
# Strategy: Semantic Variant
# Result: ✅ Automatically finds "Send" button
```

### Example 2: Element Moved
```python
# Original position: (100, 200)
# New position: (120, 210)
# Strategy: Spatial Fallback
# Result: ✅ Finds element within 50px radius
```

### Example 3: Slow Page Load
```python
# Original timeout: 5s
# Actual load time: 8s
# Strategy: Timing Adaptation
# Result: ✅ Increases timeout to 7.5s
```

### Example 4: Date Format Changed
```python
# Original: "2024-11-30"
# Required: "30/11/2024"
# Strategy: Format Transformation
# Result: ✅ Converts to DD/MM/YYYY format
```

## Next Steps

1. **Integrate with your execution loop** - Add failure handling
2. **Monitor for a week** - Collect statistics and patterns
3. **Review insights** - Identify common failure patterns
4. **Optimize workflows** - Update based on learned patterns
5. **Enable automatic mode** - Let the system handle recoveries

## Support

For issues or questions:
- Check logs in `logs/healing/recovery.log`
- Review metrics in `data/healing/metrics.json`
- Run diagnostics: `healing.get_statistics()`

Happy self-healing! 🎉