Self-Healing

How Self-Healing Works

When a @vectorize-decorated function throws an error, VectorWave can automatically:

1. Detect the error and store it with full context
2. Diagnose the root cause using RAG over your codebase
3. Generate a code fix using LLM + AST parsing
4. Submit a GitHub Pull Request with the fix

Error Occurs → RAG Diagnosis → LLM Code Fix → AST Patch → GitHub PR

Quick Example

@vectorize(auto=True)
def risky_calculation(a, b):
    return a / b

risky_calculation(10, 0)  # ZeroDivisionError!

What happens automatically:

1. AutoHealerBot detects ZeroDivisionError
2. Retrieves the source code and error stack trace from Weaviate
3. Sends context to GPT-4 for analysis
4. Generates a patched version with zero-division guard
5. Creates a new branch and opens a GitHub Pull Request

Using VectorWaveHealer

Basic Usage

from vectorwave import VectorWaveHealer

healer = VectorWaveHealer(model="gpt-4-turbo")

# Diagnose recent errors for a specific function
diagnosis = healer.diagnose_and_heal(
    function_name="generate_response",
    lookback_minutes=60,
    create_pr=True,  # Opens a GitHub PR with the fix
)

print(diagnosis)
# {
#   "error_type": "ZeroDivisionError",
#   "root_cause": "No guard for zero denominator",
#   "fix_description": "Added zero-check with fallback",
#   "pr_url": "https://github.com/org/repo/pull/42"
# }

Diagnosis Only (No PR)

diagnosis = healer.diagnose_and_heal(
    function_name="generate_response",
    lookback_minutes=60,
    create_pr=False,  # Just diagnose, don't create PR
)

print(diagnosis["root_cause"])
print(diagnosis["suggested_fix"])

The Healing Pipeline

Step 1: Error Detection

When a @vectorize function fails, the execution log is stored in Weaviate with:

• status: "error"
• Full exception type and message
• Stack trace
• Function inputs that caused the error
• Source code of the function

Step 2: RAG-Based Diagnosis

The healer performs a RAG query over your stored data:

1. Searches VectorWaveFunctions for the function's source code
2. Searches VectorWaveExecutions for recent error logs
3. Retrieves similar past errors and their resolutions
4. Constructs a comprehensive prompt with all context

Step 3: LLM Code Generation

The prompt is sent to GPT-4 with instructions to:

• Analyze the root cause
• Generate a minimal, targeted fix
• Preserve the original function's behavior for non-error cases
• Include proper error handling

Step 4: AST Patching

VectorWave uses Python's ast module to:

1. Parse the original source file
2. Locate the target function in the AST
3. Replace it with the LLM-generated fix
4. Write the patched file (preserving formatting)

This is safer than string replacement — it ensures syntactically valid Python.

Step 5: GitHub PR

Using PyGithub, VectorWave:

1. Creates a new branch: vectorwave/fix-{function_name}-{timestamp}
2. Commits the patched file
3. Opens a Pull Request with:
   • Error description
   • Root cause analysis
   • Diff of the fix
   • Test suggestions

Scheduled Healing (AutoHealerBot)

VectorWave includes a built-in scheduler that automatically scans for errors and creates fix PRs:

from vectorwave.utils.scheduler import start_scheduler
import threading

# Start the auto-healer in a background thread
scheduler_thread = threading.Thread(
    target=start_scheduler,
    args=(5,),  # check every 5 minutes
    daemon=True
)
scheduler_thread.start()

The AutoHealerBot automatically:

1. Scans for ERROR status executions in the last 60 minutes
2. Deduplicates by function name
3. Calls VectorWaveHealer.diagnose_and_heal(create_pr=True) for each
4. Tracks cooldown (60 min per function) to prevent duplicate PRs
5. Skips errors listed in .vtwignore

Cooldown Mechanism

To prevent PR spam for recurring errors, VectorWave implements a cooldown:

• After creating a PR for a function, the healer will not create another for 60 minutes
• Both on-demand and scheduled healing respect the cooldown
• This prevents flooding your repository with duplicate fix attempts

Error Suppression with .vtwignore

Create a .vtwignore file in your project root to exclude specific error types from healing and alerts:

# Ignore expected exceptions
ValueError
KeyError
DeprecationWarning

Errors matching these codes are marked as FAILURE instead of ERROR:

• The AutoHealerBot skips FAILURE status (only processes ERROR)
• No webhook alerts are sent for suppressed errors
• Suppressed errors are still logged in Weaviate for analysis

Configuration

Environment Variables

# Required for self-healing
OPENAI_API_KEY=sk-...

# GitHub integration (for auto-PR)
GITHUB_TOKEN=ghp_...
GITHUB_REPO_NAME=org/repo-name

Healer Options

healer = VectorWaveHealer(
    model="gpt-4-turbo",     # LLM model for diagnosis (only parameter)
)

Error Code Tracking

VectorWave uses a 3-tier priority system for error classification:

1. Custom Exception Attribute — If your exception has a .error_code attribute, it's used first
2. Global Mapping File — .vectorwave_errors.json in project root maps exception types to codes
3. Default — Falls back to the exception class name (e.g., ZeroDivisionError)

Custom Error Mapping

Create .vectorwave_errors.json in your project root:

{
  "ValueError": "VW-001",
  "ConnectionError": "VW-002",
  "TimeoutError": "VW-003",
  "RateLimitError": "VW-004"
}

VectorSurfer: Error diagnosis, batch healing, and PR creation are available through the VectorSurfer dashboard with a visual interface — browse errors, view AI-generated diagnoses, and create PRs with one click.

External Resources

• OpenAI API Documentation — LLM API used for diagnosis and code generation

Next Steps

• Golden Dataset — Curate high-quality data for caching and testing
• Drift Detection — Monitor input quality changes
• Replay Testing — Regression test with past executions