### Manual Python Virtual Environment Setup

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Manually creates and activates a Python virtual environment and installs dependencies from requirements.txt.

```bash
python3 -m venv data_work/.venv
source data_work/.venv/bin/activate
pip install -r data_work/requirements.txt
```

--------------------------------

### Install LatentScore

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Installation commands for the library using pip or conda.

```bash
pip install latentscore
```

```bash
conda create -n latentscore python=3.10 -y
conda activate latentscore
pip install latentscore
```

--------------------------------

### CLI usage

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Command-line interface commands for checking setup, playing demos, and saving output.

```bash
latentscore doctor                       # check setup and model availability
latentscore demo                         # render and play a sample
latentscore demo --duration 30           # 30-second demo
latentscore demo --output ambient.wav    # save to file
```

--------------------------------

### Install Dependencies with Pip

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

For users who prefer pip, install project dependencies directly from 'requirements.txt'. This is an alternative to using 'environment.yml'.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install and Download Expressive LLM

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Installs the necessary package for expressive mode and downloads the model. This mode is for experimentation and not recommended for production.

```bash
pip install 'latentscore[expressive]'
latentscore download expressive
```

--------------------------------

### Install Linux Prerequisites

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

On Linux systems, install SoX and ALSA development headers required for audio playback. This command updates package lists and installs the necessary packages.

```bash
sudo apt-get update
sudo apt-get install -y sox libasound2-dev
```

--------------------------------

### Quickstart Audio Rendering

Source: https://github.com/prabal-rje/latentscore/blob/main/latentscore/README.md

Renders audio from a text prompt and plays or saves it. Requires `sounddevice` or `simpleaudio` for playback. Use in notebooks requires `ipython`.

```python
import latentscore as ls

audio = ls.render("warm sunrise over water")
audio.play()  # uses sounddevice/simpleaudio; install ipython for notebooks
audio.save(".examples/quickstart.wav")
```

--------------------------------

### Setup Local Python Virtual Environment

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Uses a helper script to set up a local Python virtual environment. Activate it using the provided source command.

```bash
./data_work/setup_python_env.sh
source data_work/.venv/bin/activate
```

--------------------------------

### Run Full Config File CLI

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Example of running a training script using a full configuration file specified via the command line.

```bash
# Full config file
python -m data_work.03_modal_train grpo \
  --config-file experiments/ablation_lr.json \
  --model checkpoints/sft \
  --data data/train.jsonl \
  --output grpo-from-config \
  --epochs 3
```

--------------------------------

### Install LatentScore and Restart Runtime

Source: https://github.com/prabal-rje/latentscore/blob/main/notebooks/quickstart.ipynb

Installs the LatentScore library from GitHub and restarts the Colab runtime to ensure the installation is recognized.

```python
!pip install -q git+https://github.com/prabal-rje/latentscore.git@main

import os
os.kill(os.getpid(), 9)  # restarts the Colab runtime
```

--------------------------------

### Run Ablation Preset CLI

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Example of running a training script using a predefined ablation preset via the command line. Requires the `--advanced` flag.

```bash
# Using ablation preset (requires --advanced)
python -m data_work.03_modal_train --advanced grpo \
  --model checkpoints/sft \
  --data data/train.jsonl \
  --output grpo-lora-r32 \
  --epochs 3 \
  --ablation-preset lora_rank:r32
```

--------------------------------

### Training Configuration JSON

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Example JSON structure for defining a complete training configuration, including model, optimizer, and GRPO settings.

```json
{
  "base_model": "gemma3-270m",
  "epochs": 3,
  "seed": 42,
  "lora": {
    "r": 32,
    "alpha": 32,
    "dropout": 0.05
  },
  "optimizer": {
    "learning_rate": 1e-4,
    "warmup_ratio": 0.1
  },
  "grpo": {
    "beta": 0.02,
    "num_generations": 6,
    "reward": {
      "weights": {
        "format_weight": 0.15,
        "schema_weight": 0.35,
        "audio_weight": 0.5
      }
    }
  }
}
```

--------------------------------

### Install SoX on macOS

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

Install the SoX audio utility on macOS using Homebrew. This is a prerequisite for audio playback.

```bash
brew install sox
```

--------------------------------

### Generate Music Configs Script Usage

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Example for generating music configurations from vibes using a SOTA model. Supports best-of-N sampling and validation.

```bash
python -m data_work.02b_generate_configs \
  --input-dir data_work/.vibes \
  --output-dir data_work/.processed \
  --model gemini/gemini-3-flash-preview \
  --num-candidates 3 \
  --temperature 0.8 \
  --max-concurrency 10 \
  --max-qps 5.0 \
  --seed 42
```

--------------------------------

