SwarmLabs Server

Open-source client SDK, MCP server, and Skill catalog for the SwarmLabs physics-informed multi-agent scientific experiment automation engine.

License: MIT

SwarmLabs is an open infrastructure that turns multidisciplinary scientific experiments (chemistry, energy, materials, environment, biology, pharma, quantum computing, brain science, CFD, structural mechanics, …) into callable, auditable physics-informed predictions served over a small HTTP API. This repository is the open-source developer toolkit around that engine — it does not contain the proprietary physics models, only the interface, reference integrations, and honesty-first contracts that let any agent or application consume the engine safely.

Why this exists

Scientific-AI tooling is flooded with demos that return confident-but-fake numbers. SwarmLabs takes the opposite stance — honesty-first:

• Every prediction reports an uncertainty and, where applicable, an epistemic_uncertainty (how far the request is from validated parameter space).
• Validation is split into empirical_validated (matched to real published experiment data) and literature_validated (matched to a real paper), never a single inflated "validated" count.
• The v2/pi (physics-informed) endpoint returns the real physics model — it does not return a constant placeholder.

This kit makes those guarantees easy to build on top of, from a Python script, an MCP-compatible agent runtime, or a no-code agent builder.

What's inside

Path	What
src/swarmlabs_engine/	Python client SDK (SwarmLabsClient)
mcp/server.py	Reference MCP server exposing engine calls as tools
skills/skill_catalog.json	Machine-readable catalog of the 4 core Skills
examples/quickstart.py	Minimal end-to-end example
docs/API.md	Endpoint reference

Install

pip install swarmlabs-engine-kit

Or use it directly from source:

git clone https://github.com/lm203688/swarmlabs-engine-kit.git
cd swarmlabs-engine-kit
pip install -e .

Quick start

from swarmlabs_engine import SwarmLabsClient

# Point the client at YOUR deployed SwarmLabs engine endpoint.
client = SwarmLabsClient(base_url="https://your-swarmlabs-engine.example.com")

# List available engines
info = client.list_engines()
print(info["engines"], "engines across", info["physics_models"], "physics models")

# Run a real physics-informed prediction (e.g. H2 dissociation via VQE)
result = client.run("vqe_h2", {"bond_length_A": 0.74})
print(result["result"], "+/-", result["uncertainty"])

See examples/quickstart.py for a fuller walkthrough.

Engine API surface (summary)

All endpoints are served under /api/v2/.

Method	Path	Purpose
GET / POST	/api/v2/list	List engines + physics-model coverage
POST	/api/v2/run/{engine}	Run a real physics-informed prediction
POST	/api/v2/pi/{engine}	Physics-informed variant (same honest models)
POST	/api/v2/sweep/{engine}	Parameter sweep for trend analysis
POST	/api/v2/multifidelity	Multi-fidelity cross-engine query
POST	/api/v2/measure/{engine}	Record a real measurement to compare vs prediction

The engine deployment URL is provided by you. This kit is the client side and works against any SwarmLabs engine deployment that exposes the /api/v2/ surface.

MCP integration

The reference MCP server turns engine calls into standard MCP tools so any MCP-aware agent (Claude Desktop, Cursor, custom runtimes) can use SwarmLabs as a trusted scientific-compute tool:

python -m mcp.server --base-url https://your-swarmlabs-engine.example.com

It exposes swarmlabs_run, swarmlabs_list, and swarmlabs_sweep tools with explicit input schemas and the same honesty-first result contract.

Skill catalog

skills/skill_catalog.json describes the 4 core Skills that compose a SwarmLabs multi-agent workflow:

1. PhysicsPredictSkill — call the real engine.
2. ExperimentDesignSkill — turn a goal into a parameter plan.
3. ActiveLearningSkill — pick the next most informative experiment point.
4. ReportGenerationSkill — emit an auditable report.

These are the building blocks of the SwarmLabs "Planner → Executor → Verifier" agent loop.

License

MIT.