| Name | modzy-sdk JSON |
| Version |
0.11.6
JSON |
| download |
| home_page | https://github.com/modzy/sdk-python |
| Summary | Modzy's Python SDK queries and deploys models, submits inference jobs and returns results directly to your editor. |
| upload_time | 2023-09-08 15:53:39 |
| maintainer | |
| docs_url | None |
| author | Modzy |
| requires_python | >=3.7 |
| license | |
| keywords |
modzy
sdk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
**[Python SDK Documentation Page](https://docs.modzy.com)**
</div>
# Installation
Install Modzy's Python SDK with PIP
```bash
pip install modzy-sdk
```
# Usage/Examples
## Initializing the SDK
Initialize your client by authenticating with an API key. You can [download an API Key](https://docs.modzy.com/docs/view-and-manage-api-keys#download-team-api-key) from your instance of Modzy.
```python
from modzy import ApiClient
# Sets BASE_URL and API_KEY values
# Best to set these as environment variables
BASE_URL = "Valid Modzy URL" # e.g., "https://trial.modzy.com"
API_KEY = "Valid Modzy API Key" # e.g., "JbFkWZMx4Ea3epIrxSgA.a2fR36fZi3sdFPoztAXT"
client = ApiClient(base_url=BASE_URL, api_key=API_KEY)
```
## Running Inferences
### Raw Text Inputs
Submit an inference job to a text-based model by providing the model ID, version, and raw input text:
```python
# Creates a dictionary for text input(s)
sources = {}
# Adds any number of inputs
sources["first-phone-call"] = {
"input.txt": "Mr Watson, come here. I want to see you.",
}
# Submit the text to v1.0.1 of a Sentiment Analysis model, and to make the job explainable, change explain=True
job = client.jobs.submit_text("ed542963de", "1.0.1", sources, explain=False)
```
### File Inputs
Pass a file from your local directory to a model by providing the model ID, version, and the filepath of your sample data:
```python
# Generate a mapping of your local file (nyc-skyline.jpg) to the input filename the model expects
sources = {"nyc-skyline": {"image": "./images/nyc-skyline.jpg"}}
# Submit the image to v1.0.1 of an Image-based Geolocation model
job = client.jobs.submit_file("aevbu1h3yw", "1.0.1", sources)
```
### Embedded Inputs
Convert images and other large inputs to base64 embedded data and submit to a model by providing a model ID, version number, and dictionary with one or more base64 encoded inputs:
```python
from modzy._util import file_to_bytes
# Embed input as a string in base64
image_bytes = file_to_bytes('./images/tower-bridge.jpg')
# Prepare the source dictionary
sources = {"tower-bridge": {"image": image_bytes}}
# Submit the image to v1.0.1 of an Imaged-based Geolocation model
job = client.jobs.submit_embedded("aevbu1h3yw", "1.0.1", sources)
```
### Inputs from Databases
Submit data from a SQL database to a model by providing a model ID, version, a SQL query, and database connection credentials:
```python
# Add database connection and query information
db_url = "jdbc:postgresql://db.bit.io:5432/bitdotio"
db_username = DB_USER_NAME
db_password = DB_PASSWORD
db_driver = "org.postgresql.Driver"
# Select as "input.txt" becase that is the required input name for this model
db_query = "SELECT \"mailaddr\" as \"input.txt\" FROM \"user/demo_repo\".\"atl_parcel_attr\" LIMIT 10;"
# Submit the database query to v0.0.12 of a Named Entity Recognition model
job = client.jobs.submit_jdbc("a92fc413b5","0.0.12",db_url, db_username, db_password, db_driver, db_query)
```
### Inputs from Cloud Storage
Submit data directly from your cloud storage bucket (Amazon S3, Azure Blob, NetApp StorageGrid supported) by providing a model ID, version, and storage-blob-specific parameters.
#### AWS S3
```python
# Define sources dictionary with bucket and key that points to the correct file in your s3 bucket
sources = {
"first-amazon-review": {
"input.txt": {
"bucket": "s3-bucket-name",
"key": "key-to-file.txt"
}
}
}
AWS_ACCESS_KEY = "aws-acces-key"
AWC_SECRET_ACCESS_KEY = "aws-secret-access-key"
AWS_REGION = "us-east-1"
# Submit s3 input to v1.0.1 of a Sentiment Analysis model
job = client.jobs.submit_aws_s3("ed542963de", "1.0.1", sources, AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY, AWS_REGION)
```
#### Azure Blob Storage
```python
# Define sources dictionary with container name and filepath that points to the correct file in your Azure Blob container
sources = {
"first-amazon-review": {
"input.txt": {
"container": "azure-blob-container-name",
"filePath": "key-to-file.txt"
}
}
}
AZURE_STORAGE_ACCOUNT = "Azure-Storage-Account"
AZURE_STORAGE_ACCOUNT_KEY = "cvx....ytw=="
# Submit Azure Blob input to v1.0.1 of a Sentiment Analysis model
job = client.jobs.submit_azureblob("ed542963de", "1.0.1", sources, AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_ACCOUNT_KEY)
```
#### NetApp StorageGRID
```python
# Define sources dictionary with bucket name and key that points to the correct file in your NetApp StorageGRID bucket
sources = {
"first-amazon-review": {
"input.txt": {
"bucket": "bucket-name",
"key": "key-to-file.txt"
}
}
}
ACCESS_KEY = "access-key"
SECRET_ACCESS_KEY = "secret-access-key"
STORAGE_GRID_ENDPOINT = "https://endpoint.storage-grid.example"
# Submit StorageGRID input to v1.0.1 of a Sentiment Analysis model
job = client.jobs.submit_storagegrid("ed542963de", "1.0.1", sources, ACCESS_KEY, SECRET_ACCESS_KEY, STORAGE_GRID_ENDPOINT)
```
## Getting Results
Modzy's APIs are asynchronous by nature, which means you can use the `results` API to query available results for all completed inference jobs at any point in time. There are two ways you might leverage this Python SDK to query results:
### Block Job until it completes
This method provides a mechanism to mimic a sycnchronous API by using two different APIs subsequently and a utility function.
```python
# Define sources dictionary with input data
sources = {"my-input": {"input.txt": "Today is a beautiful day!"}}
# Submit the text to v1.0.1 of a Sentiment Analysis model, and to make the job explainable, change explain=True
job = client.jobs.submit_text("ed542963de", "1.0.1", sources, explain=False)
# Use block until complete method to periodically ping the results API until job completes
results = client.results.block_until_complete(job, timeout=None, poll_interval=5)
```
### Query a Job's Result
This method simply queries the results for a job at any point in time and returns the status of the job, which includes the results if the job has completed.
```python
# Query results for a job at any point in time
results = client.results.get(job)
# Print the inference results
results_json = result.get_first_outputs()['results.json']
print(results_json)
```
## Deploying Models
Deploy a model to a your private model library in Modzy
```Python
from modzy import ApiClient
# Sets BASE_URL and API_KEY values
# Best to set these as environment variables
BASE_URL = "Valid Modzy URL" # e.g., "https://trial.modzy.com"
API_KEY = "Valid Modzy API Key" # e.g., "JbFkWZMx4Ea3epIrxSgA.a2fR36fZi3sdFPoztAXT"
client = ApiClient(base_url=BASE_URL, api_key=API_KEY)
model_data = client.models.deploy(
container_image="modzy/grpc-echo-model:1.0.0",
model_name="Echo Model",
model_version="0.0.1",
sample_input_file="./test.txt",
run_timeout="60",
status_timeout="60",
short_description="This model returns the same text passed through as input, similar to an 'echo.'",
long_description="This model returns the same text passed through as input, similar to an 'echo.'",
technical_details="This section can include any technical information abot your model. Include information about how your model was trained, any underlying architecture details, or other pertinant information an end-user would benefit from learning.",
performance_summary="This is the performance summary."
)
print(model_data)
```
To use **`client.models.deploy()`** there are 4 fields that are required:
* `container_image (str)`: This parameter must represent a container image repository & tag name, or in other words, the string you would include after a docker pull command. For example, if you were to download this container image using docker pull modzy/grpc-echo-model:1.0.0, include just _`modzy/grpc-echo-model:1.0.0`_ for this parameter
* `model_name`: The name of the model you would like to deploy
* `model_version`: The version of the model you would like to deploy
* `sample_input_file`: Filepath to a sample piece of data that your model is expected to process and perform inference against.
## Running Inferences at the Edge
The SDK provides support for running inferences on edge devices through Modzy's Edge Client. The inference workflow is almost identical to the previously outlined workflow, and provides functionality for interacting with both Job and Inferences APIs:
### Initialize Edge Client
```python
from modzy import EdgeClient
# Initialize edge client
# Use 'localhost' for local inferences, otherwise use the device's full IP address
client = EdgeClient('localhost',55000)
```
### Submit Inference with *Job* API
Modzy Edge supports `text`, `embedded`, and `aws-s3` input types.
```python
# Submit text job to Sentiment Analysis model deployed on edge device by providing a model ID, version, and raw text data, wait for completion
job = client.jobs.submit_text("ed542963de","1.0.27",{"input.txt": "this is awesome"})
# Block until results are ready
final_job_details = client.jobs.block_until_complete(job)
results = client.jobs.get_results(job)
```
### Query Details about Inference with *Job* API
```python
# get job details for a particular job
job_details = client.jobs.get_job_details(job)
# get job details for all jobs run on your Modzy Edge instance
all_job_details = client.jobs.get_all_job_details()
```
### Submit Inference with *Inference* API
The SDK provides several methods for interacting with Modzy's Inference API:
* **Synchronous**: This convenience method wraps two SDK methods and is optimal for use cases that require real-time or sequential results (i.e., a prediction results are needed to inform action before submitting a new inference)
* **Asynchronous**: This method combines two SDK methods and is optimal for submitting large batches of data and querying results at a later time (i.e., real-time inference is not required)
* **Streaming**: This method is a convenience method for running multiple synchronous inferences consecutively and allows users to submit iterable objects to be processed sequentially in real-time
*Synchronous (image-based model example)*
```python
from modzy import EdgeClient
from modzy.edge import InputSource
image_bytes = open("image_path.jpg", "rb").read()
input_object = InputSource(
key="image", # input filename defined by model author
data=image_bytes,
)
with EdgeClient('localhost', 55000) as client:
inference = client.inferences.run("<model-id>", "<model-version>", input_object, explain=False, tags=None)
results = inference.result.outputs
```
*Asynchronous (image-based model example - submit batch of images in folder)*
```python
import os
from modzy import EdgeClient
from modzy.edge import InputSource
# submit inferences
img_folder = "./images"
inferences = []
for img in os.listdir(img_folder):
input_object = InputSource(
key="image", # input filename defined by model author
data=open(os.path.join(img_folder, img), 'rb').read()
)
with EdgeClient('localhost', 55000) as client:
inference = client.inferences.perform_inference("<model-id>", "<model-version>", input_object, explain=False, tags=None)
inferences.append(inference)
# query results
with EdgeClient('localhost', 55000) as client:
results = [client.inferences.block_until_complete(inference.identifier) for inferences in inferences]
```
*Stream*
```python
import os
from modzy import EdgeClient
from modzy.edge import InputSource
# generate requests iterator to pass to stream method
requests = []
for img in os.listdir(img_folder):
input_object = InputSource(
key="image", # input filename defined by model author
data=open(os.path.join(img_folder, img), 'rb').read()
)
with EdgeClient('localhost', 55000) as client:
requests.append(client.inferences.build_inference_request("<model-id>", "<model-version>", input_object, explain=False, tags=None))
# submit list of inference requests to streaming API
with EdgeClient('localhost', 55000) as client:
streaming_results = client.inferences.stream(requests)
```
# SDK Code Examples
View examples of practical workflows:
* [Image-Based Geolocation Inference Notebook](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Jobs%20with%20Python%20SDK%20-%20Image-Based%20Geolocation.ipynb)
* [Automobile Classification Inference Notebook with Explainability](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Jobs%20with%20Python%20SDK%20-%20Automobile%20Classification.ipynb)
* [Batch Inference with Sentiment Analysis](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Batch%20Jobs%20with%20Python%20SDK%20-%20Sentiment%20Analysis.ipynb)
# Documentation
Modzy's SDK is built on top of the [Modzy HTTP/REST API](https://docs.modzy.com/reference/introduction). For a full list of features and supported routes visit [Python SDK on docs.modzy.com](https://docs.modzy.com/docs/python)
# API Reference
| Feature | Code |Api route
| --- | --- | ---
|Deploy new model|client.models.deploy()|[api/models](https://docs.modzy.com/reference/model-deployment)
|Get all models|client.models.get_all()|[api/models](https://docs.modzy.com/reference/get-all-models)|
|List models|client.models.get_models()|[api/models](https://docs.modzy.com/reference/list-models)|
|Get model details|client.models.get()|[api/models/:model-id](https://docs.modzy.com/reference/list-model-details)|
|List models by name|client.models.get_by_name()|[api/models](https://docs.modzy.com/reference/list-models)|
|List models by tag|client.tags.get_tags_and_models()|[api/models/tags/:tag-id](https://docs.modzy.com/reference/list-models-by-tag) |
|Get related models|client.models.get_related()|[api/models/:model-id/related-models](https://docs.modzy.com/reference/get-related-models)|
|List a model's versions|client.models.get_versions()|[api/models/:model-id/versions](https://docs.modzy.com/reference/list-versions)|
|Get a version's details|client.models.get_version()|[api/models/:model-id/versions/:version-id](https://docs.modzy.com/reference/get-version-details)|
|Update processing engines|client.models.update_processing_engines()|[api/resource/models](https://docs.modzy.com/reference/update-a-version-1)|
|Get minimum engines|client.models.get_minimum_engines()|[api/models/processing-engines](https://docs.modzy.com/reference/get-minimum-engines)|
|List tags|client.tags.get_all()|[api/models/tags](https://docs.modzy.com/reference/list-tags)|
|Submit a Job (Text)|client.jobs.submit_text()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (Embedded)|client.jobs.submit_embedded()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (File)|client.jobs.submit_file()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (AWS S3)|client.jobs.submit_aws_s3()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (Azure Blob Storage)|client.jobs.submit_azureblob()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (NetApp StorageGRID)|client.jobs.submit_storagegrid()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Submit a Job (JDBC)|client.jobs.submit_jdbc()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|
|Cancel job|job.cancel()|[api/jobs/:job-id](https://docs.modzy.com/reference/cancel-a-job) |
|Hold until inference is complete|job.block_until_complete()|[api/jobs/:job-id](https://docs.modzy.com/reference/get-job-details) |
|Get job details|client.jobs.get()|[api/jobs/:job-id](https://docs.modzy.com/reference/get-job-details) |
|Get results|job.get_result()|[api/results/:job-id](https://docs.modzy.com/reference/get-results) |
|Get the job history|client.jobs.get_history()|[api/jobs/history](https://docs.modzy.com/reference/list-the-job-history) |
|Submit a Job with Edge Client (Embedded)|EdgeClient.jobs.submit_embedded()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_embedded) |
|Submit a Job with Edge Client (Text)|EdgeClient.jobs.submit_text()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_text) |
|Submit a Job with Edge Client (AWS S3)|EdgeClient.jobs.submit_aws_s3()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_aws_s3) |
|Get job details with Edge Client|EdgeClient.jobs.get_job_details()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_job_details) |
|Get all job details with Edge Client|EdgeClient.jobs.get_all_job_details()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_all_job_details) |
|Hold until job is complete with Edge Client|EdgeClient.jobs.block_until_complete()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsblock_until_complete) |
|Get results with Edge Client|EdgeClient.jobs.get_results()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_results) |
|Build inference request with Edge Client|EdgeClient.inferences.build_inference_request()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesbuild_inference_request) |
|Perform inference with Edge Client|EdgeClient.inferences.perform_inference()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesperform_inference) |
|Get inference details with Edge Client|EdgeClient.inferences.get_inference_details()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesget_inference_details) |
|Run synchronous inferences with Edge Client|EdgeClient.inferences.run()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesrun) |
|Hold until inference completes with Edge Client|EdgeClient.inferences.block_until_complete()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesblock_until_complete) |
|Stream inferences with Edge Client|EdgeClient.inferences.stream()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesstream) |
# Support
For support, email opensource@modzy.com or join our [Slack](https://www.modzy.com/slack).
# Contributing
Contributions are always welcome!
See [`contributing.md`](https://github.com/modzy/sdk-python/tree/main/contributing.adoc) for ways to get started.
Please adhere to this project's `code of conduct`.
We are happy to receive contributions from all of our users. Check out our contributing file to learn more.
[](https://github.com/modzy/sdk-python/tree/main/CODE_OF_CONDUCT.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/modzy/sdk-python",
"name": "modzy-sdk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "modzy,sdk",
"author": "Modzy",
"author_email": "support@modzy.com",
"download_url": "",
"platform": null,
"description": "<div align=\"center\">\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n**[Python SDK Documentation Page](https://docs.modzy.com)**\r\n\r\n</div>\r\n\r\n# Installation\r\n\r\nInstall Modzy's Python SDK with PIP\r\n\r\n```bash\r\n pip install modzy-sdk\r\n```\r\n \r\n# Usage/Examples\r\n\r\n## Initializing the SDK\r\nInitialize your client by authenticating with an API key. You can [download an API Key](https://docs.modzy.com/docs/view-and-manage-api-keys#download-team-api-key) from your instance of Modzy.\r\n\r\n```python\r\nfrom modzy import ApiClient\r\n\r\n# Sets BASE_URL and API_KEY values\r\n# Best to set these as environment variables\r\nBASE_URL = \"Valid Modzy URL\" # e.g., \"https://trial.modzy.com\"\r\nAPI_KEY = \"Valid Modzy API Key\" # e.g., \"JbFkWZMx4Ea3epIrxSgA.a2fR36fZi3sdFPoztAXT\"\r\n\r\nclient = ApiClient(base_url=BASE_URL, api_key=API_KEY)\r\n```\r\n## Running Inferences\r\n### Raw Text Inputs\r\nSubmit an inference job to a text-based model by providing the model ID, version, and raw input text:\r\n\r\n```python\r\n# Creates a dictionary for text input(s)\r\nsources = {}\r\n\r\n# Adds any number of inputs\r\nsources[\"first-phone-call\"] = {\r\n \"input.txt\": \"Mr Watson, come here. I want to see you.\",\r\n}\r\n\r\n# Submit the text to v1.0.1 of a Sentiment Analysis model, and to make the job explainable, change explain=True\r\njob = client.jobs.submit_text(\"ed542963de\", \"1.0.1\", sources, explain=False)\r\n```\r\n### File Inputs\r\nPass a file from your local directory to a model by providing the model ID, version, and the filepath of your sample data:\r\n\r\n```python\r\n# Generate a mapping of your local file (nyc-skyline.jpg) to the input filename the model expects\r\nsources = {\"nyc-skyline\": {\"image\": \"./images/nyc-skyline.jpg\"}}\r\n\r\n# Submit the image to v1.0.1 of an Image-based Geolocation model\r\njob = client.jobs.submit_file(\"aevbu1h3yw\", \"1.0.1\", sources)\r\n```\r\n### Embedded Inputs\r\nConvert images and other large inputs to base64 embedded data and submit to a model by providing a model ID, version number, and dictionary with one or more base64 encoded inputs:\r\n```python\r\nfrom modzy._util import file_to_bytes\r\n\r\n# Embed input as a string in base64\r\nimage_bytes = file_to_bytes('./images/tower-bridge.jpg')\r\n# Prepare the source dictionary\r\nsources = {\"tower-bridge\": {\"image\": image_bytes}}\r\n\r\n# Submit the image to v1.0.1 of an Imaged-based Geolocation model\r\njob = client.jobs.submit_embedded(\"aevbu1h3yw\", \"1.0.1\", sources)\r\n```\r\n### Inputs from Databases\r\nSubmit data from a SQL database to a model by providing a model ID, version, a SQL query, and database connection credentials:\r\n```python\r\n# Add database connection and query information\r\ndb_url = \"jdbc:postgresql://db.bit.io:5432/bitdotio\"\r\ndb_username = DB_USER_NAME\r\ndb_password = DB_PASSWORD\r\ndb_driver = \"org.postgresql.Driver\"\r\n# Select as \"input.txt\" becase that is the required input name for this model\r\ndb_query = \"SELECT \\\"mailaddr\\\" as \\\"input.txt\\\" FROM \\\"user/demo_repo\\\".\\\"atl_parcel_attr\\\" LIMIT 10;\"\r\n\r\n# Submit the database query to v0.0.12 of a Named Entity Recognition model\r\njob = client.jobs.submit_jdbc(\"a92fc413b5\",\"0.0.12\",db_url, db_username, db_password, db_driver, db_query)\r\n```\r\n### Inputs from Cloud Storage\r\nSubmit data directly from your cloud storage bucket (Amazon S3, Azure Blob, NetApp StorageGrid supported) by providing a model ID, version, and storage-blob-specific parameters.\r\n\r\n#### AWS S3\r\n```python\r\n# Define sources dictionary with bucket and key that points to the correct file in your s3 bucket\r\nsources = {\r\n \"first-amazon-review\": {\r\n \"input.txt\": {\r\n \"bucket\": \"s3-bucket-name\",\r\n \"key\": \"key-to-file.txt\"\r\n }\r\n }\r\n}\r\n\r\nAWS_ACCESS_KEY = \"aws-acces-key\"\r\nAWC_SECRET_ACCESS_KEY = \"aws-secret-access-key\"\r\nAWS_REGION = \"us-east-1\"\r\n\r\n# Submit s3 input to v1.0.1 of a Sentiment Analysis model\r\njob = client.jobs.submit_aws_s3(\"ed542963de\", \"1.0.1\", sources, AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY, AWS_REGION)\r\n```\r\n\r\n#### Azure Blob Storage\r\n```python\r\n# Define sources dictionary with container name and filepath that points to the correct file in your Azure Blob container\r\nsources = {\r\n \"first-amazon-review\": {\r\n \"input.txt\": {\r\n \"container\": \"azure-blob-container-name\",\r\n \"filePath\": \"key-to-file.txt\"\r\n }\r\n }\r\n}\r\n\r\nAZURE_STORAGE_ACCOUNT = \"Azure-Storage-Account\"\r\nAZURE_STORAGE_ACCOUNT_KEY = \"cvx....ytw==\"\r\n\r\n# Submit Azure Blob input to v1.0.1 of a Sentiment Analysis model\r\njob = client.jobs.submit_azureblob(\"ed542963de\", \"1.0.1\", sources, AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_ACCOUNT_KEY)\r\n```\r\n\r\n#### NetApp StorageGRID\r\n```python\r\n# Define sources dictionary with bucket name and key that points to the correct file in your NetApp StorageGRID bucket\r\nsources = {\r\n \"first-amazon-review\": {\r\n \"input.txt\": {\r\n \"bucket\": \"bucket-name\",\r\n \"key\": \"key-to-file.txt\"\r\n }\r\n }\r\n}\r\n\r\nACCESS_KEY = \"access-key\"\r\nSECRET_ACCESS_KEY = \"secret-access-key\"\r\nSTORAGE_GRID_ENDPOINT = \"https://endpoint.storage-grid.example\"\r\n\r\n# Submit StorageGRID input to v1.0.1 of a Sentiment Analysis model\r\njob = client.jobs.submit_storagegrid(\"ed542963de\", \"1.0.1\", sources, ACCESS_KEY, SECRET_ACCESS_KEY, STORAGE_GRID_ENDPOINT)\r\n```\r\n## Getting Results\r\nModzy's APIs are asynchronous by nature, which means you can use the `results` API to query available results for all completed inference jobs at any point in time. There are two ways you might leverage this Python SDK to query results:\r\n\r\n### Block Job until it completes \r\nThis method provides a mechanism to mimic a sycnchronous API by using two different APIs subsequently and a utility function.\r\n\r\n```python\r\n# Define sources dictionary with input data\r\nsources = {\"my-input\": {\"input.txt\": \"Today is a beautiful day!\"}}\r\n# Submit the text to v1.0.1 of a Sentiment Analysis model, and to make the job explainable, change explain=True\r\njob = client.jobs.submit_text(\"ed542963de\", \"1.0.1\", sources, explain=False)\r\n# Use block until complete method to periodically ping the results API until job completes\r\nresults = client.results.block_until_complete(job, timeout=None, poll_interval=5)\r\n```\r\n\r\n### Query a Job's Result \r\nThis method simply queries the results for a job at any point in time and returns the status of the job, which includes the results if the job has completed.\r\n\r\n```python\r\n# Query results for a job at any point in time\r\nresults = client.results.get(job)\r\n# Print the inference results\r\nresults_json = result.get_first_outputs()['results.json']\r\nprint(results_json)\r\n```\r\n\r\n## Deploying Models\r\nDeploy a model to a your private model library in Modzy\r\n\r\n```Python\r\nfrom modzy import ApiClient\r\n\r\n# Sets BASE_URL and API_KEY values\r\n# Best to set these as environment variables\r\nBASE_URL = \"Valid Modzy URL\" # e.g., \"https://trial.modzy.com\"\r\nAPI_KEY = \"Valid Modzy API Key\" # e.g., \"JbFkWZMx4Ea3epIrxSgA.a2fR36fZi3sdFPoztAXT\"\r\n\r\nclient = ApiClient(base_url=BASE_URL, api_key=API_KEY)\r\n\r\nmodel_data = client.models.deploy(\r\n container_image=\"modzy/grpc-echo-model:1.0.0\",\r\n model_name=\"Echo Model\",\r\n model_version=\"0.0.1\",\r\n sample_input_file=\"./test.txt\",\r\n run_timeout=\"60\",\r\n status_timeout=\"60\",\r\n short_description=\"This model returns the same text passed through as input, similar to an 'echo.'\",\r\n long_description=\"This model returns the same text passed through as input, similar to an 'echo.'\",\r\n technical_details=\"This section can include any technical information abot your model. Include information about how your model was trained, any underlying architecture details, or other pertinant information an end-user would benefit from learning.\",\r\n performance_summary=\"This is the performance summary.\"\r\n)\r\n\r\nprint(model_data)\r\n```\r\nTo use **`client.models.deploy()`** there are 4 fields that are required:\r\n* `container_image (str)`: This parameter must represent a container image repository & tag name, or in other words, the string you would include after a docker pull command. For example, if you were to download this container image using docker pull modzy/grpc-echo-model:1.0.0, include just _`modzy/grpc-echo-model:1.0.0`_ for this parameter\r\n* `model_name`: The name of the model you would like to deploy\r\n* `model_version`: The version of the model you would like to deploy\r\n* `sample_input_file`: Filepath to a sample piece of data that your model is expected to process and perform inference against.\r\n\r\n## Running Inferences at the Edge\r\n\r\nThe SDK provides support for running inferences on edge devices through Modzy's Edge Client. The inference workflow is almost identical to the previously outlined workflow, and provides functionality for interacting with both Job and Inferences APIs:\r\n\r\n### Initialize Edge Client\r\n\r\n```python\r\nfrom modzy import EdgeClient\r\n\r\n# Initialize edge client\r\n# Use 'localhost' for local inferences, otherwise use the device's full IP address\r\nclient = EdgeClient('localhost',55000)\r\n```\r\n\r\n### Submit Inference with *Job* API\r\nModzy Edge supports `text`, `embedded`, and `aws-s3` input types.\r\n\r\n```python\r\n# Submit text job to Sentiment Analysis model deployed on edge device by providing a model ID, version, and raw text data, wait for completion\r\njob = client.jobs.submit_text(\"ed542963de\",\"1.0.27\",{\"input.txt\": \"this is awesome\"})\r\n# Block until results are ready\r\nfinal_job_details = client.jobs.block_until_complete(job)\r\nresults = client.jobs.get_results(job)\r\n```\r\n\r\n### Query Details about Inference with *Job* API\r\n```python\r\n# get job details for a particular job\r\njob_details = client.jobs.get_job_details(job)\r\n\r\n# get job details for all jobs run on your Modzy Edge instance\r\nall_job_details = client.jobs.get_all_job_details()\r\n```\r\n\r\n### Submit Inference with *Inference* API\r\n\r\nThe SDK provides several methods for interacting with Modzy's Inference API:\r\n* **Synchronous**: This convenience method wraps two SDK methods and is optimal for use cases that require real-time or sequential results (i.e., a prediction results are needed to inform action before submitting a new inference)\r\n* **Asynchronous**: This method combines two SDK methods and is optimal for submitting large batches of data and querying results at a later time (i.e., real-time inference is not required)\r\n* **Streaming**: This method is a convenience method for running multiple synchronous inferences consecutively and allows users to submit iterable objects to be processed sequentially in real-time\r\n\r\n*Synchronous (image-based model example)*\r\n```python\r\nfrom modzy import EdgeClient\r\nfrom modzy.edge import InputSource\r\n\r\nimage_bytes = open(\"image_path.jpg\", \"rb\").read()\r\ninput_object = InputSource(\r\n key=\"image\", # input filename defined by model author\r\n data=image_bytes,\r\n) \r\n\r\nwith EdgeClient('localhost', 55000) as client:\r\n inference = client.inferences.run(\"<model-id>\", \"<model-version>\", input_object, explain=False, tags=None)\r\nresults = inference.result.outputs\r\n```\r\n\r\n*Asynchronous (image-based model example - submit batch of images in folder)*\r\n```python\r\nimport os\r\nfrom modzy import EdgeClient\r\nfrom modzy.edge import InputSource\r\n\r\n# submit inferences\r\nimg_folder = \"./images\"\r\ninferences = []\r\nfor img in os.listdir(img_folder):\r\n input_object = InputSource(\r\n key=\"image\", # input filename defined by model author\r\n data=open(os.path.join(img_folder, img), 'rb').read()\r\n )\r\n with EdgeClient('localhost', 55000) as client:\r\n inference = client.inferences.perform_inference(\"<model-id>\", \"<model-version>\", input_object, explain=False, tags=None)\r\n inferences.append(inference)\r\n\r\n# query results \r\nwith EdgeClient('localhost', 55000) as client:\r\n results = [client.inferences.block_until_complete(inference.identifier) for inferences in inferences]\r\n```\r\n\r\n*Stream*\r\n```python\r\nimport os\r\nfrom modzy import EdgeClient\r\nfrom modzy.edge import InputSource\r\n\r\n# generate requests iterator to pass to stream method\r\nrequests = []\r\nfor img in os.listdir(img_folder):\r\n input_object = InputSource(\r\n key=\"image\", # input filename defined by model author\r\n data=open(os.path.join(img_folder, img), 'rb').read()\r\n )\r\n with EdgeClient('localhost', 55000) as client:\r\n requests.append(client.inferences.build_inference_request(\"<model-id>\", \"<model-version>\", input_object, explain=False, tags=None)) \r\n\r\n# submit list of inference requests to streaming API\r\nwith EdgeClient('localhost', 55000) as client:\r\n streaming_results = client.inferences.stream(requests)\r\n```\r\n\r\n# SDK Code Examples\r\n\r\nView examples of practical workflows:\r\n\r\n* [Image-Based Geolocation Inference Notebook](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Jobs%20with%20Python%20SDK%20-%20Image-Based%20Geolocation.ipynb)\r\n* [Automobile Classification Inference Notebook with Explainability](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Jobs%20with%20Python%20SDK%20-%20Automobile%20Classification.ipynb)\r\n* [Batch Inference with Sentiment Analysis](https://github.com/modzy/modzy-jupyter-notebook-samples/blob/main/python-sdk-inference/Submitting%20Batch%20Jobs%20with%20Python%20SDK%20-%20Sentiment%20Analysis.ipynb)\r\n\r\n# Documentation\r\n\r\nModzy's SDK is built on top of the [Modzy HTTP/REST API](https://docs.modzy.com/reference/introduction). For a full list of features and supported routes visit [Python SDK on docs.modzy.com](https://docs.modzy.com/docs/python)\r\n\r\n# API Reference\r\n\r\n| Feature | Code |Api route\r\n| --- | --- | ---\r\n|Deploy new model|client.models.deploy()|[api/models](https://docs.modzy.com/reference/model-deployment)\r\n|Get all models|client.models.get_all()|[api/models](https://docs.modzy.com/reference/get-all-models)|\r\n|List models|client.models.get_models()|[api/models](https://docs.modzy.com/reference/list-models)|\r\n|Get model details|client.models.get()|[api/models/:model-id](https://docs.modzy.com/reference/list-model-details)|\r\n|List models by name|client.models.get_by_name()|[api/models](https://docs.modzy.com/reference/list-models)|\r\n|List models by tag|client.tags.get_tags_and_models()|[api/models/tags/:tag-id](https://docs.modzy.com/reference/list-models-by-tag) |\r\n|Get related models|client.models.get_related()|[api/models/:model-id/related-models](https://docs.modzy.com/reference/get-related-models)|\r\n|List a model's versions|client.models.get_versions()|[api/models/:model-id/versions](https://docs.modzy.com/reference/list-versions)|\r\n|Get a version's details|client.models.get_version()|[api/models/:model-id/versions/:version-id](https://docs.modzy.com/reference/get-version-details)|\r\n|Update processing engines|client.models.update_processing_engines()|[api/resource/models](https://docs.modzy.com/reference/update-a-version-1)|\r\n|Get minimum engines|client.models.get_minimum_engines()|[api/models/processing-engines](https://docs.modzy.com/reference/get-minimum-engines)|\r\n|List tags|client.tags.get_all()|[api/models/tags](https://docs.modzy.com/reference/list-tags)|\r\n|Submit a Job (Text)|client.jobs.submit_text()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (Embedded)|client.jobs.submit_embedded()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (File)|client.jobs.submit_file()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (AWS S3)|client.jobs.submit_aws_s3()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (Azure Blob Storage)|client.jobs.submit_azureblob()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (NetApp StorageGRID)|client.jobs.submit_storagegrid()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Submit a Job (JDBC)|client.jobs.submit_jdbc()|[api/jobs](https://docs.modzy.com/reference/create-a-job)|\r\n|Cancel job|job.cancel()|[api/jobs/:job-id](https://docs.modzy.com/reference/cancel-a-job) |\r\n|Hold until inference is complete|job.block_until_complete()|[api/jobs/:job-id](https://docs.modzy.com/reference/get-job-details) |\r\n|Get job details|client.jobs.get()|[api/jobs/:job-id](https://docs.modzy.com/reference/get-job-details) |\r\n|Get results|job.get_result()|[api/results/:job-id](https://docs.modzy.com/reference/get-results) |\r\n|Get the job history|client.jobs.get_history()|[api/jobs/history](https://docs.modzy.com/reference/list-the-job-history) |\r\n|Submit a Job with Edge Client (Embedded)|EdgeClient.jobs.submit_embedded()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_embedded) |\r\n|Submit a Job with Edge Client (Text)|EdgeClient.jobs.submit_text()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_text) |\r\n|Submit a Job with Edge Client (AWS S3)|EdgeClient.jobs.submit_aws_s3()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobssubmit_aws_s3) |\r\n|Get job details with Edge Client|EdgeClient.jobs.get_job_details()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_job_details) |\r\n|Get all job details with Edge Client|EdgeClient.jobs.get_all_job_details()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_all_job_details) |\r\n|Hold until job is complete with Edge Client|EdgeClient.jobs.block_until_complete()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsblock_until_complete) |\r\n|Get results with Edge Client|EdgeClient.jobs.get_results()|[Python/edge/jobs](https://docs.modzy.com/docs/edgeclientjobsget_results) |\r\n|Build inference request with Edge Client|EdgeClient.inferences.build_inference_request()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesbuild_inference_request) |\r\n|Perform inference with Edge Client|EdgeClient.inferences.perform_inference()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesperform_inference) |\r\n|Get inference details with Edge Client|EdgeClient.inferences.get_inference_details()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesget_inference_details) |\r\n|Run synchronous inferences with Edge Client|EdgeClient.inferences.run()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesrun) |\r\n|Hold until inference completes with Edge Client|EdgeClient.inferences.block_until_complete()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesblock_until_complete) |\r\n|Stream inferences with Edge Client|EdgeClient.inferences.stream()|[Python/edge/inferences](https://docs.modzy.com/docs/edgeclientinferencesstream) |\r\n\r\n\r\n# Support\r\n\r\nFor support, email opensource@modzy.com or join our [Slack](https://www.modzy.com/slack).\r\n# Contributing\r\n\r\nContributions are always welcome!\r\n\r\nSee [`contributing.md`](https://github.com/modzy/sdk-python/tree/main/contributing.adoc) for ways to get started.\r\n\r\nPlease adhere to this project's `code of conduct`.\r\n\r\nWe are happy to receive contributions from all of our users. Check out our contributing file to learn more.\r\n\r\n[](https://github.com/modzy/sdk-python/tree/main/CODE_OF_CONDUCT.md)\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Modzy's Python SDK queries and deploys models, submits inference jobs and returns results directly to your editor.",
"version": "0.11.6",
"project_urls": {
"Homepage": "https://github.com/modzy/sdk-python"
},
"split_keywords": [
"modzy",
"sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65dd94d6b747a1cd4e34df2bdbe80a97139ec9a8caea4c12e8cc9bb88c04f7c5",
"md5": "5df663d864ed037f181333f7e01a2a00",
"sha256": "5a354b77d57e004696283be73a480aa3d7d6064a19bcb3e8ec82bde1fcd1d178"
},
"downloads": -1,
"filename": "modzy_sdk-0.11.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5df663d864ed037f181333f7e01a2a00",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 106234,
"upload_time": "2023-09-08T15:53:39",
"upload_time_iso_8601": "2023-09-08T15:53:39.867458Z",
"url": "https://files.pythonhosted.org/packages/65/dd/94d6b747a1cd4e34df2bdbe80a97139ec9a8caea4c12e8cc9bb88c04f7c5/modzy_sdk-0.11.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-08 15:53:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "modzy",
"github_project": "sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "modzy-sdk"
}