### Generate and play ambient music

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

A simple one-line example to generate and play audio from a text prompt.

```python
import latentscore as ls

ls.render("warm sunset over water").play()
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Sets up a dedicated conda environment for data-related tasks. Ensure you have conda installed.

```bash
conda env create -f data_work/environment.yml
conda activate latentscore-data
```

--------------------------------

### Editable Pip Install

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

Install the project in editable mode using pip. This is useful for development, allowing changes in the source code to be reflected immediately without reinstallation.

```bash
pip install -e .
```

--------------------------------

### Get and Print Prompt Template

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Demonstrates how to retrieve a prompt template from the prompt registry using `get_prompt`. Requires `common.prompt_registry` and `PromptVersion`.

```python
from common.prompt_registry import get_prompt, register_prompt, PromptVersion

# Get current prompt
current = get_prompt("system_v1")
print(current.template)
```

--------------------------------

### Generate different vibes

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Examples of generating audio for various atmospheric prompts.

```python
ls.render("jazz cafe at midnight").play()
ls.render("thunderstorm on a tin roof").play()
ls.render("lo-fi study beats").play()
```

--------------------------------

### Tweak Music Generation with MusicConfigUpdate (Absolute)

Source: https://github.com/prabal-rje/latentscore/blob/main/notebooks/quickstart.ipynb

Starts music generation from a vibe string and modifies specific parameters using `MusicConfigUpdate` for absolute changes.

```python
audio = ls.render(
    "morning coffee shop",
    duration=10.0,
    update=ls.MusicConfigUpdate(
        brightness="very_bright",
        rhythm="electronic",
    ),
)
listen(audio)
```

--------------------------------

### Pytest examples for async notification function

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/examples.md

Includes two pytest examples for testing the `notify_user` function. One tests successful sending, and the other tests early exit when a recipient is missing. Requires `pytest-asyncio`.

```python
import pytest

@pytest.mark.asyncio
async def test_notify_user_sends_once():
    fake = FakeSender()
    await notify_user(fake, "a@example.com", "Hi", "Body")
    assert fake.sent == [("a@example.com", "Hi", "Body")]

@pytest.mark.asyncio
async def test_notify_user_early_exit_on_missing_recipient():
    fake = FakeSender()
    await notify_user(fake, "", "Hi", "Body")
    assert fake.sent == []
```

--------------------------------

### Run Single Parameter Override CLI

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Example of running a training script with a single parameter override via the command line.

```bash
# Single parameter override
python -m data_work.03_modal_train grpo \
  --model checkpoints/sft \
  --data data/train.jsonl \
  --output grpo-beta02 \
  --epochs 3 \
  --beta 0.02 \
  --lora-r 32
```

--------------------------------

### Download Base Data Script Usage

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Example of how to run the script for downloading and sampling Common Pile datasets. Specify output directory and sampling parameters.

```bash
python -m data_work.01_download_base_data \
  --seed 123 \
  --sample-size 1000 \
  --output-dir data_work/.outputs
```

--------------------------------

### Run Reward Weight Overrides CLI

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Example of running a training script with custom reward weight overrides via the command line. Requires the `--advanced` flag.

```bash
# With reward weight overrides (requires --advanced)
python -m data_work.03_modal_train --advanced grpo \
  --model checkpoints/sft \
  --data data/train.jsonl \
  --output grpo-custom-rewards \
  --epochs 3 \
  --format-weight 0.3 \
  --schema-weight 0.4 \
  --audio-weight 0.3
```

--------------------------------

### Step 2: Config Generation (02b)

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Generates configurations using a specified LLM, with parameters for candidate generation, temperature, and concurrency. High concurrency is used to leverage the model's rate limit. Batching is enabled for cost efficiency.

```bash
conda run -n latentscore-data python -m data_work.02b_generate_configs \
  --input-dir data_work/2026-01-26_vibes \
  --output-dir data_work/2026-01-26_processed \
  --model gemini/gemini-3-flash-preview \
  --api-key-env GEMINI_API_KEY \
  --env-file .env \
  --num-candidates 5 \
  --temperature 0.8 \
  --seed 42 \
  --max-concurrency 500 \
  --max-qps 300.0
```

--------------------------------

### Render Hooks for Progress

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/latentscore-dx.md

Attaches render hooks to capture events during blocking renders, such as model start, synthesis start, and completion. Events are collected in a list.

```python
import latentscore as ls

events: list[str] = []
hooks = ls.RenderHooks(
    on_start=lambda: events.append("start"),
    on_model_start=lambda model: events.append(f"model:{model}"),
    on_synth_start=lambda: events.append("synth_start"),
    on_end=lambda: events.append("end"),
)

