Metadata-Version: 2.4
Name: autosteer
Version: 1.0.1
Summary: Research direction generator for autoresearch — analyzes experiment history and suggests next steps
Project-URL: Homepage, https://github.com/dean0x/autolab
Project-URL: Repository, https://github.com/dean0x/autolab
Project-URL: Issues, https://github.com/dean0x/autolab/issues
License-Expression: MIT
Keywords: autoresearch,experiment-suggestions,gpt,karpathy,pretraining
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Description-Content-Type: text/markdown

# autosteer

Research direction generator for [autoresearch](https://github.com/karpathy/autoresearch). Analyzes experiment history and suggests data-driven next steps instead of random-walking through experiment space.

## Install

```bash
pip install autosteer
```

## Usage

```bash
# Get 5 suggestions (default)
autosteer --results results.tsv

# Explore mode — favor untried directions (good when stuck)
autosteer --results results.tsv --strategy explore

# Exploit mode — double down on what works
autosteer --results results.tsv --strategy exploit

# More suggestions
autosteer --results results.tsv --num-suggestions 10

# Quick numbered list
autosteer --results results.tsv --quiet
```

## Strategy Modes

| Mode | When to Use |
|------|-------------|
| `auto` | Default. Balances explore/exploit based on experiment count. |
| `explore` | Early research, or stuck after 3+ discards. Favors untried categories. |
| `exploit` | You have proven wins. Doubles down on what works. |

## Output

Each suggestion includes:
- **Badge**: `[EXPLORE]` or `[EXPLOIT]` indicating category status
- **Category, risk, and expected improvement range**
- **Reasoning**: Why this direction is recommended

```
1. [EXPLOIT] Tune learning rate warmup schedule
   Category: hyperparams | Risk: low | Expected: +0.1-0.3%
   Currently WARMUP_RATIO=0.0 (no warmup). Try WARMUP_RATIO=0.05...

2. [EXPLORE] Tune RoPE base frequency
   Category: embedding | Risk: low | Expected: +0.1-0.3%
   Adjust the RoPE base frequency (theta)...
```

## How It Works

- 20 built-in research directions specific to GPT pretraining
- Categorizes past experiments (architecture, hyperparams, optimizer, etc.)
- Keyword deduplication: won't re-suggest failed directions
- Git integration: reads diffs to classify experiments automatically
- Strategy-weighted scoring that adapts to experiment count

## Requirements

- Python >= 3.10
- A `results.tsv` file from autoresearch
- Git repository (for diff-based experiment classification)

## License

MIT
