Work with multi-file inputs and outputs

In this tutorial you will learn how to work with multi-file inputs and outputs on the Nextmv Platform. Complete this tutorial if you:

• Want to work with CSV, Excel, or multiple data files instead of single JSON.
• Are fluent using Python 🐍.

At a high level, this tutorial will go through the following steps:

1. When to use multi-file format.
2. Scaffold a multi-file app.
3. Understand the app manifest.
4. Load multi-file inputs.
5. Write multi-file outputs.
6. Run locally.
7. View in Console.

Let's dive right in 🤿.

1. When to use multi-file format

By default, Nextmv applications use JSON as the data format. Input is read from stdin and output is written to stdout, all as a single JSON object. This works well for many use cases, but sometimes you need more flexibility.

The multi-file format reads from an inputs/ directory and writes to an outputs/ directory. Use it when:

• Your data lives in CSV or Excel files.
• You have multiple related input files (e.g., items, capacities, and configuration).
• You work with large datasets that are easier to manage as separate files.

Multi-file format is supported in local runs, cloud runs, and the Console.

2. Scaffold a multi-file app

Use the nextmv init command to create a new multi-file application. When prompted, select Python as the language and Multi-file as the format:

nextmv init

Walk through the prompts: Template, Python, Multi-file, and then the path for your new app. Alternatively, you can clone the python-ortools-knapsack-multicsv community app:

nextmv community clone -a python-ortools-multiknapsack-multiexcel

After scaffolding, the resulting directory structure looks like this:

my-app/
├── app.yaml
├── inputs/
│   ├──input.xlsx
├── main.py
├── requirements.txt
└── README.md

The inputs/ directory contains your input data files. The app.yaml file configures the multi-file format. The main.py file contains your application logic.

3. Understand the app manifest

The app.yaml file is the app manifest that tells Nextmv how to run your application. For multi-file apps, it includes format configuration:

type: python
runtime: ghcr.io/nextmv-io/runtime/python:3.11
files:
  - main.py
python:
  pip-requirements: requirements.txt
configuration:
  content:
    format: multi-file
    multi-file:
      input:
        path: inputs
      output:
        solutions: outputs/solutions
        metrics: outputs/metrics.json
        assets: outputs/assets/assets.json

Key fields:

• format: multi-file enables the multi-file format.
• input.path specifies where input files are read from.
• output.solutions specifies where solution files are written.
• output.metrics specifies where run metrics are written.
• output.assets specifies where asset metadata is written.

4. Load multi-file inputs

The nextmv Python package provides helpful functions for interacting with multi-file inputs/ outputs. You are not required to use these functions. The only requirement is that your model reads from the input path and and writes to the output path specified in your app.yaml.

You can use nextmv.load() with InputFormat.MULTI_FILE to load data from multiple files. Each file is described by a data file descriptor that specifies the file name, format, and key in the resulting data dictionary.

import nextmv

input = nextmv.load(
    input_format=nextmv.InputFormat.MULTI_FILE,
    data_files=[
        nextmv.csv_data_file("items", input_data_key="items"),
        nextmv.json_data_file("config", input_data_key="config"),
    ],
    path="inputs",
)

items = input.data["items"]    # list of dicts from CSV
config = input.data["config"]  # dict from JSON
options = input.options         # from CLI args

How it works:

• csv_data_file("items") loads items.csv from the input directory. The .csv extension is added automatically.
• json_data_file("config") loads config.json from the input directory. The .json extension is added automatically.
• input_data_key sets the key used to access the data in input.data.
• CSV files are loaded as a list of dicts, where each row becomes a dict.

import pandas as pd

nextmv.DataFile(
    name="file.xlsx",
    loader=lambda p: pd.read_excel(p),
)

5. Write multi-file outputs

Use nextmv.Output with OutputFormat.MULTI_FILE to write solution files. Each solution file is described by a solution file descriptor that specifies the file name, format, and data.

output = nextmv.Output(
    output_format=nextmv.OutputFormat.MULTI_FILE,
    solution_files=[
        nextmv.json_solution_file("result", data=solution),
        nextmv.csv_solution_file("assignments", data=assignments),
    ],
    options=options,
    statistics=nextmv.Statistics(
        run=nextmv.RunStatistics(duration=duration),
        result=nextmv.ResultStatistics(
            value=objective_value,
        ),
    ),
)

nextmv.write(output, path="outputs")

How it works:

• json_solution_file("result", data=solution) writes to outputs/solutions/result.json.
• csv_solution_file("assignments", data=assignments) writes to outputs/solutions/assignments.csv.
• File extensions are added automatically by the convenience functions.
• Statistics are written to outputs/metrics.json.

import pandas as pd

nextmv.SolutionFile(
    name="out.xlsx",
    data=df,
    writer=lambda p, d: d.to_excel(p),
)

The path parameter in nextmv.load() and nextmv.write() should match the paths configured in your app.yaml.

6. Run locally

Run your multi-file application locally using nextmv local run create, pointing to the inputs directory:

nextmv local run create --input inputs/

After running, the output directory structure looks like this:

outputs/
├── solutions/
│   ├── result.json
│   └── assignments.csv
├── metrics.json
└── assets/
    └── assets.json

The solutions/ directory contains your solution files, and the metrics.json file contains run statistics such as duration and objective value.

7. View in Console

When your app is pushed to Nextmv Cloud and run remotely, the Console provides a multi-file viewer for inspecting results.

The viewer shows:

• A file tree on the left with all input and output files.
• A content preview on the right for the selected file.
• CSV files render as interactive tables.
• JSON files render in the code editor.

This makes it easy to browse through all the files associated with a run without downloading them individually.