MAPLE

Model-Agnostic Platform for Laboratory Experiments

MAPLE adds LLM agent capabilities to any MADSci-powered laboratory (v0.5.x) via MCP. Two agents — an Operator for experiment execution and an Overseer for lab monitoring — connect to your lab through configurable MCP servers.

Architecture

Quick Start

pip install maple-mcp
cd your-experiment/
cp .env.example .env          # Configure MADSci URLs + model provider
maple serve stub              # Start demo (no LLM needed)
maple chat operator           # Open TUI — type anything
maple down                    # Stop all services

For a real LLM experiment:

maple serve operator          # Start with your configured model
maple chat operator           # Run an experiment
maple chat operator --resume  # Pick up where you left off

See examples/block_sorting/ for a complete walkthrough.

Installation

pip install maple-mcp

Requires Python 3.10+ and a running MADSci lab (v0.5.x).

CLI

maple serve {all, operator, overseer, stub, mock} [--dev]
maple chat {operator, overseer} [--resume]
maple down
maple status
maple logs

Configuration

One maple.config.yaml per experiment:

experiment:
  name: My Experiment
  objective: Sort samples by type
  constraints:
    - "Only handle one sample at a time"

operator:
  vision:
    views:
      workspace:
        backend: "vision:MyVision"
        capture:
          node: MyRobot
          action: capture_camera_image
        covers: [MyRobot]
    default_view: workspace
  custom_tools:
    - "my_tools:prepare_sample"
  post_action_hooks:
    - node: AnalysisNode
      action: verify_placement

Infrastructure goes in .env (IPs, API keys, model provider).

Extending MAPLE

Config keys below are dotted paths into maple.config.yaml — e.g. operator.vision.views is the views: key nested under operator: → vision:.

Supported Models

Multi-User

Each device auto-generates a unique identity token. Multiple users can run experiments simultaneously — sessions are isolated automatically.

Programmatic Usage

from maple.operator.agent import create_operator_agent

agent = create_operator_agent("my-session")
result = agent("Sort the colored blocks by color.")

Testing

pytest -m "not integration"                    # Unit tests (no network)
docker compose -f docker-compose.ci.yaml up -d # Start MADSci
pytest -m integration                          # Integration tests

Compatibility

• Python 3.10+
• MADSci >=0.5.0, <0.6.0
• FastMCP 3.x

License

MIT