Metadata-Version: 2.4
Name: healspace
Version: 0.5.0
Summary: HealSpace — Guardian AI for Hugging Face Spaces
Author: Onyxl · TeraBites
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/healspace/
Project-URL: Repository, https://github.com/MegaBites-AI/HealSpace
Keywords: huggingface,spaces,gradio,error,healing,guardian,runtime,auto-fix,ai,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: gradio>=4.0.0

# HealSpace

[![PyPI](https://img.shields.io/pypi/v/healspace?color=blue&label=PyPI)](https://pypi.org/project/healspace/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/healspace)](https://pypi.org/project/healspace/)

**HealSpace** is a guardian AI package for Hugging Face Spaces.

It automatically detects backend errors, attempts auto-fixes, and injects a live healing panel into your Gradio app — all in one line of code.

---

## ✨ Features

- **Auto-detects** 9 common Space error types: missing deps, port conflicts, GPU OOM, Gradio mismatches, disk quota, startup timeouts, syntax errors, auth errors, and generic RuntimeErrors
- **Auto-fixes** what it can: installs missing packages at runtime, clears CUDA cache, frees locked ports
- **Gradio UI panel** — paste any traceback and get a structured report + fix steps
- **"Error this Space" demo button** — trigger a live healing demo in your app
- **Background monitor** — watches stderr continuously and heals without intervention
- **Lineage seal** — `🛡️ Protected by HealSpace` footer on every protected app

---

## 📦 Installation

Add to your Space's `requirements.txt`:

```
healspace
```

Or install locally:

```bash
pip install healspace
```

---

## 🚀 Quickstart

### Minimal — one line in `app.py`

```python
import gradio as gr
from healspace import heal

with gr.Blocks() as demo:
    gr.Markdown("# My Space")
    # ... your UI ...

heal(demo)          # inject guardian panel + start monitor
demo.launch()
```

That's it. HealSpace will:
1. Add a collapsible **🛡️ HealSpace** accordion to your app
2. Start a background monitor watching for errors
3. Stamp the lineage seal in the footer

---

### Diagnose a log snippet

```python
from healspace import diagnose

log = """
Traceback (most recent call last):
  File "app.py", line 3, in <module>
    import mylib
ModuleNotFoundError: No module named 'mylib'
"""

reports = diagnose(log)
for r in reports:
    print(r)
```

Output:
```
[HealSpace] ERROR: Missing dependency: mylib
  The package 'mylib' is not installed in this Space.
  Suggested fixes:
    1. Add 'mylib' to your requirements.txt
    2. Trigger a factory reboot via Space Settings → Factory reboot
    3. If it's a system package, add it to packages.txt instead
```

---

### Auto-fix

```python
from healspace import diagnose, fix

reports = diagnose(open("space.log").read())
for r in reports:
    fix(r)       # attempts auto-fix; prints steps if no auto-fix available
```

---

### Full control

```python
from healspace import HealSpace

hs = HealSpace(auto_fix=True, verbose=True)

# Start background stderr monitor
hs.watch()

# Inject UI into your Gradio app
hs.protect(demo)

demo.launch()
```

---

## 🩺 Detected Error Types

| Error type | Trigger | Auto-fix |
|---|---|---|
| `missing_dep` | `ModuleNotFoundError` | ✅ pip-installs at runtime |
| `port_conflict` | `Address already in use` | ✅ frees port 7860 |
| `gpu_oom` | `CUDA out of memory` | ✅ clears CUDA cache |
| `gradio_mismatch` | Gradio `AttributeError` / bad import | ❌ suggests pinning version |
| `disk_full` | `No space left on device` | ❌ suggests cache cleanup |
| `startup_timeout` | Space timeout errors | ❌ suggests lazy loading |
| `syntax_error` | `SyntaxError` / `IndentationError` | ❌ points to exact file |
| `auth_error` | 401/403 / `RepositoryNotFoundError` | ❌ guides to HF_TOKEN secret |
| `runtime_error` | Generic `RuntimeError` | ❌ suggests restart + debug |

---

## 🗂 Project Structure

```
healspace/
├── healspace/
│   ├── __init__.py   ← public API: heal, diagnose, fix, HealSpace
│   ├── core.py       ← HealSpace class + auto-fixers + Gradio injection
│   └── errors.py     ← KnownError pattern registry + ErrorReport dataclass
└── pyproject.toml
```

---

## 📋 Changelog

### v0.2.0
- **Complete rewrite** — v0.1.0 was an empty package (no source files)
- `HealSpace` class with `diagnose`, `fix`, `heal`, `protect`, `watch`
- 9 known error patterns with structured `ErrorReport` output
- Auto-fixers for missing deps, port conflicts, GPU OOM
- Gradio UI panel injection with "Diagnose & Heal" + "Error this Space" buttons
- Background stderr monitor thread
- `heal()`, `diagnose()`, `fix()` convenience functions at module level

### v0.1.0
- Initial (incomplete) release

---

## 📄 License

Apache 2.0 — see LICENSE.
