Metadata-Version: 2.4
Name: certushd
Version: 0.1.17
Summary: Automated Heuristics Discovery for LLM Planning - Enable LLMs to generate and evolve heuristic functions for complex planning tasks
Author-email: Tommy Ferreira <tommy@vcb-ai.online>
Maintainer-email: Tommy Ferreira <tommy@vcb-ai.online>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/autohd
Project-URL: Documentation, https://github.com/yourusername/autohd#readme
Project-URL: Repository, https://github.com/yourusername/autohd
Project-URL: Issues, https://github.com/yourusername/autohd/issues
Project-URL: Bug Tracker, https://github.com/yourusername/autohd/issues
Keywords: llm,planning,heuristics,reasoning,inference-time,autohd,test-time-compute
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Provides-Extra: providers
Requires-Dist: anthropic>=0.20.0; extra == "providers"
Requires-Dist: litellm>=1.0.0; extra == "providers"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: rich>=13.0.0; extra == "cli"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Requires-Dist: langchain-openai>=0.0.5; extra == "langchain"
Provides-Extra: all
Requires-Dist: certushd[cli,dev,langchain,providers]; extra == "all"
Dynamic: license-file

# AutoHD: Automated Heuristics Discovery for LLM Planning

[![PyPI](https://img.shields.io/pypi/v/autohd)](https://pypi.org/project/autohd/)
[![Python](https://img.shields.io/pypi/pyversions/autohd)](https://www.python.org/downloads/)
[![License](https://img.shields.io/pypi/l/autohd)](https://github.com/yourusername/autohd/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-User%20Guide-blue)](https://github.com/yourusername/autohd#readme)

---

## 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"](https://arxiv.org/abs/2502.19295v1) (arXiv:2502.19295v1, Feb 2025, Texas A&M University).

> **Two names, one project:** this code is published on PyPI as both
> [`autohd`](https://pypi.org/project/autohd/) and
> [`certushd`](https://pypi.org/project/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

```bash
pip install autohd
```

### Basic Usage

```python
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

```bash
# 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:

| Task | GPT-4o-mini | GPT-4o | Llama 3.1 70B | Best Baseline |
|------|-------------|--------|---------------|---------------|
| Blocksworld | 42.4% | **75.1%** | 59.1% | ~2× improvement |
| Game of 24 | 54% | **70%** | 69% | vs ToT 42/62/59 |
| Rubik's Cube (2×2) | **82.5%** | **83.1%** | **84.7%** | vs XoT 67/80/78 |

## 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}
}
```
