Metadata-Version: 2.5
Name: hillclimb
Version: 0.7.0
Summary: Hillclimbing on verifiable rewards: coding agents search for Python programs that optimize a score you define
Project-URL: Homepage, https://hillclimb.sh
Project-URL: Documentation, https://docs.hillclimb.sh
Project-URL: Repository, https://github.com/rebase-energy/hillclimb
Project-URL: Changelog, https://github.com/rebase-energy/hillclimb/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/rebase-energy/hillclimb/issues
Project-URL: Discord, https://discord.gg/DDKh9UtSH
Author: Rebasian Technologies AB
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,codex,coding-agents,evolutionary-search,hillclimbing,optimization,program-search,verifiable-rewards
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Requires-Dist: networkx>=3.0
Requires-Dist: pandas>=3.0.3
Requires-Dist: plotui>=0.6
Requires-Dist: psutil>=5.9; sys_platform == 'win32'
Requires-Dist: pydantic>=2.7
Requires-Dist: pydot>=4.0.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn>=1.9.0
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: uv>=0.5
Provides-Extra: emflow
Requires-Dist: emflow<0.4,>=0.3.1; extra == 'emflow'
Provides-Extra: gepa
Requires-Dist: gepa<0.2,>=0.1.4; extra == 'gepa'
Requires-Dist: optuna<5,>=3.6; extra == 'gepa'
Provides-Extra: openevolve
Requires-Dist: openevolve<0.4,>=0.3; extra == 'openevolve'
Provides-Extra: optuna
Requires-Dist: optuna<5,>=3.6; extra == 'optuna'
Provides-Extra: tui
Description-Content-Type: text/markdown

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hillclimb-logo.svg">
  <img alt="hillclimb" src="docs/assets/hillclimb-logo-light.svg" width="620">
</picture>

**Hillclimbing on verifiable rewards.**<br>
Use Claude Code and Codex to autonomously search for python programs that optimize a score you define.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hillclimb-mountain-dark.png">
  <img alt="An ASCII mountain: one climber on the summit under a gold star, another stuck on a lower peak" src="docs/assets/hillclimb-mountain-light.png" width="560">
</picture>

