Cadenza

CLI and Python SDK for the Luca AI Evolutionary Database (EvoDB). Import experiments from Weights & Biases, explore evolutionary search spaces, and power autonomous ML research loops.

Overview

Cadenza connects your ML experiment tracking (Weights & Biases) with Luca AI's Evolutionary Database. It organizes experiments into an evolutionary structure — genotypes define the search space, islands partition subpopulations, and an elite archive tracks the top-performing experiments.

While human researchers can use Cadenza directly, it is primarily designed for LLM-based AI agents running autonomous research loops. The sample command generates compact, LLM-ready JSON context snapshots that agents consume to decide their next experiment.

CLI

12 commands for authentication, querying the evolutionary database, importing W&B projects, and generating agent context.

CLI Reference →

Python SDK

Async CadenzaClient class with full programmatic access to all EvoDB operations.

SDK Reference →

Installation

Prerequisites

Python 3.11 or higher
pip or uv package manager
Luca account with an API token (evodb_sk_...)

Install via pip

Install Cadenzabash

pip install cadenza

Or with uv

Install with uvbash

uv pip install cadenza

Verify Installation

Check installationbash

cadenza --help

This should display the help message with all available commands.

Quick Start

Step 1: Authenticate

cadenza login --token evodb_sk_your_token_here

Generate a token from your account at app.myluca.ai. Tokens must start with evodb_sk_.

Step 2: Configure W&B

Set W&B credentialsbash

cadenza config wandb.entity your-wandb-team
cadenza config wandb.api-key your-wandb-api-key

Step 3: Import a Project

Import from W&Bbash

cadenza import my-wandb-project

This starts an import job that pulls your W&B runs into the evolutionary database.

Step 4: Explore

Explore the evolutionary databasebash

# List your projects
cadenza projects

# View the search space
cadenza genotype -p my-project

# See subpopulations
cadenza islands -p my-project

# Get the elite archive
cadenza elites -p my-project

# Generate an LLM-ready context snapshot
cadenza sample -p my-project

Core Concepts

Cadenza organizes ML experiments into an evolutionary structure. Understanding these concepts is key to using the CLI and SDK effectively.

Genotype

Defines the search space for a project. A genotype includes behavioral dimensions — named axes (e.g., “learning_rate_strategy”, “architecture_type”) that describe how experiments differ from each other. Think of it as the coordinate system for your experiment space.

Islands

Subpopulations that explore different regions of the search space. Each island groups experiments with similar behavioral characteristics. Islands enable diversity — instead of converging on a single optimum, the system maintains multiple promising directions.

Experiments (Phenotypes)

Individual ML runs within an island. Each experiment has a title, description, status, behavioral coordinates (its position in the search space), and a link back to its W&B source. Experiments are the leaves of the evolutionary tree.

Elites

The elite archive contains the top-performing experiments across all islands. Each elite has fitness scores and behavioral coordinates. The archive is the evolutionary memory — it tracks the best solutions found so far and guides future exploration.

Sample

A compact JSON snapshot of the current evolutionary state, optimized for LLM consumption. Includes the genotype definition, island summaries, and top-performing elites. This is the primary interface for AI agents — they read a sample, decide what experiment to run next, and repeat.

Configuration

Configuration is stored in ~/.cadenza/config.toml. Use cadenza config to get and set values.

Key	Type	Description
`wandb.entity`	string	Your W&B team or username
`wandb.api-key`	string	Your W&B API key
`defaults.project`	string	Default project name (avoids passing `-p` every time)
`sampling.p-explore`	float	Exploration probability for sampling
`sampling.p-exploit`	float	Exploitation probability for sampling
`evodb.max-dimensions`	int	Maximum behavioral dimensions for imports
`evodb.elite-archive-size`	int	Maximum size of the elite archive
`evodb.max-islands`	int	Maximum number of islands for imports

Agent Loop Pattern

The primary use case for Cadenza is powering autonomous ML research loops. An AI agent repeatedly samples the evolutionary state, decides what experiment to run next, executes it, and feeds results back into the database.

The Loop

Sample — Get a compact snapshot of the current evolutionary state (genotype, islands, elites).

Decide — Feed the sample to an LLM. It analyzes the search space, current elites, and under-explored regions to propose the next experiment.

Execute — Run the experiment and log results to W&B.

Import — Re-import from W&B so the new experiment enters the evolutionary database.

Repeat — The elite archive updates, islands evolve, and the next sample reflects the new state.

Using the CLI

CLI agent loopbash

# Agent samples the current state
cadenza sample -p my-project --top-phenotypes 5

# Output is compact JSON — feed directly to your LLM
# {
#   "genotype": { ... behavioral dimensions ... },
#   "islands": [ ... island summaries ... ],
#   "elite_archive": [ ... top experiments ... ]
# }

Using the Python SDK

Python SDK agent looppython

from cadenza import CadenzaClient

async def agent_step(client: CadenzaClient, project: str):
    # 1. Get the current evolutionary state
    context = await client.sample(project, top_phenotypes=5)

    # 2. Feed to your LLM
    # context.genotype   — search space definition
    # context.islands    — subpopulation summaries
    # context.elite_archive — best experiments so far
    llm_input = context.model_dump()

    # 3. LLM decides next experiment → run it → log to W&B
    # 4. Re-import
    await client.start_wandb_import(
        entity="my-team",
        api_key="...",
        projects=[project],
    )

    # 5. Repeat

Need more help? Contact support

CLI Reference →Python SDK →