Metadata-Version: 2.4
Name: self-heal-runtime
Version: 0.2.0
Summary: Open-source self-healing runtime for Python: RAG + OpenAI-compatible LLM + unified diff patches
Author: self-heal contributors
License: MIT
Keywords: llm,self-heal,debugging,openai,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: unidiff>=0.7.5
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pathspec>=0.12.0
Provides-Extra: notifications
Requires-Dist: sentry-sdk>=2.0.0; extra == "notifications"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Dynamic: license-file

# self-heal

[![PyPI version](https://img.shields.io/pypi/v/self-heal-runtime?style=flat)](https://pypi.org/project/self-heal-runtime/) [![Python](https://img.shields.io/badge/python-3.11%2B-blue?style=flat)](https://pypi.org/project/self-heal-runtime/) [![License](https://img.shields.io/github/license/universe-coder/self-heal?style=flat)](https://github.com/universe-coder/self-heal/blob/main/LICENSE) [![Last commit](https://img.shields.io/github/last-commit/universe-coder/self-heal?style=flat)](https://github.com/universe-coder/self-heal/commits/main) [![Open issues](https://img.shields.io/github/issues/universe-coder/self-heal?style=flat)](https://github.com/universe-coder/self-heal/issues) [![Forks](https://img.shields.io/github/forks/universe-coder/self-heal?style=flat)](https://github.com/universe-coder/self-heal/network/members) [![Stars](https://img.shields.io/github/stars/universe-coder/self-heal?style=flat)](https://github.com/universe-coder/self-heal/stargazers)

Open-source **self-healing** helper for Python: index your repo (AST chunks + OpenAI-compatible **embeddings**), capture tracebacks (in-process hook / decorator or supervised subprocess), ask an **OpenAI-compatible** chat model for a **unified diff**, validate paths, optionally **apply** via `git apply` / `patch`, and **audit** proposals.

- **Python** ≥ 3.11  
- **Protocol**: OpenAI-compatible HTTP APIs (`base_url` + chat completions + embeddings)  
- **Safety**: no `exec` of model output; patches are unified diffs only; allow/deny paths; secrets masked in captured locals; API keys from env only.

## Install

```bash
pip install self-heal-runtime
# optional: notifications integrations (Sentry SDK extra)
pip install "self-heal-runtime[notifications]"
```

Set `OPENAI_API_KEY` (or the env name from `[llm].api_key_env` in `.self-heal.toml`).

## Quickstart

1. **Init config** in your project root:

   ```bash
   self-heal init
   ```

2. **Index** code (needs embeddings endpoint):

   ```bash
   self-heal index
   ```

3. **Supervised run** (captures stderr tracebacks and can propose/heal):

   ```bash
   PYTHONPATH=. self-heal run -- python -m examples.broken_app.main
   ```

   With auto-apply (still validates paths; use with care):

   ```bash
   PYTHONPATH=. self-heal run --auto --no-dry-run -- python -m examples.broken_app.main
   ```

4. **Offline heal** from a traceback file:

   ```bash
   python -m examples.broken_app.main 2> tb.txt   # or copy a traceback
   self-heal heal --tb tb.txt
   ```

5. **Library usage** (in-process):

   ```python
   from pathlib import Path
   from self_heal import install, self_heal

   install(project_root=Path(__file__).resolve().parents[1])

   @self_heal(mode="suggest")
   def risky():
       ...
   ```

## Configuration

See [.self-heal.example.toml](.self-heal.example.toml) or run `self-heal init` (template ships in `self_heal/templates/`).

Key sections: `[llm]`, `[index]`, `[heal]`, `[supervisor]`, `[notifications]`.

## Notifications

Optional outbound reports when an error is captured and when a heal is proposed or applied. Enable `[notifications].enabled = true`, then turn on individual channels under `[notifications.telegram]`, `[notifications.slack]`, `[notifications.webhook]`, or `[notifications.sentry]`. Secrets stay in environment variables (e.g. `TELEGRAM_BOT_TOKEN`, `SLACK_WEBHOOK_URL`, `SELF_HEAL_WEBHOOK_URL`, `SENTRY_DSN`).

- **Payload**: By default, diffs are omitted and tracebacks are truncated (`include_diff`, `include_traceback`, `max_traceback_lines`).
- **Webhook**: JSON POST with optional HMAC (`X-SelfHeal-Signature: sha256=…`, `X-SelfHeal-Timestamp`). Only `https` targets are allowed unless `allow_insecure = true`.
- **Sentry**: Install extras: `pip install 'self-heal-runtime[notifications]'` (pulls in `sentry-sdk`).

Delivery is asynchronous; successes and failures are also written to `.self-heal/audit.jsonl` as `notification_sent` / `notification_failed`.

## Security

- Model output is **never executed** as Python; only **unified diffs** are accepted.
- Patches are checked against `allowed_paths` / `forbidden_paths`; defaults block `.git/`, `.env*`, secrets globs, `pyproject.toml`.
- Locals and tracebacks are **sanitized** before being sent to the model.
- Prefer **`dry-run`** (default in CLI) until you trust the workflow; use `--no-dry-run` with `--auto` only when appropriate.

## Limitations (MVP)

- Patch application: prefers **`git apply`** inside a git repo; otherwise tries system **`patch`**, then a small Python hunk applier.
- Supervised mode expects **Python-style** tracebacks on stderr.
- Embedding dimension is assumed compatible with Chroma’s stored vectors (default client setup targets OpenAI `text-embedding-3-small`-sized vectors).

## License

MIT — see [LICENSE](LICENSE).