audio = ls.render("underwater cave", hooks=hooks)
```

--------------------------------

### CLI Utilities

Source: https://context7.com/prabal-rje/latentscore/llms.txt

Command-line interface commands for system diagnostics, demo playback, and asset management.

```bash
# Check setup and model availability
latentscore doctor

# Render and play a demo clip
latentscore demo

# Render a longer demo
latentscore demo --duration 30

# Save demo to a specific file
latentscore demo --output my_ambient.wav

# Download optional expressive model for local LLM inference
latentscore download expressive
```

--------------------------------

### Run Model-Specific Baseline Training for Gemma3 and Qwen3

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Commands to perform SFT and GRPO training for specific model architectures with tailored sampling parameters.

```bash
# Gemma3-270M-IT (Unsloth sampling guidance)
conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output exp-sft-base-gemma3-270m \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --base-model gemma3-270m \
  --overwrite

conda run -n latentscore-data python -m data_work.03_modal_train grpo \
  --data data_work/.processed/GRPO.jsonl \
  --model unsloth/gemma-3-270m-it \
  --init-adapter-dir exp-sft-base-gemma3-270m \
  --output exp-grpo-base-gemma3-270m \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --max-completion-length 2048 \
  --temperature 0.8 \
  --top-p 0.95 \
  --top-k 64 \
  --overwrite

# Qwen3-0.6B (disable thinking mode via chat template)
conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output exp-sft-base-qwen3-600m \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --base-model qwen3-600m \
  --overwrite

conda run -n latentscore-data python -m data_work.03_modal_train grpo \
  --data data_work/.processed/GRPO.jsonl \
  --model unsloth/Qwen3-0.6B \
  --init-adapter-dir exp-sft-base-qwen3-600m \
  --output exp-grpo-base-qwen3-600m \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --max-completion-length 2048 \
  --temperature 0.7 \
  --top-p 0.8 \
  --top-k 20 \
  --overwrite
```

--------------------------------

### Show All Options for Generate Configs

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

This command displays all available command-line options for the 'generate_configs' module, useful for understanding its full capabilities.

```bash
python -m data_work.02b_generate_configs --help
```

--------------------------------

### GET /get_prompt

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Retrieves a registered prompt template by its name.

```APIDOC
## GET /get_prompt

### Description
Retrieves the template associated with a specific prompt name.

### Method
GET

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the prompt to retrieve

### Response
#### Success Response (200)
- **template** (string) - The template string associated with the prompt
```

--------------------------------

### Update Payload Constructor

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/plans/2026-01-19-title-payload-implementation-plan.md

Example of updating the payload instantiation to include the new title parameter.

```python
MusicConfigPromptPayload(thinking=..., title=..., config=..., palettes=...)
```

--------------------------------

### Run Latentscore Demo

Source: https://github.com/prabal-rje/latentscore/blob/main/latentscore/README.md

Executes the Latentscore demonstration script. This is a command-line utility.

```bash
python -m latentscore.demo
```

--------------------------------

### Run Supervised Fine-Tuning (SFT) with Modal

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/METHODOLOGY.md

Execute the SFT training script using Modal, specifying training and validation data, output directory, base model, and various hyperparameters. This command initiates the fine-tuning process for the model.

```bash
conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/2026-01-26_scored/SFT-Train.jsonl \
  --val-data data_work/2026-01-26_scored/SFT-Val.jsonl \
  --output prod-sft-gemma3-270m-v4 \
  --overwrite \
  --base-model gemma3-270m \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --lr 1e-4 \
  --lr-scheduler cosine \
  --warmup-ratio 0.06 \
  --weight-decay 0.01 \
  --lora-r 16 \
  --lora-alpha 16 \
  --lora-dropout 0.0 \
  --lora-bias none \
  --max-seq-length 4096 \
  --optim adamw_8bit \
  --seed 42 \
  --download-dir data_work/.modal_outputs
```

--------------------------------

### Benchmark Dataset Configurations with LAION-CLAP

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Use this script to benchmark dataset configurations against LiteLLM and local Hugging Face models. Supports multiprocess parallelism with `--workers N` and tracks per-sample timing and success rates. Arguments use `value:label` format for custom display names in benchmark output.

```bash
python -m data_work.04_clap_benchmark \
  --input data_work/.processed/TEST.jsonl \
  --dataset-field config_payload:synthetic \
  --litellm-model openrouter/openai/gpt-oss-20b:teacher \
  --api-key-env OPENROUTER_API_KEY \
  --env-file .env \
  --limit 10
```

```bash
python -m data_work.04_clap_benchmark \
  --input data_work/.processed/TEST.jsonl \
  --local-model /path/to/sft-model:finetuned \
  --limit 10
