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.
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.
Monorepo plugins must declare non-standard project paths so every CLI command uses the same frontend and generated client:
[tool.mint]
frontend_dir = "packages/ui"
generated_dir = "packages/contracts/client"
Both values are project-relative. generated_dir defaults to
<frontend_dir>/src/generated when omitted. Conventional single-package
plugins need no path settings.
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 experiment object files, let the platform choose local, S3, or OpenStack
Swift storage and keep only the returned reference in your experiment data.
Standalone plugin runs use a local store under
~/.mint/plugins/<plugin-name>/objects.
class MyPlugin(AnalysisPlugin):
async def initialize(self, context=None):
self._context = context
async def save_report(self, experiment_id: int, payload: bytes) -> dict:
store = self.get_data_store(experiment_id)
ref = await store.put_bytes(
"reports/report.json",
payload,
content_type="application/json",
metadata={"kind": "qc-report"},
)
return ref.to_dict()
The platform stores object bytes under {server.dataPath}/objects by default.
Admins can switch the object backend between storage.objects.backend = "local"
"s3", and "swift" and can set storage.objects.localPath for local storage.
When the backend is S3, the same SDK calls write to storage.s3.objectBucket
under storage.s3.objectPrefix. When the backend is Swift, they write to
storage.swift.objectContainer under storage.swift.objectPrefix. The platform
owns endpoint, region, access key, secret key, session token, SSL, path-style,
Keystone auth URL, project/domain, and Swift password settings; saved
credentials are encrypted at rest and redacted from admin config responses. Use
Admin -> Configuration -> Object Storage to choose Local Path, S3 Bucket, or
OpenStack Swift, and the Test Connection button to validate provider access.
Isolated plugin uploads use multipart transfer for put_file / put_fileobj
instead of base64 JSON.
S3-compatible provider settings may also come from environment variables. The
platform reads endpoint/region names such as MINT_S3_ENDPOINT_URL,
MINT_S3_REGION_NAME, S3_ENDPOINT_URL, and AWS_ENDPOINT_URL_S3; credential
names such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and
AWS_SESSION_TOKEN; and MINT-specific MINT_S3_* /
MINT_STORAGE__S3__* variants for SSL and path-style addressing.
Native Swift settings may come from MINT_SWIFT_* /
MINT_STORAGE__SWIFT__* variables or standard OpenStack variables such as
OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME,
OS_USER_DOMAIN_NAME, OS_PROJECT_DOMAIN_NAME, OS_AUTH_VERSION, and
OS_REGION_NAME.
Scripts can use MINTClient.objects for the same storage API by passing
plugin_id explicitly. Older get_s3_connector() code can pass
experiment_id to receive a compatibility adapter, but new plugins should call
get_data_store() directly.
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mint_sdk-1.0.58.tar.gz.
File metadata
- Download URL: mint_sdk-1.0.58.tar.gz
- Upload date:
- Size: 583.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5cc8dcfcacd991588faca810321454dc0cff44fd938fbdd7de70872eed3cb235
|
|
| MD5 |
5f82f00e594b6d754c5bb10e6c382edc
|
|
| BLAKE2b-256 |
e596adef148c9d96255306dc1b02c8b1522f58717e8104ec7cf773b92c0066eb
|
File details
Details for the file mint_sdk-1.0.58-py3-none-any.whl.
File metadata
- Download URL: mint_sdk-1.0.58-py3-none-any.whl
- Upload date:
- Size: 491.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f6b5f82fcc6b5776015c2c2c6611f4a79e1f1fd01d741e8ff06b223d3316681f
|
|
| MD5 |
62a555eb70a70ef956ce541d68358549
|
|
| BLAKE2b-256 |
632d2b969ca5c5fbd96a22fea6ce986684cc5c7731c7293ff856725ebd31cc4e
|
