# Proposed contract, version 1: endpoints, errors, paging, idempotency, security and the capability of every
# operation. Resource schemas were initialized from the data model (docs/06-data) and are kept aligned with it; input
# schemas (*Input, *Request) and views are specific to this contract. Status: proposal for review, not confirmed design.
# Conventions: docs/05-interfaces/choosing-an-interface.md. Vendor extensions: x-moonitoring-audience (who calls),
# x-moonitoring-capability (the capability checked), x-moonitoring-entitlement (the entitlement feature checked),
# x-moonitoring-requirements (the requirements of 1.requisiti-raffinati.txt the operation serves).
openapi: 3.1.0
info:
  title: AI Model Platform Model Runs API
  version: 1.0.0
  description: 'Every use of the data by a model, so it can be rebuilt exactly: training, scoring, pricing and analyses,
    with the write number read, the feature code version, the rule set and the knowledge clock. Pipelines record
    their runs; `farm` records the runs of on-demand predictions through the gRPC service of the Models domain.'
servers:
- url: https://ai-model-platform.moonitoring.com/runs/v1
  description: Prod
- url: https://stage-ai-model-platform.moonitoring.com/runs/v1
  description: Stage, through IAP
security:
- bearer: []
tags:
- name: Runs
  description: Reproducible uses of the data
paths:
  /runs:
    get:
      summary: List model runs
      operationId: listModelRuns
      tags:
      - Runs
      parameters:
      - name: kind
        in: query
        required: false
        schema:
          type: string
          enum:
          - training
          - scoring
          - pricing
          - analysis
        description: Only this kind.
      - name: model
        in: query
        required: false
        schema:
          type: string
        description: Only this model name and version.
      - name: dataset_version
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Only runs that read this version.
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Created at or after.
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Created before.
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of results.
          content:
            application/json:
              schema:
                type: object
                description: One page of items.
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ModelRun'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
      x-moonitoring-audience: staff
      x-moonitoring-capability:
      - ai-model-platform.datasets.read
      - ai-model-platform.models.read
      x-moonitoring-requirements:
      - '62'
      - '1006.30'
      - '1006.25'
    post:
      summary: Record a model run
      operationId: createModelRun
      description: By a pipeline's service account or a data scientist recording an analysis. Training labels exclude
        disputed facts; admission by trust is part of the feature code.
      tags:
      - Runs
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelRunInput'
      responses:
        '201':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRun'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
        '422':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/UnprocessableEntity
      x-moonitoring-audience: staff
      x-moonitoring-capability:
      - ai-model-platform.models.manage
      - ai-model-platform.datasets.read
      x-moonitoring-requirements:
      - '62'
      - '62.3'
      - '62.4'
      - '62.5'
      - '62.12'
  /runs/{run_id}:
    get:
      summary: Read a model run
      operationId: getModelRun
      tags:
      - Runs
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRun'
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
      x-moonitoring-audience: staff
      x-moonitoring-capability:
      - ai-model-platform.datasets.read
      - ai-model-platform.models.read
      x-moonitoring-requirements:
      - '62'
components:
  schemas:
    ModelRun:
      description: 'One reproducible use of the data by a model: training, scoring, pricing or an analysis. It records
        the write number it read, the feature code and the rule set, so the same dataset can be built again.'
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Key.
        kind:
          type: string
          enum:
          - training
          - scoring
          - pricing
          - analysis
        data_seq:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/ReadSequence
          description: The read cutoff the run used; zero represents the initial state before any writes.
            Re-reading at this cutoff gives the same data.
        feature_code_version:
          type: string
          description: Version (commit or hash) of the feature code, including the time grid of the dataset (e.g.
            daily, at each calving).
        rule_set:
          type: string
          format: uuid
          description: ID of the ReconciliationRuleSet. Reconciliation rules and reliability ranking in force for
            the resolved facts it read.
        model:
          type: string
          description: Model name and version.
        scope:
          type: string
          description: Farms, animals and period covered.
        dataset_path:
          type: string
          description: The dataset file in the bucket, kept for models used in production (scoring, pricing). Immutable.
        dataset_hash:
          type: string
        previous_run:
          type: string
          format: uuid
          description: ID of the ModelRun. e.g. the training run a scoring or pricing run used.
        dataset_version:
          type: string
          format: uuid
          description: ID of the MlDatasetVersion. The catalogued version the run read, when it read one; its manifest
            hash is then the run's `dataset_hash` (`ModelRun.dataset_hash`). `ModelRun.dataset_path` and `ModelRun.dataset_hash`
            alone remain for runs that build their data outside the catalog (e.g. scoring in production).
        created_by:
          type: string
          format: uuid
          description: ID of the MoonitoringUser.
        knowledge_clock:
          type: string
          enum:
          - platform
          - source
          description: '`platform`: a record is visible at D if its revision was available to us by `data_seq` (live
            data). `source`: a record is visible at D if the source had recorded it by D (`recorded_at`), read at
            `data_seq` (imported history, where our arrival time is the import date). The feature code decides what
            to assume when `recorded_at` is empty.'
        created_at:
          type: string
          format: date-time
      required:
      - id
      - kind
      - data_seq
      - feature_code_version
      - rule_set
      - model
      - scope
      - knowledge_clock
      - created_at
    ModelRunInput:
      type: object
      description: Records a run. Rebuilding its dataset requires the same selection, data_seq, knowledge_clock,
        feature_code_version, rule_set and anonymization configuration. Matching only the write number, code and
        rules is insufficient. Identical hashes for independent rebuilds also require deterministic serialization
        and transformations.
      properties:
        kind:
          type: string
          enum:
          - training
          - scoring
          - pricing
          - analysis
        data_seq:
          $ref: ../../../../common/v1/schemas.yaml#/components/schemas/ReadSequence
          description: The read cutoff the run used; zero represents the initial state before any writes.
            Re-reading at this cutoff gives the same data.
        feature_code_version:
          type: string
          description: Version (commit or hash) of the feature code, including the time grid of the dataset (e.g.
            daily, at each calving).
        rule_set:
          type: string
          format: uuid
          description: ID of the ReconciliationRuleSet. Reconciliation rules and reliability ranking in force for
            the resolved facts it read.
        model:
          type: string
          description: Model name and version.
        scope:
          type: string
          description: Farms, animals and period covered.
        dataset_path:
          type: string
          description: The dataset file in the bucket, kept for models used in production (scoring, pricing). Immutable.
        dataset_hash:
          type: string
        previous_run:
          type: string
          format: uuid
          description: ID of the ModelRun. e.g. the training run a scoring or pricing run used.
        dataset_version:
          type: string
          format: uuid
          description: ID of the MlDatasetVersion. The catalogued version the run read, when it read one; its manifest
            hash is then the run's `dataset_hash` (`ModelRun.dataset_hash`). `ModelRun.dataset_path` and `ModelRun.dataset_hash`
            alone remain for runs that build their data outside the catalog (e.g. scoring in production).
        knowledge_clock:
          type: string
          enum:
          - platform
          - source
          description: '`platform`: a record is visible at D if its revision was available to us by `data_seq` (live
            data). `source`: a record is visible at D if the source had recorded it by D (`recorded_at`), read at
            `data_seq` (imported history, where our arrival time is the import date). The feature code decides what
            to assume when `recorded_at` is empty.'
      required:
      - kind
      - data_seq
      - feature_code_version
      - rule_set
      - model
      - scope
      - knowledge_clock
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The short-lived token signed by `access`: an Organization user token, a staff token or a client
        token, as the operation''s audience says.'