Metadata-Version: 2.4
Name: wolverine-x
Version: 0.2.0
Summary: Self-healing scripts: run any script and let a local LLM fix it when it crashes.
License: MIT
Project-URL: Homepage, https://github.com/Mrawdian/wolverine
Project-URL: Issues, https://github.com/Mrawdian/wolverine/issues
Project-URL: Changelog, https://github.com/Mrawdian/wolverine/blob/main/CHANGELOG.md
Keywords: llm,ai,debugging,self-healing,ollama,cli,developer-tools,autofix
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.0
Requires-Dist: fire>=0.5.0
Requires-Dist: termcolor>=2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.3; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Dynamic: license-file

# wolverine-x

> Run your scripts. When they crash, an LLM fixes them. Repeat until green.

**No API key required.** Runs 100% locally via [Ollama](https://ollama.com).

[![PyPI](https://img.shields.io/pypi/v/wolverine-x)](https://pypi.org/project/wolverine-x/)
[![Python](https://img.shields.io/pypi/pyversions/wolverine-x)](https://pypi.org/project/wolverine-x/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/Mrawdian/wolverine/actions/workflows/build.yml/badge.svg)](https://github.com/Mrawdian/wolverine/actions)

---

<p align="center">
  <img src="docs/demo.svg" alt="wolverine-x demo" width="640"/>
</p>

---

## What it does

```
$ wolverine examples/buggy_script.py "subtract" 20 3

Wolverine activated.
  Script   : examples/buggy_script.py
  Model(s) : ollama/qwen2.5-coder:7b -> ollama/qwen2.5-coder:14b
  Max iter : 10

[iter 1/10]  model: ollama/qwen2.5-coder:7b
Script crashed. Sending to LLM...

  - The function 'subtract_numbers' is referenced but never defined. Adding it.

  Diff:
  + def subtract_numbers(a, b):
  +     return a - b

  Changes applied. Rerunning...

[iter 2/10]  model: ollama/qwen2.5-coder:7b
Script crashed. Sending to LLM...

  - Variable 'res' used but never defined. Should be 'result'.

  Diff:
  - return res
  + return result

  Changes applied. Rerunning...

[iter 3/10]  model: ollama/qwen2.5-coder:7b
Script ran successfully.
Output: 17

Session: 3499 tokens | $0.00 total cost
```

---

## Why wolverine-x?

wolverine-x is a fork/revival of the original [biobootloader/wolverine](https://github.com/biobootloader/wolverine) (5.1k stars, deprecated 2023). The original was broken by OpenAI SDK v1.x and only worked with GPT-4.

This version:
- **Works out of the box** with local Ollama models (free, private, offline)
- **Supports 6 languages**: Python, JavaScript, TypeScript, Bash, Ruby, Go
- **Is smart about cost**: tries cheaper/faster models first, escalates on failure
- **Doesn't loop forever**: stall detection, configurable max iterations, backup restore

### vs other tools

| | wolverine-x | Aider | Cursor | GitHub Copilot CLI |
|---|---|---|---|---|
| Autonomous fix loop | Yes | No (human-in-loop) | No (IDE) | No (suggests only) |
| Local LLM (free) | **Yes** | Yes | No | No |
| Works in CI | **Yes** (`--ci`) | No | No | No |
| No API key needed | **Yes** | Requires key | Requires key | Requires key |
| Use case | Fix crashes | Write features | Write features | Suggest commands |

---

## Install

```bash
# Recommended: via pip
pip install wolverine-x

# Or from source
git clone https://github.com/Mrawdian/wolverine
cd wolverine
pip install -e .
```

**Prerequisite for local models:** [install Ollama](https://ollama.com/download) and pull a model:

```bash
ollama pull qwen2.5-coder:14b   # best quality (~9GB)
ollama pull qwen2.5-coder:7b    # faster, lighter (~5GB)
```

---

## Usage

```bash
# Basic — fix a Python script using the local default model
wolverine buggy_script.py

# Pass arguments to your script
wolverine buggy_script.py arg1 arg2

# Use a specific model
wolverine --model=ollama/qwen2.5-coder:7b buggy_script.py

# Cascade: try 7b first, escalate to 14b if stuck
wolverine --model="ollama/qwen2.5-coder:7b,ollama/qwen2.5-coder:14b" buggy_script.py

# Ask for confirmation before each fix
wolverine --confirm buggy_script.py

# CI mode (exit 0 on success, exit 1 on failure)
wolverine --ci --max-iter=5 buggy_script.py

# Revert to the original file (before wolverine touched it)
wolverine --revert buggy_script.py

# Short alias
wlvr buggy_script.py
```

---

## Supported languages

| Extension | Runtime required |
|-----------|-----------------|
| `.py` | Python (auto-detected) |
| `.js` | Node.js |
| `.ts` | Node.js + `ts-node` |
| `.sh` | bash |
| `.rb` | Ruby |
| `.go` | Go |

---

## Configuration

### Environment variables (`.env` or shell)

| Variable | Default | Description |
|----------|---------|-------------|
| `DEFAULT_MODEL` | `ollama/qwen2.5-coder:14b` | Model or comma-separated cascade |
| `WOLVERINE_MAX_ITER` | `10` | Max fix attempts |
| `VALIDATE_JSON_RETRY` | `3` | Max LLM retries on bad JSON |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server URL |
| `OPENAI_API_KEY` | — | Required for OpenAI models |
| `ANTHROPIC_API_KEY` | — | Required for Anthropic models |
| `XAI_API_KEY` | — | Required for Grok/xAI models |

### Project config (`wolverine.toml`)

```toml
[wolverine]
# Cascade: try fast local model first, escalate to heavier one on stall
model = "ollama/qwen2.5-coder:7b,ollama/qwen2.5-coder:14b"
max_iter = 10
confirm = false
max_json_retry = 3
```

CLI flags always override `wolverine.toml`, which overrides `.env`.

---

## Using cloud models

wolverine-x supports any provider that litellm supports.

```bash
# OpenAI
OPENAI_API_KEY=sk-... wolverine --model=gpt-4o buggy_script.py

# Anthropic
ANTHROPIC_API_KEY=sk-ant-... wolverine --model=claude-opus-4-6 buggy_script.py

# Grok/xAI
XAI_API_KEY=xai-... wolverine --model=xai/grok-3 buggy_script.py

# Local → cloud cascade (free first, pay only if needed)
wolverine --model="ollama/qwen2.5-coder:14b,gpt-4o" buggy_script.py
```

---

## How it works

```
1. wolverine backs up your script (.bak)
2. Runs the script
3. If it crashes → sends current file + error to the LLM
4. LLM responds with a JSON list of line-level edits (Replace / Delete / InsertAfter)
5. Edits are applied, script reruns
6. Repeat until success, max iterations reached, or stall detected
7. On failure → original file restored from backup
```

The conversation history is preserved across iterations, so the LLM sees what it already tried — no fix is applied twice.

---

## Development

```bash
git clone https://github.com/Mrawdian/wolverine
cd wolverine
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Try it
wolverine examples/buggy_script_simple.py 10
```

---

## Credits

Original concept and implementation: [@biobootloader](https://github.com/biobootloader) — [biobootloader/wolverine](https://github.com/biobootloader/wolverine)

Revival and v0.2.0: multi-provider support, local LLM, model cascade, stall detection, multi-language.

---

## License

MIT
