Skip to content
/ sdk-java Public

The official Java library for the Modzy Machine Learning Operations (MLOps) Platform

License

Notifications You must be signed in to change notification settings

modzy/sdk-java

Repository files navigation

Modzy Java SDK

Modzy Logo

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

GitHub contributors GitHub last commit GitHub Release Date

The job lifecycle | API Keys | Samples | Documentation

Installation

installation

Clone the repository:

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

Use maven to install the SDK.

  • $ ./mvnw install -DskipTests=true

Add the dependency in your pom.xml file:

<dependency>
	<groupId>com.modzy</groupId>
	<artifactId>modzy-sdk</artifactId>
	<version>0.0.1</version>
</dependency>

Get your API key

API keys are security credentials required to perform API requests to Modzy. Our API keys are composed of an ID that is split by a dot into two parts: a public and private part.

The public part is the API keys' visible part only used to identify the key and by itself, it’s unable to perform API requests.

The private part is the public part's complement and it’s required to perform API requests. Since it’s not stored on Modzy’s servers, it cannot be recovered. Make sure to save it securely. If lost, you can replace the API key.

Find your API key in your user profile. To get your full API key click on "Get key":

get key

Initialize

Once you have a model and version identified, get authenticated with your API key.

ModzyClient modzyClient = new ModzyClient("http://url.to.modzy/api", "API Key");

Basic usage

Basic Usage

Browse models

Modzy’s Marketplace includes pre-trained and re-trainable AI models from industry-leading machine learning companies, accelerating the process from data to value.

The Model service drives the Marketplace and can be integrated with other applications, scripts, and systems. It provides routes to list, search, and filter model and model-version details.

List models:

List<Model> models = modzyClient.getAllModels();
for( Model model : models ){
    System.out.println("Model: "+model);
}

Tags help categorize and filter models. They make model browsing easier.

List tags:

List<Tag> tags = modzyClient.getTagClient().getAllTags();
for( Tag tag : tags ){
    System.out.println("Tag: "+tag);
}

List models by tag:

TagWrapper tagsModels = modzyClient.getTagsAndModels("language_and_text");
for( Model model : tagsModels.getModels() ){
    System.out.println("Model: "+model);
}

Get a model's details

Models accept specific input file MIME types. Some models may require multiple input file types to run data accordingly. In this sample, we use a model that requires text/plain.

Models require inputs to have a specific input name declared in the job request. This name can be found in the model’s details. In this sample, we use a model that requires input.txt.

Additionally, users can set their own input names. When multiple input items are processed in a job, these names are helpful to identify and get each input’s results. In this sample, we use a model that requires input-1 and input-2.

Get a model's details:

Model saModel = modzyClient.getModel("ed542963de");
System.out.println("Model: "+saModel);

Model specific sample requests are available in the version details and in the Model Details page.

Get version details:

ModelVersion modelVersion = modzyClient.getModelVersion("ed542963de", "0.0.27");
// then you'll get all the details about the specific model version
System.out.println(String.format("ModelVersion details properties: %s", getNotNullProperties(modelVersion)));
// Probably the more interesting are the ones related with the inputs and outputs of the model
System.out.println("  inputs:");
for( ModelInput input : modelVersion.getInputs() ){
    System.out.println(
        String.format("    key %s, type %s, description: %s", input.getName(), input.getAcceptedMediaTypes(), input.getDescription())
    );
}
System.out.println("  outputs:");
for( ModelOutput output : modelVersion.getOutputs() ){
    System.out.println(
        String.format("    key %s, type %s, description: %s", output.getName(), output.getMediaType(), output.getDescription())
    );
}

Submit a job and get results

A job is the process that sends data to a model, sets the model to run the data, and returns results.

Modzy supports several input types such as text, embedded for Base64 strings, aws-s3 and aws-s3-folder for inputs hosted in buckets, and jdbc for inputs stored in databases. In this sample, we use text.

Here are samples to submit jobs with embedded, aws-s3, aws-s3-folder, and jdbc input types.

Submit a job with the model, version, and input items:

Job job = modzyClient.submitJobText("ed542963de", "0.0.27", "Modzy is great!");

Hold until the inference is complete and results become available:

Job job = modzyClient.blockUntilComplete(job, 20000);

Get the results:

Results are available per input item and can be identified with the name provided for each input item upon job request. You can also add an input name to the route and limit the results to any given input item.

Jobs requested for multiple input items may have partial results available prior to job completion.

JobOutput<JsonNode> jobResult = modzyClient.getResult(job);
Map<String,Map<String,JsonNode>> results = jobResult.getResults();

Fetch errors

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

Error Description
ApiException Wrapper for different exceptions, check the message and the stacktrace.

Submitting jobs:

try{
    Map<String,JsonNode> retValue = this.modzyClient.submitJobTextBlockUntilComplete("ed542963de", "Modzy is great!");
}
catch(ApiException ae){
    System.out.println("The job submission fails with message "+ae.getMessage());
    as.printStackTrace();
}

Features

Modzy supports batch processing, explainability, and model drift detection.

APIs

Here is a list of Modzy APIs. To see all the APIs, check our Documentation.

Feature Code Api route
Get all models modzyClient.getAllModels() api/models
List models modzyClient.getModels() api/models
Get model details modzyClient.getModel() api/models/:model-id
List models by name modzyClient.getModelByName() api/models
List models by tags modzyClient.getTagsAndModels() api/models/tags/:tag-id
Get related models modzyClient.getRelatedModels() api/models/:model-id/related-models
Get a model's versions modzyClient.getModelVersions() api/models/:model-id/versions
Get version details modzyClient.getModelVersions() api/models/:model-id/versions/:version-id
List tags modzyClient.getAllTags() api/models/tags
Submit a Job (Text) modzyClient.submitJobText() api/jobs
Submit a Job (Embedded) modzyClient.submitJobEmbedded() api/jobs
Submit a Job (AWS S3) modzyClient.submitJobAWSS3() api/jobs
Submit a Job (JDBC) modzyClient.submitJobJDBC() api/jobs
Cancel a job modzyClient.cancelJob() api/jobs/:job-id
Hold until inference is complete modzyClient.blockUntilComplete() api/jobs/:job-id
Get job details modzyClient.getJob() api/jobs/:job-id
Get results modzyClient.getResults() api/results/:job-id
List the job history modzyClient.getJobHistory() api/jobs/history

Samples

Check out our samples for details on specific use cases.

To run samples:

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

// TODO: set the base url of modzy api and you api key
ModzyClient modzyClient = new ModzyClient("https://http://modzy.url", "modzy-api.key");

Or follow the instructions here to learn more.

And then, you can:

$ ./mvnw exec:java -Dexec.mainClass="com.modzy.sdk.samples.ModelSamples"

Contributing

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

Code of conduct

Contributor Covenant