self-heal-runtime 0.2.0

Open-source self-healing runtime for Python: RAG + OpenAI-compatible LLM + unified diff patches

self-heal

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

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:

   self-heal init
   

2. Index code (needs embeddings endpoint):

   self-heal index
   

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

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

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

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

4. Offline heal from a traceback file:

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

5. Library usage (in-process):

   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 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.