```

```bash
conda run -n latentscore-data python -m data_work.04_clap_benchmark \
  --input data_work/.experiments/eval_assets/test_subset_200.jsonl \
  --baseline random \
  --baseline embedding_lookup \
  --litellm-model gemini/gemini-3-flash-preview:gemini_flash \
  --litellm-model anthropic/claude-opus-4-5-20251101:opus_4.5 \
  --local-model guprab/latentscore-gemma3-270m-v5-merged:sft_finetuned \
  --local-model unsloth/gemma-3-270m-it:base_untrained \
  --local-temperature 1.0 \
  --limit 200 --workers 5 --duration 60 \
  --keep-audio \
  --output-dir data_work/.experiments/eval_assets/clap_200row_final_noprefix \
  --env-file .env
```

--------------------------------

### Functional Style for Data Processing

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/coding-guidelines.md

Examples demonstrating functional approaches versus imperative accumulation for list processing.

```python
# GOOD: Functional style
def sum_scores(items: list[dict[str, float]]) -> float:
    scores = map(lambda x: x["score"], items)
    valid_scores = filter(lambda s: s > 0, scores)
    return reduce(add, valid_scores, 0.0)


# GOOD: List comprehension for simple cases
def get_names(users: list[User]) -> list[str]:
    return [u.name for u in users if u.active]


# BAD: Imperative accumulation
def sum_scores(items: list[dict[str, float]]) -> float:
    total = 0.0
    for item in items:
        score = item["score"]
        if score > 0:
            total += score
    return total
```

--------------------------------

### Commit Payload Producer Updates

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/plans/2026-01-19-title-payload-implementation-plan.md

Git commands to stage and commit updates to payload producers and prompt examples.

```bash
git add data_work/lib/baselines.py data_work/02b_generate_configs.py latentscore/prompt_examples.py tests/test_litellm_adapter.py tests/test_models_prompt.py
git commit -m "feat: add title to payload producers"
```

--------------------------------

### Launch Modal-based SFT + GRPO Training

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

This command launches Modal-based SFT + GRPO training for tiny models. It defaults to using the 'vibe_noisy' column and full config payload. Specify the base model and optionally an adapter directory for GRPO. Debugging options are available for prompts.

```bash
python -m data_work.03_modal_train \
  --model unsloth/gemma-3-270m-it \
  --init-adapter-dir path/to/sft/lora/adapters \
  --debug-prompts \
  --debug-prompts-max 5
```

--------------------------------

### Create Conda Environment

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

Use this command to create a new Conda environment from the 'environment.yml' file. Ensure you have Conda installed.

```bash
conda env create -f environment.yml
```

--------------------------------

### Score Configurations with Multiple Methods

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Use this command to score generated configurations using multiple scoring methods and perform quality-based Best-of-N selection. Specify input and output directories, and a comma-separated list of scorers.

```bash
python -m data_work.02c_score_configs \
  --input-dir data_work/.processed \
  --output-dir data_work/.scored \
  --scorers 'clap,llm_judge' \
  --env-file .env
```

--------------------------------

### ls.render

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/latentscore-dx.md

Renders audio from a text prompt and returns an Audio object.

```APIDOC
## ls.render(prompt, model=..., hooks=...)

### Description
Generates audio based on a provided text prompt.

### Parameters
#### Arguments
- **prompt** (str) - Required - The text description for the audio generation.
- **model** (str|Adapter|Spec) - Optional - The model to use for generation (default: "fast").
- **hooks** (RenderHooks) - Optional - Callbacks for tracking generation progress.

### Response
- **Audio** (object) - An object supporting .play(), .save(), and conversion to numpy array.
```

--------------------------------

### Run SFT, GRPO, and Evaluation for Baseline Comparison

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Executes training and evaluation pipelines for SFT and GRPO baseline experiments.

```bash
conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output exp-sft-baseline \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --base-model gemma3-270m \
  --overwrite

conda run -n latentscore-data python -m data_work.03_modal_train grpo \
  --data data_work/.processed/GRPO.jsonl \
  --model unsloth/gemma-3-270m-it \
  --init-adapter-dir exp-sft-baseline \
  --output exp-grpo-baseline \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --max-completion-length 2048 \
  --num-generations 4 \
  --beta 0.04 \
  --temperature 0.8 \
  --top-p 0.95 \
  --top-k 64 \
  --overwrite

conda run -n latentscore-data python -m data_work.06_eval_suite \
  --eval-set short_prompts \
  --baseline random \
  --output-dir data_work/.experiments/eval_results/sft_vs_grpo
```

--------------------------------

### Run SFT prompt ablation variants

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Compares model performance using default versus detailed system prompts during SFT training.

```bash
conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output exp-sft-prompt-default \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --overwrite

