Skip to content

Script Healing Test

Overview

This demo demonstrates Automatic Script Healing with Version Detection.

When a Python script fails due to version conflicts, omnipkg run can automatically detect the issue, install the required version in an isolated bubble, and re-execute the script successfully—all without manual intervention. It proves OmniPkg can intelligently analyze failures and self-heal broken scripts.

Auto-Healing Capabilities

Note About Web UI

The omnipkg run command is not available in the web UI for security reasons. This demo uses omnipkg demo 7 which wraps the functionality safely.

This demo validates OmniPkg’s ability to detect, diagnose, and fix version conflicts automatically. When a script asserts it needs a specific package version that doesn’t match the active environment, OmniPkg intercepts the failure, creates an isolated bubble with the correct version, and re-runs the script seamlessly.

Usage

For local execution:

# Run Demo #7: Script-healing Test
omnipkg demo 7

If you have the OmniPkg web bridge connected, you can run it live in the UI:

omnipkg demo 7

What You’ll Learn

  1. Automatic Failure Detection: How OmniPkg captures and analyzes script failures
  2. Intelligent Version Resolution: How the system identifies which packages caused the failure
  3. Bubble Creation On-Demand: How isolation bubbles are created automatically when needed
  4. Zero-Downtime Re-execution: How scripts are transparently re-run with the correct environment
  5. Performance Optimization: How OmniPkg outperforms traditional tools like UV

The Test Script

The script intentionally requires an older version of rich (13.4.2) while the system has a newer version installed (13.7.1):

# tests/test_old_rich.py
from omnipkg.common_utils import safe_print
import rich
import importlib.metadata
from omnipkg.i18n import _
from rich import print as rich_print

# Get the actual rich version
try:
    rich_version = rich.__version__
except AttributeError:
    rich_version = importlib.metadata.version("rich")

# Assert we have the older version - this will FAIL on first run
assert rich_version == "13.4.2", _(
    "Incorrect rich version! Expected 13.4.2, got {}"
).format(rich_version)

# If we reach here, the correct version is active
safe_print(_("✅ Successfully imported rich version: {}").format(rich_version))

# Use rich's styled output to confirm it works
rich_print(
    "[bold green]This script is running with the correct, older version of rich![/bold green]"
)

The Healing Workflow

The auto-healing process follows these stages:

┌─────────────────────────────────────────────────────────────────┐
│  INITIAL EXECUTION                                              │
│  Script runs with system rich 13.7.1                            │
│  ❌ AssertionError: Expected 13.4.2, got 13.7.1                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  FAILURE ANALYSIS                                               │
│  🤖 AI-powered error log capture                                │
│  🔍 Identifies: "rich==13.4.2" requirement                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  BUBBLE CREATION                                                │
│  🫧 Creates isolated bubble with rich==13.4.2                   │
│  📦 Includes dependencies: markdown-it-py, pygments, mdurl      │
│  ✅ Verifies imports work correctly                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  RE-EXECUTION                                                   │
│  🚀 Script runs again with omnipkg loader wrapper               │
│  ✅ Bubble activated in 20.9ms                                  │
│  ✅ Script completes successfully                               │
└─────────────────────────────────────────────────────────────────┘

Live Execution Log

Watch as OmniPkg detects the failure, heals the environment, and succeeds on the second attempt:

