Connect your W&B experiments to AI agents for autonomous ML research loops.
Cadenza imports your Weights & Biases runs into an Evolutionary Database, organizing them into genotypes, islands, and elites. AI agents can then query this structured view to decide what to try next — closing the loop between experiment tracking and autonomous research.
- CLI and Python SDK primiarily for agents, but also for humans
- LLM-ready async client that returns structured context for autonomous research loops
- Lightweight: only two dependencies (
httpx,pydantic)
pip install cadenzaOr with uv:
uv pip install cadenzaRequires Python 3.11+.
Log in with your API token (generate one at www.myluca.ai):
cadenza login --token evodb_sk_...First, make sure your W&B credentials are configured:
cadenza config wandb.entity my-team
cadenza config wandb.api-key my-wandb-api-keyThen import a project:
cadenza import my-wandb-projectCheck import status:
cadenza import listOr add a single run incrementally:
cadenza add --run_id abc123def# List all projects
cadenza projects
# Set a default project so you don't have to pass -p every time
cadenza config defaults.project my-wandb-project
# View the genotype (search space + behavioral dimensions)
cadenza genotype
# List islands (subpopulations)
cadenza islands
# View the elite archive (top-performing experiments across all islands)
cadenza elites
# Get a compact JSON snapshot for agent consumption
cadenza sampleThe SDK exposes an async client for programmatic access — designed for AI agent integrations.
import asyncio
from cadenza import CadenzaClient
async def main():
async with CadenzaClient(token="evodb_sk_...", user_id="...") as client:
# List projects
projects = await client.list_projects()
for p in projects:
print(p.name, p.slug)
# Get the search space definition
genotype = await client.get_genotype("my-project")
for dim in genotype.behavioral_dimensions:
print(f" {dim.name}: {dim.description}")
# Browse islands and their experiments
islands = await client.list_islands("my-project")
for island in islands:
print(f"{island.island_name}: {island.phenotype_count} phenotypes")
experiments = await client.list_island_experiments(
"my-project", islands[0].island_name
)
# Get the elite archive
elites = await client.list_elites("my-project")
# Get a compact, LLM-ready context snapshot
context = await client.sample("my-project", top_phenotypes=3)
print(context.model_dump()) # JSON-serializable dict
asyncio.run(main())The sample method is the key integration point for autonomous research loops. It returns a compact snapshot of the evolutionary state — genotype, islands, and elite archive — that fits in an LLM context window:
from cadenza import CadenzaClient
async def agent_step(client: CadenzaClient, project: str):
# 1. Get current evolutionary state
context = await client.sample(project, top_phenotypes=5)
# 2. Feed to your LLM / agent
# context.genotype — search space definition
# context.islands — subpopulation summaries
# context.elite_archive — best solutions found so far
# 3. Agent decides next experiment based on context
# 4. Run experiment, log to W&B
# 5. Re-import and repeatresult = await client.start_wandb_import(
entity="my-team",
api_key="my-wandb-api-key",
projects=["project-a", "project-b"],
max_behavioral_dimensions=8,
elite_archive_size=10,
max_islands=20,
)
for job in result.imports:
print(f"{job.project}: {job.status}")
# Check import status
imports = await client.list_imports(status_filter="running")Use add_wandb_run to incrementally add individual runs to an existing project:
result = await client.add_wandb_run(
project_name="my-project",
entity="my-team",
api_key="my-wandb-api-key",
wandb_project="my-wandb-project",
run_id="abc123def",
)
for job in result.imports:
print(f"{job.project}: {job.status}")| Command | Description |
|---|---|
cadenza login [--token TOKEN] [--url URL] |
Authenticate with an API token |
cadenza status |
Show current auth status |
cadenza logout |
Remove stored credentials |
cadenza config # List all config values
cadenza config <key> # Get a value
cadenza config <key> <value> # Set a value| Command | Description |
|---|---|
cadenza projects |
List all accessible projects |
cadenza genotype [-p PROJECT] |
Show active genotype and behavioral dimensions |
cadenza islands [-p PROJECT] |
List islands and population stats |
cadenza experiments -i ISLAND [-p PROJECT] [--page N] |
List experiments in an island |
cadenza elites [-p PROJECT] |
Show the elite archive |
cadenza sample [-p PROJECT] [--top-phenotypes N] |
Generate LLM-ready JSON context |
| Command | Description |
|---|---|
cadenza import <wandb-project> |
Start importing a W&B project |
cadenza import list |
List active import jobs |
cadenza add --run_id RUN_ID [-p PROJECT] [--wandb-project NAME] |
Add a single W&B run to an existing project |
| Command | Description |
|---|---|
cadenza schema |
Output full command schema as machine-readable JSON |
All data query commands accept -p/--project to specify the project. Set a default with cadenza config defaults.project <name> to omit it.
Cadenza stores configuration in ~/.cadenza/config.toml. Manage it with cadenza config:
| Key | Type | Description |
|---|---|---|
wandb.entity |
string | W&B team or username for imports |
wandb.api-key |
string | W&B API key for imports |
defaults.project |
string | Default project for all -p flags |
sampling.p-explore |
float | Exploration probability for sampling |
sampling.p-exploit |
float | Exploitation probability for sampling |
evodb.max-dimensions |
int | Max behavioral dimensions during import |
evodb.elite-archive-size |
int | Elite archive size during import |
evodb.max-islands |
int | Max islands created during import |
Cadenza organizes ML experiment data using evolutionary algorithm concepts:
- Genotype — Defines the search space and behavioral dimensions for a project
- Islands — Subpopulations of experiments, each exploring a different region of the search space
- Phenotypes/Experiments — Individual ML runs with their metrics and behavioral coordinates
- Elites — The top-performing experiments across all islands (the elite archive)
- Sample — A compact JSON snapshot of the evolutionary state, designed for LLM consumption
Apache 2.0 — see LICENSE for details.