mint-sdk 1.0.18

MINT Plugin SDK - Build analysis plugins for the MINT (Mass-spec INtegrated Toolkit) platform

MINT SDK (Python)

SDK for building analysis plugins that integrate with the MINT platform.

Full Documentation: See the comprehensive docs for detailed API reference and guides.

• API Reference
• Plugin Development Guide
• Exception Handling

Installation

# From PyPI (when published)
uv add mint-sdk

# From git
uv add git+https://github.com/MorscherLab/MINT#subdirectory=packages/sdk-python

Quick Start

Create a plugin with the CLI:

mint init my-plugin --template analysis-basic
cd my-plugin
mint sdk generate
mint doctor --explain
mint dev

mint sdk generate writes the frontend contract and typed client from backend routes and Pydantic schemas, so Vue code can call plugin endpoints without hand-writing route prefixes or request/response types. Use mint docs contract inside a plugin to inspect the generated endpoint and client-call contract without writing files. Use mint sdk generate --check --json in CI or editor tasks when you need machine-readable drift status. Use mint doctor --json for machine-readable project health checks and safe-fix status. When adding backend pieces, pass --generate to supported mint add commands to refresh the generated client in the same step.

For R-backed analyses:

mint init drp-r --template r-analysis
# or add R support to an existing plugin:
mint add r-analysis drp-fit --page
mint doctor --r --explain
mint sdk generate

This creates an RAnalysisBridge service, FastAPI route, typed frontend composable, optional starter page, and a small mint_bridge.R helper for reading inputs, writing outputs, accessing the current experiment id, and writing analysis artifacts while keeping Python/Pydantic as the frontend contract source of truth.

For standard biology design data:

mint add data-template --list --json
mint docs template plate-map
mint add data-template plate-map --page

Built-in templates include plate-map, sample-sheet, sample-prep, dose-response, calibration-curve, time-course, protocol-steps, assay-matrix, reagent-list, flow-cytometry-panel, instrument-run, and qpcr-plate. Generated template routes expose schema/default endpoints and merge multiple templates under design_data.templates, so a plugin can combine plate layouts, sample metadata, sample prep, reagents, protocols, calibration curves, time courses, readout matrices, cytometry panels, instrument run queues, and qPCR plates without clobbering prior template data.

Use create_template_collection() / save_template_collection() when a backend route needs to persist a coordinated set of templates, and load_template_collection() when a route needs all envelopes stored for an experiment. Single-template save_template() / load_template() remains available for narrow routes.

mint add data-template-pack <name> --page generates those collection routes and the matching frontend composable for curated packs, so plugin authors can save a whole experiment design scaffold with one API call.

For platform-backed S3 storage, keep credentials in the platform config and give the plugin only the bucket name:

class MyPlugin(AnalysisPlugin):
    async def initialize(self, context=None):
        self._context = context
        self.results_bucket = self.get_s3_connector("mint-results")

    def save_report(self, experiment_id: int, payload: bytes) -> None:
        self.results_bucket.put_bytes(
            f"experiments/{experiment_id}/report.json",
            payload,
            content_type="application/json",
        )

Install mint-sdk[s3] or add boto3 to the plugin environment when the plugin uses the connector. The platform owns endpoint, region, access key, secret key, session token, SSL, and path-style settings under storage.s3.

At the Python layer, plugins implement the AnalysisPlugin interface:

from mint_sdk import AnalysisPlugin, PluginMetadata, PluginCapabilities
from fastapi import APIRouter

router = APIRouter()

@router.get("/hello")
async def hello():
    return {"message": "Hello from my plugin!"}

class MyPlugin(AnalysisPlugin):
    @property
    def metadata(self) -> PluginMetadata:
        return PluginMetadata(
            name="My Plugin",
            version="1.0.0",
            description="My analysis plugin",
            analysis_type="metabolomics",
            routes_prefix="/my-plugin",
            capabilities=PluginCapabilities(
                requires_auth=True,
                requires_experiments=True,
            ),
        )

    def get_routers(self):
        return [(router, "")]

    async def initialize(self, context=None):
        self._context = context

    async def shutdown(self):
        pass

Plugin Package Structure

mint-plugin-example/
├── pyproject.toml
├── README.md
└── src/mint_plugin_example/
    ├── __init__.py
    └── plugin.py

pyproject.toml

[project]
name = "mint-plugin-example"
version = "1.0.0"
dependencies = ["mint-sdk>=1.0.0"]

[project.entry-points."mint.plugins"]
example = "mint_plugin_example.plugin:MyPlugin"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/mint_plugin_example"]

The entry point mint.plugins is how the platform discovers your plugin.

Platform Context

When running integrated with the platform, your plugin receives a PlatformContext that provides access to:

• Authentication dependencies (get_current_user_dependency())
• Repositories for experiments, samples, users, etc.
• Platform configuration

async def initialize(self, context=None):
    self._context = context
    if context:
        # Running integrated - use platform services
        self.experiment_repo = context.get_experiment_repository()
    else:
        # Running standalone
        pass

Installation Commands

# Install from GitHub
uv add git+https://github.com/org/mint-plugin-example

# Install specific version
uv add git+https://github.com/org/mint-plugin-example@v1.0.0

# Install from PyPI
uv add mint-plugin-example

# Install local plugin for development
uv add --editable ./my-plugin