modzy-sdk 0.5.0

Modzy's Python SDK queries models, submits inference jobs and returns results directly to your editor.

:!toc: :doctype: article :icons: font :source-highlighter: highlightjs :docname: Modzy Python SDK

++++

Modzy Python SDK

Modzy's Python SDK queries models, submits inference jobs and returns results directly to your editor.

The job lifecycle | API keys | Samples | Documentation

++++

== Installation

Clone the repository:

• $ git clone https://github.com/modzy/sdk-python.git

++++

Use the package manager pip to install the SDK.

++++

• $ pip install ./sdk-python

== Usage

=== Initialize

Once you have a model and version identified, authenticate to Modzy with your API key: [source, py]

from modzy import ApiClient, error client = ApiClient(base_url='https://modzy.example.com/api', api_key='my_key.modzy')

=== Basic usage

The code below is applicable for text/plain input type.

++++

++++

Submit a job providing the model, version, and input file:

[source, py]

job = client.jobs.submit_files('ed542963de', '0.0.27', {'input.txt': './some-file.txt'})

Hold until the inference is complete and results become available:

[source, py]

result = client.results.block_until_complete(job, timeout=None)

Get the output results:

[source, py]

results_json = result.get_first_outputs()['results.json'] print(results_json)

== Fetch errors

Errors may arise for different reasons. Fetch errors to know what is their cause and how to fix them.

[cols="1,3"] |=== |NetworkError | The SDK is unable to connect. |ResponseError | The API returned an error code. |Timeout | The model is not finished running before the timeout elapsed. |ResultsError | The model returns an error during the inference job. |===

Submitting jobs: + NetworkError, ResponseError

[source, python]

try: job = client.jobs.submit_files('ed542963de', '0.0.27', {'input.txt': './some-file.txt'}) except error.NetworkError as ex: print('Could not connect to the API:', ex) raise except error.ResponseError as ex: print('We got an error response from the API:', ex) raise

While the model completes inference: + NetworkError, ResponseError, Timeout [source, python]

timeout = 600 try: result = client.results.block_until_complete(job, timeout=timeout) except error.Timeout as ex: print('Job still not finished after %d seconds' % timeout) raise except error.NetworkError as ex: print('Could not connect to the API:', ex) raise except error.ResponseError as ex: print('We got an error response from the API:', ex) raise

Retrieving results: + ResultsError [source, python]

try: outputs = result.get_first_outputs() except error.ResultsError as ex: print('the model returned an error:', ex) raise

results_json = outputs['results.json'] print(results_json)

== Features

Currently we support the following api routes:

:doc-pages: https://models.modzy.com/docs/ [cols=3*, stripes=even] |=== |Feature|Code|Api route

|[small]#Retrieve all models# |[small]#client.models.get_all()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-models[api/models]#

|[small]#Retrieve some models# |[small]#client.models.get_models()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-models[api/models]#

|[small]#Retrieve model details# |[small]#client.models.get()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-model-details[api/models/:model-id]#

|[small]#Retrieve model by name# |[small]#client.models.get_by_name()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-models[api/models]#

|[small]#Retrieve related models# |[small]#client.models.get_related()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-related-models[api/models/:model-id/related-models]#

|[small]#Retrieve model versions# |[small]#client.models.get_versions()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-versions[api/models/:model-id/versions]#

|[small]#Retrieve model version details# |[small]#client.models.get_version()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-version-details[api/models/:model-id/versions/:version-id]#

|[small]#Retrieve all tags# |[small]#client.tags.get_all()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-tags[api/models/tags]#

|[small]#Retrieve Tags and Models# |[small]#client.tags.get_tags_and_models()# |[small]#link:{doc-pages}api-reference/marketplace/retrieve-models-by-tags[api/models/tags/:tag-id]#

|[small]#Submit a Job (Single Text)# |[small]#client.jobs.submit_text()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Multiple Text)# |[small]#client.jobs.submit_text_bulk()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Single Embedded)# |[small]#client.jobs.submit_bytes()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Multiple Embedded)# |[small]#client.jobs.submit_bytes_bulk()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Single File)# |[small]#client.jobs.submit_files()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Multiple Files)# |[small]#client.jobs.submit_files_bulk()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Single AWS S3)# |[small]#client.jobs.submit_aws_s3()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (Multiple AWS S3)# |[small]#client.jobs.submit_aws_s3_bulk()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Submit a Job (JDBC)# |[small]#client.jobs.submit_jdbc()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Cancel job# |[small]#job.cancel()# |[small]#link:{doc-pages}api-reference/jobs/cancel-pending-job[api/jobs/:job-id]#

|[small]#Hold until inference is complete# |[small]#job.block_until_complete()# |[small]#link:{doc-pages}api-reference/job-inputs/submit-job[api/jobs]#

|[small]#Get Job details# |[small]#client.jobs.get()# |[small]#link:{doc-pages}api-reference/jobs/retrieve-job-details[api/jobs/:job-id]#

|[small]#Retrieve results# |[small]#job.get_result()# |[small]#link:{doc-pages}api-reference/jobs/cancel-pending-job[api/jobs/:job-id]#

|[small]#Retrieve Job History# |[small]#client.jobs.get_history()# |[small]#link:{doc-pages}api-reference/jobs/retrieve-job-history[api/jobs/history]#

|===

== Samples

++++

Check out our samples for details on specific use cases.

++++

Set the base url and api key in each sample file:

[source, python]

TODO: set the base url of modzy api and you api key

client = ApiClient(base_url=BASE_URL, api_key=API_KEY)

++++

Or follow the instructions here to learn more.

++++

And then, you can:

[source, bash]

$ py samples/job_with_text_input_sample.py

== Contributing

++++

We are happy to receive contributions from all of our users. Check out our contributing file to learn more.

++++

//For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.

==== Code of conduct

++++ ++++

== Credits

This package was bootstrapped with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

======= History

0.5.0

• Update version to match Modzy version

0.3.2 (2020-05-12)

• Update model and version client
• Added samples
• Review readme file, contributing guide
• Added .env support

0.3.1 (2019-11-22)

• Added basic logging.
• Switched to requests library for HTTP requests.

0.3.0 (2019-11-14)

• Added Tag support.
• Added ability to query job history.
• Added ability to query related models.

0.2.0 (2019-09-2)

• Rename library to modzy.

0.1.1 (2019-08-27)

• Added docstrings.

0.1.0 (2019-08-26)

• Initial release.