clabe

 ██████╗██╗      █████╗ ██████╗ ███████╗
██╔════╝██║     ██╔══██╗██╔══██╗██╔════╝
██║     ██║     ███████║██████╔╝█████╗  
██║     ██║     ██╔══██║██╔══██╗██╔══╝  
╚██████╗███████╗██║  ██║██████╔╝███████╗
 ╚═════╝╚══════╝╚═╝  ╚═╝╚═════╝ ╚══════╝

Command-line-interface Launcher for AIND Behavior Experiments

CLABE is a Python toolkit for building, running, and operating behavioral-experiment workflows. It provides a launcher for experiment scripts alongside composable utilities for user interaction, external applications, configuration and storage, resource checks, data transfer, remote execution, logging, and repository-state capture.

The library is designed to be useful both in an interactive experiment session and in scripted or remote workflows.

Install

For a project managed with uv:

uv add aind-clabe

Or install with pip:

pip install aind-clabe

To work on this repository locally:

git clone https://github.com/AllenNeuralDynamics/clabe.git
cd clabe
uv sync

What CLABE provides

• Experiment launcher — discover and run functions marked with @experiment, with console, TUI, and web-served interaction options.
• Frontends and forms — collect typed input from Pydantic models, prompt for paths, confirmations, selections, and read-only reviews.
• Applications and executors — describe external commands once and run them locally, asynchronously, detached, or through XML-RPC.
• Stores and services — compose local, in-memory, Ficus, and optional Dataverse-backed configuration and data services.
• Operational helpers — resource constraints, data transfer, structured logging, OpenTelemetry support, and session construction.
• Repository state — capture a JSON snapshot of a repository and its submodules for dataset or experiment metadata.

Quick start

Define an experiment in a Python module:

from clabe.launcher import Launcher, experiment


@experiment()
async def my_experiment(launcher: Launcher) -> None:
    launcher.frontend.notify("Experiment started")
    # Configure the session, check resources, and run applications here.

Run the module with the CLABE CLI:

uv run clabe run path/to/my_experiment.py

See examples/behavior_launcher.py for a fuller example that combines sessions, forms, stores, resource checks, applications, and telemetry.

Command line

Show available commands and their options:

uv run clabe --help

Run an experiment interactively:

uv run clabe run path/to/my_experiment.py

Serve an experiment's text UI locally:

uv run clabe serve path/to/my_experiment.py --port 8089

Capture Git state for a repository and all declared submodules:

uv run clabe repository-state path/to/repository > repository-state.json

Each repository entry includes its URL, commit SHA, exact and nearest tags, branch, dirty state, name, cwd-relative path, and nested submodules. The launcher automatically writes this snapshot to repository-state.json in each registered session directory.

Optional integrations

Some integrations are optional so a basic installation remains lightweight:

uv add "aind-clabe[aind-services]"  # AIND services, data schema, and transfer tooling
uv add "aind-clabe[web]"            # Web-served Textual UI
uv add "aind-clabe[otel]"           # OpenTelemetry exporters and YAML support

Documentation and development

• Browse the documentation for API references and guides.
• Run tests with uv run pytest.
• Check style with uv run ruff check.
• Build documentation locally with uv run mkdocs serve after installing the docs dependency group.

Contributions are welcome. Please include focused tests for behavior changes and keep the package's cross-platform support in mind.