# 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: MooChat Events
  version: 1.0.0
  description: 'Changes to agents and model profiles, and the completion of a turn, which reaches the instance that
    holds the user''s live connection. 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:
  moochat.events.v1:
    address: moochat.events.v1
    description: Every event moochat publishes. Consumers filter by the `ce-type` attribute.
    messages:
      agent_definition_changed_v1:
        $ref: '#/components/messages/agent_definition_changed_v1'
      agent_model_profile_changed_v1:
        $ref: '#/components/messages/agent_model_profile_changed_v1'
      conversation_turn_completed_v1:
        $ref: '#/components/messages/conversation_turn_completed_v1'
    bindings:
      googlepubsub:
        messageRetentionDuration: 604800s
        schemaSettings:
          encoding: json
          name: projects/moonitoring-<env>-<project>/schemas/moochat.events.v1
operations:
  publish_agent_definition_changed_v1:
    action: send
    channel:
      $ref: '#/channels/moochat.events.v1'
    messages:
    - $ref: '#/channels/moochat.events.v1/messages/agent_definition_changed_v1'
    summary: An agent was created, changed, paused, resumed or archived.
    x-moonitoring-producer: moochat
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '120'
    - '1006.26'
  publish_agent_model_profile_changed_v1:
    action: send
    channel:
      $ref: '#/channels/moochat.events.v1'
    messages:
    - $ref: '#/channels/moochat.events.v1/messages/agent_model_profile_changed_v1'
    summary: A model profile was created, changed or retired. ai-gateway refreshes the routing it derives from profiles.
    x-moonitoring-producer: moochat
    x-moonitoring-consumers:
    - ai-gateway
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '121'
    - '121.11'
    - '1006.27'
  publish_conversation_turn_completed_v1:
    action: send
    channel:
      $ref: '#/channels/moochat.events.v1'
    messages:
    - $ref: '#/channels/moochat.events.v1/messages/conversation_turn_completed_v1'
    summary: 'The assistant finished a turn: its message and tool calls are stored. Every moochat instance receives
      it and forwards it to the live connections of that conversation.'
    x-moonitoring-producer: moochat
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '125'
    - '126'
components:
  messages:
    agent_definition_changed_v1:
      name: agent_definition.changed.v1
      title: agent_definition.changed.v1
      summary: An agent was created, changed, paused, resumed or archived.
      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: agent_definition.changed.v1
            subject:
              type: string
              description: The agent id.
            data:
              $ref: '#/components/schemas/AgentDefinitionChangedV1Data'
    agent_model_profile_changed_v1:
      name: agent_model_profile.changed.v1
      title: agent_model_profile.changed.v1
      summary: A model profile was created, changed or retired. ai-gateway refreshes the routing it derives from
        profiles.
      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: agent_model_profile.changed.v1
            subject:
              type: string
              description: The profile id.
            data:
              $ref: '#/components/schemas/AgentModelProfileChangedV1Data'
    conversation_turn_completed_v1:
      name: conversation.turn.completed.v1
      title: conversation.turn.completed.v1
      summary: 'The assistant finished a turn: its message and tool calls are stored. Every moochat instance receives
        it and forwards it to the live connections of that conversation.'
      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: conversation.turn.completed.v1
            subject:
              type: string
              description: The conversation id.
            data:
              $ref: '#/components/schemas/ConversationTurnCompletedV1Data'
  schemas:
    AgentDefinitionChangedV1Data:
      type: object
      properties:
        agent:
          type: string
          format: uuid
        slug:
          type: string
        status:
          type: string
          enum:
          - active
          - paused
          - archived
        feature:
          type: string
      required:
      - agent
      - slug
      - status
    AgentModelProfileChangedV1Data:
      type: object
      properties:
        profile:
          type: string
          format: uuid
        slug:
          type: string
        provider:
          type: string
        model:
          type: string
        region:
          type: string
        data_classes:
          type: array
          items:
            type: string
        tier:
          type: string
        parameters:
          type: string
          description: The profile's parameters as JSON (temperature, output cap, context cap, thinking budget), the
            bounds of a request's overrides.
        cost_input_micros:
          type: integer
          description: List price per 1M input tokens in millionths of a euro, for the ledger.
        cost_output_micros:
          type: integer
          description: List price per 1M output tokens in millionths of a euro, for the ledger.
        status:
          type: string
          enum:
          - active
          - retired
      required:
      - profile
      - slug
      - provider
      - model
      - data_classes
      - tier
      - parameters
      - cost_input_micros
      - cost_output_micros
      - status
    ConversationTurnCompletedV1Data:
      type: object
      properties:
        conversation:
          type: string
          format: uuid
        message:
          type: string
          format: uuid
        organization:
          type: string
          format: uuid
        tool_calls:
          type: array
          items:
            type: string
            format: uuid
        pending_confirmation:
          type: array
          items:
            type: string
            format: uuid
          description: Write tools waiting for the user's confirmation.
      required:
      - conversation
      - message
x-moonitoring-consumes:
- event: organization.*.v1, membership.*.v1, delegation.*.v1
  producer: access
  why: Authorizes each message as its sender and offers tools by the sender's capabilities.
- event: entitlement.*.v1, feature_usage.limit_reached.v1
  producer: farm
  why: Offers agents and tools by the Organization's features; degrades or blocks at the limit.
- event: staff_membership.changed.v1, staff_role.updated.v1
  producer: access
  why: Authorizes staff agents.
- event: data_issue.opened.v1, resolved_event.published.v1, animal.*.v1
  producer: farm
  why: Lets an agent mention what changed since the user last asked; optional.
- event: provider.degraded.v1
  producer: ai-gateway
  why: Falls back to another profile of the same tier.
- event: erasure_request.executed.v1
  producer: farm
  why: Erases the Organization's conversations.