Quickstart

This guide will help you get started with LLM4AD in 5 minutes.

Installation

First, install LLM4AD:

.. code-block:: bash

pip install llm4ad

Or install from source:

.. code-block:: bash

git clone https://github.com/Optima-CityU/LLM4AD.git
cd LLM4AD
pip install -r requirements.txt

.. important:: Python 3.9 or higher is required for the ast.unparse() function.

Basic Concepts

LLM4AD has three core components:

1. LLM: The language model interface for generating algorithms. Subclass llm4ad.base.LLM and implement draw_sample() to connect to your LLM API.

2. Evaluation: The task definition that provides templates and evaluates generated algorithms. Available tasks include Online Bin Packing, TSP, VRP, and more.

3. Method: The algorithm design method that uses the LLM to discover better algorithms. Methods include RandSample, EoH, FunSearch, HillClimb, and others.

Complete Example

Here’s a complete example using the Online Bin Packing task with a fake LLM (for debugging without an API):

.. code-block:: python

from __future__ import annotations

import pickle
import random
from typing import Any
import sys

sys.path.append('.')

from llm4ad.task.optimization.online_bin_packing import OBPEvaluation
from llm4ad.base import LLM
from llm4ad.method.randsample import RandSample
from llm4ad.tools.profiler import ProfilerBase


class FakeLLM(LLM):
    """Fake LLM that randomly selects functions from a database.
    Use this for debugging without an actual LLM API.
    """

    def __init__(self):
        super().__init__()
        with open('./example/llms/online_bin_packing_fake/_data/rand_function.pkl', 'rb') as f:
            self._functions = pickle.load(f)

    def draw_sample(self, prompt: str | Any, *args, **kwargs) -> str:
        return random.choice(self._functions)


if __name__ == '__main__':
    # Define the LLM (using FakeLLM for demonstration)
    llm = FakeLLM()

    # Define the evaluation task (Online Bin Packing)
    task = OBPEvaluation()

    # Define the method (Random Sampling)
    method = RandSample(
        llm=llm,
        profiler=ProfilerBase(log_dir='logs/quickstart', log_style='simple'),
        evaluation=task,
        max_sample_nums=10,      # Maximum number of algorithm samples
        num_samplers=1,          # Number of parallel samplers
        num_evaluators=1,        # Number of parallel evaluators
    )

    # Run the algorithm design process
    method.run()

    print("Quickstart completed! Check the logs/quickstart directory for results.")

Running the Example

Run the example script:

.. code-block:: bash

python quickstart_example.py

You should see output indicating the algorithm design process is running. The profiler will log results to the logs/quickstart directory.

Using a Real LLM

To use a real LLM instead of the fake one, replace FakeLLM with an actual LLM implementation:

.. code-block:: python

from llm4ad.tools.llm.llm_api_https import HttpsApi

llm = HttpsApi(
    host='your-api-endpoint',  # e.g., "api.bltcy.top" (no https://)
    key='your-api-key',        # e.g., "sk-..."
    model='gpt-4o'             # your model name
)

Using Different Methods

LLM4AD supports multiple methods. Here are some examples:

EoH (Evolution of Heuristics):

.. code-block:: python

from llm4ad.method.eoh import EoH

method = EoH(
    llm=llm,
    evaluation=task,
    max_generations=10,
    max_sample_nums=100,
    pop_size=5
)

FunSearch:

.. code-block:: python

from llm4ad.method.funsearch import FunSearch

method = FunSearch(
    llm=llm,
    evaluation=task,
    max_sample_nums=100,
    num_samplers=4
)

HillClimb:

.. code-block:: python

from llm4ad.method.hillclimb import HillClimb

method = HillClimb(
    llm=llm,
    evaluation=task,
    max_sample_nums=50
)

Using Built-in Tasks

LLM4AD provides pre-built tasks for common optimization problems:

TSP (Traveling Salesman Problem):

.. code-block:: python

from llm4ad.task.optimization.tsp_construct import TSPEvaluation

task = TSPEvaluation()

CVRP (Capacitated Vehicle Routing Problem):

.. code-block:: python

from llm4ad.task.optimization.cvrp_construct import CVRPEvaluation

task = CVRPEvaluation()

Knapsack Problem:

.. code-block:: python

from llm4ad.task.optimization.knapsack_construct import KnapsackEvaluation

task = KnapsackEvaluation()

Next Steps

• Read the :doc:installation guide for detailed installation instructions

• Explore :doc:examples to see more example scripts

• Check the API documentation for available methods and tasks

• Visit the GitHub repository for more examples: https://github.com/Optima-CityU/LLM4AD