gmicloud 0.1.5__tar.gz → 0.1.7__tar.gz

gmicloud-0.1.7/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: gmicloud
+Version: 0.1.7
+Summary: GMI Cloud Python SDK
+Author-email: GMI <gmi@gmitec.net>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+
+# GMICloud SDK
+
+## Overview
+Before you start: Our service and GPU resource is currenly invite-only so please contact our team (getstarted@gmicloud.ai) to get invited if you don't have one yet.
+
+The GMI Inference Engine SDK provides a Python interface for deploying and managing machine learning models in production environments. It allows users to create model artifacts, schedule tasks for serving models, and call inference APIs easily.
+
+This SDK streamlines the process of utilizing GMI Cloud capabilities such as deploying models with Kubernetes-based Ray services, managing resources automatically, and accessing model inference endpoints. With minimal setup, developers can focus on building ML solutions instead of infrastructure.
+
+## Features
+
+- Artifact Management: Easily create, update, and manage ML model artifacts.
+- Task Management: Quickly create, schedule, and manage deployment tasks for model inference.
+- Usage Data Retrieval : Fetch and analyze usage data to optimize resource allocation.
+
+## Installation
+
+To install the SDK, use pip:
+
+```bash
+pip install gmicloud
+```
+
+## Setup
+
+You must configure authentication credentials for accessing the GMI Cloud API. 
+To create account and get log in info please visit **GMI inference platform: https://inference-engine.gmicloud.ai/**.
+
+There are two ways to configure the SDK:
+
+### Option 1: Using Environment Variables
+
+Set the following environment variables:
+
+```shell
+export GMI_CLOUD_CLIENT_ID=<YOUR_CLIENT_ID> # Pick what every ID you need.
+export GMI_CLOUD_EMAIL=<YOUR_EMAIL>
+export GMI_CLOUD_PASSWORD=<YOUR_PASSWORD>
+```
+
+### Option 2: Passing Credentials as Parameters
+
+Pass `client_id`, `email`, and `password` directly to the Client object when initializing it in your script:
+
+```python
+from gmicloud import Client
+
+client = Client(client_id="<YOUR_CLIENT_ID>", email="<YOUR_EMAIL>", password="<YOUR_PASSWORD>")
+```
+
+## Quick Start
+
+### 1. How to run the code in the example folder
+```bash
+cd path/to/gmicloud-sdk
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate
+
+pip install -r requirements.txt
+python -m examples.create_task_from_artifact_template.py
+```
+
+### 2. Example of create an inference task from an artifact template
+
+This is the simplest example to deploy an inference task using an existing artifact template:
+
+Up-to-date code in /examples/create_task_from_artifact_template.py
+
+```python
+from datetime import datetime
+import os
+import sys
+
+from gmicloud import *
+from examples.completion import call_chat_completion
+
+cli = Client()
+
+# List templates offered by GMI cloud 
+templates = cli.list_templates()
+print(f"Found {len(templates)} templates: {templates}")
+
+# Pick a template from the list
+pick_template = "Llama-3.1-8B"
+
+# Create Artifact from template
+artifact_id, recommended_replica_resources = cli.create_artifact_from_template(templates[0])
+print(f"Created artifact {artifact_id} with recommended replica resources: {recommended_replica_resources}")
+
+# Create Task based on Artifact
+task_id = cli.create_task(artifact_id, recommended_replica_resources, TaskScheduling(
+    scheduling_oneoff=OneOffScheduling(
+        trigger_timestamp=int(datetime.now().timestamp()),
+        min_replicas=1,
+        max_replicas=1,
+    )
+))
+task = cli.task_manager.get_task(task_id)
+print(f"Task created: {task.config.task_name}. You can check details at https://inference-engine.gmicloud.ai/user-console/task")
+
+# Start Task and wait for it to be ready
+cli.start_task_and_wait(task.task_id)
+
+# Testing with calling chat completion
+print(call_chat_completion(cli, task.task_id))
+
+```
+
+### 3. Example of creating an inference task based on custom model with local vllm / SGLang serve command
+* Full example is available at [examples/inference_task_with_custom_model.py](https://github.com/GMISWE/python-sdk/blob/main/examples/inference_task_with_custom_model.py)
+
+1. Prepare custom model checkpoint (using a model downloaded from HF as an example)
+
+```python
+# Download model from huggingface
+from huggingface_hub import snapshot_download
+
+model_name = "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"
+model_checkpoint_save_dir = "files/model_garden"
+snapshot_download(repo_id=model_name, local_dir=model_checkpoint_save_dir)
+```
+
+2. Find a template of specific SGLang version
+
+```python
+# export GMI_CLOUD_CLIENT_ID=<YOUR_CLIENT_ID>
+# export GMI_CLOUD_EMAIL=<YOUR_EMAIL>
+# export GMI_CLOUD_PASSWORD=<YOUR_PASSWORD>
+cli = Client()
+
+# List templates offered by GMI cloud 
+templates = cli.artifact_manager.list_public_template_names()
+print(f"Found {len(templates)} templates: {templates}")
+```
+
+3. Pick a template (e.g. SGLang 0.4.5) and prepare a local serve command
+
+```python
+# Example for vllm server
+picked_template_name = "gmi_vllm_0.8.4"
+serve_command = "vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --trust-remote-code --gpu-memory-utilization 0.8"
+
+# Example for sglang server
+picked_template_name = "gmi_sglang_0.4.5.post1"
+serve_command = "python3 -m sglang.launch_server --model-path deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --trust-remote-code --mem-fraction-static 0.8 --tp 2"
+```
+
+4. Create an artifact and upload custom model. The artifact can be reused to create inference tasks later. Artifact also suggests recommended resources for each inference server replica
+
+```python
+artifact_id, recommended_replica_resources = cli.artifact_manager.create_artifact_from_template_name(
+    artifact_template_name=picked_template_name,
+    env_parameters={
+        "SERVER_COMMAND": serve_command,
+        "GPU_TYPE": "H100",
+    }
+)
+print(f"Created artifact {artifact_id} with recommended resources: {recommended_replica_resources}")
+
+# Upload model files to artifact
+cli.artifact_manager.upload_model_files_to_artifact(artifact_id, model_checkpoint_save_dir)
+```
+
+5. Create Inference task (defining min/max inference replica), start and wait
+
+```python
+new_task = Task(
+    config=TaskConfig(
+        ray_task_config=RayTaskConfig(
+            artifact_id=artifact_id,
+            file_path="serve",
+            deployment_name="app",
+            replica_resource=recommended_replica_resources,
+        ),
+        task_scheduling = TaskScheduling(
+            scheduling_oneoff=OneOffScheduling(
+                trigger_timestamp=int(datetime.now().timestamp()),
+                min_replicas=1,
+                max_replicas=4,
+            )
+        ),
+    ),
+)
+task = cli.task_manager.create_task(new_task)
+task_id = task.task_id
+task = cli.task_manager.get_task(task_id)
+print(f"Task created: {task.config.task_name}. You can check details at https://inference-engine.gmicloud.ai/user-console/task")
+
+# Start Task and wait for it to be ready
+cli.task_manager.start_task_and_wait(task_id)
+```
+
+6. Test with sample chat completion request
+
+```python
+print(call_chat_completion(cli, task_id))
+```
+
+
+## API Reference
+
+### Client
+
+Represents the entry point to interact with GMI Cloud APIs.
+Client(
+client_id: Optional[str] = "",
+email: Optional[str] = "",
+password: Optional[str] = ""
+)
+
+### Artifact Management
+
+* get_artifact_templates(): Fetch a list of available artifact templates.
+* create_artifact_from_template(template_id: str): Create a model artifact from a given template.
+* get_artifact(artifact_id: str): Get details of a specific artifact.
+
+### Task Management
+
+* create_task_from_artifact_template(template_id: str, scheduling: TaskScheduling): Create and schedule a task using an
+  artifact template.
+* start_task(task_id: str): Start a task.
+* get_task(task_id: str): Retrieve the status and details of a specific task.
+
+## Notes & Troubleshooting

gmicloud-0.1.7/README.md

@@ -0,0 +1,225 @@
+# GMICloud SDK
+
+## Overview
+Before you start: Our service and GPU resource is currenly invite-only so please contact our team (getstarted@gmicloud.ai) to get invited if you don't have one yet.
+
+The GMI Inference Engine SDK provides a Python interface for deploying and managing machine learning models in production environments. It allows users to create model artifacts, schedule tasks for serving models, and call inference APIs easily.
+
+This SDK streamlines the process of utilizing GMI Cloud capabilities such as deploying models with Kubernetes-based Ray services, managing resources automatically, and accessing model inference endpoints. With minimal setup, developers can focus on building ML solutions instead of infrastructure.
+
+## Features
+
+- Artifact Management: Easily create, update, and manage ML model artifacts.
+- Task Management: Quickly create, schedule, and manage deployment tasks for model inference.
+- Usage Data Retrieval : Fetch and analyze usage data to optimize resource allocation.
+
+## Installation
+
+To install the SDK, use pip:
+
+```bash
+pip install gmicloud
+```
+
+## Setup
+
+You must configure authentication credentials for accessing the GMI Cloud API. 
+To create account and get log in info please visit **GMI inference platform: https://inference-engine.gmicloud.ai/**.
+
+There are two ways to configure the SDK:
+
+### Option 1: Using Environment Variables
+
+Set the following environment variables:
+
+```shell
+export GMI_CLOUD_CLIENT_ID=<YOUR_CLIENT_ID> # Pick what every ID you need.
+export GMI_CLOUD_EMAIL=<YOUR_EMAIL>
+export GMI_CLOUD_PASSWORD=<YOUR_PASSWORD>
+```
+
+### Option 2: Passing Credentials as Parameters
+
+Pass `client_id`, `email`, and `password` directly to the Client object when initializing it in your script:
+
+```python
+from gmicloud import Client
+
+client = Client(client_id="<YOUR_CLIENT_ID>", email="<YOUR_EMAIL>", password="<YOUR_PASSWORD>")
+```
+
+## Quick Start
+
+### 1. How to run the code in the example folder
+```bash
+cd path/to/gmicloud-sdk
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate
+
+pip install -r requirements.txt
+python -m examples.create_task_from_artifact_template.py
+```
+
+### 2. Example of create an inference task from an artifact template
+
+This is the simplest example to deploy an inference task using an existing artifact template:
+
+Up-to-date code in /examples/create_task_from_artifact_template.py
+
+```python
+from datetime import datetime
+import os
+import sys
+
+from gmicloud import *
+from examples.completion import call_chat_completion
+
+cli = Client()
+
+# List templates offered by GMI cloud 
+templates = cli.list_templates()
+print(f"Found {len(templates)} templates: {templates}")
+
+# Pick a template from the list
+pick_template = "Llama-3.1-8B"
+
+# Create Artifact from template
+artifact_id, recommended_replica_resources = cli.create_artifact_from_template(templates[0])
+print(f"Created artifact {artifact_id} with recommended replica resources: {recommended_replica_resources}")
+
+# Create Task based on Artifact
+task_id = cli.create_task(artifact_id, recommended_replica_resources, TaskScheduling(
+    scheduling_oneoff=OneOffScheduling(
+        trigger_timestamp=int(datetime.now().timestamp()),
+        min_replicas=1,
+        max_replicas=1,
+    )
+))
+task = cli.task_manager.get_task(task_id)
+print(f"Task created: {task.config.task_name}. You can check details at https://inference-engine.gmicloud.ai/user-console/task")
+
+# Start Task and wait for it to be ready
+cli.start_task_and_wait(task.task_id)
+
+# Testing with calling chat completion
+print(call_chat_completion(cli, task.task_id))
+
+```
+
+### 3. Example of creating an inference task based on custom model with local vllm / SGLang serve command
+* Full example is available at [examples/inference_task_with_custom_model.py](https://github.com/GMISWE/python-sdk/blob/main/examples/inference_task_with_custom_model.py)
+
+1. Prepare custom model checkpoint (using a model downloaded from HF as an example)
+
+```python
+# Download model from huggingface
+from huggingface_hub import snapshot_download
+
+model_name = "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"
+model_checkpoint_save_dir = "files/model_garden"
+snapshot_download(repo_id=model_name, local_dir=model_checkpoint_save_dir)
+```
+
+2. Find a template of specific SGLang version
+
+```python
+# export GMI_CLOUD_CLIENT_ID=<YOUR_CLIENT_ID>
+# export GMI_CLOUD_EMAIL=<YOUR_EMAIL>
+# export GMI_CLOUD_PASSWORD=<YOUR_PASSWORD>
+cli = Client()
+
+# List templates offered by GMI cloud 
+templates = cli.artifact_manager.list_public_template_names()
+print(f"Found {len(templates)} templates: {templates}")
+```
+
+3. Pick a template (e.g. SGLang 0.4.5) and prepare a local serve command
+
+```python
+# Example for vllm server
+picked_template_name = "gmi_vllm_0.8.4"
+serve_command = "vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --trust-remote-code --gpu-memory-utilization 0.8"
+
+# Example for sglang server
+picked_template_name = "gmi_sglang_0.4.5.post1"
+serve_command = "python3 -m sglang.launch_server --model-path deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B --trust-remote-code --mem-fraction-static 0.8 --tp 2"
+```
+
+4. Create an artifact and upload custom model. The artifact can be reused to create inference tasks later. Artifact also suggests recommended resources for each inference server replica
+
+```python
+artifact_id, recommended_replica_resources = cli.artifact_manager.create_artifact_from_template_name(
+    artifact_template_name=picked_template_name,
+    env_parameters={
+        "SERVER_COMMAND": serve_command,
+        "GPU_TYPE": "H100",
+    }
+)
+print(f"Created artifact {artifact_id} with recommended resources: {recommended_replica_resources}")
+
+# Upload model files to artifact
+cli.artifact_manager.upload_model_files_to_artifact(artifact_id, model_checkpoint_save_dir)
+```
+
+5. Create Inference task (defining min/max inference replica), start and wait
+
+```python
+new_task = Task(
+    config=TaskConfig(
+        ray_task_config=RayTaskConfig(
+            artifact_id=artifact_id,
+            file_path="serve",
+            deployment_name="app",
+            replica_resource=recommended_replica_resources,
+        ),
+        task_scheduling = TaskScheduling(
+            scheduling_oneoff=OneOffScheduling(
+                trigger_timestamp=int(datetime.now().timestamp()),
+                min_replicas=1,
+                max_replicas=4,
+            )
+        ),
+    ),
+)
+task = cli.task_manager.create_task(new_task)
+task_id = task.task_id
+task = cli.task_manager.get_task(task_id)
+print(f"Task created: {task.config.task_name}. You can check details at https://inference-engine.gmicloud.ai/user-console/task")
+
+# Start Task and wait for it to be ready
+cli.task_manager.start_task_and_wait(task_id)
+```
+
+6. Test with sample chat completion request
+
+```python
+print(call_chat_completion(cli, task_id))
+```
+
+
+## API Reference
+
+### Client
+
+Represents the entry point to interact with GMI Cloud APIs.
+Client(
+client_id: Optional[str] = "",
+email: Optional[str] = "",
+password: Optional[str] = ""
+)
+
+### Artifact Management
+
+* get_artifact_templates(): Fetch a list of available artifact templates.
+* create_artifact_from_template(template_id: str): Create a model artifact from a given template.
+* get_artifact(artifact_id: str): Get details of a specific artifact.
+
+### Task Management
+
+* create_task_from_artifact_template(template_id: str, scheduling: TaskScheduling): Create and schedule a task using an
+  artifact template.
+* start_task(task_id: str): Start a task.
+* get_task(task_id: str): Retrieve the status and details of a specific task.
+
+## Notes & Troubleshooting

{gmicloud-0.1.5 → gmicloud-0.1.7}/gmicloud/__init__.py

@@ -15,7 +15,7 @@ from ._internal._models import (
     OneOffScheduling,
     DailyScheduling,
     DailyTrigger,
-    ArtifactTemplate,
+    Template,
 )
 from ._internal._enums import (
     BuildStatus,
@@ -39,7 +39,7 @@ __all__ = [
     "OneOffScheduling",
     "DailyScheduling",
     "DailyTrigger",
-    "ArtifactTemplate",
+    "Template",
     "BuildStatus",
     "TaskEndpointStatus",
 ]

{gmicloud-0.1.5 → gmicloud-0.1.7}/gmicloud/_internal/_client/_artifact_client.py

@@ -1,7 +1,7 @@
 from typing import List
 import logging
 from requests.exceptions import RequestException
-
+import json
 from ._http_client import HTTPClient
 from ._iam_client import IAMClient
 from ._decorator import handle_refresh_token
@@ -120,6 +120,39 @@ class ArtifactClient:
             logger.error(f"Failed to rebuild artifact {artifact_id}: {e}")
             return None
 
+    @handle_refresh_token
+    def add_env_parameters_to_artifact(self, artifact_id: str, env_parameters: dict[str, str]) -> None:
+        """
+        Updates an artifact by its ID.
+
+        :param artifact_id: The ID of the artifact to update.
+        :param request: The request object containing the updated artifact details.
+        """
+        try:
+            old_artifact = self.get_artifact(artifact_id)
+            if not old_artifact:
+                logger.error(f"Artifact {artifact_id} not found")
+                return
+            request = UpdateArtifactRequestBody(
+                artifact_description=old_artifact.artifact_metadata.artifact_description,
+                artifact_name=old_artifact.artifact_metadata.artifact_name,
+                artifact_tags=old_artifact.artifact_metadata.artifact_tags,
+                env_parameters=old_artifact.artifact_parameters.env_parameters,
+                model_parameters=old_artifact.artifact_parameters.model_parameters
+            )
+            new_env_parameters = [EnvParameter(key=k, value=v) for k, v in env_parameters.items()]
+            if not request.env_parameters:
+                request.env_parameters = []
+            request.env_parameters.extend(new_env_parameters)
+            response = self.client.put(
+                f"/update_artifact?artifact_id={artifact_id}",
+                self.iam_client.get_custom_headers(),
+                request.model_dump()
+            )
+        except (RequestException, ValueError) as e:
+            logger.error(f"Failed to add env parameters to artifact {artifact_id}: {e}")
+            return 
+
     @handle_refresh_token
     def delete_artifact(self, artifact_id: str) -> Optional[DeleteArtifactResponse]:
         """
@@ -140,7 +173,7 @@ class ArtifactClient:
             return None
 
     @handle_refresh_token
-    def get_bigfile_upload_url(self, request: GetBigFileUploadUrlRequest) -> Optional[GetBigFileUploadUrlResponse]:
+    def get_bigfile_upload_url(self, request: ResumableUploadLinkRequest) -> Optional[ResumableUploadLinkResponse]:
         """
         Generates a pre-signed URL for uploading a large file.
 
@@ -156,7 +189,7 @@ class ArtifactClient:
                 logger.error("Empty response from /get_bigfile_upload_url")
                 return None
 
-            return GetBigFileUploadUrlResponse.model_validate(response)
+            return ResumableUploadLinkResponse.model_validate(response)
 
         except (RequestException, ValueError) as e:
             logger.error(f"Failed to generate upload URL: {e}")
@@ -186,12 +219,12 @@ class ArtifactClient:
             return None
 
     @handle_refresh_token
-    def get_public_templates(self) -> List[ArtifactTemplate]:
+    def get_public_templates(self) -> List[Template]:
         """
         Fetches all artifact templates.
 
-        :return: A list of ArtifactTemplate objects.
-        :rtype: List[ArtifactTemplate]
+        :return: A list of Template objects.
+        :rtype: List[Template]
         """
         try:
             response = self.client.get("/get_public_templates", self.iam_client.get_custom_headers())
@@ -201,7 +234,7 @@ class ArtifactClient:
                 return []
 
             try:
-                result = GetPublicTemplatesResponse.model_validate(response)
+                result = GetTemplatesResponse.model_validate(response)
                 return result.artifact_templates
             except ValueError as ve:
                 logger.error(f"Failed to validate response data: {ve}")

{gmicloud-0.1.5 → gmicloud-0.1.7}/gmicloud/_internal/_client/_file_upload_client.py

@@ -1,8 +1,10 @@
 import os
 import requests
+import logging
 
 from .._exceptions import UploadFileError
 
+logger = logging.getLogger()
 
 class FileUploadClient:
     CHUNK_SIZE = 10 * 1024 * 1024  # 10MB Default Chunk Size
@@ -45,13 +47,13 @@ class FileUploadClient:
         """
         try:
             file_size = os.path.getsize(file_path)
-            print(f"File Size: {file_size} bytes")
+            logger.info(f"File {file_path} size: {file_size} bytes")
 
             start_byte = 0
             uploaded_range = FileUploadClient._check_file_status(upload_url, file_size)
             if uploaded_range:
                 start_byte = int(uploaded_range.split("-")[1]) + 1
-                print(f"Resuming upload from {start_byte} bytes")
+                logger.info(f"Resuming uploading {file_path} from {start_byte} bytes")
 
             with open(file_path, "rb") as file:
                 while start_byte < file_size:
@@ -74,14 +76,15 @@ class FileUploadClient:
                     # Ensure upload is successful for this chunk
                     if resp.status_code not in (200, 201, 308):
                         raise UploadFileError(
-                            f"Failed to upload file, code:{resp.status_code} ,message: {resp.text}")
+                            f"Failed to upload file {file_path}, code:{resp.status_code} ,message: {resp.text}")
 
                     start_byte = end_byte + 1
-                    print(f"Uploaded {end_byte + 1}/{file_size} bytes")
+                    percentage = (start_byte / file_size) * 100
+                    logger.info(f"File {file_path} uploaded {end_byte + 1:,}/{file_size:,} bytes ({percentage:.2f}%)")
 
-                print("Upload completed successfully.")
+                logger.info(f"File {file_path} uploaded successfully.")
         except Exception as e:
-            raise UploadFileError(f"Failed to upload file: {str(e)}")
+            raise UploadFileError(f"Failed to upload file {file_path}, got error: {str(e)}")
 
     @staticmethod
     def _check_file_status(upload_url: str, file_size: int) -> str:
@@ -104,7 +107,7 @@ class FileUploadClient:
             if resp.status_code == 308:
                 range_header = resp.headers.get("Range")
                 if range_header:
-                    print(f"Server reports partial upload range: {range_header}")
+                    logger.info(f"Server reports partial upload range: {range_header}")
                 return range_header
 
             if resp.status_code in (200, 201):

gmicloud-0.1.7/gmicloud/_internal/_config.py

@@ -0,0 +1,9 @@
+# Dev environment
+# ARTIFACT_SERVICE_BASE_URL = "https://ce-tot.gmicloud-dev.com/api/v1/ie/artifact"
+# TASK_SERVICE_BASE_URL = "https://ce-tot.gmicloud-dev.com/api/v1/ie/task"
+# IAM_SERVICE_BASE_URL = "https://ce-tot.gmicloud-dev.com/api/v1"
+
+# Prod environment
+ARTIFACT_SERVICE_BASE_URL = "https://inference-engine.gmicloud.ai/api/v1/ie/artifact"
+TASK_SERVICE_BASE_URL = "https://inference-engine.gmicloud.ai/api/v1/ie/task"
+IAM_SERVICE_BASE_URL = "https://inference-engine.gmicloud.ai/api/v1"

{gmicloud-0.1.5 → gmicloud-0.1.7}/gmicloud/_internal/_enums.py

@@ -31,3 +31,8 @@ class TaskStatus(str, Enum):
     RUNNING = "running"
     NEEDSTOP = "needstop"
     ARCHIVED = "archived"
+
+class ModelParameterType(str, Enum):
+    NUMERIC = "numeric"
+    TEXT = "text"
+    BOOLEAN = "boolean"