mlops-python-sdk 1.0.2__py3-none-any.whl → 1.0.4__py3-none-any.whl

mlops/connection_config.py

@@ -66,17 +66,7 @@ class ConnectionConfig:
             self.api_path = "/" + self.api_path
 
         # Build API URL
-        if self.debug:
-            base_url = "http://localhost:8090"
-        else:
-            # If domain already includes protocol, use it as-is
-            # Otherwise, default to http:// for backward compatibility
-            if self.domain.startswith(("http://", "https://")):
-                base_url = self.domain
-            else:
-                base_url = f"http://{self.domain}"
-        
-        self.api_url = f"{base_url}{self.api_path}"
+        self.build_api_url()
 
     @staticmethod
     def _get_request_timeout(
@@ -89,7 +79,22 @@ class ConnectionConfig:
             return request_timeout
         else:
             return default_timeout
-
+    
+    def build_api_url(self) -> None:
+        if self.debug:
+            base_url = "http://localhost:8090"
+        else:
+            # If domain already includes protocol, use it as-is
+            # Otherwise, default to http:// for backward compatibility
+            if self.domain.startswith(("http://", "https://")):
+                base_url = self.domain
+            elif self.domain.startswith("localhost") or self.domain.startswith("127.0.0.1"):
+                base_url = f"http://{self.domain}"
+            else:
+                base_url = f"https://{self.domain}"
+        
+        self.api_url = f"{base_url}{self.api_path}"
+        
     def get_request_timeout(self, request_timeout: Optional[float] = None):
         return self._get_request_timeout(self.request_timeout, request_timeout)
 

mlops/task/task.py

@@ -6,9 +6,15 @@ This module provides a convenient interface for managing tasks through the MLOps
 
 import json
 import os
+import shutil
+import sys
+import threading
+import tempfile
+import time
+import zipfile
 from http import HTTPStatus
 from pathlib import Path
-from typing import Optional
+from typing import Callable, Optional
 
 import httpx
 
@@ -53,15 +59,183 @@ def _validate_archive_file_path(file_path: str) -> Path:
         raise APIException(f"file_path must be one of .zip, .tar.gz, .tgz: {p}")
     return p
 
+def _is_archive_path(p: Path) -> bool:
+    lower = p.name.lower()
+    return lower.endswith(".zip") or lower.endswith(".tar.gz") or lower.endswith(".tgz")
+
+
+def _zip_directory(src_dir: Path, dst_zip: Path) -> None:
+    src_dir = src_dir.resolve()
+    root_name = src_dir.name
+    with zipfile.ZipFile(dst_zip, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in src_dir.rglob("*"):
+            if p.is_dir():
+                continue
+            rel = p.relative_to(src_dir).as_posix()
+            if rel in ("", "."):
+                continue
+            zf.write(p, arcname=f"{root_name}/{rel}")
+
+
+def _zip_file(src_file: Path, dst_zip: Path) -> None:
+    src_file = src_file.resolve()
+    with zipfile.ZipFile(dst_zip, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.write(src_file, arcname=src_file.name)
+
+
+def _path_to_archive_path(task_name: str, file_path: str) -> tuple[Path, Callable[[], None]]:
+    """
+    Mirror cli-go `pathToArchivePath` behavior:
+    - directory: zip it
+    - file: if already an archive (.zip/.tar.gz/.tgz) return as-is; otherwise zip it
+    Returns (archive_path, cleanup_callable).
+    """
+    p = Path(os.path.expanduser(file_path)).resolve()
+    if not p.exists():
+        raise APIException(f"File not found: {p}")
+
+    if p.is_dir():
+        tmp_dir = (
+            Path(tempfile.gettempdir())
+            / "xservice-cli"
+            / task_name
+            / time.strftime("%Y%m%d%H%M%S")
+        )
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        archive_path = tmp_dir / f"{p.name}.zip"
+        try:
+            _zip_directory(p, archive_path)
+        except Exception as e:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+            raise APIException(f"failed to compress directory: {e}") from e
+        return archive_path, lambda: shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    if not p.is_file():
+        raise APIException(f"file_path must be a file or directory: {p}")
+
+    if _is_archive_path(p):
+        return _validate_archive_file_path(str(p)), lambda: None
+
+    tmp_dir = (
+        Path(tempfile.gettempdir())
+        / "xservice-cli"
+        / task_name
+        / time.strftime("%Y%m%d%H%M%S")
+    )
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = tmp_dir / f"{p.name}.zip"
+    try:
+        _zip_file(p, archive_path)
+    except Exception as e:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+        raise APIException(f"failed to compress file: {e}") from e
+    return archive_path, lambda: shutil.rmtree(tmp_dir, ignore_errors=True)
+
 
 def _upload_file_to_presigned_url(url: str, file_path: Path, timeout: Optional[float]) -> None:
+    def _format_bytes_iec(n: int) -> str:
+        if n < 1024:
+            return f"{n}B"
+        unit = 1024.0
+        suffixes = ["KiB", "MiB", "GiB", "TiB", "PiB"]
+        v = float(n)
+        i = -1
+        while v >= unit and i < len(suffixes) - 1:
+            v /= unit
+            i += 1
+        return f"{v:.1f}{suffixes[i]}"
+
+    def _render_bar(done: int, total: int, width: int = 28) -> str:
+        if total <= 0 or width <= 1:
+            return ">"
+        done = max(0, min(done, total))
+        filled = int(width * (done / total))
+        if filled >= width:
+            return "=" * width
+        if filled <= 0:
+            return ">" + (" " * (width - 1))
+        return ("=" * filled) + ">" + (" " * (width - filled - 1))
+
+    def _format_elapsed_seconds(start: float) -> str:
+        sec = int(max(0.0, time.monotonic() - start))
+        return f"{sec}s"
+
+    class _ProgressIterable:
+        def __init__(self, f, total: int, name: str, chunk_size: int = 64 * 1024):
+            self._f = f  # file-like object
+            self._total = max(0, int(total))
+            self._name = name
+            self._chunk_size = max(1, int(chunk_size))
+            self._read = 0
+            self._start = time.monotonic()
+            self._completed = False
+            self._out = sys.stdout
+            try:
+                self._is_tty = bool(self._out.isatty())
+            except Exception:
+                self._is_tty = False
+
+        def _render_line(self, display_read: int) -> str:
+            display_read = max(0, min(int(display_read), self._total))
+            pct = (display_read / self._total) * 100.0 if self._total > 0 else 0.0
+            bar = _render_bar(display_read, self._total, width=28)
+            elapsed = _format_elapsed_seconds(self._start)
+            return (
+                f"uploading {self._name} [{bar}] {pct:6.2f}% "
+                f"({_format_bytes_iec(display_read)}/{_format_bytes_iec(self._total)}) "
+                f"elapsed {elapsed}"
+            )
+
+        def _print_line(self, line: str, final: bool = False) -> None:
+            if self._is_tty:
+                # Refresh same line in terminal.
+                print("\r" + line, end="" if not final else "\n", file=self._out, flush=True)
+            else:
+                # Always visible in non-TTY environments.
+                print(line, file=self._out, flush=True)
+
+        def __iter__(self):
+            stop_event = threading.Event()
+
+            def ticker() -> None:
+                last_sec = -1
+                # Print immediately so users see something right away.
+                self._print_line(self._render_line(self._read))
+                while not stop_event.is_set():
+                    sec = int(max(0.0, time.monotonic() - self._start))
+                    if sec != last_sec:
+                        last_sec = sec
+                        self._print_line(self._render_line(self._read))
+                    # check frequently to avoid skipping seconds
+                    stop_event.wait(0.05)
+
+            t = threading.Thread(target=ticker, name="mlops-upload-progress", daemon=True)
+            t.start()
+            try:
+                while True:
+                    chunk = self._f.read(self._chunk_size)
+                    if not chunk:
+                        break
+                    self._read += len(chunk)
+                    yield chunk
+            finally:
+                # Ensure a final 100% line and stop ticker.
+                self._read = self._total
+                self._completed = True
+                stop_event.set()
+                t.join(timeout=0.2)
+                self._print_line(self._render_line(self._read), final=True)
+
     size = file_path.stat().st_size
     # Use a dedicated client for S3 presigned upload (avoid leaking API auth headers).
     with httpx.Client(timeout=timeout) as client:
         with file_path.open("rb") as f:
+            content = f
+            if size > 0:
+                content = _ProgressIterable(f, total=size, name=file_path.name)
             resp = client.put(
                 url,
-                content=f,
+                content=content,
                 headers={
                     "Content-Length": str(size),
                     "Content-Type": "application/octet-stream",
@@ -147,6 +321,7 @@ class Task:
             config.api_key = api_key
         if domain is not None:
             config.domain = domain
+            config.build_api_url()
         if debug is not None:
             config.debug = debug
         if request_timeout is not None:
@@ -229,84 +404,82 @@ class Task:
                 request_kwargs["ntasks"] = 1
 
         if file_path:
-            local_path = _validate_archive_file_path(file_path)
+            local_path, cleanup = _path_to_archive_path(name, file_path)
             timeout = self._config.get_request_timeout()
-
-            # 1) Get presigned upload URL
-            presign_upload_obj = get_storage_presign_upload.sync_detailed(
-                client=self._client,
-                filename=local_path.name,
-            )
-            presign_upload = presign_upload_obj.parsed
-            if isinstance(presign_upload, ErrorResponse):
-                status_code = (
-                    presign_upload.code
-                    if presign_upload.code != UNSET and presign_upload.code != 0
-                    else presign_upload_obj.status_code.value
+            try:
+                # 1) Get presigned upload URL
+                presign_upload_obj = get_storage_presign_upload.sync_detailed(
+                    client=self._client,
+                    filename=local_path.name,
                 )
-                exception = handle_api_exception(
-                    Response(
-                        status_code=HTTPStatus(status_code),
-                        content=presign_upload_obj.content,
-                        headers=presign_upload_obj.headers,
-                        parsed=None,
+                presign_upload = presign_upload_obj.parsed
+                if isinstance(presign_upload, ErrorResponse):
+                    status_code = (
+                        presign_upload.code
+                        if presign_upload.code != UNSET and presign_upload.code != 0
+                        else presign_upload_obj.status_code.value
                     )
-                )
-                raise exception
-
-            if (
-                presign_upload is None
-                or presign_upload.url in (UNSET, None)
-                or presign_upload.key in (UNSET, None)
-            ):
-                raise APIException("Failed to get presigned upload url: empty response")
-
-            # 2) Upload file to S3 (presigned URL)
-            _upload_file_to_presigned_url(
-                url=str(presign_upload.url),
-                file_path=local_path,
-                timeout=timeout,
-            )
-
-            # 3) Get presigned download URL
-            presign_download_obj = get_storage_presign_download.sync_detailed(
-                client=self._client,
-                key=str(presign_upload.key),
-            )
-            presign_download = presign_download_obj.parsed
-            if isinstance(presign_download, ErrorResponse):
-                status_code = (
-                    presign_download.code
-                    if presign_download.code != UNSET and presign_download.code != 0
-                    else presign_download_obj.status_code.value
-                )
-                exception = handle_api_exception(
-                    Response(
-                        status_code=HTTPStatus(status_code),
-                        content=presign_download_obj.content,
-                        headers=presign_download_obj.headers,
-                        parsed=None,
+                    exception = handle_api_exception(
+                        Response(
+                            status_code=HTTPStatus(status_code),
+                            content=presign_upload_obj.content,
+                            headers=presign_upload_obj.headers,
+                            parsed=None,
+                        )
                     )
+                    raise exception
+
+                if (
+                    presign_upload is None
+                    or presign_upload.url in (UNSET, None)
+                    or presign_upload.key in (UNSET, None)
+                ):
+                    raise APIException("Failed to get presigned upload url: empty response")
+
+                # 2) Upload file to S3 (presigned URL)
+                _upload_file_to_presigned_url(
+                    url=str(presign_upload.url),
+                    file_path=local_path,
+                    timeout=timeout,
                 )
-                raise exception
 
-            if presign_download is None or presign_download.url in (UNSET, None):
-                raise APIException(
-                    "Failed to get presigned download url: empty response"
+                # 3) Get presigned download URL
+                presign_download_obj = get_storage_presign_download.sync_detailed(
+                    client=self._client,
+                    key=str(presign_upload.key),
                 )
-
-            # 4) Set env var (merge if user already provided environment)
-            env: dict[str, str] = {}
-            existing_env = request_kwargs.get("environment")
-            if isinstance(existing_env, TaskSubmitRequestEnvironmentType0):
-                env.update(existing_env.additional_properties)
-            elif isinstance(existing_env, dict):
-                env.update(existing_env)
-
-            env["SYSTEM_DOWNLOAD_ARCHIVE_URL"] = str(presign_download.url)
-            request_kwargs["environment"] = TaskSubmitRequestEnvironmentType0.from_dict(
-                env
-            )
+                presign_download = presign_download_obj.parsed
+                if isinstance(presign_download, ErrorResponse):
+                    status_code = (
+                        presign_download.code
+                        if presign_download.code != UNSET and presign_download.code != 0
+                        else presign_download_obj.status_code.value
+                    )
+                    exception = handle_api_exception(
+                        Response(
+                            status_code=HTTPStatus(status_code),
+                            content=presign_download_obj.content,
+                            headers=presign_download_obj.headers,
+                            parsed=None,
+                        )
+                    )
+                    raise exception
+
+                if presign_download is None or presign_download.url in (UNSET, None):
+                    raise APIException("Failed to get presigned download url: empty response")
+
+                # 4) Set env var (merge if user already provided environment)
+                env: dict[str, str] = {}
+                existing_env = request_kwargs.get("environment")
+                if isinstance(existing_env, TaskSubmitRequestEnvironmentType0):
+                    env.update(existing_env.additional_properties)
+                elif isinstance(existing_env, dict):
+                    env.update(existing_env)
+
+                env["SYSTEM_DOWNLOAD_ARCHIVE_URL"] = str(presign_download.url)
+                request_kwargs["environment"] = TaskSubmitRequestEnvironmentType0.from_dict(env)
+            finally:
+                cleanup()
 
         request = TaskSubmitRequest(**request_kwargs)
 

mlops_python_sdk-1.0.4.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.3
+Name: mlops-python-sdk
+Version: 1.0.4
+Summary: MLOps Python SDK for XCloud Service API
+License: MIT
+Author: mlops
+Author-email: mlops@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: attrs (>=23.2.0)
+Requires-Dist: httpx (>=0.27.0,<1.0.0)
+Requires-Dist: packaging (>=24.1)
+Requires-Dist: python-dateutil (>=2.8.2)
+Requires-Dist: typing-extensions (>=4.1.0)
+Project-URL: Bug Tracker, https://github.com/xcloud-service/xservice/issues
+Project-URL: Homepage, https://mlops.cloud/
+Project-URL: Repository, https://github.com/xcloud-service/xservice
+Description-Content-Type: text/markdown
+
+# SDK
+
+Software Development Kits for integrating with the XCloud Service API.
+
+> [!NOTE] SDK Support
+> SDKs provide type-safe, high-level interfaces for interacting with the platform API. They handle authentication, error handling, and request retries automatically.
+
+
+## Installation
+
+The Python SDK installation.
+
+```bash
+pip install mlops-python-sdk
+```
+
+### Configuration
+
+The SDK reads configuration from environment variables by default:
+
+- `MLOPS_API_KEY`: API key (required)
+- `MLOPS_DOMAIN`: API domain, e.g. `localhost:8090` or `https://example.com`
+- `MLOPS_API_PATH`: API path prefix (default: `/api/v1`)
+- `MLOPS_DEBUG`: `true|false` (default: `false`)
+
+Or configure in code:
+
+```python
+from mlops import ConnectionConfig, Task
+
+config = ConnectionConfig(
+    api_key="xck_...",
+    domain="https://example.com",
+    api_path="/api/v1",
+    debug=False,
+)
+task = Task(config=config)
+```
+
+## SDK Usage
+
+### Initialize client
+
+```python
+from mlops import Task
+
+task = Task()  # uses environment variables by default
+```
+
+### Submit a GPU task
+
+```python
+from mlops import Task
+
+task = Task()
+resp = task.submit(
+    name="gpu-task-from-sdk",
+    cluster_name="slurm-cn",
+    team_id=1,
+    image="/mnt/minio/images/01ai-registry.cn-shanghai.cr.aliyuncs.com+public+llamafactory+0.9.3.sqsh",
+    entry_command="llamafactory-cli train /workspace/config/test_lora.yaml",
+    resources={
+        "partition": "gpu",
+        "nodes": 2,
+        "ntasks": 2,
+        "cpus_per_task": 2,
+        "memory": "4G",
+        "time": "01:00:00",
+        "gres": "gpu:nvidia_a10:1",
+        "qos": "qos_xcloud",
+    },
+    file_path="/path/to/xservice.zip",  # optional: .zip/.tar.gz/.tgz
+)
+print(resp.job_id)
+```
+
+### Submit a CPU task
+
+```python
+from mlops import Task
+
+task = Task()
+resp = task.submit(
+    name="cpu-task-from-sdk",
+    cluster_name="slurm-cn",
+    team_id=1,
+    image="docker://01ai-registry.cn-shanghai.cr.aliyuncs.com/01-ai/xcs/v2/alpine:3.23.0",
+    entry_command="echo hello",
+    resources={
+        "partition": "cpu",
+        "nodes": 1,
+        "ntasks": 1,
+        "cpus_per_task": 1,
+        "memory": "1G",
+        "time": "01:00:00",
+        "qos": "qos_xcloud",
+    },
+)
+print(resp.job_id)
+```
+
+### List tasks
+
+```python
+from mlops import Task
+from mlops.api.client.models.task_status import TaskStatus
+
+task = Task()
+resp = task.list(status=TaskStatus.COMPLETED, cluster_name="slurm-cn", page=1, page_size=20)
+print(len(resp.tasks or []))
+```
+
+### Get task details
+
+```python
+from mlops import Task
+
+task = Task()
+task_info = task.get(task_id=12345, cluster_name="slurm-cn")
+print(task_info)
+```
+
+### Cancel a task
+
+```python
+from mlops import Task
+
+task = Task()
+task.cancel(task_id=12345, cluster_name="slurm-cn")
+```
+
+### Delete a task
+
+```python
+from mlops import Task
+
+task = Task()
+task.delete(task_id=12345, cluster_name="slurm-cn")
+```
+
+**Task Management Methods:**
+
+- `submit()` - Submit a new task with container image and entry command
+- `get()` - Get task details by task ID
+- `list()` - List tasks with optional filters (status, cluster_name, team_id, user_id)
+- `cancel()` - Cancel a running task
+- `delete()` - Delete a task record
+
+**Task Status Values:**
+
+```python
+from mlops.api.client.models.task_status import TaskStatus
+
+TaskStatus.PENDING      # Task is pending
+TaskStatus.QUEUED       # Task is queued
+TaskStatus.RUNNING      # Task is running
+TaskStatus.COMPLETED    # Task completed successfully
+TaskStatus.SUCCEEDED    # Task succeeded
+TaskStatus.FAILED       # Task failed
+TaskStatus.CANCELLED    # Task was cancelled
+TaskStatus.CREATED      # Task was created
+```
+
+**Error Handling:**
+
+```python
+from mlops.exceptions import (
+    APIException,
+    AuthenticationException,
+    NotFoundException,
+    RateLimitException,
+    TimeoutException,
+    InvalidArgumentException,
+    NotEnoughSpaceException
+)
+from mlops import Task
+
+task = Task()
+
+try:
+    result = task.submit(
+        name="test",
+        cluster_name="slurm-cn",
+        image="docker://alpine:3.23.0",
+        entry_command="echo hello",
+    )
+except AuthenticationException as e:
+    print(f"Authentication failed: {e}")
+except NotFoundException as e:
+    print(f"Resource not found: {e}")
+except APIException as e:
+    print(f"API error: {e}")
+```
+
+> [!TIP] Error Handling
+> SDKs automatically parse typed responses and raise structured exceptions.
+
+## Features
+
+- Type-safe API clients
+- Automatic authentication
+- Error handling
+- Typed response parsing (generated models)
+- Unexpected-status guard (optional)
+
+## Resources
+
+- [Python SDK Documentation](https://github.com/xcloud-service/xservice/tree/main/client/python-sdk)
+- [API Reference](https://xcloud-service.com/docs/api)
+

{mlops_python_sdk-1.0.2.dist-info → mlops_python_sdk-1.0.4.dist-info}/RECORD

@@ -42,11 +42,11 @@ mlops/api/client/models/task_tres_type_0.py,sha256=rEaiQG7A19mlTIHDppzxuWa4oPfh9
 mlops/api/client/models/task_tres_used_type_0.py,sha256=4w6An7-ZCqa8cc3SPi7mcwGK-ekT6AYq_dEdf8KzoYA,1320
 mlops/api/client/py.typed,sha256=8ZJUsxZiuOy1oJeVhsTWQhTG_6pTVHVXk5hJL79ebTk,25
 mlops/api/client/types.py,sha256=AX4orxQZQJat3vZrgjJ-TYb2sNBL8kNo9yqYDT-n8y8,1391
-mlops/connection_config.py,sha256=_b9sVFGJtf1GynmIB4NtKCzg7kkgE-wSrsG3LwzlOqk,2946
+mlops/connection_config.py,sha256=yrY-FKyqtgqXmbAQyhlLIwDy1wDyjnT_mOhAFHAzek0,3170
 mlops/exceptions.py,sha256=3kfda-Rz0km9kV-gvnPCw7ueemWkXIGGdT0NXx6z9Xk,1680
 mlops/task/__init__.py,sha256=M983vMPLj3tZQNFXQyTP5I2RsRorFElezLeppr3WLsw,133
 mlops/task/client.py,sha256=V131WLVJl1raGAVixUhJCX8s1neN15mxAjQwO01qlIg,3552
-mlops/task/task.py,sha256=Y_lWpIVY9Wq-2iuaoZYuskcWHasUzLSpXi9fkwn7S3s,23882
-mlops_python_sdk-1.0.2.dist-info/METADATA,sha256=lBkRytOiRISGMHHzk93fijbmF9EC9iKSpHm-6I9QNsM,7637
-mlops_python_sdk-1.0.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-mlops_python_sdk-1.0.2.dist-info/RECORD,,
+mlops/task/task.py,sha256=HT7TtOqLw4FvF80c-_I-XWK97_9OBR7pC2i2NGZNVO4,30663
+mlops_python_sdk-1.0.4.dist-info/METADATA,sha256=3_g9WfaGdDtmNBnqMONGOTL_Mol8UAdC607tE947kLs,5679
+mlops_python_sdk-1.0.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+mlops_python_sdk-1.0.4.dist-info/RECORD,,

mlops_python_sdk-1.0.2.dist-info/METADATA

@@ -1,254 +0,0 @@
-Metadata-Version: 2.3
-Name: mlops-python-sdk
-Version: 1.0.2
-Summary: MLOps Python SDK for XCloud Service API
-License: MIT
-Author: mlops
-Author-email: mlops@example.com
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: attrs (>=23.2.0)
-Requires-Dist: httpx (>=0.27.0,<1.0.0)
-Requires-Dist: packaging (>=24.1)
-Requires-Dist: python-dateutil (>=2.8.2)
-Requires-Dist: typing-extensions (>=4.1.0)
-Project-URL: Bug Tracker, https://github.com/xcloud-service/xservice/issues
-Project-URL: Homepage, https://mlops.cloud/
-Project-URL: Repository, https://github.com/xcloud-service/xservice
-Description-Content-Type: text/markdown
-
-# SDK
-
-Software Development Kits for integrating with the XCloud Service API.
-
-> [!NOTE] SDK Support
-> SDKs provide type-safe, high-level interfaces for interacting with the platform API. They handle authentication, error handling, and request retries automatically.
-
-## Available SDKs
-
-### Python SDK
-
-### Installation
-
-The Python SDK installation.
-
-```bash
-pip install mlops-python-sdk
-```
-
-### Configuration
-
-The SDK reads configuration from environment variables by default:
-
-- `MLOPS_API_KEY`: API key (required)
-- `MLOPS_DOMAIN`: API domain, e.g. `localhost:8090` or `https://example.com`
-- `MLOPS_API_PATH`: API path prefix (default: `/api/v1`)
-- `MLOPS_DEBUG`: `true|false` (default: `false`)
-
-Or configure in code:
-
-```python
-from mlops import ConnectionConfig, Task
-
-config = ConnectionConfig(
-    api_key="xck_...",
-    domain="https://example.com",
-    api_path="/api/v1",
-    debug=False,
-)
-task = Task(config=config)
-```
-
-### Usage
-
-```python
-from mlops import Task
-from mlops.api.client.models.task_status import TaskStatus
-from pathlib import Path
-
-# Initialize Task client (uses environment variables by default)
-task = Task()
-
-# Submit a task with gpu type
-try:
-    result = task.submit(
-        name="gpu-task-from-sdk",
-        image="/mnt/minio/images/01ai-registry.cn-shanghai.cr.aliyuncs.com+public+llamafactory+0.9.3.sqsh",
-        entry_command="llamafactory-cli train /workspace/config/test_lora.yaml",
-        resources={
-            "partition": "gpu",
-            "nodes": 2,
-            "ntasks": 2,
-            "cpus_per_task": 2,
-            "memory": "4G",
-            "time": "01:00:00",
-            "gres": "gpu:nvidia_a10:1",
-            "qos": "qos_xcloud",
-            },
-        cluster_name="slurm-cn",
-        team_id=1,
-        file_path="your file path", # optional, support for .zip, .tar.gz, .tgz
-    )
-
-    if result is not None:
-        print("==== gpu task submitted successfully ====")
-        job_id = result.job_id
-    else:
-        print("==== gpu task submitted failed ====")
-except Exception as e:
-    print("==== gpu task submitted failed error ====", e)
-
-# Submit a task with cpu type
-try:
-    entry_content = Path("entry.sh").read_text(encoding="utf-8")
-    result = task.submit(
-        name="cpu-task-from-sdk",
-        image="docker://01ai-registry.cn-shanghai.cr.aliyuncs.com/01-ai/xcs/v2/alpine:3.23.0",
-        entry_command=entry_content,
-        resources={
-            "partition": "cpu",
-            "nodes": 1,
-            "ntasks": 1,
-            "cpus_per_task": 1,
-            "memory": "1G",
-            "time": "01:00:00",
-            "qos": "qos_xcloud",
-        },
-        cluster_name="slurm-cn",
-        team_id=1,
-    )
-
-    if result is not None:
-        print("==== cpu task submitted successfully ====")
-        job_id = result.job_id
-    else:
-        print("==== cpu task submitted failed ====")
-except Exception as e:
-    print("==== cpu task submitted failed error ====", e)
-
-# List tasks with filters
-try:
-    completed_tasks = task.list(
-        status=TaskStatus.COMPLETED,
-        cluster_name="slurm-cn",
-        page=1,
-        page_size=20
-    )
-
-    # Get task details
-    if completed_tasks is not None and len(completed_tasks.tasks) > 0:
-        print("==== completed_tasks number ====", len(completed_tasks.tasks))
-        task_info = task.get(task_id=completed_tasks.tasks[0].job_id, cluster_name="slurm-cn")
-        print("==== task_info ====", task_info)
-    else:
-        print("==== no completed tasks to get details ====")
-except Exception as e:
-    print("==== get task details failed error ====", e)
-
-
-# Cancel a running task
-try:
-    running_tasks = task.list(
-        status=TaskStatus.RUNNING,
-        cluster_name="slurm-cn",
-        page=1,
-        page_size=20
-    )
-    if running_tasks is not None and len(running_tasks.tasks) > 0:
-        print("==== running_tasks number ====", len(running_tasks.tasks))
-        # Cancel a task
-        result = task.cancel(task_id=running_tasks.tasks[0].job_id, cluster_name="slurm-cn")
-        print("==== task cancelled ====", running_tasks.tasks[0].job_id, result)
-    else:
-        print("==== no running tasks to cancel ====")
-except Exception as e:
-    print("==== cancel running task failed error ====", e)
-
-
-# Delete a task
-try:
-    completed_tasks = task.list(
-        status=TaskStatus.COMPLETED,
-        cluster_name="slurm-cn",
-        page=1,
-        page_size=20
-    )
-    if completed_tasks is not None and len(completed_tasks.tasks) > 0:
-        print("==== completed_tasks number ====", len(completed_tasks.tasks))
-        # Delete a task
-        result = task.delete(task_id=completed_tasks.tasks[0].job_id, cluster_name="slurm-cn")
-        print("==== task deleted ====", completed_tasks.tasks[0].job_id, result)
-    else:
-        print("==== no completed tasks to delete ====")
-except Exception as e:
-    print("==== delete completed task failed error ====", e)
-```
-
-**Task Management Methods:**
-
-- `submit()` - Submit a new task with container image and entry command
-- `get()` - Get task details by task ID
-- `list()` - List tasks with optional filters (status, cluster_name, team_id, user_id)
-- `cancel()` - Cancel a running task
-- `delete()` - Delete a task record
-
-**Task Status Values:**
-
-```python
-from mlops.api.client.models.task_status import TaskStatus
-
-TaskStatus.PENDING      # Task is pending
-TaskStatus.QUEUED       # Task is queued
-TaskStatus.RUNNING      # Task is running
-TaskStatus.COMPLETED    # Task completed successfully
-TaskStatus.SUCCEEDED    # Task succeeded
-TaskStatus.FAILED       # Task failed
-TaskStatus.CANCELLED    # Task was cancelled
-TaskStatus.CREATED      # Task was created
-```
-
-**Error Handling:**
-
-```python
-from mlops.exceptions import (
-    APIException,
-    AuthenticationException,
-    NotFoundException,
-    RateLimitException,
-    TimeoutException,
-    InvalidArgumentException,
-    NotEnoughSpaceException
-)
-
-try:
-    result = task.submit(name="test", cluster_name="slurm-cn", command="echo hello")
-except AuthenticationException as e:
-    print(f"Authentication failed: {e}")
-except NotFoundException as e:
-    print(f"Resource not found: {e}")
-except APIException as e:
-    print(f"API error: {e}")
-```
-
-> [!TIP] Error Handling
-> SDKs automatically handle common errors and retry failed requests. Check SDK documentation for error handling best practices.
-
-## Features
-
-- Type-safe API clients
-- Automatic authentication
-- Error handling
-- Request retry logic
-- Response validation
-
-## Resources
-
-- [Python SDK Documentation](https://github.com/xcloud-service/xservice/tree/main/client/python-sdk)
-- [API Reference](https://xcloud-service.com/docs/api)
-