#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
#  SPDX-License-Identifier: Apache-2.0
$schema: "http://json-schema.org/draft-07/schema#"
$id: "urn:mas-lab:run-input:v1"
title: "mas-lab Run Input Envelope (v1)"
description: >
  Per-run document. ``user`` is prompt text (string) or ``{ref: file}``.
  ``tool_fixtures`` / ``memory_seeds`` use ``{ref:}`` or a bare path
  shorthand. Expectation values and tool-fixture payloads are free-form.

type: object
additionalProperties: false

properties:
  inputs:
    type: object
    additionalProperties: false
    required: [user]
    properties:
      user:
        description: >
          The user prompt. A string is the text. A list of strings is
          sequential user messages (no role dicts). A ref object loads
          that file (scalar, YAML string, or .txt/.md).
        oneOf:
          - type: string
            minLength: 1
          - type: array
            minItems: 1
            items:
              type: string
              minLength: 1
          - $ref: "urn:mas-lab:fragments:ref:v1"
          - type: array
            deprecated: true
            description: >
              DEPRECATED. OpenAI-style [{role, content}] from older
              datasets. Use a string or list of strings. Loader warns.
              See https://ioc-project.github.io/mas-lab/manifests/dataset-migration/
            minItems: 1
            items:
              type: object
              required: [role, content]
              additionalProperties: true
              properties:
                role:
                  type: string
                content:
                  type: string
      hitl:
        description: >
          Scripted operator replies, in order, after the user prompt.
          Strings, not role dicts.
        oneOf:
          - $ref: "urn:mas-lab:fragments:ref:v1"
          - type: string
            minLength: 1
          - type: array
            items:
              type: string
              minLength: 1
        default: []
      memory_seeds:
        description: >
          Inline seed list, MemorySeed kind document, ``{ref:}``, or bare
          path shorthand. Kind files keep ``docs/schemas/memory-seed.schema.yaml``.
        oneOf:
          - $ref: "urn:mas-lab:fragments:ref:v1"
          - type: string
            minLength: 1
          - type: array
            items:
              $ref: "urn:mas-lab:fragments:memory-seed-entry:v1"
          - type: object
            additionalProperties: true
            required: [kind, entries]
            properties:
              kind:
                type: string
                const: MemorySeed
              apiVersion:
                type: string
              metadata:
                type: object
                additionalProperties: true
              entries:
                type: array
                minItems: 1
                items:
                  $ref: "urn:mas-lab:fragments:memory-seed-entry:v1"
      tool_fixtures:
        description: >
          Generic mapping (which tool gets which payload). Payloads are
          free-form and only read by the tools: put them in referenced files
          or inline under by_tool ("*" for every tool). Ground truth is not
          stored here.
        $ref: "urn:mas-lab:fragments:tool-fixture-mapping:v1"
      checkpoint:
        type: object
        additionalProperties: false
        properties:
          load:
            oneOf:
              - type: "null"
              - $ref: "urn:mas-lab:fragments:ref:v1"
              - type: object
                additionalProperties: true
          save:
            oneOf:
              - type: boolean
              - type: string
                minLength: 1
        default: {}
      session_id:
        type: string
        minLength: 1

  expectations:
    description: >
      Ground truth for evaluation. Generic keys are read by mas-lab metrics;
      app- or tool-specific ground truth goes under ``details`` (free-form).
    oneOf:
      - $ref: "urn:mas-lab:fragments:ref:v1"
      - type: object
        additionalProperties: false
        properties:
          ground_truth:
            description: Expected answer compared by generic metrics.
            oneOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
              - type: object
                additionalProperties: true
              - type: array
          metrics:
            description: Metric names this item is scored on.
            type: array
            items:
              type: string
          details:
            description: Free-form ground truth owned by the app or its evaluators.
            type: object
            additionalProperties: true
          correct_action:
            deprecated: true
            description: >
              DEPRECATED. Use expectations.details.correct_action.
              Loader still accepts this key and folds it under details.
          governance:
            deprecated: true
            description: >
              DEPRECATED. Use expectations.details.governance.
              Loader still accepts this key and folds it under details.