mint-sdk 1.0.0a1__py3-none-any.whl

mint_sdk/__init__.py

@@ -0,0 +1,131 @@
+"""
+MINT Plugin SDK
+
+SDK for building analysis plugins that integrate with the MINT platform.
+"""
+
+from mint_sdk.context import PlatformContext
+
+# Exceptions
+from mint_sdk.exceptions import (
+    ConfigurationException,
+    ConflictException,
+    NotFoundException,
+    PermissionException,
+    PluginException,
+    PluginLifecycleException,
+    RepositoryException,
+    ValidationException,
+)
+from mint_sdk.export import auto_json_to_csv, auto_json_to_summary, auto_json_to_tree
+
+# Local database (optional dependency)
+from mint_sdk.local_database import LocalDatabase, LocalDatabaseConfig
+from mint_sdk.logging import get_plugin_logger
+
+# Migration framework (requires sqlalchemy — optional dependency)
+try:
+    from mint_sdk.migrations import (
+        MigrationOps,
+        MigrationResult,
+        MigrationRunner,
+        PluginMigration,
+    )
+except ImportError:
+    pass
+from mint_sdk.models import PluginCapabilities, PluginMetadata, PluginType
+from mint_sdk.plugin import (
+    AnalysisPlugin,
+    HealthStatus,
+    LifecycleHookResult,
+    PluginHealth,
+)
+
+# Repository protocols and data models
+from mint_sdk.repositories import (
+    DesignData,
+    # Data models
+    Experiment,
+    # Repository protocols
+    ExperimentRepository,
+    PlatformConfig,
+    PluginAnalysisResult,
+    PluginDataRepository,
+    PluginExperimentData,  # backward compatibility alias for DesignData
+    PluginRoleRepository,
+    User,
+    UserPluginRole,
+    UserRepository,
+)
+
+# App factory and helpers
+from mint_sdk.app import (
+    PluginDependency,
+    SPAStaticFiles,
+    create_standalone_app,
+    require_context,
+)
+
+# API Client
+from mint_sdk.client import MINTClient
+
+try:
+    from mint_sdk._version import __version__
+except ImportError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    # API Client
+    "MINTClient",
+    # Core plugin classes
+    "AnalysisPlugin",
+    "PluginMetadata",
+    "PluginCapabilities",
+    "PluginType",
+    "PlatformContext",
+    # Lifecycle types
+    "HealthStatus",
+    "PluginHealth",
+    "LifecycleHookResult",
+    # Exceptions
+    "PluginException",
+    "ValidationException",
+    "PermissionException",
+    "ConfigurationException",
+    "RepositoryException",
+    "NotFoundException",
+    "ConflictException",
+    "PluginLifecycleException",
+    # Local database
+    "LocalDatabase",
+    "LocalDatabaseConfig",
+    # Data models
+    "Experiment",
+    "DesignData",
+    "PluginExperimentData",  # backward compatibility alias
+    "PluginAnalysisResult",
+    "User",
+    "UserPluginRole",
+    # Repository protocols
+    "ExperimentRepository",
+    "PluginDataRepository",
+    "PluginRoleRepository",
+    "UserRepository",
+    "PlatformConfig",
+    # Export utilities
+    "auto_json_to_tree",
+    "auto_json_to_csv",
+    "auto_json_to_summary",
+    # Logging
+    "get_plugin_logger",
+    # Migration framework
+    "MigrationOps",
+    "MigrationResult",
+    "MigrationRunner",
+    "PluginMigration",
+    # App factory and helpers
+    "create_standalone_app",
+    "SPAStaticFiles",
+    "PluginDependency",
+    "require_context",
+]

mint_sdk/_discover.py

