# Proposed event contract, version 1 (AsyncAPI 3.0): the events this system publishes, their consumers, payloads and delivery
# guarantees, and the events it consumes. Status: proposal for review, not confirmed design.
asyncapi: 3.0.0
info:
  title: AI Model Platform Events
  version: 1.0.0
  description: 'Dataset versions that became ready or failed, model versions deployed or retired, and batch scorings
    completed. Envelope, delivery guarantees and webhook headers: `common/v1/events.yaml`. Status: proposal for
    review, not confirmed design.'
defaultContentType: application/cloudevents+json
servers:
  prod:
    host: pubsub.googleapis.com
    protocol: googlepubsub
    description: Pub/Sub in the project that hosts the system, prod.
  stage:
    host: pubsub.googleapis.com
    protocol: googlepubsub
    description: Pub/Sub in the project that hosts the system, stage.
channels:
  ai-model-platform.events.v1:
    address: ai-model-platform.events.v1
    description: Every event ai-model-platform publishes. Consumers filter by the `ce-type` attribute.
    messages:
      dataset_version_ready_v1:
        $ref: '#/components/messages/dataset_version_ready_v1'
      dataset_version_failed_v1:
        $ref: '#/components/messages/dataset_version_failed_v1'
      model_version_deployed_v1:
        $ref: '#/components/messages/model_version_deployed_v1'
      model_version_retired_v1:
        $ref: '#/components/messages/model_version_retired_v1'
      scoring_batch_completed_v1:
        $ref: '#/components/messages/scoring_batch_completed_v1'
    bindings:
      googlepubsub:
        messageRetentionDuration: 604800s
        schemaSettings:
          encoding: json
          name: projects/moonitoring-<env>-<project>/schemas/ai-model-platform.events.v1
operations:
  publish_dataset_version_ready_v1:
    action: send
    channel:
      $ref: '#/channels/ai-model-platform.events.v1'
    messages:
    - $ref: '#/channels/ai-model-platform.events.v1/messages/dataset_version_ready_v1'
    summary: A dataset version was built and is readable by its manifest.
    x-moonitoring-producer: ai-model-platform
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '72'
    - '72.15'
  publish_dataset_version_failed_v1:
    action: send
    channel:
      $ref: '#/channels/ai-model-platform.events.v1'
    messages:
    - $ref: '#/channels/ai-model-platform.events.v1/messages/dataset_version_failed_v1'
    summary: A build failed.
    x-moonitoring-producer: ai-model-platform
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '72.15'
  publish_model_version_deployed_v1:
    action: send
    channel:
      $ref: '#/channels/ai-model-platform.events.v1'
    messages:
    - $ref: '#/channels/ai-model-platform.events.v1/messages/model_version_deployed_v1'
    summary: A model version was deployed and answers predictions.
    x-moonitoring-producer: ai-model-platform
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '1006.25'
  publish_model_version_retired_v1:
    action: send
    channel:
      $ref: '#/channels/ai-model-platform.events.v1'
    messages:
    - $ref: '#/channels/ai-model-platform.events.v1/messages/model_version_retired_v1'
    summary: A model version was retired and refuses calls.
    x-moonitoring-producer: ai-model-platform
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '1006.25'
  publish_scoring_batch_completed_v1:
    action: send
    channel:
      $ref: '#/channels/ai-model-platform.events.v1'
    messages:
    - $ref: '#/channels/ai-model-platform.events.v1/messages/scoring_batch_completed_v1'
    summary: A batch scoring finished; its predictions are in farm as computed records.
    x-moonitoring-producer: ai-model-platform
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '62'
    - '62.2'
components:
  messages:
    dataset_version_ready_v1:
      name: dataset_version.ready.v1
      title: dataset_version.ready.v1
      summary: A dataset version was built and is readable by its manifest.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: dataset_version.ready.v1
            subject:
              type: string
              description: The version id.
            data:
              $ref: '#/components/schemas/DatasetVersionReadyV1Data'
    dataset_version_failed_v1:
      name: dataset_version.failed.v1
      title: dataset_version.failed.v1
      summary: A build failed.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: dataset_version.failed.v1
            subject:
              type: string
              description: The version id.
            data:
              $ref: '#/components/schemas/DatasetVersionFailedV1Data'
    model_version_deployed_v1:
      name: model_version.deployed.v1
      title: model_version.deployed.v1
      summary: A model version was deployed and answers predictions.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: model_version.deployed.v1
            subject:
              type: string
              description: The model version id.
            data:
              $ref: '#/components/schemas/ModelVersionDeployedV1Data'
    model_version_retired_v1:
      name: model_version.retired.v1
      title: model_version.retired.v1
      summary: A model version was retired and refuses calls.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: model_version.retired.v1
            subject:
              type: string
              description: The model version id.
            data:
              $ref: '#/components/schemas/ModelVersionRetiredV1Data'
    scoring_batch_completed_v1:
      name: scoring_batch.completed.v1
      title: scoring_batch.completed.v1
      summary: A batch scoring finished; its predictions are in farm as computed records.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: scoring_batch.completed.v1
            subject:
              type: string
              description: The batch id.
            data:
              $ref: '#/components/schemas/ScoringBatchCompletedV1Data'
  schemas:
    DatasetVersionReadyV1Data:
      type: object
      properties:
        dataset:
          type: string
          format: uuid
        version:
          type: string
          format: uuid
        number:
          type: integer
        data_seq:
          type: integer
        manifest_path:
          type: string
        manifest_hash:
          type: string
        row_count:
          type: integer
        size_bytes:
          type: integer
      required:
      - dataset
      - version
      - number
      - data_seq
      - manifest_path
      - manifest_hash
    DatasetVersionFailedV1Data:
      type: object
      properties:
        dataset:
          type: string
          format: uuid
        version:
          type: string
          format: uuid
        number:
          type: integer
        error:
          type: string
      required:
      - dataset
      - version
      - number
      - error
    ModelVersionDeployedV1Data:
      type: object
      properties:
        model:
          type: string
          format: uuid
        name:
          type: string
        version:
          type: string
          format: uuid
        version_label:
          type: string
        feature:
          type: string
      required:
      - model
      - name
      - version
      - feature
    ModelVersionRetiredV1Data:
      type: object
      properties:
        model:
          type: string
          format: uuid
        name:
          type: string
        version:
          type: string
          format: uuid
      required:
      - model
      - name
      - version
    ScoringBatchCompletedV1Data:
      type: object
      properties:
        batch:
          type: string
          format: uuid
        model_version:
          type: string
          format: uuid
        model_run:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - done
          - failed
        predictions_written:
          type: integer
        write_seqs:
          type: array
          items:
            type: integer
      required:
      - batch
      - model_version
      - status
x-moonitoring-consumes:
- event: dataset_export.completed.v1
  producer: farm
  why: Marks the version ready or failed.
- event: write_commit.committed.v1
  producer: farm
  why: Knows when the watermark advanced, for scheduled builds.
- event: feed_coverage.updated.v1
  producer: farm
  why: Keeps labels before the settled date of each feed.
- event: staff_membership.changed.v1, staff_role.updated.v1
  producer: access
  why: Authorizes data scientists.
- event: erasure_request.executed.v1
  producer: farm
  why: Rewrites kept datasets and versions.