Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

The Modular Autonomous Discovery for Science (MADSci) Framework

Docker Pre-Commit PyPI Pytests Coverage badge JOSS status

Diagram of a MADSci laboratory's Architecture

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 Architecture

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:

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

Metadata

Release files for madsci 0.7.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for madsci 0.7.0rc1
File Size Uploaded Provenance Actions
madsci-0.7.0rc1.tar.gz 740.3 kB Without provenance Details for madsci-0.7.0rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for madsci 0.7.0rc1
File Interpreter ABI Platform Actions
madsci-0.7.0rc1-py3-none-any.whl Python 3 none any Details for madsci-0.7.0rc1-py3-none-any.whl

Total release size: 1.6 MB

Release files / madsci-0.7.0rc1.tar.gz

Download URL madsci-0.7.0rc1.tar.gz
Size 740.3 kB
Tags Source
SHA-256 checksum
How to use checksums
487e38466d02524b4959bfde199f0dba36299c4135e443ff27506a057673bed6
BLAKE2b-256 checksum
How to use checksums
9aa46a2ffeb2dc16f8c50cb904d7364b8cb08670fc0dc62cda50d83637b3965d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via pdm/2.26.2 CPython/3.13.11 Darwin/25.2.0

Release files / madsci-0.7.0rc1-py3-none-any.whl

Download URL madsci-0.7.0rc1-py3-none-any.whl
Size 892.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bcd00600c4c8e0479f3a62df4aa3696a8dbf3d3115ee9dc297fa3313828f09bf
BLAKE2b-256 checksum
How to use checksums
9f9a2ec52f385ded2d58c4d2df4e5edbb5b94b89c0642dc53645fd23d0bd1cae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via pdm/2.26.2 CPython/3.13.11 Darwin/25.2.0

Security for madsci 0.7.0rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page