Metadata-Version: 2.4
Name: heal
Version: 0.1.20
Summary: A Python package for healing and wellness
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yourusername/heal
Project-URL: Repository, https://github.com/yourusername/heal
Project-URL: Issues, https://github.com/yourusername/heal/issues
Keywords: health,wellness,healing,llm,shell,fix
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: privacy
Requires-Dist: priv-masker>=0.1.0; extra == "privacy"
Requires-Dist: spacy>=3.0.0; extra == "privacy"
Dynamic: license-file

# Heal 🩺

**LLM-powered shell error fixing** - Your AI assistant for debugging and fixing command-line errors instantly.

## Installation

```bash
pip install heal
```

## Quick Start

### Complete Setup (Recommended)

```bash
# 1. Configure heal (first time only)
heal config

# 2. Test your configuration
heal test

# 3. Initialize bash integration
heal init

# 4. Restart your shell
source ~/.bashrc

# 5. Use heal - just run any command and then heal!
python broken_script.py
heal
```

### Simplest Usage - Just `heal`

```bash
# Run any failing command, then simply run heal
npm install
heal

# Or pipe errors directly
make build 2>&1 | heal

# From error file
heal < error.log

# With privacy protection (anonymize sensitive data)
production_script.py 2>&1 | heal --anonymize
```

### Automatic Mode (with shell integration)

```bash
# Initialize bash integration (recommended)
heal init

# This will automatically add to ~/.bashrc
# Or manually add: source ~/.heal/heal.bash

# Restart your shell
source ~/.bashrc

# Now you can run any command and heal will capture it:
your_failing_command
heal
```

## Features

- 🤖 **LLM-powered error analysis** - Uses GPT models to understand and fix shell errors
- 🔄 **Automatic command capture** - Shell hook captures last command and output
- 📥 **Multiple input methods** - Works with stdin, files, or shell hooks
- ⚙️ **Configurable models** - Support for various LLM providers via litellm
- 🔒 **Privacy protection** - Anonymize sensitive data before sending to LLM (optional)
- 🚀 **Zero-config start** - Just run `heal` after any error

## Usage Examples

### Python Development

```bash
# Missing dependencies
python app.py 2>&1 | heal
# → Suggests: pip install <missing-package>

# Import errors
python -m pytest 2>&1 | heal
# → Analyzes import paths and suggests fixes

# Virtual environment issues
python script.py 2>&1 | heal
# → Detects venv problems and suggests activation
```

### Node.js / JavaScript

```bash
# NPM install failures
npm install 2>&1 | heal
# → Suggests clearing cache, fixing package.json, or using --legacy-peer-deps

# Build errors
npm run build 2>&1 | heal
# → Analyzes webpack/vite errors and suggests configuration fixes

# Module not found
node app.js 2>&1 | heal
# → Suggests installing missing packages or fixing import paths
```

### Docker & Containers

```bash
# Docker build failures
docker build . 2>&1 | heal
# → Analyzes Dockerfile errors and suggests fixes

# Container runtime errors
docker-compose up 2>&1 | heal
# → Suggests port conflicts, volume issues, or network problems

# Permission issues
docker run myimage 2>&1 | heal
# → Suggests user/group fixes or volume mount corrections
```

### Git Operations

```bash
# Merge conflicts
git merge feature-branch 2>&1 | heal
# → Suggests conflict resolution strategies

# Push/pull errors
git push origin main 2>&1 | heal
# → Analyzes authentication, branch tracking, or force push needs

# Rebase issues
git rebase main 2>&1 | heal
# → Suggests conflict resolution or rebase abort/continue
```

### Build Systems

```bash
# Make errors
make build 2>&1 | heal
# → Analyzes missing dependencies or compilation errors

# CMake configuration
cmake . 2>&1 | heal
# → Suggests missing libraries or configuration flags

# Gradle/Maven builds
./gradlew build 2>&1 | heal
# → Analyzes Java compilation or dependency errors
```

### Database Operations

```bash
# PostgreSQL connection
psql -U user -d database 2>&1 | heal
# → Suggests authentication fixes or connection string corrections

# MySQL import errors
mysql < dump.sql 2>&1 | heal
# → Analyzes syntax errors or permission issues

# MongoDB connection
mongosh mongodb://localhost:27017 2>&1 | heal
# → Suggests service status checks or authentication fixes
```

### System Administration

