maind 0.1.0__py3-none-any.whl

mai/__init__.py

@@ -0,0 +1,38 @@
+"""Mai SDK + CLI."""
+
+from mai._core.workspace import PublishResult, Workspace
+from mai.async_client import AsyncMaiClient
+from mai.client import MaiClient
+from mai.errors import (
+    ApiError,
+    AuthError,
+    DependencyMissingError,
+    MaiError,
+    ResourceNotFoundError,
+    ValidationError,
+    WorkspaceError,
+)
+from mai.models import BuildTask, FileInfo, LoginResult, Project, ProjectContext, Resource
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncMaiClient",
+    "MaiClient",
+    "LoginResult",
+    "Project",
+    "ProjectContext",
+    "Resource",
+    "FileInfo",
+    "BuildTask",
+    "Workspace",
+    "PublishResult",
+    "MaiError",
+    "ValidationError",
+    "AuthError",
+    "ApiError",
+    "ResourceNotFoundError",
+    "WorkspaceError",
+    "DependencyMissingError",
+    "__version__",
+]

mai/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m mai``."""
+
+from .app import main
+
+if __name__ == "__main__":
+    main()

mai/_core/__init__.py

@@ -0,0 +1 @@
+"""Internal synchronous implementation. Not part of the public API."""

mai/_core/api_response.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def unwrap_data(response: Any) -> Any:
+    """Return the nested ``data`` field when present, otherwise the response itself."""
+    if isinstance(response, dict) and "data" in response:
+        return response["data"]
+    return response

mai/_core/cli_output.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import sys
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+_Echo = Callable[[str], None]
+
+_NOISY_LOGGERS = (
+    "modelscope_hub",
+    "modelscope",
+    "dvc",
+    "dulwich",
+    "scmrepo",
+    "fsspec",
+    "urllib3",
+    "botocore",
+    "boto3",
+    "s3transfer",
+)
+
+_PROVIDER_LABELS = {
+    "hf": "Hugging Face",
+    "ms": "ModelScope",
+}
+
+
+def provider_display_name(provider: str) -> str:
+    return _PROVIDER_LABELS.get(provider.lower(), provider)
+
+
+@contextlib.contextmanager
+def quiet_external_output(*, keep_stderr: bool = False) -> Iterator[None]:
+    """Reduce noisy third-party logging and stdout chatter during CLI orchestration."""
+    previous_levels: dict[str, int] = {}
+    for name in _NOISY_LOGGERS:
+        logger = logging.getLogger(name)
+        previous_levels[name] = logger.level
+        logger.setLevel(logging.WARNING)
+
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr if not keep_stderr else None
+    try:
+        with open(os.devnull, "w", encoding="utf-8") as devnull:
+            sys.stdout = devnull
+            if old_stderr is not None:
+                sys.stderr = devnull
+            try:
+                yield
+            finally:
+                sys.stdout = old_stdout
+                if old_stderr is not None:
+                    sys.stderr = old_stderr
+    finally:
+        for name, level in previous_levels.items():
+            logging.getLogger(name).setLevel(level)
+
+
+@contextlib.contextmanager
+def quiet_stdio() -> Iterator[None]:
+    """Redirect both stdout and stderr to devnull."""
+    old_stdout = sys.stdout
+    old_stderr = sys.stderr
+    with open(os.devnull, "w", encoding="utf-8") as devnull:
+        sys.stdout = devnull
+        sys.stderr = devnull
+        try:
+            yield
+        finally:
+            sys.stdout = old_stdout
+            sys.stderr = old_stderr
+
+
+@dataclass
+class OperationReporter:
+    echo: _Echo
+
+    def phase(self, message: str) -> None:
+        self.echo(message)
+
+
+@dataclass(frozen=True)
+class SyncSummary:
+    resource_type: str
+    name: str
+    version: str
+    source_uri: str
+    path: Path
+
+
+def format_sync_summary(summary: SyncSummary) -> list[str]:
+    return [
+        "Sync completed successfully.",
+        f"  Resource : {summary.resource_type} {summary.name}@{summary.version}",
+        f"  Source   : {summary.source_uri}",
+        f"  Local    : {summary.path}",
+    ]

mai/_core/fvm_provider.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mai._core.operations import fvm
+from mai._core.transport import Transport
+
+
+class TransportFvmProvider:
+    """Adapt a :class:`Transport` to the workspace ``FvmProvider`` protocol."""
+
+    def __init__(self, transport: Transport, *, env: dict[str, str] | None = None) -> None:
+        self._transport = transport
+        self._env = env
+
+    def lookup_fvs(self, bind_type: str, bind_name: str) -> dict[str, Any]:
+        return fvm.lookup_fvs(self._transport, bind_type, bind_name, env=self._env)
+
+    def wait_for_repo_ready(self, fvs_id: str, label: str | None = None) -> dict[str, Any]:
+        return fvm.wait_for_repo_ready(
+            self._transport, fvs_id, label=label, env=self._env
+        )
+
+    def get_fvs_credentials(self, fvs_id: str) -> dict[str, Any]:
+        return fvm.get_fvs_credentials(self._transport, fvs_id, env=self._env)
+
+    def build_git_url(self, fvs_info: dict[str, Any], fallback_name: str) -> str:
+        return fvm.build_git_url(
+            self._transport, fvs_info, fallback_name, env=self._env
+        )
+
+    def notify_branch_pushed(
+        self,
+        fvs_id: str,
+        branch: str,
+        *,
+        message: str = "",
+        paths: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return fvm.notify_branch_pushed(
+            self._transport,
+            fvs_id,
+            branch,
+            message=message,
+            paths=paths,
+            env=self._env,
+        )

mai/_core/image_copy.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+from mai._core.operations.images import normalize_image_ref
+from mai.errors import DependencyMissingError, MaiError
+
+
+@dataclass(frozen=True)
+class ImageCopyPlan:
+    args: list[str]
+
+    @property
+    def command_text(self) -> str:
+        return "skopeo " + " ".join(self.args)
+
+
+def plan_image_copy(
+    source: str,
+    target: str,
+    *,
+    src_tls_verify: bool = False,
+    dest_tls_verify: bool = False,
+) -> ImageCopyPlan:
+    return ImageCopyPlan(
+        args=[
+            "copy",
+            "--all",
+            f"--src-tls-verify={str(src_tls_verify).lower()}",
+            f"--dest-tls-verify={str(dest_tls_verify).lower()}",
+            normalize_image_ref(source, "Source"),
+            normalize_image_ref(target, "Destination"),
+        ]
+    )
+
+
+def execute_image_copy(plan: ImageCopyPlan) -> None:
+    if shutil.which("skopeo") is None:
+        raise DependencyMissingError(
+            "skopeo is required for image copy. Please install skopeo first.",
+            tool="skopeo",
+        )
+    try:
+        completed = subprocess.run(
+            ["skopeo", *plan.args],
+            check=False,
+            text=True,
+            capture_output=True,
+        )
+    except OSError as exc:
+        raise MaiError(f"Failed to run skopeo: {exc}") from exc
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "").strip()
+        message = "skopeo image copy failed"
+        if detail:
+            message = f"{message}: {detail}"
+        raise MaiError(message)

mai/_core/operations/__init__.py

@@ -0,0 +1 @@
+"""Per-capability synchronous operations."""

mai/_core/operations/auth.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mai._core.transport import Transport
+from mai.errors import AuthError
+from mai.models import LoginResult
+
+
+def _extract_token(response: Any) -> str | None:
+    if not isinstance(response, dict):
+        return None
+    token = response.get("token") or response.get("accessToken")
+    if token:
+        return str(token)
+    data = response.get("data")
+    if isinstance(data, dict):
+        token = data.get("token") or data.get("accessToken")
+        if token:
+            return str(token)
+    return None
+
+
+def _extract_error_message(response: Any) -> str:
+    if isinstance(response, dict):
+        message = response.get("msg") or response.get("message") or response.get("error")
+        if message:
+            return str(message)
+    return "Login response did not contain a token."
+
+
+def login(
+    transport: Transport,
+    username: str,
+    password: str,
+    tenant: str | None = None,
+    *,
+    env: dict[str, str] | None = None,
+) -> LoginResult:
+    body: dict[str, str] = {"username": username, "password": password}
+    if tenant:
+        body["tenant"] = tenant
+    response = transport.request_service(
+        "iam", "/api/v1/auth/login", method="POST", body=body, env=env
+    )
+    token = _extract_token(response)
+    if not token:
+        raise AuthError(_extract_error_message(response))
+    return LoginResult(token=token, username=username, tenant=tenant)

mai/_core/operations/config_center.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any, cast
+from urllib.parse import urlencode
+
+from mai._core.api_response import unwrap_data
+from mai._core.transport import Transport
+from mai.errors import ValidationError
+from mai.models import JsonData
+
+_PATHS = {
+    "runtime-config": "/api/v1/runtime-configs",
+    "parameter-template": "/api/v1/parameter-templates",
+}
+_SOURCES = {"custom", "preset"}
+
+
+def _path_for_kind(kind: str) -> str:
+    try:
+        return _PATHS[kind]
+    except KeyError as exc:
+        raise ValidationError(
+            "Unsupported config center resource kind. "
+            "Use runtime-config or parameter-template."
+        ) from exc
+
+
+def _validate_name(name: str, kind: str) -> str:
+    normalized = name.strip()
+    if not normalized:
+        raise ValidationError(f"{kind} name is required.")
+    return normalized
+
+
+def _validate_source(source: str | None) -> str | None:
+    if source is None:
+        return None
+    normalized = source.strip()
+    if normalized and normalized not in _SOURCES:
+        raise ValidationError('--source must be "custom" or "preset".')
+    return normalized or None
+
+
+def resource_exists(
+    transport: Transport,
+    kind: str,
+    *,
+    name: str,
+    source: str | None = None,
+    env: dict[str, str] | None = None,
+) -> bool:
+    path = _path_for_kind(kind)
+    normalized_name = _validate_name(name, kind)
+    normalized_source = _validate_source(source)
+    params = {"name": normalized_name}
+    if normalized_source:
+        params["source"] = normalized_source
+    response = transport.request_service(
+        "ai-nexus",
+        f"{path}/exists?{urlencode(params)}",
+        env=env,
+    )
+    data = unwrap_data(response)
+    return bool(isinstance(data, dict) and data.get("exists") is True)
+
+
+def create_config_center_resource(
+    transport: Transport,
+    kind: str,
+    body: dict[str, Any],
+    *,
+    env: dict[str, str] | None = None,
+) -> JsonData:
+    path = _path_for_kind(kind)
+    name = body.get("name") if isinstance(body, dict) else None
+    _validate_name(str(name or ""), kind)
+    response = transport.request_service(
+        "ai-nexus",
+        path,
+        method="POST",
+        body=body,
+        env=env,
+    )
+    return cast(JsonData, unwrap_data(response))

mai/_core/operations/files.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from urllib.parse import quote, urlsplit
+
+from mai._core.routes import get_service_prefix, resolve_service_base_url
+from mai._core.transport import Transport
+from mai.errors import ApiError
+from mai.models import FileInfo
+
+
+def build_tus_metadata(pairs: dict[str, str]) -> str:
+    return ",".join(
+        f"{key} {base64.b64encode(str(value).encode()).decode()}"
+        for key, value in pairs.items()
+    )
+
+
+def _patch_url(base_url: str, prefix: str, raw_location: str) -> str:
+    if raw_location.startswith(("http://", "https://")):
+        parsed = urlsplit(raw_location)
+        if parsed.path.startswith(prefix):
+            return raw_location
+        return f"{base_url}{prefix}{parsed.path}"
+    return f"{base_url}{raw_location}"
+
+
+def upload_file(
+    transport: Transport,
+    local_path: Path | str,
+    *,
+    remote_path: str | None = None,
+    scope: str = "personal",
+    env: dict[str, str] | None = None,
+) -> FileInfo:
+    path = Path(local_path)
+    size = path.stat().st_size
+    destination = remote_path or f"/{path.name}"
+    base_url = resolve_service_base_url("file-center", fallback_url=transport.base_url, env=env)
+    prefix = get_service_prefix("file-center", base_url, env=env)
+    meta = build_tus_metadata(
+        {"scope": scope, "relativePath": destination, "override": "true"}
+    )
+    headers = {
+        "Tus-Resumable": "1.0.0",
+        "Upload-Length": str(size),
+        "Upload-Metadata": meta,
+        "Content-Length": "0",
+    }
+    create_response = transport.request_raw(
+        f"{prefix}/api/v1/tus/",
+        method="POST",
+        headers=headers,
+        base_url=base_url,
+    )
+    if create_response.status_code != 201:
+        raise ApiError(
+            f"TUS create failed ({create_response.status_code}): {create_response.text[:200]}",
+            status=create_response.status_code,
+            data=create_response.text,
+        )
+    patch_url = _patch_url(base_url, prefix, create_response.headers.get("location", ""))
+    patch_headers = {
+        "Tus-Resumable": "1.0.0",
+        "Upload-Offset": "0",
+        "Content-Type": "application/offset+octet-stream",
+        "Content-Length": str(size),
+    }
+    with path.open("rb") as handle:
+        patch_response = transport.request_raw(
+            patch_url,
+            method="PATCH",
+            headers=patch_headers,
+            content=handle,
+        )
+    if patch_response.status_code != 204:
+        raise ApiError(
+            f"TUS patch failed ({patch_response.status_code}): {patch_response.text[:200]}",
+            status=patch_response.status_code,
+            data=patch_response.text,
+        )
+    url = (
+        f"{base_url}{prefix}/api/v1/resources/download"
+        f"?scope={scope}&paths={quote(destination, safe='')}"
+    )
+    return FileInfo(url=url, path=destination, scope=scope)

mai/_core/operations/fvm.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+from urllib.parse import quote, urlencode, urlsplit
+
+from mai._core.api_response import unwrap_data
+from mai._core.routes import (
+    get_service_prefix,
+    resolve_service_base_url,
+    should_use_gateway_prefix,
+)
+from mai._core.transport import Transport
+from mai.errors import MaiError
+
+
+def _fvm_push_notify_timeout(env: dict[str, str] | None = None) -> float:
+    value = str(
+        (env or {}).get("MAI_FVM_PUSH_NOTIFY_TIMEOUT")
+        or os.environ.get("MAI_FVM_PUSH_NOTIFY_TIMEOUT")
+        or ""
+    ).strip()
+    if value:
+        try:
+            return max(1.0, float(value))
+        except ValueError:
+            return 600.0
+    return 600.0
+
+
+def _truthy(value: str) -> bool | None:
+    normalized = value.strip().lower()
+    if normalized in {"true", "1", "yes", "y", "on"}:
+        return True
+    if normalized in {"false", "0", "no", "n", "off"}:
+        return False
+    return None
+
+
+def should_request_external_credentials(
+    transport: Transport, *, env: dict[str, str] | None = None
+) -> bool:
+    resolved_env = env or os.environ
+    for key in (
+        "MAI_FVM_EXTERNAL",
+        "MAI_EXTERNAL",
+    ):
+        value = resolved_env.get(key)
+        if isinstance(value, str):
+            parsed = _truthy(value)
+            if parsed is not None:
+                return parsed
+    base_url = resolve_service_base_url("fvm", fallback_url=transport.base_url, env=env)
+    return should_use_gateway_prefix(base_url, env=resolved_env)
+
+
+def lookup_fvs(
+    transport: Transport, bind_type: str, name: str, *, env: dict[str, str] | None = None
+) -> dict[str, Any]:
+    query = urlencode({"bindType": bind_type, "name": name})
+    data = unwrap_data(transport.request_service("fvm", f"/api/v1/fvs/lookup?{query}", env=env))
+    if not isinstance(data, dict):
+        raise MaiError(f"Unable to resolve FVS for {bind_type} '{name}'.")
+    return data
+
+
+def get_fvs(
+    transport: Transport, fvs_id: str, *, env: dict[str, str] | None = None
+) -> dict[str, Any]:
+    data = unwrap_data(transport.request_service("fvm", f"/api/v1/fvs/{quote(fvs_id)}", env=env))
+    if not isinstance(data, dict):
+        raise MaiError(f"Unable to fetch FVS '{fvs_id}'.")
+    return data
+
+
+def wait_for_repo_ready(
+    transport: Transport,
+    fvs_id: str,
+    *,
+    label: str | None = None,
+    env: dict[str, str] | None = None,
+    attempts: int = 10,
+    sleep_seconds: float = 2.0,
+) -> dict[str, Any]:
+    max_attempts = max(1, attempts)
+    info: dict[str, Any] = {}
+    status = ""
+    for attempt in range(max_attempts):
+        info = get_fvs(transport, fvs_id, env=env)
+        status = str(info.get("repoStatus") or "").strip().lower()
+        if status in {"", "ready"}:
+            return info
+        if attempt < max_attempts - 1:
+            time.sleep(sleep_seconds)
+    status_message = str(info.get("repoStatusMessage") or "").strip()
+    display = label or f"FVS '{fvs_id}'"
+    detail = f"{status}: {status_message}" if status_message else status
+    raise MaiError(f"FVS repository is not ready for {display}. Status: {detail}")
+
+
+def get_fvs_credentials(
+    transport: Transport,
+    fvs_id: str,
+    *,
+    external: bool | None = None,
+    env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    use_external = (
+        should_request_external_credentials(transport, env=env) if external is None else external
+    )
+    suffix = "?external=true" if use_external else ""
+    data = unwrap_data(
+        transport.request_service(
+            "fvm", f"/api/v1/fvs/{quote(fvs_id)}/credentials{suffix}", env=env
+        )
+    )
+    if not isinstance(data, dict):
+        raise MaiError(f"Unable to fetch credentials for FVS '{fvs_id}'.")
+    return data
+
+
+def notify_branch_pushed(
+    transport: Transport,
+    fvs_id: str,
+    branch: str,
+    *,
+    message: str = "",
+    paths: list[str] | None = None,
+    env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if message:
+        body["message"] = message
+    if paths is not None:
+        body["paths"] = paths
+    data = unwrap_data(
+        transport.request_service(
+            "fvm",
+            f"/api/v1/fvs/{quote(fvs_id)}/branches/{quote(branch)}/push",
+            method="POST",
+            body=body,
+            env=env,
+            timeout=_fvm_push_notify_timeout(env),
+        )
+    )
+    return data if isinstance(data, dict) else {}
+
+
+def get_git_access_token(transport: Transport, *, env: dict[str, str] | None = None) -> str:
+    data = unwrap_data(transport.request_service("fvm", "/api/auth/git-token", env=env))
+    token = ""
+    if isinstance(data, dict):
+        token = data.get("token") or data.get("accessToken") or data.get("gitToken") or ""
+    if not token:
+        raise MaiError("Failed to exchange Git access token from FVM.")
+    return str(token)
+
+
+def build_git_url(
+    transport: Transport,
+    fvs_info: dict[str, Any],
+    fallback_name: str,
+    *,
+    env: dict[str, str] | None = None,
+) -> str:
+    fvs_id = fvs_info.get("id") or fvs_info.get("fvsId") or fvs_info.get("repoId") or fallback_name
+    if not fvs_id:
+        raise MaiError("Unable to resolve Git repository identifier from FVS.")
+    token = quote(get_git_access_token(transport, env=env), safe="")
+    base_url = resolve_service_base_url("fvm", fallback_url=transport.base_url, env=env)
+    prefix = get_service_prefix("fvm", base_url, env=env)
+    parsed = urlsplit(base_url)
+    base_path = parsed.path.rstrip("/")
+    return f"{parsed.scheme}://oauth2:{token}@{parsed.netloc}{base_path}{prefix}/{quote(str(fvs_id))}.git"