# 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 Gateway Events
  version: 1.0.0
  description: 'What the gateway observed: every model call, without the prompt, and the state of the providers.
    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-gateway.events.v1:
    address: ai-gateway.events.v1
    description: Every event ai-gateway publishes. Consumers filter by the `ce-type` attribute.
    messages:
      model_call_completed_v1:
        $ref: '#/components/messages/model_call_completed_v1'
      provider_degraded_v1:
        $ref: '#/components/messages/provider_degraded_v1'
    bindings:
      googlepubsub:
        messageRetentionDuration: 604800s
        schemaSettings:
          encoding: json
          name: projects/moonitoring-<env>-<project>/schemas/ai-gateway.events.v1
operations:
  publish_model_call_completed_v1:
    action: send
    channel:
      $ref: '#/channels/ai-gateway.events.v1'
    messages:
    - $ref: '#/channels/ai-gateway.events.v1/messages/model_call_completed_v1'
    summary: A model call ended, with its usage and outcome; the ledger row. Consumed by the security detection
      rules and the Console's usage views.
    x-moonitoring-producer: ai-gateway
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '69'
    - '121.9'
    - '121.10'
  publish_provider_degraded_v1:
    action: send
    channel:
      $ref: '#/channels/ai-gateway.events.v1'
    messages:
    - $ref: '#/channels/ai-gateway.events.v1/messages/provider_degraded_v1'
    summary: A provider is answering slowly or failing; callers may fall back.
    x-moonitoring-producer: ai-gateway
    x-moonitoring-consumers:
    - moochat
    - grant
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '121.3'
components:
  messages:
    model_call_completed_v1:
      name: model_call.completed.v1
      title: model_call.completed.v1
      summary: A model call ended, with its usage and outcome; the ledger row. Consumed by the security detection
        rules and the Console's usage views.
      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_call.completed.v1
            subject:
              type: string
              description: The call id.
            data:
              $ref: '#/components/schemas/ModelCallCompletedV1Data'
    provider_degraded_v1:
      name: provider.degraded.v1
      title: provider.degraded.v1
      summary: A provider is answering slowly or failing; callers may fall back.
      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: provider.degraded.v1
            subject:
              type: string
              description: The provider name.
            data:
              $ref: '#/components/schemas/ProviderDegradedV1Data'
  schemas:
    ModelCallCompletedV1Data:
      type: object
      properties:
        call:
          type: string
          format: uuid
        request_id:
          type: string
        organization:
          type: string
          format: uuid
        moonitoring_user:
          type: string
          format: uuid
        feature:
          type: string
        caller:
          type: string
        provider:
          type: string
        model:
          type: string
        data_class:
          type: string
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        cost_micros:
          type: integer
        latency_ms:
          type: integer
        outcome:
          type: string
      required:
      - call
      - request_id
      - feature
      - caller
      - provider
      - model
      - outcome
    ProviderDegradedV1Data:
      type: object
      properties:
        provider:
          type: string
        status:
          type: string
          enum:
          - degraded
          - down
          - healthy
        since:
          type: string
          format: date-time
      required:
      - provider
      - status
      - since
x-moonitoring-consumes:
- event: agent_model_profile.changed.v1
  producer: moochat
  why: Refreshes provider, model, region and data classes per profile.
- event: entitlement.*.v1
  producer: farm
  why: 'Nothing: usage is reserved and settled synchronously through the Entitlements gRPC service.'