Metadata-Version: 2.4
Name: healspace
Version: 0.6.2
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

**Automated AI runtime guardian for Hugging Face Spaces.**

HealSpace monitors your Space for runtime errors, attempts automatic fixes, and alerts you — so your Space stays alive even when you're not watching.

---

## Install

```bash
pip install healspace
```

---

## Quickstart

```python
import healspace as HS

HS.protect(demo)
demo.launch()
```

Or the one-liner shorthand:

```python
import healspace as HS
HS(demo)
demo.launch()
```

---

## Configuration

Call `HS.configure()` before `HS.protect()` to customise behaviour.
All commands support inline `# comments` and are case-insensitive.

```python
import healspace as HS

HS.configure(
    "disable HS_promo\n"
    "inspect every 30 sec\n"
    "set fix quota to 100\n"
    "inform dev when retry count 10\n"
    'set inform email to "you@gmail.com"\n'
    "retry limit 50\n"
)

HS.protect(demo)
demo.launch()
```

---

## Command Reference

### `disable HS_promo`
Removes the *Protected by HealSpace* footer from your Gradio UI.
Enabled by default — use this if it conflicts with your layout.

```
disable HS_promo
```

---

### `inspect every N sec / min / hrs`
Starts a background polling loop that **actively** checks for errors on a schedule.

Without this, HealSpace only reacts when an error surfaces on stderr.
With this, it proactively scans at every interval.

```
inspect every 30 sec
inspect every 5 min
inspect every 1 hrs
```

---

### `set fix quota to N`
Caps the number of automatic fixes HealSpace will apply this session.
After the quota is reached HealSpace continues to detect and report errors,
but stops applying fixes.

```
set fix quota to 100
```

Without this, HealSpace fixes indefinitely.

---

### `inform dev when retry count N`
Sends a **Hugging Face inbox** notification to your account once the total
number of errors in this session reaches N.

```
inform dev when retry count 10
```

Requires `HF_TOKEN` to be set as a Space secret (Settings → Variables and secrets).

---

### `set inform email to "address"`
Sends an **email alert** to any address when errors accumulate.

```
set inform email to "you@gmail.com"
set inform email to "team@company.io"
```

Works with **any email provider** — Gmail, Outlook, Yahoo, iCloud, custom domains.
Emails arrive from `healspace@proton.me`.

Requires **one** Space secret — no password, no SMTP config:

| Secret | Where to get it |
|---|---|
| `HS_RESEND_KEY` | [resend.com](https://resend.com) — free, 3 000 emails/month |
| `HS_SENDGRID_KEY` | [sendgrid.com](https://sendgrid.com) — free, 100 emails/day (fallback) |

---

### `retry limit N`
**Hard stop.** After N total errors HealSpace prints a final warning,
sends one last email + HF inbox message (if configured), then raises
a `RuntimeError` that stops the Space process entirely.

```
retry limit 50
```

Use this when you want a broken Space to fail loudly and visibly
rather than silently loop forever.

---

## What HealSpace Fixes Automatically

| Error type | What it does |
|---|---|
| Missing dependency | `pip install` the missing package at runtime |
| Port conflict | Frees port 7860 so Gradio can restart |
| GPU out-of-memory | Clears the CUDA cache |
| And more… | Covers 9 known HF Space error patterns |

---

## Space Secrets Reference

| Secret | Required for |
|---|---|
| `HF_TOKEN` | `inform dev when retry count N` |
| `HS_RESEND_KEY` | `set inform email to` (preferred) |
| `HS_SENDGRID_KEY` | `set inform email to` (fallback) |

Add secrets under **Space Settings → Variables and secrets**.

---

## Mini AI — Code Healer

HealSpace also ships a context-aware code repair engine that reads your
codebase style (indentation, quotes, naming, type hints) and writes fixes
that match it.

```python
from healspace import CodeHealer

healer = CodeHealer()
patch  = healer.heal_traceback(traceback_text, source_file="app.py")
print(patch)   # shows a diff
patch.apply()  # writes the fix back to the file
```

---

## Full API

```python
import healspace as HS

HS.fix_quota = 10        # set quota via attribute
HS.protect(demo)         # inject UI + start monitoring
HS.watch()               # start background stderr monitor only
HS.heal(demo)            # one-call: monitor + protect
HS.configure("...")      # apply DSL config string
HS.fix(report)           # manually attempt a fix for an ErrorReport
```

---

## License

Apache 2.0 — [pypi.org/project/healspace](https://pypi.org/project/healspace/)
