LLM4AD

# Basic installation
pip install llm4ad

# With GUI support
pip install llm4ad[gui]

# With all LLM backends
pip install llm4ad[all]

# Development installation
git clone https://github.com/Optima-CityU/llm4ad.git
cd llm4ad
pip install -e ".[dev]"

from llm4ad import LLM4AD, EoH, BinPacking
from llm4ad.llm import OpenAIBackend

# Configure LLM backend
llm = OpenAIBackend(model="gpt-4o", api_key="sk-...")

# Define the task
task = BinPacking(
    instance="benchmark/bpp_500_items",
    metric="waste_ratio",
    direction="minimize",
)

# Select search method
method = EoH(
    population_size=20,
    num_generations=50,
    crossover_rate=0.3,
    mutation_rate=0.7,
    elite_size=3,
)

# Run optimization
runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    max_workers=4,
    timeout_per_eval=30,
    log_to="wandb",          # Log to Weights & Biases
    project_name="llm4ad-bpp",
)

result = runner.run()

print(f"Best waste ratio: {result.best_score:.4f}")
print(f"Best algorithm:\n{result.best_code}")

# Launch the graphical interface
llm4ad gui --port 8080

# Or from Python
from llm4ad.gui import launch
launch(port=8080)

+-----------------------------------------------------------------------------------+
|                            LLM4AD Platform Architecture                            |
+-----------------------------------------------------------------------------------+
|                                                                                    |
|  +----------------------------------+   +--------------------------------------+   |
|  |          User Interface           |   |          Configuration Layer          |   |
|  |                                   |   |                                      |   |
|  |  CLI  |  Python API  |  GUI (Web) |   |  YAML Config  |  Programmatic API   |   |
|  +----------------------------------+   +--------------------------------------+   |
|                        |                              |                            |
|                        v                              v                            |
|  +------------------------------------------------------------------------+        |
|  |                       LLM4AD Orchestrator                               |        |
|  |                                                                         |        |
|  |   +-------------------+    +-------------------+    +----------------+  |        |
|  |   | Search Method     |    | Task Registry     |    | LLM Backend    |  |        |
|  |   | Selector          |    |                   |    | Manager        |  |        |
|  |   |                   |    | - BinPacking      |    |                |  |        |
|  |   | - EoH             |    | - TSP             |    | - OpenAI       |  |        |
|  |   | - MEoH            |    | - FacilityLoc     |    | - Google       |  |        |
|  |   | - FunSearch        |    | - Knapsack        |    | - DeepSeek     |  |        |
|  |   | - ReEvo           |    | - QAP             |    | - Local (vLLM) |  |        |
|  |   | - MCTS-AHD        |    | - Scheduling      |    |                |  |        |
|  |   | - (1+1)-EPS       |    | - BO Acquisition  |    +----------------+  |        |
|  |   | - LLaMEA          |    | - RL Environments |                        |        |
|  |   +-------------------+    | - CFD Turbulence  |                        |        |
|  |           |                | - Bacteria Growth |                        |        |
|  |           |                | - Math Discovery  |                        |        |
|  |           |                +-------------------+                        |        |
|  |           v                         |                                   |        |
|  |   +------------------------------------------------------------------+ |        |
|  |   |                    Evaluation Engine                              | |        |
|  |   |                                                                   | |        |
|  |   |  [Multiprocessing Pool] --> [Timeout Guard] --> [Score Collect]  | |        |
|  |   |        |                        |                      |          | |        |
|  |   |   max_workers=N           per-eval timeout         Caching        | |        |
|  |   |   Process isolation       Graceful kill            Content hash   | |        |
|  |   +------------------------------------------------------------------+ |        |
|  |                              |                                          |        |
|  |                              v                                          |        |
|  |   +------------------------------------------------------------------+ |        |
|  |   |                    Logging & Visualization                        | |        |
|  |   |                                                                   | |        |
|  |   |  W&B Integration  |  TensorBoard  |  CSV Export  |  Checkpoints  | |        |
|  |   +------------------------------------------------------------------+ |        |
|  +------------------------------------------------------------------------+        |
+-----------------------------------------------------------------------------------+