@@ -0,0 +1,159 @@
+"""Plugin discovery from pyproject.toml without importing the plugin.
+
+Parses entry points, module paths, and routes prefix by inspecting files
+statically — no plugin code is executed.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass(slots=True)
+class DiscoveredPlugin:
+    """Statically discovered plugin metadata."""
+
+    entry_point_name: str  # "drp-analysis"
+    module_path: str  # "mld_plugin_drp.plugin"
+    class_name: str  # "DRPAnalysisPlugin"
+    factory_target: str  # "mld_plugin_drp.plugin:create_standalone_app"
+    routes_prefix: str  # "/drp" (from source) or "/drp-analysis" (fallback)
+    project_name: str  # "mld-plugin-drp"
+    project_version: str | None  # "0.2.0" or None if dynamic
+    project_description: str  # from [project].description
+    has_frontend: bool  # frontend/package.json exists
+
+
+def _read_full_pyproject(project_dir: Path) -> dict:
+    """Read and return the full pyproject.toml as a dict."""
+    path = project_dir / "pyproject.toml"
+    if not path.exists():
+        print(f"Error: {path} not found.", file=sys.stderr)
+        sys.exit(1)
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _parse_entry_point(data: dict) -> tuple[str, str, str] | None:
+    """Extract (name, module_path, class_name) from [project.entry-points."mld.plugins"].
+
+    Returns None if no mld.plugins entry point is found.
+    """
+    entry_points = (
+        data.get("project", {}).get("entry-points", {}).get("mld.plugins", {})
+    )
+    if not entry_points:
+        return None
+
+    # Take the first entry point
+    name, value = next(iter(entry_points.items()))
+    # value is "mld_plugin_drp.plugin:DRPAnalysisPlugin"
+    if ":" not in value:
+        return None
+    module_path, class_name = value.rsplit(":", 1)
+    return name, module_path, class_name
+
+
+def _parse_routes_prefix_from_source(
+    module_path: str, project_dir: Path
+) -> str | None:
+    """Parse PLUGIN_ROUTES_PREFIX from the plugin source file without importing it.
+
+    Looks for patterns like:
+        PLUGIN_ROUTES_PREFIX = "/drp"
+        PLUGIN_ROUTES_PREFIX = '/drp'
+    """
+    # Convert module path to file path: mld_plugin_drp.plugin -> src/mld_plugin_drp/plugin.py
+    parts = module_path.split(".")
+    candidates = [
+        project_dir / "src" / Path(*parts).with_suffix(".py"),
+        project_dir / Path(*parts).with_suffix(".py"),
+    ]
+
+    for source_path in candidates:
+        if not source_path.exists():
+            continue
+        try:
+            content = source_path.read_text()
+        except OSError:
+            continue
+
+        match = re.search(
+            r'PLUGIN_ROUTES_PREFIX\s*=\s*["\'](/[^"\']+)["\']', content
+        )
+        if match:
+            return match.group(1)
+
+    return None
+
+
+def discover_plugin(project_dir: Path) -> DiscoveredPlugin:
+    """Discover plugin metadata from pyproject.toml and source files.
+
+    Raises SystemExit if the project directory lacks required configuration.
+    """
+    data = _read_full_pyproject(project_dir)
+
+    project = data.get("project")
+    if not project:
+        print("Error: pyproject.toml has no [project] table.", file=sys.stderr)
+        sys.exit(1)
+
+    entry_point = _parse_entry_point(data)
+    if not entry_point:
+        print(
+            "Error: No [project.entry-points.\"mld.plugins\"] found in pyproject.toml.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    ep_name, module_path, class_name = entry_point
+
+    # Routes prefix: parse from source, fallback to /{entry_point_name}
+    routes_prefix = _parse_routes_prefix_from_source(module_path, project_dir)
+    if routes_prefix is None:
+        routes_prefix = f"/{ep_name}"
+
+    # Factory target for uvicorn --factory
+    factory_target = f"{module_path}:create_standalone_app"
+
+    # Version: static or None if dynamic
+    version = project.get("version")
+
+    has_frontend = (project_dir / "frontend" / "package.json").exists()
+
+    return DiscoveredPlugin(
+        entry_point_name=ep_name,
+        module_path=module_path,
+        class_name=class_name,
+        factory_target=factory_target,
+        routes_prefix=routes_prefix,
+        project_name=project["name"],
+        project_version=version,
+        project_description=project.get("description", ""),
+        has_frontend=has_frontend,
+    )
+
+
+def get_sdk_dependency_spec(project_dir: Path) -> str | None:
+    """Extract the mint-sdk version specifier from pyproject.toml dependencies.
+
+    Returns e.g. ">=0.9.4" or None if mint-sdk is not in dependencies.
+    """
+    data = _read_full_pyproject(project_dir)
+    deps = data.get("project", {}).get("dependencies", [])
+    for dep in deps:
+        # Match "mint-sdk>=0.9.4", "mint-sdk>=0.9.4,<1.0", "mint-sdk"
+        match = re.match(r"mint[-_]sdk\s*(.*)", dep, re.IGNORECASE)
+        if match:
+            spec = match.group(1).strip()
+            return spec if spec else "*"
+    return None

mint_sdk/_prompt.py

@@ -0,0 +1,228 @@
+"""Interactive terminal prompts with arrow-key selection (gh-style).
+
+Zero external dependencies — uses ``tty``/``termios`` for raw input on
+Unix systems.  Falls back to plain ``input()`` when stdin is not a TTY
+or on unsupported platforms.
+"""
+
+from __future__ import annotations
+
+import sys
+
+# ANSI helpers
+_BOLD = "\033[1m"
+_CYAN = "\033[36m"
+_GREEN = "\033[32m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+_CLEAR_LINE = "\033[2K"
+_HIDE_CURSOR = "\033[?25l"
+_SHOW_CURSOR = "\033[?25h"
+
+
+def _is_interactive() -> bool:
+    """Return True when stdin/stdout are both TTYs."""
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def _read_key() -> str:
+    """Read a single keypress (or escape sequence) in raw mode."""
+    import termios
+    import tty
+
+    fd = sys.stdin.fileno()
+    old = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        ch = sys.stdin.read(1)
+        if ch == "\x1b":
+            ch2 = sys.stdin.read(1)
+            if ch2 == "[":
+                ch3 = sys.stdin.read(1)
+                return f"\x1b[{ch3}"
+            return ch + ch2
+        return ch
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+
+
+def prompt_text(label: str, default: str = "") -> str:
+    """Prompt for free-form text input with a default value.
+
+    Example output::
+
+        ? Plugin name (My Plugin):
+    """
+    if not _is_interactive():
+        return default
+
+    suffix = f" ({default})" if default else ""
+    try:
+        answer = input(f"{_GREEN}?{_RESET} {_BOLD}{label}{_RESET}{_DIM}{suffix}{_RESET}: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(1)
+    return answer or default
+
+
+def prompt_select(label: str, choices: list[str], default: int = 0) -> int:
+    """Arrow-key selection from a list of choices.  Returns the chosen index.
+
+    Example output::
+
+        ? Plugin type:
+        > Analysis
+          Experiment Design
+
+    Falls back to numbered input when not interactive.
+    """
+    if not _is_interactive():
+        return default
+
+    cursor = default
+
+    def _render(first: bool = False) -> None:
+        if not first:
+            # Move cursor up to overwrite previous render
+            sys.stdout.write(f"\033[{len(choices)}A")
+        for i, choice in enumerate(choices):
+            sys.stdout.write(_CLEAR_LINE)
+            if i == cursor:
+                sys.stdout.write(f"  {_CYAN}> {choice}{_RESET}\n")
+            else:
+                sys.stdout.write(f"    {choice}\n")
+        sys.stdout.flush()
+
+    sys.stdout.write(f"{_GREEN}?{_RESET} {_BOLD}{label}{_RESET}\n")
+    sys.stdout.write(_HIDE_CURSOR)
+    sys.stdout.flush()
+
+    try:
+        _render(first=True)
+        while True:
+            key = _read_key()
+            if key == "\x1b[A":  # Up
+                cursor = (cursor - 1) % len(choices)
+                _render()
+            elif key == "\x1b[B":  # Down
+                cursor = (cursor + 1) % len(choices)
+                _render()
+            elif key in ("\r", "\n"):  # Enter
+                break
+            elif key == "\x03":  # Ctrl+C
+                raise KeyboardInterrupt
+    except (KeyboardInterrupt, EOFError):
+        sys.stdout.write(_SHOW_CURSOR)
+        sys.stdout.flush()
+        print()
+        sys.exit(1)
+
+    # Replace the choice list with the final answer
+    sys.stdout.write(f"\033[{len(choices)}A")
+    for _ in choices:
+        sys.stdout.write(f"{_CLEAR_LINE}\n")
+    sys.stdout.write(f"\033[{len(choices)}A")
+    sys.stdout.write(f"  {_CYAN}{choices[cursor]}{_RESET}\n")
+    sys.stdout.write(_SHOW_CURSOR)
+    sys.stdout.flush()
+
+    return cursor
+
+
+def prompt_multiselect(
+    label: str,
+    choices: list[str],
+    defaults: list[int] | None = None,
+) -> list[int]:
+    """Arrow-key multi-select with space to toggle.  Returns selected indices.
+
+    Example output::
+
+        ? AI coding assistant  (space = toggle, enter = confirm)
+          [x] Claude Code
+          [ ] Codex (OpenAI)
+          [x] Cursor
+          [ ] Windsurf
+          [ ] None
+
+    Falls back to returning *defaults* when not interactive.
+    """
+    if not _is_interactive():
+        return list(defaults) if defaults else []
+
+    selected = set(defaults) if defaults else set()
+    cursor = 0
+
+    hint = f"{_DIM}  (space = toggle, enter = confirm){_RESET}"
+
+    def _render(first: bool = False) -> None:
+        if not first:
+            sys.stdout.write(f"\033[{len(choices)}A")
+        for i, choice in enumerate(choices):
+            sys.stdout.write(_CLEAR_LINE)
+            check = "x" if i in selected else " "
+            if i == cursor:
+                sys.stdout.write(f"  {_CYAN}>[{check}] {choice}{_RESET}\n")
+            else:
+                sys.stdout.write(f"   [{check}] {choice}\n")
+        sys.stdout.flush()
+
+    sys.stdout.write(f"{_GREEN}?{_RESET} {_BOLD}{label}{_RESET}{hint}\n")
+    sys.stdout.write(_HIDE_CURSOR)
+    sys.stdout.flush()
+
+    try:
+        _render(first=True)
+        while True:
+            key = _read_key()
+            if key == "\x1b[A":  # Up
+                cursor = (cursor - 1) % len(choices)
+                _render()
+            elif key == "\x1b[B":  # Down
+                cursor = (cursor + 1) % len(choices)
+                _render()
+            elif key == " ":  # Space — toggle
+                if cursor in selected:
+                    selected.discard(cursor)
+                else:
+                    selected.add(cursor)
+                _render()
+            elif key in ("\r", "\n"):  # Enter — confirm
+                break
+            elif key == "\x03":  # Ctrl+C
+                raise KeyboardInterrupt
+    except (KeyboardInterrupt, EOFError):
+        sys.stdout.write(_SHOW_CURSOR)
+        sys.stdout.flush()
+        print()
+        sys.exit(1)
+
+    # Collapse to summary line
+    sys.stdout.write(f"\033[{len(choices)}A")
+    for _ in choices:
+        sys.stdout.write(f"{_CLEAR_LINE}\n")
+    sys.stdout.write(f"\033[{len(choices)}A")
+    picked = [choices[i] for i in sorted(selected)]
+    summary = ", ".join(picked) if picked else "None"
+    sys.stdout.write(f"  {_CYAN}{summary}{_RESET}\n")
+    sys.stdout.write(_SHOW_CURSOR)
+    sys.stdout.flush()
+
+    return sorted(selected)
+
+
+def prompt_confirm(label: str, default: bool = True) -> bool:
+    """Yes/No selection with arrow keys.
+
+    Example output::
+
+        ? Include frontend?
+        > Yes
+          No
+    """
+    choices = ["Yes", "No"]
+    idx = prompt_select(label, choices, default=0 if default else 1)
+    return idx == 0

mint_sdk/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0a1'
+__version_tuple__ = version_tuple = (1, 0, 0, 'a1')
+
+__commit_id__ = commit_id = None