Metadata-Version: 2.4
Name: healix-ai
Version: 0.1.0
Summary: An autonomous self-healing agent for Playwright tests with AI-powered Root Cause Analysis.
Author: Kunaal Thanik
License-Expression: MIT
Project-URL: Homepage, https://github.com/kunaal-ai/healix
Project-URL: Repository, https://github.com/kunaal-ai/healix
Project-URL: Issues, https://github.com/kunaal-ai/healix/issues
Keywords: playwright,testing,self-healing,automation,ai,selenium,qa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Framework :: Pytest
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# Healix

**Healix** is an intelligent web automation agent that self-heals broken selectors and adapts to dynamic web pages using AI-powered DOM analysis.

## 🎯 The Problem

Web automation is fragile. Selectors break when:
- Developers change class names
- DOM structure shifts
- Content loads dynamically
- A/B tests alter page layouts

## 🚀 The Solution

Healix uses an **agentic loop** to automatically detect and fix selector failures:

1. **Observe** - Analyze the current page state and DOM
2. **Reason** - Use AI to determine the correct selector/action
3. **Act** - Execute the corrected action
4. **Verify** - Confirm the action succeeded
5. **Learn** - Cache successful fixes for future use

### Operational Workflow

```mermaid
flowchart TD
    subgraph Execution["Test Execution Layer"]
        Start(["💥 Test Failure Detected"])
        RetryCache(["♻️ Re-run with Cache"])
        RetryAI(["⚡ Re-run with AI Fix"])
    end

    subgraph Persistence["Persistence Layer"]
        CheckCache{"🧠 Check Cache"}
        ApplyCache["📥 Apply Cached Selector"]
        UpdateCache[("💾 Update Cache")]
    end

    subgraph Intelligence["AI Intelligence Layer"]
        CleanDOM["🧼 DOM Scrubbing & Minification"]
        AskOllama["🤖 Query Ollama (qwen2.5-coder)"]
        Analyze["📊 Confidence Scoring"]
    end

    subgraph Feedback["Reporting Layer"]
        Success(["✅ Healing Successful"])
        Manual(["⚠️ Manual Review Required"])
        Proposal[("📝 Log Code Proposal")]
    end

    %% Flow Logic
    Start --> CheckCache
    
    CheckCache -- "Hit" --> ApplyCache
    ApplyCache --> RetryCache
    
    CheckCache -- "Miss" --> CleanDOM
    
    RetryCache -- "Success" --> Success
    RetryCache -- "Fail" --> CleanDOM
    
    CleanDOM --> AskOllama
    AskOllama --> Analyze
    
    Analyze -- "High Confidence" --> RetryAI
    Analyze -- "Low Confidence" --> Manual
    
    RetryAI -- "Success" --> UpdateCache
    UpdateCache --> Success
    
    RetryAI -- "Fail" --> Manual
    
    Success --> Proposal
    Manual --> Proposal
    Proposal --> End(["🏁 Action Complete"])

    %% Premium Styling
    classDef startEnd fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#1e293b
    classDef intelligence fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
    classDef persistence fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b
    classDef execution fill:#fff7ed,stroke:#f59e0b,stroke-width:2px,color:#7c2d12
    classDef feedback fill:#faf5ff,stroke:#a855f7,stroke-width:2px,color:#581c87
    classDef decision fill:#ffffff,stroke:#334155,stroke-width:2px,stroke-dasharray: 5 5

    class Start,End startEnd
    class CleanDOM,AskOllama,Analyze intelligence
    class CheckCache,ApplyCache,UpdateCache persistence
    class RetryCache,RetryAI execution
    class Success,Manual,Proposal,GenerateFeedback feedback
    class CheckCache,Analyze decision
```

## 🏗️ Architecture

```
healix/
├── .github/                   # CI/CD workflows
│   └── workflows/
│       └── main.yml           # Automated test runs
├── src/                       # Source code for the library
│   └── healix/
│       ├── __init__.py        # Makes it a package
│       ├── engine.py          # The core Healix class
│       └── utilities/         # Helper functions
│           ├── __init__.py
│           └── dom_scrubber.py # BeautifulSoup logic
├── tests/                     # Test suites to verify Healix
│   ├── integration/
│   │   └── test_login.py      # Demo test case
│   └── unit/
│       └── test_engine.py     # Testing the AI logic/cleaner
├── data/                      # Local data storage
│   └── healix_cache.json      # Persistent cache for fixes
├── docker/                    # Containerized environments
│   └── Dockerfile
├── .gitignore                 # Ignore __pycache__ and local config
├── requirements.txt           # Dependencies
└── README.md                  # This file
```

## 🛠️ Installation

```bash
# Clone the repository
git clone <repository-url>
cd healix

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium
```

## 🚦 Quick Start

```python
import asyncio
from playwright.async_api import async_playwright
from healix.engine import smart_click

async def test_healix_agent():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=False)
        page = await browser.new_page()
        
        await page.goto("https://example.com")
        
        # Healix will automatically fix broken selectors
        await smart_click(page, "#broken-selector")
        
        await browser.close()

if __name__ == "__main__":
    asyncio.run(test_healix_agent())
```

## 🧠 How It Works

### DOM Cleaning & Privacy
- Strips scripts, styles, and heavy elements to save tokens
- Masks PII (Personally Identifiable Information) for privacy
- Focuses on actionable elements (buttons, links, inputs)

### AI-Powered Reasoning
- Uses local LLM (Ollama) for selector analysis
- Considers both technical errors and visible page state
- Returns confidence scores and explanations

### Persistent Learning
- Caches successful fixes in `healix_cache.json`
- Gets faster over time as it learns common patterns
- Maintains context across test runs

## 🔧 Configuration

Healix uses Ollama for local AI inference:

```python
from healix.engine import Healix

# Default model: qwen2.5-coder:7b
healix = Healix(model="your-preferred-model")
```

Make sure Ollama is running:
```bash
ollama serve
```

## 🧪 Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/healix --cov-report=html

# Run integration tests (requires browser)
pytest tests/integration/
```

## 🐳 Docker Support

```bash
# Build the container
docker build -t healix .

# Run tests in container
docker run healix
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## 📄 License

[Add your license here]

## 🔮 Roadmap

- [ ] Support for more AI models (OpenAI, Anthropic)
- [ ] Visual regression testing
- [ ] Multi-browser support expansion
- [ ] Performance optimization for large-scale testing
- [ ] Plugin system for custom healing strategies