from llm4ad.methods import EoH

method = EoH(
    population_size=20,            # Population of (thought, code) pairs
    num_generations=50,            # Number of evolutionary generations
    crossover_rate=0.3,            # Probability of crossover vs mutation
    mutation_rate=0.7,             # Probability of mutation
    elite_size=3,                  # Top-3 preserved across generations
    thought_mutation_temp=0.9,     # Higher temp for thought diversity
    code_mutation_temp=0.7,        # Lower temp for code precision
    tournament_size=3,             # Tournament selection size
)

from llm4ad.methods import MEoH

method = MEoH(
    population_size=30,
    num_generations=100,
    objectives=["quality", "runtime"],
    directions=["maximize", "minimize"],
    crossover_rate=0.3,
    mutation_rate=0.7,
    reference_point=[0.0, 1000.0],   # For hypervolume computation
    objective_focus_strategy="lagging", # Focus mutation on lagging objectives
)

from llm4ad.methods import FunSearch

method = FunSearch(
    num_islands=10,                # Number of islands
    programs_per_island=50,        # Population per island
    num_samplers=4,                # Parallel LLM samplers
    samples_per_prompt=4,          # Candidates per LLM call
    temperature=1.0,               # High temperature for diversity
    top_k_for_prompt=2,            # Best-k examples in prompt
    reset_period=100,              # Reset worst island every N evals
    migration_interval=50,         # Migrate between islands
)

from llm4ad.methods import ReEvo

method = ReEvo(
    population_size=15,
    num_generations=60,
    reflection_depth=2,            # Number of reflection iterations per mutation
    short_term_memory=5,           # Recent reflections kept in context
    long_term_memory=20,           # Total reflections stored
    reflection_temperature=0.7,    # Temperature for reflection LLM calls
    mutation_temperature=0.8,      # Temperature for mutation LLM calls
)

# ReEvo reflection prompt (simplified)
"""
## Current Heuristic
{code}

## Evaluation Results
Score: {score}
Test case breakdown:
{per_case_results}

## Previous Reflections
{recent_reflections}

## Task
1. Analyze WHY this heuristic scored {score}
2. Identify the specific weakness causing failures
3. Propose a concrete improvement strategy
4. Explain how the improvement addresses the weakness

## Your Reflection:
"""

from llm4ad.methods import MCTSAHD

method = MCTSAHD(
    max_depth=8,                   # Maximum tree depth (algorithm complexity)
    num_simulations=200,           # MCTS simulations per step
    exploration_constant=1.414,    # UCB exploration parameter (sqrt(2))
    expansion_width=5,             # Number of children per expansion
    rollout_policy="llm",          # Use LLM for rollout (vs random)
    backprop_strategy="max",       # Backpropagate max score (vs average)
)

# (1+1)-EPS pseudocode
def eps_search(initial_solution, evaluate, llm, max_iterations):
    current = initial_solution
    current_score = evaluate(current)

    for i in range(max_iterations):
        # Mutate the current solution using LLM
        mutant = llm.mutate(current, feedback=get_feedback(current))

        # Evaluate the mutant
        mutant_score = evaluate(mutant)

        # Accept if improved (greedy)
        if mutant_score >= current_score:
            current = mutant
            current_score = mutant_score
            log(f"Iteration {i}: improved to {current_score}")

    return current, current_score

from llm4ad.methods import EPS

method = EPS(
    max_iterations=200,            # Total mutation attempts
    mutation_temperature=0.8,      # LLM temperature for mutations
    include_feedback=True,         # Include eval feedback in mutation prompt
    feedback_window=5,             # Include last 5 mutations in context
    restart_on_stagnation=True,    # Restart from best-so-far after N stagnant iters
    stagnation_threshold=30,       # Iterations without improvement to trigger restart
)

from llm4ad.methods import LLaMEA

method = LLaMEA(
    population_size=10,
    num_generations=30,
    algorithm_template="metaheuristic",  # Generate full metaheuristics
    benchmark_portfolio=[                # Evaluate on multiple problems
        "sphere_d10", "rastrigin_d10",
        "rosenbrock_d10", "ackley_d10",
    ],
    aggregation="geometric_mean",        # Aggregate scores across benchmarks
    mutation_strategy="component_swap",  # Swap algorithmic components
)