conda run -n latentscore-data python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output exp-sft-prompt-detailed \
  --epochs 3 \
  --batch-size 16 \
  --grad-accum 1 \
  --max-seq-length 4096 \
  --system-prompt "You are an expert sound designer. Return only JSON matching the schema." \
  --overwrite
```

--------------------------------

### Extract Vibes Script Usage

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Example for extracting structured vibe objects from text. This script handles deduplication and diversity sampling for training data.

```bash
python -m data_work.02a_extract_vibes \
  --input-dir data_work/.outputs \
  --output-dir data_work/.vibes \
  --model openrouter/openai/gpt-oss-120b \
  --seed 42 \
  --error-rate 0.15 \
  --dedupe-threshold 0.95
```

--------------------------------

### CLAP Benchmark

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/METHODOLOGY.md

Command to run the CLAP benchmark with specified parameters including number of sources, rows, and audio handling.

```bash
04_clap_benchmark --keep-audio
```

--------------------------------

### Run Synth Sensitivity Analysis

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Executes the synth sensitivity analysis script using a specified input configuration file.

```bash
conda run -n latentscore-data python -m data_work.08_synth_sensitivity \
  --input data_work/.experiments/mini_configs.jsonl \
  --limit 1 \
  --output-dir data_work/.experiments/synth_sensitivity
```

--------------------------------

### Activate Conda Environment

Source: https://github.com/prabal-rje/latentscore/blob/main/CONTRIBUTE.md

Activate the 'latentscore' Conda environment before installing packages or running project commands. This makes the environment's packages available in your current shell session.

```bash
conda activate latentscore
```

--------------------------------

### Standard SFT Training Run

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Execute a standard Supervised Fine-Tuning (SFT) training run with specified data, output directory, and epochs. Supports custom sequence length and download/delete options for remote data.

```bash
python -m data_work.03_modal_train sft \
  --data data_work/.processed/SFT-Train.jsonl \
  --output gemma3-sft \
  --epochs 1 \
  --max-seq-length 4096 \
  --download-dir data_work/.modal_outputs \
  --delete-remote
```

--------------------------------

### EvalPrompt Schema Example

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/eval_sets/README.md

This JSON structure represents a single evaluation prompt record, including its ID, the prompt text, category, expected fields, difficulty, source, and any notes.

```json
{
  "id": "short_001",
  "prompt": "lonely mass, drifting through the void",
  "category": "short",
  "subcategory": null,
  "expected_fields": {},
  "difficulty": "easy",
  "source": "manual",
  "paraphrase_group": null,
  "notes": "Classic ambient vibe"
}
```

--------------------------------

### Render Text with Local Expressive LLM

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Renders text using the locally installed expressive LLM. Note that this mode is experimental and may produce lower-quality results compared to default models.

```python
ls.render("jazz cafe at midnight", model="expressive").play()
```

--------------------------------

### Step 1: Vibe Extraction (02a)

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/EXPERIMENTS.md

Extracts vibes from input data using a specified model and API key. Includes parameters for limiting input, controlling output, and deduplication. Note the use of `--limit` to process a subset of available texts due to API reliability.

```bash
conda run -n latentscore-data python -m data_work.02a_extract_vibes \
  --input-dir data_work/2026-01-18_outputs \
  --output-dir data_work/2026-01-26_vibes \
  --model openrouter/openai/gpt-oss-120b \
  --api-key-env OPENROUTER_API_KEY \
  --env-file .env \
  --seed 42 \
  --error-rate 0.15 \
  --max-input-tokens 80000 \
  --max-concurrency 16 \
  --max-qps 10 \
  --dedupe-threshold 0.95 \
  --limit 160 \
  --max-vibes 14000
```

--------------------------------

### Load Training Config from JSON File

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Use this command to load training hyperparameters from a specified JSON configuration file. Ensure the JSON file adheres to the TrainingConfig structure.

```bash
python -m data_work.03_modal_train sft \
  --config-file my_config.json \
  --data data_work/.processed/SFT-Train.jsonl \
  --output gemma3-sft \
  --epochs 1
```

--------------------------------

### Render with LiteLLM Adapter

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/latentscore-dx.md

Renders audio using an external model configured via LiteLLMAdapter for advanced control, including API keys and timeouts.

```python
import os
import latentscore as ls
from latentscore.providers.litellm import LiteLLMAdapter

adapter = LiteLLMAdapter(
    model="external:gemini/gemini-3-flash-preview",
    api_key=os.getenv("GEMINI_API_KEY"),
    litellm_kwargs={"timeout": 60},
)

