AutoHD: Automated Heuristics Discovery for LLM Planning

What is AutoHD?

AutoHD (Automated Heuristics Discovery) is a Python package that enables LLMs to generate and evolve heuristic functions for guiding inference-time search in complex planning tasks.

Based on the research paper: "Complex LLM Planning via Automated Heuristics Discovery" (arXiv:2502.19295v1, Feb 2025, Texas A&M University).

Two names, one project: this code is published on PyPI as both autohd and certushd with identical versions. pip install autohd gives import autohd; pip install certushd gives import certushd. Everything below applies to both — substitute the name you installed.

Key Features

• LLM-Generated Heuristics: LLMs automatically generate heuristic functions as Python code
• Heuristic Evolution: Iterative refinement through exploration and modification strategies
• Multiple Search Algorithms: Support for Greedy BFS and A* search
• Multiple Planning Tasks: Blocksworld, Game of 24, and Rubik's Cube
• LLM-Agnostic: Works with OpenAI, Anthropic, and other providers via litellm
• LangChain Integration: Plug into LangChain agents and chains

Quick Start

pip install autohd

Basic Usage

import asyncio
from autohd import AutoHD
from autohd.core.config import AutoHDConfig, LLMConfig

async def main():
    # Configure AutoHD
    config = AutoHDConfig(
        task_name="blocksworld",
        llm=LLMConfig(model="gpt-4o", provider="openai"),
    )
    
    # Initialize AutoHD
    autohd = AutoHD(config=config)
    
    # Real benchmark instances per the AutoHD paper (arXiv:2502.19295)
    from autohd.benchmarks import get_dataset
    train_data = get_dataset("blocksworld", 10, seed=0)
    test_data = get_dataset("blocksworld", 10, seed=1)

    # Run the pipeline
    results = await autohd.run(
        train_data=train_data,
        test_data=test_data,
    )
    
    print(f"Best heuristic accuracy: {results['test_results']['accuracy']:.1%}")

asyncio.run(main())

CLI Usage

# Run on Blocksworld
autohd run --task blocksworld --model gpt-4o

# Run on Game of 24
autohd run --task game24 --model gpt-4o

# Run on Rubik's Cube
autohd run --task rubiks_cube --model gpt-4o

# Custom configuration
autohd run --task blocksworld --generations 5 --population 10 --search-algorithm astar

Architecture

autohd/
├── core/           # Core framework
│   ├── autohd.py   # Main AutoHD class
│   ├── config.py   # Configuration classes
│   └── llm_client.py # LLM API abstraction
├── search/         # Search algorithms
│   ├── greedy_bfs.py # Greedy BFS solver
│   └── astar.py     # A* solver
├── benchmarks/     # Planning task implementations
│   ├── base.py     # Base benchmark class
│   ├── blocksworld.py # Blocksworld task
│   ├── game24.py   # Game of 24 task
│   └── rubiks_cube.py # Rubik's Cube task
├── integrations/   # Framework integrations
│   └── langchain.py # LangChain integration
└── cli/            # Command-line interface
    └── main.py     # CLI entry point

How It Works

AutoHD follows a 5-step pipeline:

1. Generate Initial Heuristics: LLMs are prompted to create heuristic functions as Python code
2. Evaluate Heuristics: Each heuristic is tested on validation data using heuristic-guided search
3. Evolve Heuristics: Iterative refinement through exploration (new ideas) and modification (tweaking existing)
4. Select Best: The best heuristic from all generations is chosen
5. Test: The selected heuristic is evaluated on test data

Performance

Based on the research paper:

Requirements

• Python 3.10+
• OpenAI API key (or other LLM provider)
• Optional: litellm for multi-provider support

License

MIT License

Citation

If you use AutoHD in your research, please cite:

@article{ling2025autohd,
  title={Complex LLM Planning via Automated Heuristics Discovery},
  author={Ling, Hongyi and Parashar, Shubham and Khurana, Sambhav and Olson, Blake and Basu, Anwesha and Sinha, Gaurangi and Tu, Zhengzhong and Caverlee, James and Ji, Shuiwang},
  journal={arXiv preprint arXiv:2502.19295},
  year={2025}
}