Apps

An app represents a published decision model. You can submit input to this app which then runs the input through your custom model and returns an ouput. You can do this with the app’s unique API endpoints or using Nextmv CLI (or in some cases using Nextmv’s web app Console).

An app also contains versions of your custom model’s executable binary and instances to manage how those versions are deployed and used for runs. The diagram below displays some of the core pieces of an optimization application.

An application can be thought of as a container for all of the assets used to solve a particular problem for your business. As mentioned above, an app contains all of your past runs, versions and instances you’ve defined, and experiment results as well. Each app also has a set of unique API endpoints for programmatically managing the app’s services and connecting it to your services.

There are two types of apps: subscription apps and custom apps. Subscription apps and custom apps mainly differ in how the code is accessed and versioned:

• with custom apps you control the code for your model and how versions of this model are published;
• with subscription apps, you are subscribed to a custom app in the Nextmv Marketplace and someone else controls this model code and the published versions.

But otherwise how custom and subscription apps operate is the same. They both can be managed with our developer tools and cloud-based web app Console and executing a run on either type of app is the same.

Subscription apps

Subscription apps are apps you have created, but instead of managing the model source code and features, it is subscribed to an app in the Nextmv Marketplace and thus has access to all of that app’s features and functionality. Though you do not control the source code or how the versions are published, you can control which versions you use and which features you access.

For example, the Nextmv Routing app allows you instant access to a powerful routing app that can be used to route vehicles for pickup and delivery, solve sourcing and delivery problems and more. All you need to do to access these features is create a new app and subscribe it to the Nextmv Routing app. Then when you submit a run to this new app it will use the Nextmv Routing app to process the input and deliver the output. It’s a fast way to spin up a routing service with low code effort.

Subscription apps can still be customized to your business needs based on the constraints and customization it offers, but you cannot access the source code of the Marketplace app. For more on how to create and manage subscription apps, see the Subscription apps reference page.

What is Nextmv Marketplace?

The Nextmv Marketplace contains apps that have been created to solve specific problem domains like routing or scheduling. These apps are published and maintained by Nextmv and can be accessed via Nextmv CLI or Nextmv Console. Subscription apps are apps that are subscribed to apps published in the Nextmv Marketplace.

Custom apps

With custom apps you can customize all parts of the model and therefore completely customize a decision app to your unique business needs. There are also a variety of apps available that are a great way to get started in a particular problem domain (e.g. routing, scheduling).

Custom apps begin by initializing a new template with the Nextmv CLI. You can then edit the model and run it locally. Once your model is ready, or you’re ready to test it remotely, you can build the model and then deploy it to a remote environment with the push command in Nextmv CLI.

You first must create a new app which exists independently from a custom model built locally. Then when you push your custom custom build you specify this new app’s ID as the application to push the custom model’s executable binary to. Once the executable binary is stored in the custom app (in the form of a version), it can be attached to an instance and then run (or used in an experiment).

For a guide to creating and managing custom apps see the Custom apps reference page.

App concepts

There are five main concepts to understand about apps, and these concepts apply to both custom and subscription apps.

1. Executable binaries
2. Versions
3. Instances
4. Configuration
5. Runs (input/output)

Executable binaries

An executable binary is your model code in a form that can accept input and return output. Nextmv CLI automatically builds and publishes your custom model as an executable binary with the push command.

Each app contains only one active executable binary. When you push a new executable binary, it overwrites the executable binary that was there prior (if one existed). Executable binaries are not named or versioned. The way to preserve a specific executable binary is to create a new version and attach the app’s current binary to that version.

Versions

An application version represents a specific executable binary. When you create a new version (either from Nextmv CLI, the REST API, or Nextmv Console), your app’s current executable binary (remember there can only be one) is attached to the version.

Once this version is created, the executable binary will always be attached to this version no matter how many other executable binaries are published to your app. You can update the name and description of a version, but you cannot change the referenced executable. Versions provides a way to explicitly manage the behavior of your app.

Instances

An application instance is a representation of a version and optional configuration that you want to use in some context.

Examples include:

• You want to use different optimization logic for different regions, even though both run off the app, you can have separate instances for different regions. This also allows you to partition your run history (e.g. you want to see runs made in a specific region only) and also provide different configuration settings per region.
• You want to test two different app version/configuration combinations. You can specify multiple instances that use the same version but have different configurations.
• You want to have different environments for staging and production. You can specify one instance for staging, and one for production.
• You want to give each developer their own instance so they can push their working code to their own endpoints.
• You want to have an instance for each GitHub PR.
• And more.

Instances are the mechanism by which a run is made. When you submit input to your app for a run, the app determines which instance to use and then uses the executable binary specified in the version specified by that instance for the run.

An application knows which instance to use by two ways:

1. You can specify an instance explicitly with a flag on the Nextmv CLI command or with a query parameter in the API call.
2. You can set a default instance for your app and this instance is always used when no instance is specified. (If no application instance is specified, and no default application instance is defined, then the run will fail.)

The same version can be used by multiple application instances, and an instance’s version can be changed as well. This allows you to publish model updates to a specific environment in a controlled way.

Instances are the way to manage which versions are used for runs, as well as a way to manage consistent configuration per run.

Reserved devint instance

There is a special reserved instance called the devint that has been created for the developer experience. The devint instance is a special reserved instance that always contains the most recently pushed executable. There is no version tied to devint, it is just always assigned the most recently pushed executable.

Further, when making a run from Nextmv CLI (nextmv app run) we assume a developer context and assume that you want to use the latest pushed binary which means we direct the app to use devint for the run rather than your app’s default instance. (Though note if you have not yet pushed a binary to the app, the run command will fail.)

If you want to use the default instance when running remotely from Nextmv CLI you must be explicit by appending the --default flag to the run command. In this case the CLI will direct the app to use the default instance. (Note that if you have not yet set a default instance for your app then the command will fail)

With the API endpoints, if you run the /applications/<app-id>/runs endpoint, we assume that you want to use the default instance. If you do not yet have a default instance the run will fail.

Conversely, if you want to use the devint with the applications REST API endpoints, you must explicitly set it by appending ?instance_id=devint to the endpoint. The REST API endpoints will always use the app’s default instance by default.

Configuration

An instance can be assigned a specific configuration. The configuration is defined as a set of key/value pairs and should correspond to the model’s available configuration. Configuration can be added to, edited on, and removed from an instance at any time. Any run made with an instance will preserve the configuration used.

When an instance contains configuration values, these values will take precedence over the model’s default configuration and any environment variable. However, if the input itself contains a value for the same configurable variable, the input will take precedence over the instance configuration.

For more information on configuration, visit the Configuration reference page.

Runs

Runs are executed for an app using the Nextmv CLI or the REST API endpoints. You can also create new runs in Nextmv Console. A run consists of submitting an input (either a file or raw JSON) and then retrieving the output from the run along with metadata and statistics, altogether called the run result.

A run is made by specifying which instance to use (either explicitly or using the app’s default instance) and then that instance’s version’s executable binary is used for the run along with any specified config to produce the run result.

For more on runs, see the applications API reference for runs as well as the CLI reference for runs.