[Website](https://hillclimb.sh) ·
[Docs](https://docs.hillclimb.sh) ·
[Quickstart](https://docs.hillclimb.sh/quickstart) ·
[CLI reference](https://docs.hillclimb.sh/cli) ·
[Blog](https://docs.hillclimb.sh/blogposts) ·
[Discord](https://discord.gg/DDKh9UtSH)

[![PyPI](https://img.shields.io/pypi/v/hillclimb.svg)](https://pypi.org/project/hillclimb/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB.svg?logo=python&logoColor=white)](https://pypi.org/project/hillclimb/)
[![Quickstart](https://github.com/rebase-energy/hillclimb/actions/workflows/quickstart.yml/badge.svg)](https://github.com/rebase-energy/hillclimb/actions/workflows/quickstart.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Discord](https://img.shields.io/badge/discord-join%20chat-5865F2.svg?logo=discord&logoColor=white)](https://discord.gg/DDKh9UtSH)

</div>

---

Give hillclimb a **problem** — a folder whose verifier scores a `solution.py` —
and a budget. It runs Claude Code, Codex or pi as operators that draft, debug
and improve solutions, scores every candidate through your verifier, and keeps
the best.

The harness is fixed. The **climber** — what to try next and how each attempt
is prompted — is a block you can swap, edit and share, so two methods can be
compared on the same problem under the same budget.

## Quickstart

```bash
pip install hillclimb
hillclimb connect claude               # or codex, pi; add --agent dummy to any run for no LLM at all

hillclimb init                         # hillclimb.yaml, problems/, runs/ in this folder
hillclimb problem get heilbronn-11     # the verifier is the problem; description.md is the brief
hillclimb verify heilbronn-11          # score the floor solution

hillclimb run heilbronn-11 --budget 10m
hillclimb watch                        # live coding agents and scores (also: chart, tree)
hillclimb stop --all
```

The best solution lands in `runs/<run-id>/searches/heilbronn-11/best/`.
The [walkthrough](https://docs.hillclimb.sh/walkthrough) goes through each step.

## Climbers

A climber is one block of config, in a run spec or as the folder's default in
`hillclimb.yaml`:

```yaml
climber:
  selector_policy: map-elites     # which candidate to build on next
  operator_policy: greedy         # which operator to use on it
  operators: [draft, debug, improve, crossover.py:Crossover]
  tuner: optuna
  params: {num_drafts: 5}
```

Every slot takes a prebuilt module, a `.py` file of your own, or
`package.module:Class`. Presets: `greedy`, `openevolve`, `gepa`. Or compose in
Python:

```python
from hillclimb import Budget, Climber, Problem
from hillclimb.policies import Greedy
from hillclimb.selectors import MapElites

problem = Problem("heilbronn-11")
budget = Budget(wall_clock="10m", evaluations=40)
climber = Climber(selector_policy=MapElites(num_drafts=5), operator_policy=Greedy())

climber.search(problem, budget=budget)
climber.best, climber.history, climber.to_frame()
```

`climber.start(...)` opens the same search to drive by hand, one `climber.step()` at a
time, and `Problem(name, score=my_function, ...)` defines a problem from a scoring function.
Runnable scripts are in [`examples/`](examples/).

Compare two head to head:

```bash
hillclimb run heilbronn-11 --climber greedy --climber openevolve --parallel-searches 2
hillclimb experiment report <run-id>
```

## Example problems

Exact, noise-free construction problems, each with its best known value as the
target line. `hillclimb problem list` shows the full catalog.

| Family | Instances | Score |
|---|---|---|
| Circle packing | `circle-packing`, `circle-packing-32` | sum of radii ↑ |
| Heilbronn triangles | `heilbronn-11`, `-14`, `-17`, `heilbronn-convex-13` | smallest triangle ↑ |
| Low-autocorrelation sequences | `labs-40`, `labs-60` | sidelobe energy ↓ |
| Tammes / Thomson | `tammes-30`, `-50`, `thomson-50`, `-100` | min angle ↑ / energy ↓ |
| Autocorrelation inequalities | `autocorr-1`, `autocorr-3`, `erdos-overlap` | the constant ↓ |
| Kissing configuration | `kissing-11` | points ↑ |
| Golomb rulers | `golomb-20`, `golomb-27` | length ↓ |
| TSP / knapsack | `tsp-200`, `mknap-100-5`, `mknap-250-10` | tour ↓ / value ↑ |

[Define your own](https://docs.hillclimb.sh/problems): `hillclimb problem new
my-problem` writes a small problem that already runs, for you to edit into yours. Kaggle (MLE-bench) and Einstein Arena
come in as [benchmark problems](https://docs.hillclimb.sh/benchmarks).

## Learn more

<table>
<tr>
<td width="50%" valign="top">

### [Website →](https://hillclimb.sh)

What hillclimb is for, the terminal views you watch a climb in, and the
modules a climber is built from.

</td>
<td width="50%" valign="top">

### [Problems →](https://docs.hillclimb.sh/examples)

Every example problem with its verifier, its best known value and who found
it, plus the [verifier contract](https://docs.hillclimb.sh/problems/verifier-contract).

</td>
</tr>
<tr>
<td width="50%" valign="top">

### [CLI reference →](https://docs.hillclimb.sh/cli)

Every `hillclimb` command and its flags, from `run` and `watch` to
`experiment` and `climber check`.

</td>
<td width="50%" valign="top">

### [Blogposts →](https://docs.hillclimb.sh/blogposts)

Starting with [Hillclimbing on verifiable rewards](https://docs.hillclimb.sh/blogposts/hillclimbing-on-verifiable-rewards):
from Cauchy's gradient descent to LLMs searching over programs.

</td>
</tr>
</table>

Questions, results, ideas: [join the Discord](https://discord.gg/DDKh9UtSH).

## License

[MIT](LICENSE)
