Metadata-Version: 2.5
Name: maple-mcp
Version: 0.1.0
Summary: Model-Agnostic Platform for Laboratory Experiments — LLM agents for autonomous MADSci experiments via MCP
Project-URL: Homepage, https://github.com/gabrielferrer/maple-mcp
Project-URL: Repository, https://github.com/gabrielferrer/maple-mcp
Project-URL: Issues, https://github.com/gabrielferrer/maple-mcp/issues
Author: Gabriel Ferrer
License: MIT
License-File: LICENSE
Keywords: agents,autonomous-lab,llm,madsci,mcp,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.100.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: madsci-client<0.6.0,>=0.5.0
Requires-Dist: madsci-common<0.6.0,>=0.5.0
Requires-Dist: madsci-experiment-application<0.6.0,>=0.5.0
Requires-Dist: madsci-node-module<0.6.0,>=0.5.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: strands-agents[anthropic,ollama]>=1.0.0
Requires-Dist: textual>=4.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: watchfiles>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# MAPLE

**Model-Agnostic Platform for Laboratory Experiments**

MAPLE adds LLM agent capabilities to any [MADSci](https://github.com/AD-SDL/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

![MAPLE Architecture](figures/architecture-1.png)

## Quick Start

```bash
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:
```bash
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/`](examples/block_sorting/) for a complete walkthrough.

## Installation

```bash
pip install maple-mcp
```

Requires Python 3.10+ and a running [MADSci](https://github.com/AD-SDL/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:

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

operator:
  vision_backend: "vision:MyVision"
  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

| Extension Point | Mechanism | Config Key |
|---|---|---|
| Vision detection | Subclass `VisionBackend` | `operator.vision_backend` |
| MCP tools | `@mcp.tool` decorator | `operator.custom_tools` / `overseer.custom_tools` |
| Agent hooks | `extra_hooks` param on factory | Programmatic |
| Post-action hooks | YAML (no code) | `operator.post_action_hooks` |
| System prompts | Markdown file | `operator.prompt` / `overseer.prompt` |

## Supported Models

| Provider | Environment Variable |
|---|---|
| OpenAI | `MODEL_PROVIDER=openai` |
| Anthropic | `MODEL_PROVIDER=anthropic` |
| Ollama (local, free) | `MODEL_PROVIDER=ollama` |

## Multi-User

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

## Programmatic Usage

```python
from maple.operator.agent import create_operator_agent

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

## Testing

```bash
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](LICENSE)