audio = ls.render("late night neon", model=adapter)
```

--------------------------------

### Live Interactive Streaming

Source: https://context7.com/prabal-rje/latentscore/llms.txt

Enables dynamic music generation using an async generator to steer music in real-time with absolute and relative adjustments.

```python
import asyncio
from collections.abc import AsyncIterator
import latentscore as ls
from latentscore.config import Step

async def my_set() -> AsyncIterator[str | ls.MusicConfigUpdate]:
    # Start with an initial vibe
    yield "warm jazz cafe at midnight"
    await asyncio.sleep(8)

    # Absolute override: switch to bright electronic
    yield ls.MusicConfigUpdate(
        tempo="fast",
        brightness="very_bright",
        rhythm="electronic"
    )
    await asyncio.sleep(8)

    # Relative nudge: dial brightness down, add more echo
    yield ls.MusicConfigUpdate(
        brightness=Step(-2),  # Two levels darker
        echo=Step(+1),        # One level more echo
    )


# Create live session with 2-second transitions
session = ls.live(my_set(), transition_seconds=2.0)

# Play for 30 seconds (or until generator exhausts)
session.play(seconds=30)

# Or save the live session
session.save("live_session.wav", seconds=30)
```

--------------------------------

### Reward Weight Ablation via Python

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Illustrates reward weight ablation by creating `RewardConfig` objects with different weight combinations. Requires `RewardConfig` and `RewardWeights`.

```python
# Reward weight ablation
reward_configs = [
    RewardConfig(weights=RewardWeights(format_weight=0.1, schema_weight=0.4, audio_weight=0.5)),
    RewardConfig(weights=RewardWeights(format_weight=0.2, schema_weight=0.3, audio_weight=0.5)),
    RewardConfig(weights=RewardWeights(format_weight=0.3, schema_weight=0.2, audio_weight=0.5)),
]
```

--------------------------------

### Show All Options for Extract Vibes

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

This command displays all available command-line options for the 'extract_vibes' module, useful for understanding its full capabilities.

```bash
python -m data_work.02a_extract_vibes --help
```

--------------------------------

### Stream Multiple Vibes with Transitions

Source: https://context7.com/prabal-rje/latentscore/llms.txt

Demonstrates streaming sequences of vibes with crossfade transitions and saving the output to a file.

```python
stream = ls.stream(
    "morning coffee",
    "afternoon focus",
    "evening wind-down",
    duration=60,       # 60 seconds per vibe (total: 180 seconds)
    transition=5.0,    # 5-second crossfade between vibes
)

# Play the stream directly
stream.play()

# Or collect all audio and save to file
collected = stream.collect()
collected.save("ambient_session.wav")

# Stream with MusicConfig objects mixed with text vibes
stream = ls.stream(
    "peaceful morning",
    ls.MusicConfig(tempo="fast", brightness="bright", rhythm="electronic"),
    "calm evening meditation",
    duration=30,
    transition=3.0,
)
stream.play()
```

--------------------------------

### Basic GRPO Beta Ablation via Python

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/ablation-guide.md

Demonstrates running a GRPO beta ablation study by generating multiple `TrainingConfig` objects with varying beta values. Requires `common.training_config` and `GRPOConfig`.

```python
from common.training_config import TrainingConfig, GRPOConfig, LoRAConfig
from common.reward_config import RewardConfig, RewardWeights

# Basic ablation: vary GRPO beta
configs = [
    TrainingConfig(grpo=GRPOConfig(beta=b))
    for b in [0.01, 0.02, 0.04, 0.08]
]
for config in configs:
    print(f"Beta: {config.grpo.beta}")
    # run_grpo(config)
```

--------------------------------

### Live Streaming with a Generator

Source: https://github.com/prabal-rje/latentscore/blob/main/notebooks/quickstart.ipynb

Uses `ls.live()` with a generator to yield vibes, `MusicConfigUpdate`s, or `Track`s on the fly for live music generation. The generator can be sync or async. Use `.play()` for local speaker output or `.collect()` for notebook playback.

```python
import asyncio
from collections.abc import AsyncIterator


async def my_set() -> AsyncIterator[str | ls.MusicConfigUpdate]:
    """Yield vibes and config tweaks — the live engine crossfades between them."""

    yield "warm jazz cafe at midnight"
    await asyncio.sleep(8)

    # Absolute override: switch to bright electronic
    yield ls.MusicConfigUpdate(tempo="fast", brightness="very_bright", rhythm="electronic")
    await asyncio.sleep(8)

    # Relative nudge: dial brightness back down, add more echo
    yield ls.MusicConfigUpdate(brightness=Step(-2), echo=Step(+1))


session = ls.live(my_set(), transition_seconds=2.0)

