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

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:

# 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

# 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

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

Set Confidence Thresholds

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

Configure Pattern Pruning

# 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

pytest tests/unit/test_self_healing.py -v

Run Property Tests

pytest tests/property/test_self_healing_properties.py -v

Test Specific Strategy

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

# 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

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

# 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

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

# Original: "Submit"
# New: "Send"
# Strategy: Semantic Variant
# Result: ✅ Automatically finds "Send" button

Example 2: Element Moved

# Original position: (100, 200)
# New position: (120, 210)
# Strategy: Spatial Fallback
# Result: ✅ Finds element within 50px radius

Example 3: Slow Page Load

# Original timeout: 5s
# Actual load time: 8s
# Strategy: Timing Adaptation
# Result: ✅ Increases timeout to 7.5s

Example 4: Date Format Changed

# 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! 🎉