106. Evaluation Pipeline input list

An input list tells the pipeline which data packages to process. You pass it to the run subcommand with --input_list, and to validate to check every entry before a full batch.

The input list is a JSON document with a single top-level key, inputs, holding an array of entries. Each entry describes one recording to process.

{
  "inputs": [
    {
      "drive_data": "/data/recordings/recording_001.parquet",
      "map_data": "/data/maps/area.xodr",
      "matches_data": "/data/matches/recording_001_matches.pb",
      "video_data": "/data/videos/recording_001.mp4",
      "metadata": {"source": "fleet_a", "date": "2026-03-15"}
    },
    {
      "drive_data": "/data/recordings/recording_002.parquet"
    }
  ]
}

106.1 Entry fields

Only drive_data is required. All other fields are optional.

Field	Required	Description
`drive_data`	Yes	Path to the raw data package — a single measurement file. Directories are rejected; each pipeline run processes exactly one measurement file.
`map_data`	No	Path to a map file. Overrides any map discovered by the explore stage.
`matches_data`	No	Path to external match data for the `ext_match` stage.
`video_data`	No	Path to a video file for playback in Foretify Manager.
`metadata`	No	An arbitrary JSON object stored alongside the run for traceability.

106.2 Explorer discovery versus explicit fields

When you omit map_data, matches_data, or video_data, the explore stage plugin discovers them automatically from the recording directory. If the explorer cannot find a field that the flow requires — for example, a map file — the pipeline fails with a clear error.

Any value you specify explicitly in the input list always takes precedence over explorer discovery. The second entry in the example above relies entirely on the explorer, while the first entry specifies every input path explicitly.

106.3 Path expansion

Paths support environment variable expansion, so you can keep the input list portable across installations:

{
  "inputs": [
    {"drive_data": "${DATA_ROOT}/recordings/recording_001.parquet"}
  ]
}

$FTX/..., ${HOME}/..., and any other environment variable are expanded when the list is loaded.

106.4 Inline JSON

Instead of a file path, you can pass the JSON directly to --input_list. This is useful for quick one-off runs and scripting:

$FTX_EVALUATE_EXE run \
    --input_list '{"inputs": [{"drive_data": "/data/recordings/recording_001"}]}' \
    --output_path /tmp/eval_output \
    --flow /path/to/flow_config.yaml

106.5 Cloud storage paths

Both the input list file itself and the individual drive_data, map_data, and other path values can use s3:// URLs. The pipeline downloads them as needed during the run.

{
  "inputs": [
    {
      "drive_data": "s3://my-bucket/recordings/recording_001.parquet",
      "map_data": "s3://my-bucket/maps/area.xodr"
    }
  ]
}