# nicola-ibrahim/aad_llm architecture

> Architecture diagram of the GitHub repository nicola-ibrahim/aad_llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nicola-ibrahim/aad_llm
- Repository: https://github.com/nicola-ibrahim/aad_llm
- Video tour (about a minute): https://gitdiagram.com/nicola-ibrahim/aad_llm/video

## Overview

aad-llm is a notebook-first research framework that evolves Python black-box optimizers with an LLM, evaluates candidates on noisy BBOB problems, and independently benchmarks selected champions against classical methods. The map follows the documented experiment workflow and preserves separate audit, statistical-analysis, and optional generalization branches. Paths come from the supplied tree; several application and analysis internals were not sampled, so their uncertain call wiring is intentionally omitted.

Main entry points: [`src/evolution/application/campaign/run.py`](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/campaign/run.py) (Synthesis campaign), [`src/evolution/application/synthesis/run.py`](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/synthesis/run.py) (Synthesis session), [`src/evolution/infra/engines/llamea/runner.py`](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/runner.py) (LLaMEA adapter), [`src/benchmarking/application/analysis/report.py`](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/analysis/report.py) (Statistical analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_synthesis["Algorithm synthesis"]
  node_campaign["Synthesis campaign<br/>[run.py]"]
  node_campaign_plan["Campaign planning<br/>[plan.py]"]
  node_synth_config["Synthesis configuration<br/>[repository.py]"]
  node_single_synthesis["Synthesis session<br/>[run.py]"]
end

subgraph group_runtime["Candidate execution"]
  node_llamea["LLaMEA adapter<br/>[runner.py]"]
  node_prompts["Prompt construction<br/>[builder.py]"]
  node_llm_client["LLM provider client<br/>[client.py]"]
  node_candidate_evaluator["Candidate evaluator<br/>[evaluator.py]"]
  node_guarded_executor["Guarded execution<br/>[executor.py]"]
  node_problem_factory["BBOB problem factory<br/>[factory.py]"]
  node_noise_model["Noise model<br/>[noise_model.py]"]
end

subgraph group_benchmark["Benchmarking and audit"]
  node_evaluation["Champion and baseline trials<br/>[run.py]"]
  node_baselines["Classical optimizers<br/>[baselines.py]"]
  node_champions["Champion selection"]
  node_audit["Coverage and run audit<br/>[audit.py]"]
end

subgraph group_analysis["Analysis and transfer"]
  node_analysis["Statistical analysis<br/>[report.py]"]
  node_analysis_services["ECDF and statistics<br/>[ecdf.py]"]
  node_transfer["Noise and transfer analysis<br/>[transfer.py]"]
  node_figures["Analysis figures<br/>[summary.py]"]
end

subgraph group_persistence["Experiment persistence"]
  node_code_store["Candidate code store<br/>[repository.py]"]
  node_synthesis_store[("Synthesis records<br/>[repository.py]")]
  node_database[("SQLite database<br/>[engine.py]")]
  node_trace_repo["Benchmark traces"]
end

node_researcher(("Notebook researcher"))
node_llm_service{{"LLM provider"}}

node_researcher -->|"starts campaign"| node_campaign
node_researcher -->|"runs trials"| node_evaluation
node_researcher -->|"audits coverage"| node_audit
node_researcher -->|"analyses results"| node_analysis
node_campaign -->|"plans matrix"| node_campaign_plan
node_campaign -->|"loads settings"| node_synth_config
node_campaign -->|"dispatches sessions"| node_single_synthesis
node_single_synthesis -->|"runs synthesis"| node_llamea
node_llamea -->|"builds prompts"| node_prompts
node_llamea -->|"requests generations"| node_llm_client
node_llm_client -->|"calls provider"| node_llm_service
node_llamea -->|"evaluates candidates"| node_candidate_evaluator
node_candidate_evaluator -->|"executes candidate"| node_guarded_executor
node_candidate_evaluator -->|"creates objective"| node_problem_factory
node_problem_factory -->|"applies noise"| node_noise_model
node_single_synthesis -->|"persists code"| node_code_store
node_single_synthesis -->|"records iterations"| node_synthesis_store
node_evaluation -->|"runs baselines"| node_baselines
node_evaluation -->|"writes traces"| node_trace_repo
node_champions -->|"reads candidates"| node_synthesis_store
node_audit -->|"checks trace coverage"| node_trace_repo
node_analysis -->|"reads traces"| node_trace_repo
node_analysis -->|"computes metrics"| node_analysis_services
node_analysis -->|"presents results"| node_figures
node_transfer -.->|"writes isolated traces"| node_trace_repo

click node_campaign "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/campaign/run.py"
click node_campaign_plan "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/campaign/plan.py"
click node_synth_config "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/synthesis_config/repository.py"
click node_single_synthesis "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/synthesis/run.py"
click node_llamea "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/runner.py"
click node_prompts "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/prompts/builder.py"
click node_llm_client "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/llm/client.py"
click node_candidate_evaluator "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/evaluator.py"
click node_guarded_executor "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/execution/executor.py"
click node_problem_factory "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/problems/factory.py"
click node_noise_model "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/domain/noise_model.py"
click node_code_store "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/code/repository.py"
click node_synthesis_store "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/synthesis/repository.py"
click node_database "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/database/engine.py"
click node_evaluation "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/evaluation/run.py"
click node_baselines "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/infra/solvers/baselines.py"
click node_champions "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/select_champions.py"
click node_trace_repo "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/infra/io/trace_repository.py"
click node_audit "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/evaluation/audit.py"
click node_analysis "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/analysis/report.py"
click node_analysis_services "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/domain/services/ecdf.py"
click node_transfer "https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/domain/services/transfer.py"
click node_figures "https://github.com/nicola-ibrahim/aad_llm/blob/main/notebooks/analysis/plotting/summary.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_campaign,node_campaign_plan,node_synth_config,node_single_synthesis toneBlue
class node_llamea,node_prompts,node_llm_client,node_candidate_evaluator,node_guarded_executor,node_problem_factory,node_noise_model toneAmber
class node_evaluation,node_baselines,node_champions,node_audit toneMint
class node_analysis,node_analysis_services,node_transfer,node_figures toneRose
class node_code_store,node_synthesis_store,node_database,node_trace_repo,node_researcher,node_llm_service toneIndigo
```

## Components

### Algorithm synthesis

- [Synthesis campaign](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/campaign/run.py): `src/evolution/application/campaign/run.py`
- [Campaign planning](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/campaign/plan.py): `src/evolution/application/campaign/plan.py`
- [Synthesis configuration](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/synthesis_config/repository.py): `src/evolution/infra/storage/synthesis_config/repository.py`
- [Synthesis session](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/application/synthesis/run.py): `src/evolution/application/synthesis/run.py`

### Candidate execution

- [LLaMEA adapter](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/runner.py): `src/evolution/infra/engines/llamea/runner.py`
- [Prompt construction](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/prompts/builder.py): `src/evolution/infra/engines/llamea/prompts/builder.py`
- [LLM provider client](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/llm/client.py): `src/evolution/infra/llm/client.py`
- [Candidate evaluator](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/engines/llamea/evaluator.py): `src/evolution/infra/engines/llamea/evaluator.py`
- [Guarded execution](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/execution/executor.py): `src/shared/infra/execution/executor.py`
- [BBOB problem factory](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/problems/factory.py): `src/shared/infra/problems/factory.py`
- [Noise model](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/domain/noise_model.py): `src/shared/domain/noise_model.py`

### Benchmarking and audit

- [Champion and baseline trials](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/evaluation/run.py): `src/benchmarking/application/evaluation/run.py`
- [Classical optimizers](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/infra/solvers/baselines.py): `src/benchmarking/infra/solvers/baselines.py`
- [Champion selection](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/select_champions.py): `src/benchmarking/application/select_champions.py`
- [Coverage and run audit](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/evaluation/audit.py): `src/benchmarking/application/evaluation/audit.py`

### Analysis and transfer

- [Statistical analysis](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/application/analysis/report.py): `src/benchmarking/application/analysis/report.py`
- [ECDF and statistics](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/domain/services/ecdf.py): `src/benchmarking/domain/services/ecdf.py`
- [Noise and transfer analysis](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/domain/services/transfer.py): `src/benchmarking/domain/services/transfer.py`
- [Analysis figures](https://github.com/nicola-ibrahim/aad_llm/blob/main/notebooks/analysis/plotting/summary.py): `notebooks/analysis/plotting/summary.py`

### Experiment persistence

- [Candidate code store](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/code/repository.py): `src/evolution/infra/storage/code/repository.py`
- [Synthesis records](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/evolution/infra/storage/synthesis/repository.py): `src/evolution/infra/storage/synthesis/repository.py`
- [SQLite database](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/shared/infra/database/engine.py): `src/shared/infra/database/engine.py`
- [Benchmark traces](https://github.com/nicola-ibrahim/aad_llm/blob/main/src/benchmarking/infra/io/trace_repository.py): `src/benchmarking/infra/io/trace_repository.py`

### Other components

- **Notebook researcher**
- **LLM provider**

## Connections

- Notebook researcher → Synthesis campaign: starts campaign
- Notebook researcher → Champion and baseline trials: runs trials
- Notebook researcher → Coverage and run audit: audits coverage
- Notebook researcher → Statistical analysis: analyses results
- Synthesis campaign → Campaign planning: plans matrix
- Synthesis campaign → Synthesis configuration: loads settings
- Synthesis campaign → Synthesis session: dispatches sessions
- Synthesis session → LLaMEA adapter: runs synthesis
- LLaMEA adapter → Prompt construction: builds prompts
- LLaMEA adapter → LLM provider client: requests generations
- LLM provider client → LLM provider: calls provider
- LLaMEA adapter → Candidate evaluator: evaluates candidates
- Candidate evaluator → Guarded execution: executes candidate
- Candidate evaluator → BBOB problem factory: creates objective
- BBOB problem factory → Noise model: applies noise
- Synthesis session → Candidate code store: persists code
- Synthesis session → Synthesis records: records iterations
- Champion and baseline trials → Classical optimizers: runs baselines
- Champion and baseline trials → Benchmark traces: writes traces
- Champion selection → Synthesis records: reads candidates
- Coverage and run audit → Benchmark traces: checks trace coverage
- Statistical analysis → Benchmark traces: reads traces
- Statistical analysis → ECDF and statistics: computes metrics
- Statistical analysis → Analysis figures: presents results
- Noise and transfer analysis → Benchmark traces: writes isolated traces