healspace 0.3.0

HealSpace — Guardian AI for Hugging Face Spaces

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:

pip install healspace

---

🚀 Quickstart

Minimal — one line in app.py

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

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

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

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.