Metadata-Version: 2.4
Name: runr-ai
Version: 0.1.0
Summary: Automatically set up and run any GitHub repository using AI-powered dependency resolution
Project-URL: Homepage, https://wasifAhmed1917.github.io/runr
Project-URL: Repository, https://github.com/WasifAhmed1917/runr
Author-email: Wasif Ahmed <wasif.ahmed1687@gmail.com>
License: MIT
Keywords: ai,automation,cli,dependency-resolution,github
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: gitpython>=3.1.40
Requires-Dist: groq>=0.9.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=24.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# runr

> Automatically set up and run any GitHub repository using AI-powered dependency resolution.

```
runr https://github.com/karpathy/nanoGPT
```

That's it. runr clones the repo, reads every dependency file, resolves conflicts via an LLM, creates an isolated virtual environment, installs everything, and runs the project — self-healing up to 5 times if anything goes wrong.

---

## Install

```bash
pip install runr
# or, for latest:
pip install git+https://github.com/runr-cli/runr
```

Requires Python 3.10+. Optionally install **uv** for faster installs:

```bash
pip install uv
```

## Setup

Set your Groq API key (get one free at [console.groq.com](https://console.groq.com)):

```bash
export GROQ_API_KEY=gsk_...
```

## Usage

```bash
# Run a GitHub repo
runr https://github.com/karpathy/nanoGPT

# Run a local repo
runr ./my_local_project

# Force Python version
runr https://github.com/user/repo --python 3.11

# CPU-only (skip CUDA deps)
runr https://github.com/user/repo --no-gpu

# Preview plan without running
runr https://github.com/user/repo --dry-run

# Override entry point
runr https://github.com/user/repo --entry src/train.py

# Verbose (shows install logs + resolved requirements)
runr https://github.com/user/repo --verbose

# Private repo
runr https://github.com/org/private-repo --token ghp_...
# or set GITHUB_TOKEN env var
```

## What happens

```
◆ runr v0.1.0

● Cloning karpathy/nanoGPT...         ✓  (2.3s)
● Detecting dependencies...           ✓  14 imports detected, 2 dep files
● Environment: Python 3.11.9, Darwin arm64, CPU only
● Resolving conflicts...              ✓  12 packages resolved
● Creating environment & installing...✓  installed via uv in 18.4s
● Entry point: python train.py

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[live repo output streams here]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Successfully completed after 1 attempt(s)
```

If the run fails, runr self-heals:

```
✗ Run failed (attempt 1/5)
  Error: No module named 'flash_attn'

◆ Healing...
  → pip install flash-attn==2.3.0
  Installing flash-attn compatible with CUDA 12.1

✓ Fix applied
● Retrying... ✓ Success
```

## How it works

| Step | Module | What it does |
|------|--------|-------------|
| Clone | `cli.py` | Clones to a temp directory; never touches your original files |
| Detect | `detector.py` | Reads requirements.txt, setup.py, pyproject.toml, environment.yml, Dockerfile, scans .py imports |
| Resolve | `resolver.py` | Sends everything to Groq `llama-3.3-70b-versatile`; gets back a pinned requirements.txt |
| Install | `installer.py` | Creates venv via `uv venv` (falls back to `python -m venv`), installs pinned deps |
| Run | `runner.py` | Streams live output; on failure passes error to healer |
| Heal | `healer.py` | LLM returns a structured fix: install package / modify file / set env var |

## Caching

Resolved requirements are cached in `~/.runr/cache/` keyed by a SHA-256 hash of all dependency files. Same repo + same deps = instant resolution skip. Use `--no-cache` to force a fresh resolve.

## Logs

Full logs are written to `~/.runr/logs/<repo>_<timestamp>.log`.

## Environment detection

runr automatically detects:
- Python version and OS/arch
- CUDA version (`nvcc --version`, `nvidia-smi`)
- GPU presence
- Already-installed packages (avoids re-pinning what's there)

## Supported dependency files

- `requirements.txt`
- `requirements-dev.txt`
- `setup.py`
- `setup.cfg`
- `pyproject.toml`
- `environment.yml` (conda)
- `Dockerfile` (extracts `RUN pip install` lines)
- Implicit imports scanned from all `.py` files

## Error handling

| Error | How runr handles it |
|-------|---------------------|
| torch CUDA mismatch | Detects CUDA version, installs correct `+cu*` build |
| Package not on PyPI | LLM skips or finds alternative |
| Python version mismatch | Reads `requires-python`, suggests correct version |
| Missing system deps | Prints human-readable install instructions |
| Private repo | Prompts for `--token` or `GITHUB_TOKEN` |
| Notebook-only repo | Launches `jupyter notebook` |

## License

MIT
