Predictors

The Core of NatML

NatML exposes a Predictor type which completely encapsulates all the information needed to use an ML model, whether at the edge or in the cloud:

# ML predictor.
type Predictor {
    ...
}

Identifying the Predictor

type Predictor {
    # Predictor tag.
    tag: String!
    # Predictor name.
    name: String!
}

The predictor tag uniquely identifies a predictor across the NatML platform. The predictor tag is always scoped with the username of its owner, followed by the predictor name:

Request

predictor (input: $input) {
    tag
    name
}

Response

"predictor": {
    // The predictor tag is always with the format:
    // "@username/name"
    "tag": "@natsuite/mobilenet-v2",
    // The predictor name is usually the name of the underlying model:
    "name": "mobilenet-v2"
}

The predictor name is always lowercase and dasherized.

Identifying the Predictor Owner

type Predictor {
    # Predictor owner.
    owner: PredictorOwner!
}

The predictor provides information about its author:

PredictorOwner

# User info.
type PredictorOwner {
    # Username.
    username: String!
    # User website.
    website: URL
    # User avatar.
    avatar: URL
}

Describing the Predictor

type Predictor {
    # Predictor description.
    description: String!
    # Predictor category.
    category: Category!
}

The predictor always includes a short description (usually under 100 characters) along with a category.

Checking the Predictor Status

type Predictor {
    # Predictor status.
    status: PredictorStatus!
}

Predictors will always be in one of the following statuses:

Predictor Status

enum PredictorStatus {
    # Predictor is a draft.
    # Predictor can only be viewed and used by owner.
    DRAFT
    # Predictor is pending review.
    # Predictor can only be viewed and used by owner.
    PENDING
    # Predictor is under review.
    # Predictor can be viewed and used by owner or NatML predictor review team.
    REVIEW
    # Predictor has been published.
    # Predictor viewing and fetching permissions are dictated by the access mode.
    PUBLISHED
    # Predictor is archived.
    # Predictor can be viewed but cannot be used by anyone including owner.
    ARCHIVED
}

Checking the Predictor Access

type Predictor {
    # Predictor access.
    access: AccessMode!
}

Access to predictors is governed by the chosen access mode:

Access Mode

enum AccessMode {
    # Predictor can be viewed and used by anyone with NatML authentication.
    PUBLIC
    # Predictor can only be viewed and used by owner.
    PRIVATE
}

Inspecting the Underlying Model

type Predictor {
    # Model license.
    license: License!
    # Model info URL.
    info: URL
}

The predictor includes model info along with a license:

License

enum License {
    # No license.
    NONE
    # MIT License.
    MIT
    # Apache License 2.0.
    APACHE20
    # GNU GPL v3 Copyleft License.
    GPLv3
    # GNU Affero GPL v3 Copyleft License.
    AGPLv3
}

Accessing Supplemental Data

Predictors contain supplemental data required to make predictions with a given model

Classification Labels

type Predictor {
    # Classification labels.
    labels: [String!]
    # Classification label count.
    labelCount: Int
}

INCOMPLETE.

Feature Normalization

type Predictor {
    # Feature normalization.
    normalization: Normalization
}

INCOMPLETE.

type Normalization {
    # Per-channel means.
    mean: [Float!]!
    # Per-channel standard deviations.
    std: [Float!]!
}

Image Aspect Mode

type Predictor {
    # Image aspect mode.
    aspectMode: AspectMode
}

INCOMPLETE.

enum AspectMode {
    # Scale to fit.
    SCALE_TO_FIT
    # Aspect fill.
    ASPECT_FILL
    # Aspect fit.
    ASPECT_FIT
}

See this page for a visual explanation of the aspect modes:

MLImageFeatureNatML

Image feature aspect modes

Audio Format

type Predictor {
    # Audio format.
    audioFormat: AudioFormat
}

INCOMPLETE.

type AudioFormat {
    # Audio sample rate.
    sampleRate: Int!
    # Audio channel count.
    channelCount: Int!
}

Using the Predictor

type Predictor {
    # Predictor packages.
    packages: [Package!]!
}

Most predictors will include pre-made predictor packages for different development frameworks. These predictor packages are nano-libraries that expose the predictor in code, allowing developers to use the predictor in under five lines of code:

Predictor Package

type Package {
    # Package framework.
    framework: Framework!
    # Package URL.
    url: URL!
    # Predictor caption in framework programming language.
    caption: String!
}

The caption illustrates how the predictor is used in the framework programming language. This MUST always be under five lines of code.

The package url should typically link to an official package manager for the given framework, like NPM for NodeJS or PyPi for Python.

Predictor Framework

The framework corresponds to the development framework that the package is written for:

enum Framework {
    # Unity Engine.
    UNITY
    # JavaScript.
    JAVASCRIPT
}

If you'd like to see a new development framework supported, please reach out to us!

Inspecting the Predictor Media

type Predictor {
    # Predictor media.
    media: URL
}

Predictors will usually include media that illustrate the predictor in action.

NatML currently supports images and animated GIF's for predictor media.