Skip to content

Getting Started

This is the User Guide — for researchers and benchmarkers who want to run experiments, explore parameter spaces, and analyse results without writing bespoke data management scripts from scratch. If you want to extend ado with new experiments or search strategies, the Developer Guide is your starting point.

New to ado?

Before diving in, familiarise yourself with the key concepts so the YAML examples and CLI commands throughout these examples make immediate sense.

The research loop with ado

ado organises research around a repeatable five-step process:

  1. Choose your experiments — select what you want to run
  2. Define your space — describe the parameter space you want to explore
  3. Configure your strategy — choose how to search or analyse that space
  4. Execute — apply the experiments on the points in the space
  5. Analyse — inspect results, then refine and continue

Core concepts

The loop is possible thanks to these three building blocks (explore them all in the concepts section):

Concept Role
Discovery Space Defines what to measure, how to measure it (via Experiments, which are pluggable python functions), and where to store results.
Operation You explore or analyse a Discovery Space using operations. You can select from different operators to perform different types of operations. Operators are also pluggable python functions.
Sample Store Stores the results of measurements, and enables operations to transparently reuse existing results (memoization).

How do you want to use ado?

You can run this loop yourself through the CLI, or let an AI coding assistant drive it for you using built-in agent skills.

Path A — Direct CLI Path B — AI-assisted
Best for Quick starts, existing scripts, and experienced CLI users who prefer manual control. Exploratory research, complex parameter spaces, and iterative analysis where an AI can handle the boilerplate.
Key benefit Lightweight — integrates into any standard Python workflow. Unlocks built-in agent skills that automate complex research tasks.

Installing

Make sure you are on Python 3.10 – 3.14 (python --version), and work inside a virtual environment to avoid dependency conflicts:

python -m venv ado-venv && source ado-venv/bin/activate

Install ado-core from PyPI:

pip install ado-core

You drive everything through the ado CLI. See the CLI reference and work through the examples to get up to speed.

Clone the repository and set up the full environment:

git clone https://github.com/IBM/ado.git
cd ado
uv sync --no-default-groups
source .venv/bin/activate

Open the cloned ado folder as your workspace root in an agent-enabled IDE (Claude, Cursor, Bob, and others will automatically detect and load the built-in skills).

See ado and Agents for a full overview of what agents can do with ado and example prompts to get started.

Next steps

  • See ado in action

    Walk through end-to-end examples that cover common research workflows.

    Choose an example

  • Extend ado

    Add custom experiments, benchmarks, or search strategies via the plugin model.

    Developer Guide