from llm4ad.llm import LLMBackend, LLMResponse

class MyBackend(LLMBackend):
    """Custom LLM backend for LLM4AD."""

    async def generate(self, prompt: str, **kwargs) -> LLMResponse:
        response = await my_api(prompt, **kwargs)
        return LLMResponse(
            text=response.text,
            tokens_used=response.total_tokens,
            model=self.model_name,
        )

    def get_model_info(self) -> dict:
        return {
            "name": self.model_name,
            "context_window": 128000,
            "supports_system_prompt": True,
        }

# Weights & Biases logging
runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    log_to="wandb",
    project_name="my-experiment",
    run_name="eoh-binpacking-v1",
    tags=["eoh", "binpacking", "gpt4o"],
)

# TensorBoard logging
runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    log_to="tensorboard",
    log_dir="./runs/experiment-1",
)

# Both simultaneously
runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    log_to=["wandb", "tensorboard"],
)

runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    max_workers=8,            # 8 parallel evaluation workers
    timeout_per_eval=60,      # Kill evaluation after 60 seconds
    memory_limit_mb=2048,     # 2GB memory limit per evaluation
    retry_on_timeout=True,    # Retry timed-out evaluations once
    gpu_allocation={          # GPU assignment per worker
        0: [0, 1],           # Workers 0-1 use GPU 0
        1: [2, 3],           # Workers 2-3 use GPU 1
    },
)

# Start a run with checkpointing
runner = LLM4AD(
    method=method,
    task=task,
    llm=llm,
    checkpoint_dir="./checkpoints/exp-1",
    checkpoint_interval=10,     # Checkpoint every 10 generations
)
result = runner.run()

# Resume from checkpoint after crash/interruption
runner = LLM4AD.resume("./checkpoints/exp-1")
result = runner.run()  # Continues from last checkpoint

from llm4ad import LLM4AD
from llm4ad.methods import EoH, FunSearch, ReEvo, MCTSAHD, EPS
from llm4ad.tasks import TSP
from llm4ad.llm import OpenAIBackend

llm = OpenAIBackend(model="gpt-4o")
task = TSP(instance="tsplib/eil51", metric="tour_length", direction="minimize")

methods = {
    "EoH": EoH(population_size=20, num_generations=50),
    "FunSearch": FunSearch(num_islands=5, programs_per_island=20),
    "ReEvo": ReEvo(population_size=15, num_generations=60),
    "MCTS-AHD": MCTSAHD(max_depth=8, num_simulations=200),
    "(1+1)-EPS": EPS(max_iterations=200),
}

results = {}
for name, method in methods.items():
    print(f"\n--- Running {name} ---")
    runner = LLM4AD(method=method, task=task, llm=llm, max_workers=4)
    results[name] = runner.run()
    print(f"{name}: best tour length = {results[name].best_score:.2f}")

# Compare results
print("\n=== Comparison ===")
for name, result in sorted(results.items(), key=lambda x: x[1].best_score):
    print(f"{name:15s}: {result.best_score:.2f} (evals: {result.stats.total_evaluations})")

from llm4ad import LLM4AD
from llm4ad.methods import FunSearch
from llm4ad.tasks import CirclePacking
from llm4ad.llm import GoogleBackend

task = CirclePacking(
    n=26,
    metric="packing_ratio",
    direction="maximize",
    evaluator="exact",             # Use exact geometric computation
    timeout_per_eval=120,          # Allow longer evals for large n
)

method = FunSearch(
    num_islands=15,
    programs_per_island=100,
    num_samplers=8,
    samples_per_prompt=8,
    temperature=1.0,
    top_k_for_prompt=3,
    reset_period=200,
)

llm = GoogleBackend(model="gemini-2.0-pro")
runner = LLM4AD(method=method, task=task, llm=llm, max_workers=16)
result = runner.run()

print(f"Best packing ratio: {result.best_score:.5f}")  # 2.63594