The Modular Autonomous Discovery for Science (MADSci) Framework

Experiment Control Flow Using MADSci

Overview

MADSci is a modular, autonomous, and scalable framework for scientific discovery and experimentation. It aims to provide:

• Laboratory Instrument Automation and Integration via the MADSci Node standard. Developers can implement device-specific Node modules in any language that can then be integrated into a MADSci system using a common interface standard (currently supports REST-based HTTP communication)
• Workflow Management, allowing users to define and run flexible scientific workflows that can leverage one or more Nodes to complete complex tasks.
• Experiment Management, conducting flexible closed loop autonomous experiments by combining multiple workflow runs, as well as any compute, decision making, data collection, and analysis as needed.
• Resource Management, allowing robust tracking of all the labware, consumables, equipment, samples, and assets used in an autonomous laboratory.
• Event Management, enabling distributed logging and event handling across every part of the autonomous lab.
• Data Management, collecting and storing data created by instruments or analysis as part of an experiment.
• Location Management, coordinating multiple different representations of locations in the laboratory and their interactions with resources and nodes.
• Observability, with built-in OpenTelemetry integration for distributed tracing, metrics, and log correlation across the entire lab infrastructure.

Diagram of a MADSci Laboratory's Infrastructure

Notes on Stability

MADSci is currently in beta. Most of the core functionality is working and tested, but there may be bugs or stability issues (if you run into any, please open an issue so we can get it fixed). New releases will likely include breaking changes, so we recommend pinning the version in your dependencies and upgrading only after reviewing the release notes.

Documentation

MADSci is made up of a number of different modular components, each of which can be used independently to fulfill specific needs, or composed to build more complex and capable systems. Below we link to specific documentation for each system component.

• Common: the common types and utilities used across the MADSci toolkit
• Clients: A collection of clients for interacting with different components of MADSci
• Event Manager: handles distributed event logging and querying across a distributed lab.
• Workcell Manager: handles coordinating and scheduling a collection of interoperating instruments, robots, and resources using Workflows.
• Location Manager: manages laboratory locations, resource attachments, and node-specific references.
• Experiment Manager: manages experimental runs and campaigns across a MADSci-powered lab.
• Experiment Application: extensible python class for running autonomous experiments.
• Resource Manager: For tracking labware, assets, samples, and consumables in an automated or autonomous lab.
• Data Manager: handles capturing, storing, and querying data, in either JSON value or file form, created during the course of an experiment (either collected by instruments, or synthesized during anaylsis)
• Squid Lab Manager: a central lab configuration manager and dashboard provider for MADSci-powered labs.

Guides

• CLI Reference: Complete reference for all 17 CLI commands, options, and aliases.
• Template Catalog: All 26 built-in templates with parameters and examples.
• Logging and Event Context: Guide to MADSci's structured logging system and hierarchical context propagation.
• Observability: How to use the OpenTelemetry observability stack for distributed tracing, metrics, and logs.
• Daily Operations: Day-to-day lab operations, startup, shutdown, and health checks.

Installation

Python Packages

All MADSci components are available via PyPI. Install individual components as needed:

# Core components
pip install madsci.common          # Shared types and utilities
pip install madsci.client          # Client libraries
pip install madsci.experiment_application # Experiment Logic

# Manager services
pip install madsci.event_manager    # Event logging and querying
pip install madsci.workcell_manager # Workflow coordination
pip install madsci.location_manager # Location management
pip install madsci.resource_manager # Resource tracking
pip install madsci.data_manager     # Data capture and storage
pip install madsci.experiment_manager # Experiment management

# Lab infrastructure
pip install madsci.squid           # Lab manager with dashboard
pip install madsci.node_module      # Node development framework

Docker Images

We provide pre-built Docker images for easy deployment:

• ghcr.io/ad-sdl/madsci: Base image with all MADSci packages. Use as foundation for custom services.
• ghcr.io/ad-sdl/madsci_dashboard: Extends base image with web dashboard for lab management.

For users new to docker, we recommend checking out our Docker Guide

Quick Start

pip install madsci-client
madsci init my_lab          # Interactive lab setup wizard
cd my_lab
madsci start                # Start with Docker
# or
madsci start --mode=local   # Start without Docker (pure Python)