# .play() streams to speakers (local only); .collect() buffers for notebook playback
audio = session.collect(seconds=30)
listen(audio)
```

--------------------------------

### Generate Configurations - Step 2 of Two-Step Pipeline

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

This command is the second step in a recommended two-step pipeline. It generates configurations using a specified model and API key, saving the processed output to a designated directory. It supports setting the number of candidates and maximum concurrency.

```bash
python -m data_work.02b_generate_configs \
  --input-dir data_work/.vibes \
  --output-dir data_work/.processed \
  --env-file .env \
  --model gemini/gemini-3-flash-preview \
  --api-key-env GEMINI_API_KEY \
  --num-candidates 3 \
  --max-concurrency 10 \
  --max-qps 5.0
```

--------------------------------

### Generate Configurations

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/METHODOLOGY.md

Command to generate configurations, specifying the number of candidates and maximum concurrency.

```bash
02b_generate_configs --num-candidates 5 --max-concurrency 500
```

--------------------------------

### Run Config Generation Script

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/METHODOLOGY.md

Command to execute the config generation script. Specifies input/output directories, model, API key, environment file, number of candidates, temperature, seed, and concurrency/QPS limits.

```bash
python -m data_work.02b_generate_configs \
  --input-dir data_work/2026-01-26_vibes \
  --output-dir data_work/2026-01-26_processed \
  --model gemini/gemini-3-flash-preview \
  --api-key-env GEMINI_API_KEY \
  --env-file .env \
  --num-candidates 5 \
  --temperature 0.8 \
  --seed 42 \
  --max-concurrency 500 \
  --max-qps 300.0
```

--------------------------------

### Run Project Checks

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/plans/2026-01-19-title-payload-implementation-plan.md

Execute the project's check targets using 'make' within the specified environment.

```bash
ENV_NAME=latentscore-data make check
```

--------------------------------

### Render Music with Full MusicConfig Control

Source: https://github.com/prabal-rje/latentscore/blob/main/notebooks/quickstart.ipynb

Provides precise control over music generation by building a `MusicConfig` object with human-readable parameters.

```python
config = ls.MusicConfig(
    tempo="slow",
    brightness="dark",
    space="vast",
    density=3,
    bass="drone",
    pad="ambient_drift",
    melody="contemplative",
    rhythm="minimal",
    texture="shimmer",
    echo="heavy",
    root="d",
    mode="minor",
)

audio = ls.render(config, duration=10.0)
listen(audio)
```

--------------------------------

### Run Quality-Based Best-of-N Selection Script

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/METHODOLOGY.md

Execute the script to perform quality-based Best-of-N selection by scoring all valid candidates with CLAP and selecting the highest-scoring one. This script ensures the selected configuration is not just valid but also of the best quality among the options.

```bash
python -m data_work.02c_score_configs \
  --input-dir data_work/2026-01-26_processed \
  --output-dir data_work/2026-01-26_scored \
  --scorers 'clap' \
  --env-file .env
```

--------------------------------

### Dependency Injection with dependency-injector

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/examples.md

Demonstrates dependency injection using the `dependency-injector` library in Python. It sets up a container with a `ConsoleSender` and a `notify_user` callable.

```python
from typing import Protocol
from dependency_injector import containers, providers

class EmailSender(Protocol):
    async def send(self, to: str, subject: str, body: str) -> None: ...

async def notify_user(sender: EmailSender, to: str, subject: str, body: str) -> None:
    if not to:
        return
    await sender.send(to, subject, body)

class ConsoleSender:
    async def send(self, to: str, subject: str, body: str) -> None:
        print(f"{to=} {subject=} {body=}")

class Container(containers.DeclarativeContainer):
    email_sender = providers.Singleton(ConsoleSender)
    notify_user = providers.Callable(notify_user, sender=email_sender)
```

--------------------------------

### Render Ambient Audio with Python

Source: https://context7.com/prabal-rje/latentscore/llms.txt

Generate audio from a text vibe, save to a file, or access raw samples as a numpy array.

```python
import latentscore as ls

# Simple one-liner: render and play
ls.render("warm sunset over water").play()

# Render with custom duration and save to file
audio = ls.render("thunderstorm on a tin roof", duration=15.0)
audio.play()              # Play on speakers
audio.save("output.wav")  # Save to WAV file

# Access raw audio samples as numpy array
import numpy as np
samples = np.asarray(audio)  # NDArray[np.float32], shape (n,), range [-1.0, 1.0]
print(f"Duration: {len(samples) / 44100:.2f}s, Sample rate: 44100 Hz")
```

--------------------------------

### Configure music parameters

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Use MusicConfig to define specific musical attributes for generation.

```python
import latentscore as ls

