berg(ai)n

Sample music generated by bergain is available on soundcloud.

bergain is an experimental AI DJ that controls Ableton Live with thinking and reflection loops. A DSPy Recursive Language Model (RLM) browses sounds, creates tracks, writes MIDI clips, and manages live performance in real time based on a creative prompt.

Two Modes

• Palette mode (default): builds a session grid of looping clips organized by scene/energy. The human DJ fires scenes to perform.
• Live mode (--live): builds a palette first, then evolves it in real time. A sub-LM makes musical decisions while the human can type creative directions at any time. Scenes are overwritten and fired automatically.

Why RLMs?

bergain uses DSPy's Reactive Language Model — an LLM-as-programmer iterative loop. The RLM writes Python code that calls tools: it browses sounds, queries sub-LMs for creative decisions, writes MIDI clips, fires scenes. It adapts based on what it finds. Guardrails enforce musical structure (energy arc, variety, timing).

This is fundamentally different from single-shot generation using tools or models that generate entire songs: mistakes are recoverable, you can see the LLM think and reason in real-time, plans adapt to available instruments, and sub-LM queries produce genuine creative variation.

Requirements

• Python 3.11+
• uv
• Ableton Live (with AbletonOSC, see below. 30 day free trial available)
• Modal account (optional — for aesthetics scoring)

AbletonOSC Setup

AbletonOSC is a fork that serves as a bridge between the dSPY LLM and Ableton itself.

1. Clone the AbletonOSC fork:

   git clone git@github.com:smithclay/AbletonOSC.git
   

2. Symlink into Ableton's Remote Scripts:

   ln -s /path/to/AbletonOSC/abletonosc "$HOME/Music/Ableton/User Library/Remote Scripts/AbletonOSC"
   

3. In Ableton: Preferences → Link, Tempo & MIDI → Control Surface → select AbletonOSC from the dropdown.

   

4. Verify the connection:

   uv run bergain check
   

Install

pip install git+https://github.com/smithclay/bergain.git
cp .env.example .env  # add your API keys

Or for development:

git clone https://github.com/smithclay/bergain.git && cd bergain
uv sync
cp .env.example .env  # add your API keys

Usage

# Note: it takes several minutes for bergin to run, put on some ambient music and chill.
# Expect ~10 minutes or so for a song.

# Palette mode — builds session grid, auto-fires scenes, exports WAV, analyzes
bergain "Dark Berlin techno in F minor, 130 BPM"

# Live mode — builds palette, then evolves in real time (type directions or let it auto-evolve)
bergain --live --duration 10 "Evolving ambient in F minor"

# Dry run — print config without connecting to Ableton
bergain --dry-run "test brief"

# Verify OSC connection
bergain check

# Browse Ableton sounds
bergain-browse search "909"

Flags

Flag	Description	Default
--live	Live composition mode	off (palette)
--duration N	Target duration in minutes (live mode)	60
--model	Primary LM (LiteLLM string)	$BERGAIN_MODEL or openrouter/google/gemini-3-flash-preview
--sub-model	Sub-LM for creative queries	same as --model
--max-iterations	Max REPL iterations	30
--max-llm-calls	Max llm_query() calls	40
--min-clips	Minimum clips before SUBMIT	6
--bars-per-scene	Bars per scene for palette auto-fire	16
--skip-export	Skip audio recording/export	off
--analyze	Run Modal aesthetics analysis	off
--no-progress	Disable rich progress display	off
--output-dir	Output directory for reports and WAV	./output/compose/
--dry-run	Print config without connecting	off
--brief-file	Read brief from a file	-

Development

# Run tests (no Ableton needed — uses stub session)
uv run python -m pytest tests/ -v

# Lint and format
uvx ruff check --fix . && uvx ruff format .

# Deploy Modal endpoints (aesthetics scoring + audio analysis)
uvx modal deploy aesthetics/app.py

Environment Variables

Variable	Description
BERGAIN_MODEL	Default LM model string
BERGAIN_ANALYZER_URL	Modal Analyzer endpoint URL
BERGAIN_JUDGE_URL	Modal Judge endpoint URL

Architecture

bergain/cli.py          Unified CLI entry point
bergain/compose.py      DSPy RLM signature (Compose)
bergain/evolve.py       Live evolution engine (LiveEvolver)
bergain/tools.py        Tool closures over Session + milestone tracking
bergain/progress.py     Rich progress display (ProgressState + ProgressDisplay)
bergain/session.py      High-level API: tracks, clips, mix, recording
bergain/osc.py          Low-level UDP OSC client + Modal endpoints
bergain/music.py        Pure functions: chord math, drum/bass/pad renderers
bergain/spec_data.py    Typed AbletonOSC endpoint specifications
aesthetics/app.py       Modal GPU/CPU endpoints (Judge + Analyzer)