Access the dashboard at http://localhost:8000 to monitor your lab.

To try the complete example lab instead:

git clone https://github.com/AD-SDL/MADSci.git
cd MADSci
docker compose up  # Starts all services with example configuration

Configuration

MADSci uses environment variables for configuration with hierarchical precedence. Key patterns:

• Service URLs: Each manager defaults to localhost with specific ports (Event: 8001, Experiment: 8002, Resource: 8003, Data: 8004, Workcell: 8005, Location: 8006, etc.)
• Database connections: MongoDB/PostgreSQL on localhost by default
• File storage: Defaults to ~/.madsci/ subdirectories
• Environment prefixes: Each service has a unique prefix (e.g., WORKCELL_, EVENT_, LOCATION_)
• OpenTelemetry: Configurable per-manager with *_OTEL_ENABLED, *_OTEL_ENDPOINT, etc.

See Configuration.md for comprehensive options, example_lab/ for working configurations, and OBSERVABILITY.md for OpenTelemetry setup.

Roadmap

We're working on bringing the following additional components to MADSci:

• Auth Manager: For handling authentication and user and group management for an autonomous lab.

Getting Started

Learning Resources

1. Example Lab: Complete working lab with virtual instruments (robot arm, liquid handler, plate reader)
2. Example Notebooks: Jupyter notebooks covering core concepts and implementation patterns, included in the example lab
3. Configuration examples: See example_lab/settings.yaml and example_lab/compose.yaml for lab configuration

CLI Overview

MADSci provides a unified CLI (madsci) with 17 commands:

Command	Alias	Description
init		Initialize a new lab interactively
new	n	Create components from 26 built-in templates
start		Start lab services (Docker or local mode)
stop		Stop lab services
status	s	Check service health
doctor	doc	Run diagnostic checks
logs	l	View and filter event logs
run		Run workflows or experiments
validate	val	Validate configuration files
config	cfg	Export or create configuration files
backup		Create database backups
registry		Manage service registry
migrate		Run database migrations
tui	ui	Launch interactive terminal interface
completion		Generate shell completions
commands	cmd	List all commands
version		Show version information

Run madsci <command> --help for details on any command. See CLI Reference for full documentation.

Templates

Generate scaffolding for any MADSci component:

madsci new list                       # Browse all 26 templates
madsci new module                     # Interactive module creation
madsci new experiment --modality tui  # TUI experiment
madsci new lab --template standard    # Full lab with Docker Compose

See Template Catalog for the complete list.

TUI (Terminal User Interface)

madsci tui    # Launch interactive dashboard

Provides real-time service status, log browsing, node management, and workflow monitoring with auto-refresh.

Local Mode

Run all managers without Docker using in-memory backends:

madsci start --mode=local

Useful for development, testing, and environments without Docker. Data is ephemeral.

Configuration Management

madsci config export event     # Export Event Manager settings to YAML
madsci config export --all     # Export all manager settings
madsci config create manager event  # Create a new manager config file

Common Usage Patterns

Creating custom nodes:

# See examples/example_lab/example_modules/ for reference implementations
from madsci.node_module import AbstractNodeModule

class MyInstrument(AbstractNodeModule):
    def my_action(self, param1: str) -> dict:
        # Your instrument control logic
        return {"result": "success"}

Submitting workflows:

# See examples/example_lab/workflows/ for workflow definitions
from madsci.client.workcell_client import WorkcellClient

client = WorkcellClient("http://localhost:8005")
result = client.submit_workflow("path/to/workflow.yaml")

Contributing

Interested in contributing to MADSci? We welcome all contributions, from bug reports to new features!

See our Contributing Guide for:

• Development setup and prerequisites
• Development commands and workflows
• How to report bugs and request features
• Pull request guidelines
• Configuration best practices

For quick development setup:

git clone https://github.com/AD-SDL/MADSci.git
cd MADSci
just init  # Installs dependencies and sets up pre-commit hooks
just up    # Start example lab for testing

Note: The pdm.lock file was generated using uv as the resolver. If pdm install fails with resolver errors, either install uv and run pdm config use_uv true, or delete pdm.lock to let PDM regenerate it with the standard resolver. See CONTRIBUTING.md for details.