config = ls.MusicConfig(
    tempo="slow",
    brightness="dark",
    space="vast",
    density=3,
    bass="drone",
    pad="ambient_drift",
    melody="contemplative",
    rhythm="minimal",
    texture="shimmer",
    echo="heavy",
    root="d",
    mode="minor",
)

ls.render(config, duration=10.0).play()
```

--------------------------------

### Quick E2E Smoke Run - Step 2: Generate Configs

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

This command performs the second step of a quick E2E smoke run, generating configurations with a limit on the number of rows. Ensure the API key environment variable is set.

```bash
# Step 2: Generate configs (limit 5 rows)
python -m data_work.02b_generate_configs \
  --input-dir data_work/.vibes \
  --output-dir data_work/.processed \
  --env-file .env \
  --api-key-env ANTHROPIC_API_KEY \
  --limit 5
```

--------------------------------

### Select Generation Models

Source: https://context7.com/prabal-rje/latentscore/llms.txt

Choose between different generation models based on performance requirements and quality needs. The 'fast' model is the default, while 'external' allows integration with LLM providers.

```python
import latentscore as ls

# Default: fast embedding-based retrieval (~2s, no API key needed)
audio = ls.render("peaceful garden", model="fast")

# CLAP audio embeddings (higher quality, requires laion-clap)
audio = ls.render("peaceful garden", model="fast_heavy")

# Top-K interpolation blending
audio = ls.render("peaceful garden", model="interp")

# Zero-shot semantic matching
audio = ls.render("peaceful garden", model="semantic")

# Local LLM (requires latentscore[expressive] install)
# Note: Slower and less reliable than embedding models
audio = ls.render("peaceful garden", model="expressive")

# External LLM via LiteLLM (any supported provider)
audio = ls.render(
    "peaceful garden",
    model="external:anthropic/claude-sonnet-4-5-20250929"
)
```

--------------------------------

### Demo CLI execution command

Source: https://github.com/prabal-rje/latentscore/blob/main/docs/examples.md

Command-line instruction to run the LatentScore demo. Specifies the model and indicates that results should be saved.

```bash
python -m latentscore.demo --model fast --save
```

--------------------------------

### Apply relative parameter changes

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Use Step to incrementally adjust configuration parameters.

```python
from latentscore.config import Step

audio = ls.render(
    "morning coffee shop",
    duration=10.0,
    update=ls.MusicConfigUpdate(
        brightness=Step(+2),   # two levels brighter
        space=Step(-1),        # one level less spacious
    ),
)
audio.play()
```

--------------------------------

### Live interactive streaming

Source: https://github.com/prabal-rje/latentscore/blob/main/README.md

Use a generator to steer music in real-time for interactive applications.

```python
import asyncio
from collections.abc import AsyncIterator

import latentscore as ls
from latentscore.config import Step


async def my_set() -> AsyncIterator[str | ls.MusicConfigUpdate]:
    yield "warm jazz cafe at midnight"
    await asyncio.sleep(8)

    # Absolute override: switch to bright electronic
    yield ls.MusicConfigUpdate(tempo="fast", brightness="very_bright", rhythm="electronic")
    await asyncio.sleep(8)

    # Relative nudge: dial brightness back down, add more echo
    yield ls.MusicConfigUpdate(brightness=Step(-2), echo=Step(+1))


session = ls.live(my_set(), transition_seconds=2.0)
session.play(seconds=30)
```

--------------------------------

### Tweak Music Generation with MusicConfigUpdate (Relative Step)

Source: https://github.com/prabal-rje/latentscore/blob/main/notebooks/quickstart.ipynb

Modifies music generation parameters relative to the current settings using `Step`. `Step(+1)` increases a parameter, `Step(-1)` decreases it. Boundaries are saturated.

```python
from latentscore.config import Step

audio = ls.render(
    "morning coffee shop",
    duration=10.0,
    update=ls.MusicConfigUpdate(
        brightness=Step(+2),  # two levels brighter
        space=Step(-1),       # one level less spacious
    ),
)
listen(audio)
```

--------------------------------

### Modal-based SFT Inference with Batched Decoding

Source: https://github.com/prabal-rje/latentscore/blob/main/data_work/README.md

Run SFT inference using Modal with batched, constrained decoding. Outputs results to a JSONL file and downloads it locally. Configure adapter, input data, and decoding parameters.

```bash
conda run -n latentscore-data python -m data_work.07_modal_infer_eval \
  --adapter prod-sft-gemma3-270m-v5 \
  --input data_work/2026-01-26_scored/SFT-Val.jsonl \
  --limit 100 \
  --prompt-field vibe_noisy \
  --score-vibe-field vibe_original \
  --do-sample \
  --max-retries 3 \
  --batch-size 16 \
  --log-first-n 10 \
  --log-every 10 \
  --output sftval-100-v5-infer-batch
```