🚀 Executing script directly...
Traceback (most recent call last):
  File "/tmp/tmpeppoblzp.py", line 27, in <module>
    assert rich_version == "13.4.2", _(
           ^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError: Incorrect rich version! Expected 13.4.2, got 13.7.1

❌ Script exited with code: 1
🤖 [AI-INFO] Attempting to capture error log for healing...
🤖 [AI-INFO] Script execution failed. Analyzing for auto-healing...

🔍 Runtime version assertion failed. Auto-healing with omnipkg bubbles...
   - Conflict identified for: rich==13.4.2

🔍 Comprehensive Healing Plan Compiled (Attempt 1): ['rich==13.4.2']
🛠️  Installing bubble for rich==13.4.2...

============================================================
📦 Processing: rich==13.4.2
============================================================
   🫧 Creating isolated bubble for rich v13.4.2 (Python 3.11 context)
   - 🏗️  Staging install for rich==13.4.2...

   - 🧪 Running SMART import verification...
      ==============================
      VERIFICATION SUMMARY
      ==============================
      ✅ rich: OK
      ✅ markdown-it-py: OK
      ✅ Pygments: OK
      ✅ mdurl: OK

   ✅ Bubble created successfully

🚀 Re-running with omnipkg auto-heal...

🌀 omnipkg auto-heal: Wrapping script with loaders for ['rich==13.4.2']...
------------------------------------------------------------
🐍 [omnipkg loader] Running in Python 3.11 context
🚀 Fast-activating rich==13.4.2 ...
   📂 Searching for bubble: .../rich-13.4.2
   ✅ Bubble found
   📊 Bubble: 4 packages, 0 conflicts
   🧹 Purging 4 module(s) from memory...
   ⚡ HEALED in 20,892.4 μs
   ✅ Bubble activated

🚀 Running target script inside the combined bubble + local context...
✅ Successfully imported rich version: 13.4.2
This script is running with the correct, older version of rich!

🌀 omnipkg loader: Deactivating rich==13.4.2...
   ✅ Environment restored.
   ⏱️  Swap Time: 43,535.037 μs

------------------------------------------------------------
✅ Script completed successfully inside omnipkg bubble.

======================================================================
🚀 PERFORMANCE COMPARISON: UV vs OMNIPKG
======================================================================
UV Failed Run      :    112.968 ms  (    112,968,072 ns)
omnipkg Activation :     20.892 ms  (     20,892,381 ns)
----------------------------------------------------------------------
🎯 omnipkg is         5.41x FASTER than UV!
💥 That's           440.71% improvement!
======================================================================

Key Features Demonstrated

1. Intelligent Error Analysis

OmniPkg doesn’t just fail—it analyzes the error:

  • Captures the full stack trace
  • Identifies version assertions in the code
  • Extracts the exact package requirements
  • Compiles a comprehensive healing plan

2. Bubble Stability Protection

Before modifying the main environment, OmniPkg:

  • Creates a pre-install snapshot
  • Stages the installation in isolation
  • Runs smart import verification
  • Only commits if all checks pass
  • Restores stable versions to main env

3. Overlay Mode Activation

The loader uses overlay mode for maximum compatibility:

🧬 OVERLAY mode
- Bubble paths prepended to sys.path
- Main environment remains active
- Compatible dependencies shared
- 🔗 Linked 22 compatible dependencies to bubble

This means: - Only rich==13.4.2 comes from the bubble - Dependencies like pygments are shared if compatible - No unnecessary duplication - Faster activation times

4. Memory Management

OmniPkg ensures clean module state:

🧹 Purging 4 module(s) from memory...
   - Removes stale imports
   - Prevents module conflicts
   - Ensures fresh imports from bubble

Then on cleanup:

Purging 49 modules for 'rich'
🔍 Scanning for remaining cloaks...
✅ Verified: No orphaned cloaks for rich

5. Performance Metrics

The demo includes a direct comparison with UV:

Tool Activation Time Speed Improvement
UV 112.97 ms Baseline
OmniPkg 20.89 ms 5.41x faster

OmniPkg achieves this through: - Pre-built bubble manifests - Smart caching of package metadata - Optimized sys.path manipulation - Minimal module reloading

How It Works

Stage 1: Initial Failure

  1. Script runs with system packages
  2. Version assertion fails
  3. Exit code 1 triggers healing logic

Stage 2: Analysis

  1. Error log captured and parsed
  2. Package requirements extracted via regex
  3. Healing plan compiled with dependencies

Stage 3: Bubble Creation

  1. Check if bubble already exists
  2. If not, create via standard install flow
  3. Stage installation in temp directory
  4. Verify imports work correctly
  5. Move to permanent bubble location
  6. Register in manifest database

Stage 4: Re-execution

  1. Generate wrapper script with loader
  2. Activate bubble in overlay mode
  3. Run original script inside bubble
  4. Capture output and exit code
  5. Deactivate bubble and restore environment

Real-World Applications

This healing mechanism enables several powerful workflows:

  1. Legacy Code Resurrection: Run old scripts without modifying them
  2. Reproducible Research: Ensure papers’ code runs with exact versions
  3. CI/CD Flexibility: Test across multiple package versions automatically
  4. Dependency Hell Resolution: Try different versions until one works
  5. Version Bisection: Automatically find which version introduced a bug

Comparison to Traditional Approaches

Without OmniPkg:

# Traditional approach
python script.py
# AssertionError: wrong version!

# Manual fix
pip install rich==13.4.2
python script.py
# Success, but main environment now polluted

# Cleanup
pip install rich==13.7.1
# Hope nothing broke

With OmniPkg:

# Just run it - healing happens automatically
omnipkg run script.py
# ✅ Success with zero manual intervention

Common Use Cases

Case 1: Testing Multiple Versions

# Test script against many rich versions
for version in ["13.4.2", "13.5.3", "13.7.1"]:
    assert rich.__version__ == version
    # OmniPkg heals each time automatically

Case 2: Gradual Upgrades

# Old code expects old dependencies
import old_library  # needs numpy<2

# New code uses modern stack
import tensorflow  # needs numpy>=2

# OmniPkg isolates automatically

Case 3: Reproducible Science

# Paper published with exact versions
assert numpy.__version__ == "1.24.3"
assert scipy.__version__ == "1.10.1"

# Readers can reproduce results years later
# OmniPkg creates historical bubbles on-demand

Performance Characteristics

From the live execution:

  • Failure detection: < 1ms
  • Error analysis: ~5ms
  • Bubble creation: ~2 seconds (first time only)
  • Bubble activation: ~21ms (subsequent runs)
  • Total overhead: ~43ms for full cycle

The first run pays a one-time cost to create the bubble. All future runs activate it in microseconds.

Limitations & Caveats

  1. Source Code Analysis: Healing relies on parsing assertion errors and import statements—complex dynamic imports may not be detected
  2. Bubble Storage: Each version consumes disk space (typically 1-50 MB per package)
  3. System Packages: Cannot heal packages requiring system libraries without proper stubs
  4. Network Required: First-time bubble creation needs PyPI access

Best Practices

  1. Use Version Pins: Explicit assertions like assert pkg.__version__ == "1.2.3" work best
  2. Import Early: Put version checks at module top for fast failure
  3. Document Dependencies: Comment why specific versions are needed
  4. Test Healing: Verify your scripts heal correctly in CI
  5. Monitor Bubbles: Run omnipkg info to see bubble disk usage

Future Enhancements

Planned improvements for script healing:

  • ML-based prediction: Predict likely version fixes without trial runs
  • Conflict resolution: Auto-resolve version conflicts in healing plan
  • Cloud bubbles: Share bubbles across machines via remote cache
  • Incremental healing: Fix one package at a time for faster convergence