self-heal-llm 0.0.2__tar.gz

self_heal_llm-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest -v

self_heal_llm-0.0.2/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    # OIDC trusted publishing — no API tokens required.
+    # Configure a pending publisher at:
+    # https://pypi.org/manage/account/publishing/
+    #   Project:   self-heal
+    #   Owner:     Johin2
+    #   Repo:      self-heal
+    #   Workflow:  publish.yml
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

self_heal_llm-0.0.2/.gitignore

@@ -0,0 +1,79 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# uv
+.uv/
+uv.lock
+
+# Ruff
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Type checkers
+.mypy_cache/
+.pyright/
+.pytype/

self_heal_llm-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johin Johny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

self_heal_llm-0.0.2/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: self-heal-llm
+Version: 0.0.2
+Summary: Automatic repair for failing Python code, powered by any LLM.
+Project-URL: Homepage, https://github.com/Johin2/self-heal
+Project-URL: Repository, https://github.com/Johin2/self-heal
+Project-URL: Issues, https://github.com/Johin2/self-heal/issues
+Author-email: Johin Johny <anandowais@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Johin Johny
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent,ai,claude,code-repair,gemini,litellm,llm,openai,repair,self-healing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40.0; extra == 'all'
+Requires-Dist: google-genai>=0.3.0; extra == 'all'
+Requires-Dist: litellm>=1.0.0; extra == 'all'
+Requires-Dist: openai>=1.40.0; extra == 'all'
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.40.0; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40.0; extra == 'dev'
+Requires-Dist: google-genai>=0.3.0; extra == 'dev'
+Requires-Dist: litellm>=1.0.0; extra == 'dev'
+Requires-Dist: openai>=1.40.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.3.0; extra == 'gemini'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0.0; extra == 'litellm'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# self-heal
+
+[![CI](https://github.com/Johin2/self-heal/actions/workflows/ci.yml/badge.svg)](https://github.com/Johin2/self-heal/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/self-heal-llm.svg)](https://pypi.org/project/self-heal-llm/)
+[![Python](https://img.shields.io/pypi/pyversions/self-heal-llm.svg)](https://pypi.org/project/self-heal-llm/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> Automatic repair for failing Python code, powered by any LLM.
+
+When a function fails, `self-heal` catches the exception, analyzes it with an LLM, proposes a repaired version, and retries. One decorator. Works with Claude, OpenAI, Gemini, and 100+ other providers.
+
+```python
+from self_heal import repair
+
+@repair(max_attempts=3)
+def extract_price(text: str) -> float:
+    # Naive: only handles "$X.YY"
+    return float(text.replace("$", ""))
+
+print(extract_price("$12.99"))    # 12.99
+print(extract_price("₹1,299"))    # 1299.0  (repaired)
+print(extract_price("€5,49"))     # 5.49    (repaired)
+```
+
+## Install
+
+`self-heal` ships with a Protocol and several optional adapters. Install the adapter(s) you want:
+
+```bash
+pip install 'self-heal-llm[claude]'    # Anthropic Claude (default)
+pip install 'self-heal-llm[openai]'    # OpenAI + OpenAI-compatible endpoints
+pip install 'self-heal-llm[gemini]'    # Google Gemini
+pip install 'self-heal-llm[litellm]'   # 100+ providers via LiteLLM
+pip install 'self-heal-llm[all]'       # everything
+```
+
+> PyPI distribution name is `self-heal-llm` (the short name `self-heal` was blocked by PyPI's similarity check with an unrelated package). The Python import stays `from self_heal import ...`.
+
+## Provider support
+
+| Adapter | Covers |
+|---|---|
+| `ClaudeProposer` | Anthropic Claude (native SDK) |
+| `OpenAIProposer` | OpenAI + **any OpenAI-compatible endpoint** (OpenRouter, Together, Groq, Fireworks, Anyscale, Perplexity, xAI, DeepSeek, Azure, Ollama, LM Studio, vLLM, llama.cpp server, ...) |
+| `GeminiProposer` | Google Gemini (native SDK) |
+| `LiteLLMProposer` | 100+ providers via LiteLLM (Bedrock, Vertex, Cohere, Mistral, ...) |
+
+## Using different providers
+
+**Claude (default):**
+```python
+from self_heal import repair
+
+@repair()  # uses ClaudeProposer under the hood
+def my_fn(...): ...
+```
+
+**OpenAI:**
+```python
+from self_heal import repair
+from self_heal.llm import OpenAIProposer
+
+@repair(proposer=OpenAIProposer(model="gpt-5"))
+def my_fn(...): ...
+```
+
+**Gemini:**
+```python
+from self_heal import repair
+from self_heal.llm import GeminiProposer
+
+@repair(proposer=GeminiProposer(model="gemini-2.5-pro"))
+def my_fn(...): ...
+```
+
+**Any OpenAI-compatible endpoint (OpenRouter, Groq, Ollama, ...):**
+```python
+from self_heal.llm import OpenAIProposer
+
+# OpenRouter — hundreds of models through one key
+proposer = OpenAIProposer(
+    model="google/gemini-2.5-pro",
+    base_url="https://openrouter.ai/api/v1",
+)
+
+# Groq — fast inference
+proposer = OpenAIProposer(
+    model="llama-3.3-70b-versatile",
+    base_url="https://api.groq.com/openai/v1",
+)
+
+# Local Ollama
+proposer = OpenAIProposer(
+    model="llama3.3",
+    base_url="http://localhost:11434/v1",
+    api_key="ollama",
+)
+```
+
+**LiteLLM catch-all (100+ providers):**
+```python
+from self_heal.llm import LiteLLMProposer
+
+proposer = LiteLLMProposer(model="anthropic/claude-sonnet-4-6")
+proposer = LiteLLMProposer(model="bedrock/anthropic.claude-3-5-sonnet")
+proposer = LiteLLMProposer(model="vertex_ai/gemini-2.5-pro")
+proposer = LiteLLMProposer(model="cohere/command-r-plus")
+```
+
+## Why this exists
+
+AI coding agents fail on a lot of real tasks. The industry's current answer is "retry and hope." That's not a strategy.
+
+`self-heal` treats repair as a first-class primitive: diagnose the failure, propose a targeted fix, verify, retry. A thin library you can wrap around any Python function or agent tool.
+
+Built on ongoing code-repair research (RepairBench, NeurIPS 2026).
+
+## How it works
+
+1. **Catch** the exception and capture inputs, traceback, and failure type.
+2. **Classify** the failure (validation, exception, assertion).
+3. **Propose** a repaired function via LLM with a failure-aware prompt.
+4. **Recompile** the proposed function into the running process.
+5. **Retry** with the same inputs.
+
+All within a single decorator boundary.
+
+## API
+
+**Decorator:**
+```python
+from self_heal import repair
+
+@repair(max_attempts=3, model="claude-sonnet-4-6", verbose=True)
+def my_tool(x): ...
+
+my_tool(42)
+my_tool.last_repair  # -> RepairResult with full attempt history
+```
+
+**Loop (for advanced use):**
+```python
+from self_heal import RepairLoop
+
+loop = RepairLoop(max_attempts=5, verbose=True)
+result = loop.run(my_tool, args=(42,))
+if result.succeeded:
+    print(result.final_value)
+else:
+    print(result.attempts[-1].failure.traceback)
+```
+
+**Custom proposer:**
+```python
+from self_heal.llm import LLMProposer
+
+class MyProposer:
+    def propose(self, system: str, user: str) -> str:
+        # ... your logic ...
+        return "def my_tool(x): return x * 2"
+```
+
+## Safety
+
+`self-heal` executes LLM-generated code via `exec()` in the same process. Same trust boundary as any LLM-in-the-loop system: do not run against untrusted inputs without a sandbox. Sandboxed execution is on the roadmap.
+
+## Roadmap
+
+- [x] v0.0.1: core repair loop + decorator + Claude backend
+- [x] v0.0.2: OpenAI, Gemini, LiteLLM adapters — works with any LLM
+- [ ] v0.1: user-provided verifiers (beyond exception-catching)
+- [ ] v0.2: telemetry + before/after success metrics
+- [ ] v0.3: async support
+- [ ] v0.4: sandboxed execution
+- [ ] v0.5: repair persistence (learn from past fixes)
+- [ ] v1.0: NeurIPS 2026 paper co-release
+
+## Development
+
+```bash
+git clone https://github.com/Johin2/self-heal.git
+cd self-heal
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"   # Windows
+# .venv/bin/pip install -e ".[dev]"     # macOS/Linux
+pytest
+```
+
+## License
+
+MIT

self_heal_llm-0.0.2/README.md

@@ -0,0 +1,191 @@
+# self-heal
+
+[![CI](https://github.com/Johin2/self-heal/actions/workflows/ci.yml/badge.svg)](https://github.com/Johin2/self-heal/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/self-heal-llm.svg)](https://pypi.org/project/self-heal-llm/)
+[![Python](https://img.shields.io/pypi/pyversions/self-heal-llm.svg)](https://pypi.org/project/self-heal-llm/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> Automatic repair for failing Python code, powered by any LLM.
+
+When a function fails, `self-heal` catches the exception, analyzes it with an LLM, proposes a repaired version, and retries. One decorator. Works with Claude, OpenAI, Gemini, and 100+ other providers.
+
+```python
+from self_heal import repair
+
+@repair(max_attempts=3)
+def extract_price(text: str) -> float:
+    # Naive: only handles "$X.YY"
+    return float(text.replace("$", ""))
+
+print(extract_price("$12.99"))    # 12.99
+print(extract_price("₹1,299"))    # 1299.0  (repaired)
+print(extract_price("€5,49"))     # 5.49    (repaired)
+```
+
+## Install
+
+`self-heal` ships with a Protocol and several optional adapters. Install the adapter(s) you want:
+
+```bash
+pip install 'self-heal-llm[claude]'    # Anthropic Claude (default)
+pip install 'self-heal-llm[openai]'    # OpenAI + OpenAI-compatible endpoints
+pip install 'self-heal-llm[gemini]'    # Google Gemini
+pip install 'self-heal-llm[litellm]'   # 100+ providers via LiteLLM
+pip install 'self-heal-llm[all]'       # everything
+```
+
+> PyPI distribution name is `self-heal-llm` (the short name `self-heal` was blocked by PyPI's similarity check with an unrelated package). The Python import stays `from self_heal import ...`.
+
+## Provider support
+
+| Adapter | Covers |
+|---|---|
+| `ClaudeProposer` | Anthropic Claude (native SDK) |
+| `OpenAIProposer` | OpenAI + **any OpenAI-compatible endpoint** (OpenRouter, Together, Groq, Fireworks, Anyscale, Perplexity, xAI, DeepSeek, Azure, Ollama, LM Studio, vLLM, llama.cpp server, ...) |
+| `GeminiProposer` | Google Gemini (native SDK) |
+| `LiteLLMProposer` | 100+ providers via LiteLLM (Bedrock, Vertex, Cohere, Mistral, ...) |
+
+## Using different providers
+
+**Claude (default):**
+```python
+from self_heal import repair
+
+@repair()  # uses ClaudeProposer under the hood
+def my_fn(...): ...
+```
+
+**OpenAI:**
+```python
+from self_heal import repair
+from self_heal.llm import OpenAIProposer
+
+@repair(proposer=OpenAIProposer(model="gpt-5"))
+def my_fn(...): ...
+```
+
+**Gemini:**
+```python
+from self_heal import repair
+from self_heal.llm import GeminiProposer
+
+@repair(proposer=GeminiProposer(model="gemini-2.5-pro"))
+def my_fn(...): ...
+```
+
+**Any OpenAI-compatible endpoint (OpenRouter, Groq, Ollama, ...):**
+```python
+from self_heal.llm import OpenAIProposer
+
+# OpenRouter — hundreds of models through one key
+proposer = OpenAIProposer(
+    model="google/gemini-2.5-pro",
+    base_url="https://openrouter.ai/api/v1",
+)
+
+# Groq — fast inference
+proposer = OpenAIProposer(
+    model="llama-3.3-70b-versatile",
+    base_url="https://api.groq.com/openai/v1",
+)
+
+# Local Ollama
+proposer = OpenAIProposer(
+    model="llama3.3",
+    base_url="http://localhost:11434/v1",
+    api_key="ollama",
+)
+```
+
+**LiteLLM catch-all (100+ providers):**
+```python
+from self_heal.llm import LiteLLMProposer
+
+proposer = LiteLLMProposer(model="anthropic/claude-sonnet-4-6")
+proposer = LiteLLMProposer(model="bedrock/anthropic.claude-3-5-sonnet")
+proposer = LiteLLMProposer(model="vertex_ai/gemini-2.5-pro")
+proposer = LiteLLMProposer(model="cohere/command-r-plus")
+```
+
+## Why this exists
+
+AI coding agents fail on a lot of real tasks. The industry's current answer is "retry and hope." That's not a strategy.
+
+`self-heal` treats repair as a first-class primitive: diagnose the failure, propose a targeted fix, verify, retry. A thin library you can wrap around any Python function or agent tool.
+
+Built on ongoing code-repair research (RepairBench, NeurIPS 2026).
+
+## How it works
+
+1. **Catch** the exception and capture inputs, traceback, and failure type.
+2. **Classify** the failure (validation, exception, assertion).
+3. **Propose** a repaired function via LLM with a failure-aware prompt.
+4. **Recompile** the proposed function into the running process.
+5. **Retry** with the same inputs.
+
+All within a single decorator boundary.
+
+## API
+
+**Decorator:**
+```python
+from self_heal import repair
+
+@repair(max_attempts=3, model="claude-sonnet-4-6", verbose=True)
+def my_tool(x): ...
+
+my_tool(42)
+my_tool.last_repair  # -> RepairResult with full attempt history
+```
+
+**Loop (for advanced use):**
+```python
+from self_heal import RepairLoop
+
+loop = RepairLoop(max_attempts=5, verbose=True)
+result = loop.run(my_tool, args=(42,))
+if result.succeeded:
+    print(result.final_value)
+else:
+    print(result.attempts[-1].failure.traceback)
+```
+
+**Custom proposer:**
+```python
+from self_heal.llm import LLMProposer
+
+class MyProposer:
+    def propose(self, system: str, user: str) -> str:
+        # ... your logic ...
+        return "def my_tool(x): return x * 2"
+```
+
+## Safety
+
+`self-heal` executes LLM-generated code via `exec()` in the same process. Same trust boundary as any LLM-in-the-loop system: do not run against untrusted inputs without a sandbox. Sandboxed execution is on the roadmap.
+
+## Roadmap
+
+- [x] v0.0.1: core repair loop + decorator + Claude backend
+- [x] v0.0.2: OpenAI, Gemini, LiteLLM adapters — works with any LLM
+- [ ] v0.1: user-provided verifiers (beyond exception-catching)
+- [ ] v0.2: telemetry + before/after success metrics
+- [ ] v0.3: async support
+- [ ] v0.4: sandboxed execution
+- [ ] v0.5: repair persistence (learn from past fixes)
+- [ ] v1.0: NeurIPS 2026 paper co-release
+
+## Development
+
+```bash
+git clone https://github.com/Johin2/self-heal.git
+cd self-heal
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"   # Windows
+# .venv/bin/pip install -e ".[dev]"     # macOS/Linux
+pytest
+```
+
+## License
+
+MIT

self_heal_llm-0.0.2/examples/basic.py

@@ -0,0 +1,29 @@
+"""Minimal self-heal example.
+
+Requires ANTHROPIC_API_KEY in the environment.
+
+Run:
+    python examples/basic.py
+"""
+
+from __future__ import annotations
+
+import logging
+
+from self_heal import repair
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+@repair(max_attempts=3, verbose=True)
+def divide(a: float, b: float) -> float:
+    # Naive: crashes on b == 0.
+    return a / b
+
+
+if __name__ == "__main__":
+    print("divide(10, 2) =", divide(10, 2))
+    print()
+    print("divide(10, 0) =", divide(10, 0))
+    print()
+    print("Attempts:", divide.last_repair.total_attempts)

self_heal_llm-0.0.2/examples/extract_price.py

@@ -0,0 +1,31 @@
+"""A realistic self-heal example: messy real-world input.
+
+Requires ANTHROPIC_API_KEY in the environment.
+
+Run:
+    python examples/extract_price.py
+"""
+
+from __future__ import annotations
+
+import logging
+
+from self_heal import repair
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+
+@repair(max_attempts=3, verbose=True)
+def extract_price(text: str) -> float:
+    # Naive: only handles "$X.YY" with no commas.
+    return float(text.replace("$", ""))
+
+
+if __name__ == "__main__":
+    samples = ["$12.99", "₹1,299", "€5,49", "1000.50 USD", "  $4,999.00 "]
+    for sample in samples:
+        try:
+            value = extract_price(sample)
+            print(f"{sample!r:>18}  ->  {value}")
+        except Exception as e:
+            print(f"{sample!r:>18}  ->  FAILED: {e}")