```bash
# Permission denied
./script.sh 2>&1 | heal
# → Suggests chmod +x or sudo usage

# Port already in use
python -m http.server 8000 2>&1 | heal
# → Suggests finding and killing the process using the port

# Disk space issues
cp large-file.zip /destination 2>&1 | heal
# → Suggests cleaning up space or alternative locations
```

### Package Management

```bash
# APT/DNF errors
sudo apt install package 2>&1 | heal
# → Suggests repository updates or alternative package names

# Homebrew issues
brew install tool 2>&1 | heal
# → Suggests tap additions or formula fixes

# pip install failures
pip install package 2>&1 | heal
# → Suggests using --user, venv, or resolving dependency conflicts
```

## Commands

### `heal` (default)
Fix shell errors using LLM. Reads from stdin or captured output.

```bash
heal [--model MODEL] [--api-key KEY]
```

### `heal init`
Initialize bash integration for automatic command and output capture.

```bash
heal init
```

This will:
- Create `~/.heal/heal.bash` with command capture hooks
- Optionally add to your `~/.bashrc` automatically
- Enable helper commands: `heal-last`, `heal-output`

### `heal test`
Test your configuration with a simulated error.

```bash
heal test
```

This will:
- Verify your provider and API key are configured
- Send a test request to the LLM
- Show you a sample response

### `heal config`
Configure or reconfigure heal settings (provider, API key, model).

```bash
heal config
```

### `heal fix`
Explicit fix command (same as default `heal`).

```bash
heal fix [--model MODEL] [--api-key KEY]
```

### `heal install`
Legacy command (use `heal init` instead).

```bash
heal install
```

### `heal uninstall`
Remove shell hook and configuration.

```bash
heal uninstall
```

### `heal --help`
Show help message and available commands.

```bash
heal --help
```

## Configuration

### First-Time Setup

On first run, heal will guide you through an interactive setup:

```bash
$ heal

🔧 First-time setup - Let's configure your LLM provider

Available providers:
  1. OpenRouter (recommended)
  2. OpenAI
  3. Anthropic
  4. Google AI

💡 Tip: OpenRouter gives you access to all models with one API key

Select provider [1]: 1

🔑 Get your OpenRouter API key here:
   https://openrouter.ai/keys

Enter your API key: sk-or-...

🤖 Select a model from OpenRouter:

  1. openai/gpt-4o-mini
     GPT-4o Mini (fast, cheap, recommended)
  2. openai/gpt-4o
     GPT-4o (most capable)
  3. anthropic/claude-3.5-sonnet
     Claude 3.5 Sonnet (excellent reasoning)
  4. google/gemini-pro-1.5
     Gemini Pro 1.5 (long context)
  5. meta-llama/llama-3.1-70b-instruct
     Llama 3.1 70B (open source)
  6. qwen/qwen-2.5-72b-instruct
     Qwen 2.5 72B (multilingual)
  7. Custom (enter model name manually)

Select model [1]: 1
```

### Reconfigure Settings

Change your provider, API key, or model anytime:

```bash
heal config
```

### Supported Providers

#### 🌐 OpenRouter (Recommended)
- **Why?** Access to all models with one API key
- **Get API key:** [openrouter.ai/keys](https://openrouter.ai/keys)
- **Models:** GPT-4, Claude, Gemini, Llama, Qwen, and 100+ more

#### 🤖 OpenAI
- **Get API key:** [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
- **Models:** GPT-4o, GPT-4o-mini, GPT-4-turbo, GPT-3.5-turbo

#### 🧠 Anthropic
- **Get API key:** [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
- **Models:** Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku

#### 🔍 Google AI
- **Get API key:** [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)
- **Models:** Gemini Pro, Gemini Pro Vision

### Manual Configuration

Edit `~/.heal/.env`:

```bash
HEAL_PROVIDER=openrouter
HEAL_API_KEY=your-api-key-here
HEAL_MODEL=openai/gpt-4o-mini
HEAL_BASE_URL=https://openrouter.ai/api/v1
```

Configuration is stored in `~/.heal/.env`.

## Development

This package uses modern Python packaging with `pyproject.toml`.

### Install in development mode

```bash
pip install -e .
```

### Run tests

```bash
python -m pytest
```

## How it works

1. **Command capture**: Gets last command from bash history or shell hook
2. **Error collection**: Reads error output from stdin or captured file
3. **LLM analysis**: Sends command and error to LLM for analysis
4. **Solution proposal**: Returns concrete fix suggestions

## Limitations

- Shell processes cannot access previous process stderr without pipes
- Shell hook required for fully automatic operation
- Requires API key for LLM service

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## Author

Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
