AutoEoH

AutoEoH turns a coding agent (Claude Code or Codex) into an automatic front-end for EoH (Evolution of Heuristics). You describe an optimization task and point at a solver codebase; the agent writes a ready-to-run EoH example folder, auto-debugs it, and runs a tiny search to prove it works — then you scale it up.

There is no separate multi-agent framework and no second LLM backend: the coding agent itself is the brain, guided by one playbook (AGENTS.md). EoH does the evolutionary search.

How it works

task description + existing solver codebase
   └─ agent reads AGENTS.md
        1. understand → pick the evolution target
           (extract a heuristic component, or design a whole algorithm)
        2. scaffold autoeoh_examples/<task>/ from template/
        3. smoke_test.py   — auto-debug, NO tokens (template must score; eval must discriminate)
        4. runEoH.py --smoke — tiny real run, confirm the search is healthy
        5. diagnose & fix (symptom → cause → fix table in AGENTS.md)
        6. scale up + report

Layout

AGENTS.md                  # the playbook the agent follows (the whole system)
CLAUDE.md                  # thin Claude Code adapter → AGENTS.md
template/                  # files copied into each new task folder
  prob.py  runEoH.py  smoke_test.py  get_instance.py  README.md
eoh/                       # the EoH engine (pip install -e eoh/)
  src/eoh/                 #   the engine package
  eoh_examples/            #   polished reference artifacts: bp_online, bbob_metaheuristic, ale_breakout
autoeoh_examples/          # end-to-end case studies of the agent workflow (prompt → debugged task)

Quick start

pip install -e eoh/
npm install -g @anthropic-ai/claude-code   # or @openai/codex
cd "AutoEoH"
claude        # reads CLAUDE.md → AGENTS.md automatically

Then ask, e.g.:

Build an EoH task from the description "design a bin-packing scoring heuristic" and the solver in ./my_solver/, then smoke-test and run it.

Set LLM credentials — hardcode them in the generated runEoH.py, or export the env vars (which override the hardcoded defaults). Any OpenAI-compatible endpoint/model works; the values below are only an example:

export EOH_API_ENDPOINT="api.deepseek.com"   # or api.openai.com, your host, ...
export EOH_API_KEY="sk-..."
export EOH_MODEL="deepseek-chat"             # or gpt-5.4-mini, your model, ...

The EoH task contract

Each task is one BaseProblem subclass with three fields:

• template_program — runnable seed code EoH evolves (a function or a class); its docstring steers the LLM.
• task_description — a sentence or two; the objective.
• evaluate_program(self, program_str, callable_func) — return a float (lower is better) or None to discard.

See eoh/src/eoh/problem.py and eoh/eoh_examples/ for working patterns.

Related

• EoH (Evolution of Heuristics)
• LLM4AD