mint-sdk 1.0.0__tar.gz

mint_sdk-1.0.0/.gitignore

@@ -0,0 +1,104 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+env/
+venv/
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Code Quality Tools
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node/Frontend
+node_modules/
+/frontend/dist/
+packages/sdk-frontend/dist/
+npm-debug.log*
+bun-debug.log*
+yarn-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+frontend/vite.config.d.ts
+frontend/vite.config.js
+
+# IDE/Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.AppleDouble
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+config.json
+config.dev.toml
+
+# SDK Python build
+packages/sdk-python/dist/
+
+# hatch-vcs generated version files
+api/_version.py
+packages/sdk-python/src/mld_sdk/_version.py
+
+# Histoire
+.histoire/
+
+# VitePress cache + synced content
+site/.vitepress/cache/
+site/changelog.md
+
+# Database
+data/*.db
+
+# MLD CLI runtime data
+.mld/
+
+# Claude Code
+.claude/
+
+# Playwright E2E
+e2e/playwright-report/
+e2e/test-results/
+e2e/blob-report/
+
+# Git Worktrees
+.worktrees/
+
+# SDK test/eval artifacts
+packages/sdk-python/mld-init-test/
+skills/mint-sdk-plugin/evals/
+skills/mint-sdk-plugin/mint-sdk-plugin-workspace/
+
+# Local plugin development
+mld-ms-planner/
+
+# Local data
+data/
+frontend/data/
+.superpowers/
+.omx/
+docs/superpowers/
+
+# Skill eval/workspace artifacts (post-R-3 paths; old sdk/skill/* patterns
+# above remain until R-3 merges and the rename consolidates)
+skills/mint-sdk-plugin/evals/
+skills/mint-sdk-plugin/mint-sdk-plugin-workspace/
+/AGENTS.md

mint_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: mint-sdk
+Version: 1.0.0
+Summary: MINT Plugin SDK - Build analysis plugins for the MINT (Mass-spec INtegrated Toolkit) platform
+Project-URL: Homepage, https://github.com/MorscherLab/MINT
+Project-URL: Documentation, https://github.com/MorscherLab/MINT/tree/main/packages/sdk-python#readme
+Project-URL: Repository, https://github.com/MorscherLab/MINT
+Author-email: MorscherLab <morscher@chem.ethz.ch>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.19.0; extra == 'dev'
+Requires-Dist: greenlet>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: sqlmodel>=0.0.16; extra == 'dev'
+Provides-Extra: local-db
+Requires-Dist: aiosqlite>=0.19.0; extra == 'local-db'
+Requires-Dist: sqlmodel>=0.0.16; extra == 'local-db'
+Description-Content-Type: text/markdown
+
+# MINT SDK (Python)
+
+SDK for building analysis plugins that integrate with the MINT platform.
+
+> **Full Documentation:** See the [comprehensive docs](../../docs/index.md) for detailed API reference and guides.
+> - [API Reference](../../docs/python/api-reference.md)
+> - [Plugin Development Guide](../../docs/python/plugin-guide.md)
+> - [Exception Handling](../../docs/python/exceptions.md)
+
+## Installation
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+At the Python layer, plugins implement the `AnalysisPlugin` interface:
+
+```python
+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
+
+```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
+
+```python
+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
+
+```bash
+# 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
+```

mint_sdk-1.0.0/README.md

@@ -0,0 +1,166 @@
+# MINT SDK (Python)
+
+SDK for building analysis plugins that integrate with the MINT platform.
+
+> **Full Documentation:** See the [comprehensive docs](../../docs/index.md) for detailed API reference and guides.
+> - [API Reference](../../docs/python/api-reference.md)
+> - [Plugin Development Guide](../../docs/python/plugin-guide.md)
+> - [Exception Handling](../../docs/python/exceptions.md)
+
+## Installation
+
+```bash
+# 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+At the Python layer, plugins implement the `AnalysisPlugin` interface:
+
+```python
+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
+
+```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
+
+```python
+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
+
+```bash
+# 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
+```

mint_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mint-sdk"
+dynamic = ["version"]
+description = "MINT Plugin SDK - Build analysis plugins for the MINT (Mass-spec INtegrated Toolkit) platform"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "MorscherLab", email = "morscher@chem.ethz.ch" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Framework :: FastAPI",
+]
+
+dependencies = ["fastapi>=0.109.0", "pydantic>=2.0.0", "typer>=0.15.0", "httpx>=0.28.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0.0", "pytest-asyncio>=0.21.0", "sqlmodel>=0.0.16", "aiosqlite>=0.19.0", "greenlet>=3.0.0"]
+local-db = ["sqlmodel>=0.0.16", "aiosqlite>=0.19.0"]
+
+[project.urls]
+Homepage = "https://github.com/MorscherLab/MINT"
+Documentation = "https://github.com/MorscherLab/MINT/tree/main/packages/sdk-python#readme"
+Repository = "https://github.com/MorscherLab/MINT"
+
+[project.scripts]
+mint = "mint_sdk.cli:main"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = "^v(?P<version>\\d+\\.\\d+\\.\\d+.*)$"
+raw-options.root = "../.."
+raw-options.git_describe_command = "git describe --dirty --tags --long --abbrev=40 --match v[0-9]*"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/mint_sdk/_version.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mint_sdk"]