Metadata-Version: 2.4
Name: gradex
Version: 0.1.1
Summary: Measurable code improvement — autonomous optimization loop
License: MIT
License-File: LICENSE
Keywords: ai,cli,coding,plugin
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: anthropic>=0.25.0
Requires-Dist: anyio[trio]>=4.0.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: openai>=1.30.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlmodel>=0.0.18
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Gradex — autonomous code optimization. Measurable improvement, every run.

[![PyPI version](https://img.shields.io/pypi/v/gradex.svg)](https://pypi.org/project/gradex/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Gradex discovers performance targets, captures a baseline, runs autonomous optimization experiments, and ships the best verified patch.

## Install

```bash
pip install gradex
```

## 60-Second Quickstart

```bash
pip install gradex
gradex install cursor          # one-time provider + model setup
gradex discover "make this repo faster"
gradex optimize
gradex dashboard
```

After install, GradeX walks you through provider, model, and API key setup (or skip and use CLI flags). Re-run anytime with `gradex configure`. Use `gradex install cursor --no-setup` in CI.

## Providers

| Provider | Best for | Notes |
|---|---|---|
| Groq | Free cloud runs | Default. Best for serious `optimize` runs |
| OpenRouter | Low-friction testing | Free-tier models; one API key, many models |
| Anthropic | High quality reasoning | Strong patch planning and code edits |
| OpenAI | General purpose | Broad model options |
| Ollama | Local/private | Runs fully on your machine |

## CLI Reference

| Command | Description |
|---|---|
| `gradex install <host>` | Installs Gradex integration for a coding host (optional one-time model setup) |
| `gradex configure` | Set up or update LLM provider, model, and API key |
| `gradex models` | List recommended models for a provider |
| `gradex doctor <host>` | Checks host environment and setup health |
| `gradex dashboard` | Starts live optimization dashboard |
| `gradex upgrade` | Checks PyPI for newer Gradex versions |
| `gradex discover [hint]` | Discovers benchmark target and baseline |
| `gradex optimize` | Runs autonomous optimization loop |
| `gradex stats` | Shows run analytics and optional exports |
| `gradex report` | Exports a shareable HTML run report |
| `gradex history` | Lists recent optimization runs |

## How It Works

```text
+-----------+     +-----------+     +----------------------+     +----------------+
| discover  | --> | baseline  | --> | optimize loop (N)    | --> | best patch out |
+-----------+     +-----------+     +----------------------+     +----------------+
```

1. `discover` analyzes your repo and creates a measurable benchmark target.
2. Gradex records a baseline score.
3. `optimize` runs parallel experiment rounds (patch -> benchmark -> gate checks).
4. Best validated patch and run analytics are surfaced in dashboard and CLI.

## Dashboard

Dashboard screenshot: <img width="1783" height="882" alt="gradex" src="https://github.com/user-attachments/assets/fa349f5f-8bed-43e8-90af-43f2290ee84b" />


## License

MIT
