Get started with bringing your own model to Nextmv

The following sections will walk you through a brief introduction to using a custom app on the Nextmv Platform. You will:

1. Sign up for an account at https://cloud.nextmv.io.
2. Sign up for a free trial of a Plan (includes a 14-day free trial) to access custom models. Note plan can be changed or canceled at any time without fees.
3. Install a Nextmv client.
4. Nextmvify your model.
5. Push your model to Nextmv cloud.
6. Make a remote run.

1. Sign up for an account

First, sign up for a free Nextmv account (see the limits of a free plan on the Nextmv Pricing page).

2. Sign up for a free trial of a Plan

After completing the sign up process, log in and you should land on the main Nextmv Marketplace page. In the top right corner, you should see an Upgrade button. You can select either Innovator or Scale-up depending on your needs. This comes with a 14-day free trial which can be canceled or changed without any fees.

Alternatively, you can contact support@nextmv.io requesting access to Custom apps. (For security reasons, we need to verify you are a human either with your credit card or via a discussion with support).

3. Install a Nextmv client

Python developers can pip install nextmv to gain access to the Nextmv Python SDK containing helpful constructs for common patterns in decision models. Additionally, the Python SDK can be used to push your custom model up to the Nextmv cloud.

For non-Python developers, you can install the Nextmv CLI which is only needed if not using the Python SDK.

4. Nextmvify your custom app

Now, you're ready to Nextmvify your custom app to run on the Nextmv cloud.

a. Input is JSON, TEXT, or CSV and read from a file or stdin

First, make sure your input can be read from a file or stdin and is JSON, TEXT, or CSV.

If reading from a file or files (required for CSV), your input data must be nested in and read from a folder called input in your model code. This ensures we can find your input and execute it appropriately on the Nextmv Platform.

For Python users, you may use the load_local function from the Nextmv Python SDK; however, it is not required. If you are loading multiple CSVs from the input folder, your code might look like this:

input = nextmv.load_local(
    input_format=nextmv.InputFormat.CSV_ARCHIVE,
    options=options,
    path=options.input,
)

Note, you may choose to expose configuration of your model via CLI flags. For Python users, you may optionally use the Options and Parameter functions from the Nextmv Python SDK, and your code might look like this:

options = nextmv.Options(
    nextmv.Parameter("input", str, "", "Path to input folder.", False),
    nextmv.Parameter("output", str, "", "Path to output folder.", False),
    nextmv.Parameter("duration", int, 30, "Max runtime duration (in seconds).", False),
    nextmv.Parameter("provider", str, "SCIP", "Solver provider.", False),
)

load_local then receives these custom options.

If you are reading your input from stdin instead, you may also use load_local without specifying any arguments.

input = nextmv.load_local()

b. Statistics written to stdout

Next, you may add statistics to your model and write them to stdout. While this is not required to run on the platform, it is required to conduct Nextmv Experiments. Statistics must conform to the Nextmv statistics convention in order to be picked up automatically in your Nextmv Console run history and Nextmv Experiments.

For Python users, you may optionally use the Output function from the Nextmv Python SDK and your code might look like this:

output = nextmv.Output(
    solution=None,
    statistics=nextmv.Statistics(
        result=nextmv.ResultStatistics(
            value=1.23,
            custom={"message": message},
        ),
    ),
)

c. Logs written to stderr

Next, ensure your logs are written to stderr.

For Python users, you may optionally use the log function from the Nextmv Python SDK and your code might look like this:

message = f"Hello, {name}"
nextmv.log(message)

d. Output is JSON, TEXT, or CSV and written to a file or stdout and

Next, make sure your model writes a solution to a file or stdout and is JSON, TEXT, or CSV. If reading from a file or files (required for CSV), your output data must be written to a folder called output in your model code. This ensures we can find your output and render it appropriately on the Nextmv Console.

For Python users, you may optionally use the write_local function to write an Output from the Nextmv Python SDK, and your code might look like this:

nextmv.write_local(output, path=options.output)

Where options.output is optional (required only for models with CSV input regardless of output type).

f. Add an app manifest at the root of your project

Lastly, to Nextmvify your model, you must add an app manifest at the root of your project which will tell the Nextmv platform what runtime and requirements are needed to execute your custom model. For Python users, your app manifest might look like this:

# This manifest holds the information the app needs to run on the Nextmv Cloud.
type: python
runtime: ghcr.io/nextmv-io/runtime/python:3.11
python:
  # All listed packages will get bundled with the app.
  pip-requirements: requirements.txt

# List all files/directories that should be included in the app. Globbing
# (e.g.: configs/*.json) is supported.
files:
  - main.py

5. Push your custom model to the Nextmv Cloud

Now that your model is Nextmvified, you can push your model to the Nextmv Cloud.

6. Run your new app

Now, you can visit the Nextmv Console. Click into your apps icon on the left, and select your app. From your app’s main details view, click the Run app button. This will load an empty user interface for adding the input and configuration for your run.

Paste in your input if JSON or upload a file for non-JSON inputs. Modify configuration if you exposed any configuration in your model.

Next, click the Start run button to run your app. This will load a new screen where you can view the details of your app run. Your run status will start with either queued or running and will move to successful once it has completed.

Once the status reaches succeeded click on the Result tab to view the result of your run. You should either see your solution output or a button to download the output.

Next steps

🎉🎉🎉 You completed this brief introduction to using custom apps on the Nextmv Decision Platform. Here are some next steps:

1. See the solvers that are supported.
2. Begin exploring scenario tests and other experiments