asyncapi: 2.6.0
info:
  title: RAG Service Events
  version: 1.0.0
  description: |
    Kafka events published by the EventZR RAG Service for document lifecycle,
    search operations, feedback, knowledge gap detection, training, and tool synchronization.

    All events follow CloudEvents 1.0 specification and are published to 9 domain-specific
    Kafka topics, each partitioned by tenant_id for multi-tenancy isolation.
  contact:
    name: EventZR Platform Team
    email: platform@eventzr.com
  license:
    name: Proprietary
    url: https://eventzr.com/license

servers:
  staging:
    url: boot-gpm4u49z.c2.kafka-serverless.us-east-1.amazonaws.com:9098
    protocol: kafka
    description: Staging Kafka cluster (Amazon MSK Serverless)
    security:
      - saslIam: []

defaultContentType: application/json

channels:
  eventzr.rag.document.v1:
    description: |
      Document lifecycle events including indexing, deletion, updates, enrichment,
      chunk creation, and media processing. Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG document lifecycle events
      operationId: onRagDocumentEvent
      message:
        oneOf:
          - $ref: '#/components/messages/DocumentIndexed'
          - $ref: '#/components/messages/DocumentDeleted'
          - $ref: '#/components/messages/DocumentUpdated'
          - $ref: '#/components/messages/DocumentEnriched'
          - $ref: '#/components/messages/ChunksCreated'
          - $ref: '#/components/messages/MediaProcessingRequested'
          - $ref: '#/components/messages/MediaProcessingCompleted'
          - $ref: '#/components/messages/MediaProcessingFailed'

  eventzr.rag.search.v1:
    description: |
      Search events including executed queries, zero-result searches, search feedback,
      and agentic multi-step searches. Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG search events
      operationId: onRagSearchEvent
      message:
        oneOf:
          - $ref: '#/components/messages/SearchExecuted'
          - $ref: '#/components/messages/ZeroResults'
          - $ref: '#/components/messages/SearchFeedback'
          - $ref: '#/components/messages/AgenticSearchExecuted'

  eventzr.rag.training.v1:
    description: |
      Training events for RAG parameter tuning and golden set evaluation.
      Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG training events
      operationId: onRagTrainingEvent
      message:
        oneOf:
          - $ref: '#/components/messages/TrainingStarted'
          - $ref: '#/components/messages/TrainingCompleted'
          - $ref: '#/components/messages/TrainingFailed'
          - $ref: '#/components/messages/EvaluationCompleted'

  eventzr.rag.approval.v1:
    description: |
      Document governance approval events including requests, completions,
      and expirations. Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG approval events
      operationId: onRagApprovalEvent
      message:
        oneOf:
          - $ref: '#/components/messages/ApprovalRequested'
          - $ref: '#/components/messages/ApprovalCompleted'
          - $ref: '#/components/messages/ApprovalExpired'

  eventzr.rag.feedback.v1:
    description: |
      User feedback events including submission, processing, and quality alerts.
      Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG feedback events
      operationId: onRagFeedbackEvent
      message:
        oneOf:
          - $ref: '#/components/messages/FeedbackSubmitted'
          - $ref: '#/components/messages/FeedbackProcessed'
          - $ref: '#/components/messages/QualityAlert'

  eventzr.rag.knowledge-gap.v1:
    description: |
      Knowledge gap detection and resolution events including gap identification,
      resolution, and periodic coverage reports. Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG knowledge gap events
      operationId: onRagKnowledgeGapEvent
      message:
        oneOf:
          - $ref: '#/components/messages/KnowledgeGapIdentified'
          - $ref: '#/components/messages/KnowledgeGapResolved'
          - $ref: '#/components/messages/CoverageReport'

  eventzr.rag.tool-sync.v1:
    description: |
      Tool synchronization events for MCP/OpenAPI/GraphQL tool discovery and management.
      Includes sync lifecycle, tool registration, and removal. Partitioned by tenant_id.
    subscribe:
      summary: Subscribe to RAG tool sync events
      operationId: onRagToolSyncEvent
      message:
        oneOf:
          - $ref: '#/components/messages/ToolsSyncStarted'
          - $ref: '#/components/messages/ToolsSynced'
          - $ref: '#/components/messages/SyncFailed'
          - $ref: '#/components/messages/ToolRegistered'
          - $ref: '#/components/messages/ToolRemoved'

  eventzr.rag.knowledge.updated.v1:
    description: |
      Knowledge base content change events. Published when documents or chunks are
      added, updated, or deleted. Partitioned by namespaceId for affinity.
      Consumers: search-svc, analytics-svc, cypher-svc, aibrain-svc.
    subscribe:
      summary: Subscribe to knowledge updated events
      operationId: onRagKnowledgeUpdatedEvent
      message:
        $ref: '#/components/messages/KnowledgeUpdated'

  eventzr.rag.tenant.trained.v1:
    description: |
      Tenant-specific RAG training completion events. Published when specialized
      training (fine-tuning, few-shot, RAG-hybrid, custom-GPT, prompt-engineering)
      completes. Partitioned by tenant_id.
      Consumers: analytics-svc, wallet-svc, notify-svc, aibrain-svc.
    subscribe:
      summary: Subscribe to tenant trained events
      operationId: onRagTenantTrainedEvent
      message:
        $ref: '#/components/messages/TenantTrained'

components:
  messages:
    # Approval Events
    ApprovalRequested:
      name: ApprovalRequested
      title: Document Approval Requested
      summary: Triggered when a document submission requires governance approval.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ApprovalRequested'

    ApprovalCompleted:
      name: ApprovalCompleted
      title: Document Approval Completed
      summary: Triggered when a reviewer approves or rejects a document submission.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ApprovalCompleted'

    ApprovalExpired:
      name: ApprovalExpired
      title: Document Approval Expired
      summary: Triggered when an approval request expires without action.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ApprovalExpired'

    # Document Events
    DocumentIndexed:
      name: DocumentIndexed
      title: Document Successfully Indexed
      summary: Triggered when a new document is successfully processed and indexed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_DocumentIndexed'

    DocumentDeleted:
      name: DocumentDeleted
      title: Document Deleted
      summary: Triggered when a document is soft-deleted.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_DocumentDeleted'

    DocumentUpdated:
      name: DocumentUpdated
      title: Document Metadata Updated
      summary: Triggered when document metadata is updated.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_DocumentUpdated'

    DocumentEnriched:
      name: DocumentEnriched
      title: Document Enriched with Knowledge Graph
      summary: Triggered after KG enrichment completes for a document.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_DocumentEnriched'

    ChunksCreated:
      name: ChunksCreated
      title: Document Chunks Created
      summary: Triggered when chunks are created for a document.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ChunksCreated'

    MediaProcessingRequested:
      name: MediaProcessingRequested
      title: Media Processing Requested
      summary: Triggered when a vault media asset is queued for processing (OCR, transcription, visual embeddings).
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_MediaProcessingRequested'

    MediaProcessingCompleted:
      name: MediaProcessingCompleted
      title: Media Processing Completed
      summary: Triggered when media processing completes successfully.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_MediaProcessingCompleted'

    MediaProcessingFailed:
      name: MediaProcessingFailed
      title: Media Processing Failed
      summary: Triggered when media processing fails.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_MediaProcessingFailed'

    # Feedback Events
    FeedbackSubmitted:
      name: FeedbackSubmitted
      title: User Feedback Submitted
      summary: Triggered when a user submits feedback on search results or documents.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_FeedbackSubmitted'

    FeedbackProcessed:
      name: FeedbackProcessed
      title: Feedback Processed
      summary: Triggered when feedback is analyzed and triaged.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_FeedbackProcessed'

    QualityAlert:
      name: QualityAlert
      title: Quality Alert Triggered
      summary: Triggered when quality metrics exceed thresholds.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_QualityAlert'

    # Knowledge Gap Events
    KnowledgeGapIdentified:
      name: KnowledgeGapIdentified
      title: Knowledge Gap Identified
      summary: Triggered when analysis detects uncovered topics or frequent zero-result queries.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_KnowledgeGapIdentified'

    KnowledgeGapResolved:
      name: KnowledgeGapResolved
      title: Knowledge Gap Resolved
      summary: Triggered when a knowledge gap is addressed.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_KnowledgeGapResolved'

    CoverageReport:
      name: CoverageReport
      title: Knowledge Coverage Report Generated
      summary: Triggered on periodic coverage analysis (daily/weekly).
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_CoverageReport'

    # Search Events
    SearchExecuted:
      name: SearchExecuted
      title: Search Executed
      summary: Triggered after every search for analytics and learning.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_SearchExecuted'

    ZeroResults:
      name: ZeroResults
      title: Search Returned Zero Results
      summary: Triggered when a search returns no results - used for knowledge gap detection.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ZeroResults'

    SearchFeedback:
      name: SearchFeedback
      title: Search Result Feedback
      summary: Triggered when a user provides feedback on search results.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_SearchFeedback'

    AgenticSearchExecuted:
      name: AgenticSearchExecuted
      title: Agentic Search Executed
      summary: Triggered after multi-step agentic RAG search completes.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_AgenticSearchExecuted'

    # Tool Sync Events
    ToolsSyncStarted:
      name: ToolsSyncStarted
      title: Tool Synchronization Started
      summary: Triggered when a tool synchronization job begins.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ToolsSyncStarted'

    ToolsSynced:
      name: ToolsSynced
      title: Tools Successfully Synced
      summary: Triggered when tools are successfully synchronized from MCP/OpenAPI/GraphQL sources.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ToolsSynced'

    SyncFailed:
      name: SyncFailed
      title: Tool Synchronization Failed
      summary: Triggered when tool synchronization fails.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_SyncFailed'

    ToolRegistered:
      name: ToolRegistered
      title: Tool Registered
      summary: Triggered when a new MCP tool is registered.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ToolRegistered'

    ToolRemoved:
      name: ToolRemoved
      title: Tool Removed
      summary: Triggered when a tool is removed from the system.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_ToolRemoved'

    # Training Events
    TrainingStarted:
      name: TrainingStarted
      title: Parameter Training Started
      summary: Triggered when parameter tuning begins for a RAG profile.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_TrainingStarted'

    TrainingCompleted:
      name: TrainingCompleted
      title: Parameter Training Completed
      summary: Triggered when training finishes with optimal parameters.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_TrainingCompleted'

    TrainingFailed:
      name: TrainingFailed
      title: Parameter Training Failed
      summary: Triggered when training encounters an error.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_TrainingFailed'

    EvaluationCompleted:
      name: EvaluationCompleted
      title: Golden Set Evaluation Completed
      summary: Triggered after golden set evaluation completes.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_EvaluationCompleted'

    # Knowledge Updated Events
    KnowledgeUpdated:
      name: KnowledgeUpdated
      title: Knowledge Base Updated
      summary: Triggered when knowledge base content changes (document or chunk added, updated, or deleted).
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_KnowledgeUpdated'

    # Tenant Trained Events
    TenantTrained:
      name: TenantTrained
      title: Tenant RAG Training Completed
      summary: Triggered when tenant-specific RAG training completes with evaluation metrics.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/CloudEvent_TenantTrained'

  schemas:
    # CloudEvents Envelope
    CloudEvent_ApprovalRequested:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
          description: CloudEvents specification version
        type:
          type: string
          enum: ['rag.approval.requested']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
          description: Unique event identifier
        time:
          type: string
          format: date-time
          description: Event timestamp (ISO 8601)
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ApprovalRequestedData'

    CloudEvent_ApprovalCompleted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.approval.completed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ApprovalCompletedData'

    CloudEvent_ApprovalExpired:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.approval.expired']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ApprovalExpiredData'

    CloudEvent_DocumentIndexed:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.document.indexed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/DocumentIndexedData'

    CloudEvent_DocumentDeleted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.document.deleted']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/DocumentDeletedData'

    CloudEvent_DocumentUpdated:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.document.updated']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/DocumentUpdatedData'

    CloudEvent_DocumentEnriched:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.document.enriched']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/DocumentEnrichedData'

    CloudEvent_ChunksCreated:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.chunks.created']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ChunksCreatedData'

    CloudEvent_MediaProcessingRequested:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.media.processing.requested']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/MediaProcessingRequestedData'

    CloudEvent_MediaProcessingCompleted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.media.processing.completed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/MediaProcessingCompletedData'

    CloudEvent_MediaProcessingFailed:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.media.processing.failed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/MediaProcessingFailedData'

    CloudEvent_FeedbackSubmitted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.feedback.submitted']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/FeedbackSubmittedData'

    CloudEvent_FeedbackProcessed:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.feedback.processed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/FeedbackProcessedData'

    CloudEvent_QualityAlert:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.feedback.quality_alert']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/QualityAlertData'

    CloudEvent_KnowledgeGapIdentified:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.knowledge_gap.identified']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/KnowledgeGapIdentifiedData'

    CloudEvent_KnowledgeGapResolved:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.knowledge_gap.resolved']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/KnowledgeGapResolvedData'

    CloudEvent_CoverageReport:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.knowledge_gap.coverage_report']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/CoverageReportData'

    CloudEvent_SearchExecuted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.search.executed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/SearchExecutedData'

    CloudEvent_ZeroResults:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.search.zero_results']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ZeroResultsData'

    CloudEvent_SearchFeedback:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.search.feedback']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/SearchFeedbackData'

    CloudEvent_AgenticSearchExecuted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.agentic-search.executed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/AgenticSearchExecutedData'

    CloudEvent_ToolsSyncStarted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.tools.sync_started']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ToolsSyncStartedData'

    CloudEvent_ToolsSynced:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.tools.synced']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ToolsSyncedData'

    CloudEvent_SyncFailed:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.tools.sync_failed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/SyncFailedData'

    CloudEvent_ToolRegistered:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.tools.registered']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ToolRegisteredData'

    CloudEvent_ToolRemoved:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.tools.removed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/ToolRemovedData'

    CloudEvent_TrainingStarted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.training.started']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/TrainingStartedData'

    CloudEvent_TrainingCompleted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.training.completed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/TrainingCompletedData'

    CloudEvent_TrainingFailed:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.training.failed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/TrainingFailedData'

    CloudEvent_EvaluationCompleted:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['rag.training.evaluation_completed']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/EvaluationCompletedData'

    CloudEvent_KnowledgeUpdated:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['eventzr.rag.knowledge.updated.v1']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
          description: Unique event identifier
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/KnowledgeUpdatedData'

    CloudEvent_TenantTrained:
      type: object
      required:
        - specversion
        - type
        - source
        - id
        - time
        - datacontenttype
        - data
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          enum: ['eventzr.rag.tenant.trained.v1']
        source:
          type: string
          enum: ['rag-svc']
        id:
          type: string
          description: Unique event identifier
        time:
          type: string
          format: date-time
        datacontenttype:
          type: string
          enum: ['application/json']
        data:
          $ref: '#/components/schemas/TenantTrainedData'

    # Event Data Payloads
    ApprovalRequestedData:
      type: object
      required:
        - approvalId
        - tenantId
        - submittedBy
        - documentId
        - documentTitle
        - namespace
        - submissionType
        - requestedAt
      properties:
        approvalId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        submittedBy:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        documentTitle:
          type: string
        namespace:
          type: string
        submissionType:
          type: string
          enum: ['new', 'update', 'delete']
        requestedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        approverRoles:
          type: array
          items:
            type: string

    ApprovalCompletedData:
      type: object
      required:
        - approvalId
        - tenantId
        - documentId
        - status
        - reviewedBy
        - reviewedAt
        - processingTimeMs
      properties:
        approvalId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        status:
          type: string
          enum: ['approved', 'rejected', 'expired']
        reviewedBy:
          type: string
          format: uuid
        reviewedAt:
          type: string
          format: date-time
        comments:
          type: string
        processingTimeMs:
          type: integer

    ApprovalExpiredData:
      type: object
      required:
        - approvalId
        - tenantId
        - documentId
        - submittedBy
        - expiredAt
      properties:
        approvalId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        submittedBy:
          type: string
          format: uuid
        expiredAt:
          type: string
          format: date-time

    DocumentIndexedData:
      type: object
      required:
        - documentId
        - tenantId
        - namespace
        - title
        - mimeType
        - chunkCount
        - embeddingModel
        - processingTimeMs
      properties:
        documentId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        title:
          type: string
        mimeType:
          type: string
        chunkCount:
          type: integer
        embeddingModel:
          type: string
        processingTimeMs:
          type: integer
        metadata:
          type: object
          additionalProperties: true

    DocumentDeletedData:
      type: object
      required:
        - documentId
        - tenantId
        - namespace
        - deletedBy
      properties:
        documentId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        deletedBy:
          type: string
          format: uuid
        reason:
          type: string

    DocumentUpdatedData:
      type: object
      required:
        - documentId
        - tenantId
        - updates
      properties:
        documentId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        updates:
          type: object
          additionalProperties: true

    DocumentEnrichedData:
      type: object
      required:
        - documentId
        - tenantId
        - entityCount
        - taxonomyCodeCount
        - edgesCreated
        - processingTimeMs
      properties:
        documentId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        entityCount:
          type: integer
        taxonomyCodeCount:
          type: integer
        edgesCreated:
          type: integer
        processingTimeMs:
          type: integer

    ChunksCreatedData:
      type: object
      required:
        - documentId
        - tenantId
        - chunkCount
        - strategy
      properties:
        documentId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        chunkCount:
          type: integer
        strategy:
          type: string

    MediaProcessingRequestedData:
      type: object
      required:
        - assetId
        - vaultAssetId
        - tenantId
        - namespace
        - mediaType
        - options
        - requestedAt
      properties:
        assetId:
          type: string
          format: uuid
        vaultAssetId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        mediaType:
          type: string
        options:
          type: object
          required:
            - performOcr
            - generateVisualEmbedding
            - transcribeAudio
          properties:
            performOcr:
              type: boolean
            generateVisualEmbedding:
              type: boolean
            transcribeAudio:
              type: boolean
        requestedAt:
          type: string
          format: date-time

    MediaProcessingCompletedData:
      type: object
      required:
        - assetId
        - vaultAssetId
        - tenantId
        - namespace
        - mediaType
        - hasOcr
        - hasVisualEmbedding
        - hasTranscription
        - processingCostUsd
        - completedAt
      properties:
        assetId:
          type: string
          format: uuid
        vaultAssetId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        mediaType:
          type: string
        hasOcr:
          type: boolean
        hasVisualEmbedding:
          type: boolean
        hasTranscription:
          type: boolean
        processingCostUsd:
          type: number
          format: double
        completedAt:
          type: string
          format: date-time

    MediaProcessingFailedData:
      type: object
      required:
        - assetId
        - vaultAssetId
        - tenantId
        - error
        - failedAt
      properties:
        assetId:
          type: string
          format: uuid
        vaultAssetId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        error:
          type: string
        failedAt:
          type: string
          format: date-time

    FeedbackSubmittedData:
      type: object
      required:
        - feedbackId
        - tenantId
        - userId
        - feedbackType
        - submittedAt
      properties:
        feedbackId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        searchId:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        chunkId:
          type: string
          format: uuid
        feedbackType:
          type: string
          enum:
            [
              'helpful',
              'not_helpful',
              'irrelevant',
              'outdated',
              'incorrect',
              'missing_info',
              'hallucination',
            ]
        rating:
          type: integer
          minimum: 1
          maximum: 5
        comment:
          type: string
        context:
          type: object
          properties:
            query:
              type: string
            responseSnippet:
              type: string
        submittedAt:
          type: string
          format: date-time

    FeedbackProcessedData:
      type: object
      required:
        - feedbackId
        - tenantId
        - action
        - processedAt
      properties:
        feedbackId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        action:
          type: string
          enum: ['none', 'flagged', 'escalated', 'auto_corrected']
        reason:
          type: string
        processedAt:
          type: string
          format: date-time

    QualityAlertData:
      type: object
      required:
        - alertId
        - tenantId
        - alertType
        - severity
        - affectedDocuments
        - threshold
        - currentValue
        - message
        - triggeredAt
      properties:
        alertId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        alertType:
          type: string
          enum: ['high_negative_feedback', 'accuracy_drop', 'hallucination_detected']
        severity:
          type: string
          enum: ['low', 'medium', 'high', 'critical']
        affectedDocuments:
          type: array
          items:
            type: string
            format: uuid
        threshold:
          type: number
        currentValue:
          type: number
        message:
          type: string
        triggeredAt:
          type: string
          format: date-time

    KnowledgeGapIdentifiedData:
      type: object
      required:
        - gapId
        - tenantId
        - namespace
        - topic
        - description
        - severity
        - frequency
        - relatedQueries
        - identifiedAt
        - autoDetected
      properties:
        gapId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        topic:
          type: string
        description:
          type: string
        severity:
          type: string
          enum: ['low', 'medium', 'high', 'critical']
        frequency:
          type: integer
        relatedQueries:
          type: array
          items:
            type: string
        suggestedSources:
          type: array
          items:
            type: string
        identifiedAt:
          type: string
          format: date-time
        autoDetected:
          type: boolean

    KnowledgeGapResolvedData:
      type: object
      required:
        - gapId
        - tenantId
        - namespace
        - topic
        - resolution
        - resolvedBy
        - resolvedAt
        - daysOpen
      properties:
        gapId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        topic:
          type: string
        resolution:
          type: string
          enum: ['document_added', 'document_updated', 'scope_adjusted', 'false_positive']
        resolvedBy:
          type: string
          format: uuid
        documentIds:
          type: array
          items:
            type: string
            format: uuid
        resolvedAt:
          type: string
          format: date-time
        daysOpen:
          type: integer

    CoverageReportData:
      type: object
      required:
        - reportId
        - tenantId
        - namespace
        - period
        - metrics
        - topUncoveredTopics
        - generatedAt
      properties:
        reportId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        namespace:
          type: string
        period:
          type: object
          required:
            - start
            - end
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
        metrics:
          type: object
          required:
            - totalQueries
            - successfulQueries
            - zeroResultQueries
            - coveragePercent
            - newGapsIdentified
            - gapsResolved
            - openGaps
          properties:
            totalQueries:
              type: integer
            successfulQueries:
              type: integer
            zeroResultQueries:
              type: integer
            coveragePercent:
              type: number
              format: double
            newGapsIdentified:
              type: integer
            gapsResolved:
              type: integer
            openGaps:
              type: integer
        topUncoveredTopics:
          type: array
          items:
            type: object
            required:
              - topic
              - frequency
              - severity
            properties:
              topic:
                type: string
              frequency:
                type: integer
              severity:
                type: string
                enum: ['low', 'medium', 'high', 'critical']
        generatedAt:
          type: string
          format: date-time

    SearchExecutedData:
      type: object
      required:
        - searchId
        - tenantId
        - userId
        - query
        - namespace
        - searchType
        - resultCount
        - topDocumentIds
        - latencyMs
      properties:
        searchId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        query:
          type: string
        namespace:
          type: string
        searchType:
          type: string
          enum: ['hybrid', 'semantic', 'keyword', 'conversational']
        resultCount:
          type: integer
        topDocumentIds:
          type: array
          items:
            type: string
            format: uuid
        latencyMs:
          type: integer
        embeddingModel:
          type: string
        filters:
          type: object
          additionalProperties: true

    ZeroResultsData:
      type: object
      required:
        - searchId
        - tenantId
        - userId
        - query
        - namespace
        - searchType
      properties:
        searchId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        query:
          type: string
        namespace:
          type: string
        searchType:
          type: string
          enum: ['hybrid', 'semantic', 'keyword', 'conversational']
        expandedQueries:
          type: array
          items:
            type: string
        filters:
          type: object
          additionalProperties: true

    SearchFeedbackData:
      type: object
      required:
        - searchId
        - tenantId
        - userId
        - documentId
        - feedbackType
      properties:
        searchId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        documentId:
          type: string
          format: uuid
        feedbackType:
          type: string
          enum: ['helpful', 'not_helpful', 'irrelevant', 'outdated']
        comment:
          type: string

    AgenticSearchExecutedData:
      type: object
      required:
        - searchId
        - tenantId
        - userId
        - query
        - totalSteps
        - finalConfidence
        - creditsCost
        - resultCount
        - strategiesAttempted
        - graphLookupUsed
        - totalLatencyMs
        - steps
      properties:
        searchId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
        query:
          type: string
        namespace:
          type: string
        totalSteps:
          type: integer
        finalConfidence:
          type: number
          format: double
        creditsCost:
          type: number
          format: double
        resultCount:
          type: integer
        strategiesAttempted:
          type: array
          items:
            type: string
        graphLookupUsed:
          type: boolean
        totalLatencyMs:
          type: integer
        steps:
          type: array
          items:
            type: object
            required:
              - stepNumber
              - action
              - confidenceScore
              - latencyMs
            properties:
              stepNumber:
                type: integer
              action:
                type: string
              confidenceScore:
                type: number
                format: double
              latencyMs:
                type: integer

    ToolsSyncStartedData:
      type: object
      required:
        - syncJobId
        - tenantId
        - subscriberId
        - source
        - initiatedBy
        - startedAt
      properties:
        syncJobId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        subscriberId:
          type: string
          format: uuid
        source:
          type: string
          enum: ['mcp', 'openapi', 'graphql', 'custom']
        sourceUrl:
          type: string
        initiatedBy:
          type: string
          format: uuid
        startedAt:
          type: string
          format: date-time

    ToolsSyncedData:
      type: object
      required:
        - syncJobId
        - tenantId
        - subscriberId
        - source
        - toolsAdded
        - toolsUpdated
        - toolsRemoved
        - totalTools
        - durationMs
        - syncedAt
      properties:
        syncJobId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        subscriberId:
          type: string
          format: uuid
        source:
          type: string
          enum: ['mcp', 'openapi', 'graphql', 'custom']
        toolsAdded:
          type: integer
        toolsUpdated:
          type: integer
        toolsRemoved:
          type: integer
        totalTools:
          type: integer
        durationMs:
          type: integer
        syncedAt:
          type: string
          format: date-time

    SyncFailedData:
      type: object
      required:
        - syncJobId
        - tenantId
        - subscriberId
        - source
        - error
        - failedAt
        - retryCount
      properties:
        syncJobId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        subscriberId:
          type: string
          format: uuid
        source:
          type: string
          enum: ['mcp', 'openapi', 'graphql', 'custom']
        error:
          type: string
        failedAt:
          type: string
          format: date-time
        retryCount:
          type: integer

    ToolRegisteredData:
      type: object
      required:
        - toolId
        - tenantId
        - subscriberId
        - toolName
        - toolType
        - source
        - registeredAt
      properties:
        toolId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        subscriberId:
          type: string
          format: uuid
        toolName:
          type: string
        toolType:
          type: string
        source:
          type: string
          enum: ['mcp', 'openapi', 'graphql', 'custom']
        description:
          type: string
        registeredAt:
          type: string
          format: date-time

    ToolRemovedData:
      type: object
      required:
        - toolId
        - tenantId
        - subscriberId
        - toolName
        - reason
        - removedBy
        - removedAt
      properties:
        toolId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        subscriberId:
          type: string
          format: uuid
        toolName:
          type: string
        reason:
          type: string
          enum: ['manual', 'sync_cleanup', 'deprecation']
        removedBy:
          type: string
          format: uuid
        removedAt:
          type: string
          format: date-time

    TrainingStartedData:
      type: object
      required:
        - trainingId
        - tenantId
        - initiatedBy
        - profileId
        - method
        - parameters
        - startedAt
      properties:
        trainingId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        initiatedBy:
          type: string
          format: uuid
        profileId:
          type: string
          format: uuid
        method:
          type: string
          enum: ['grid_search', 'bandit', 'whatsapp_session', 'manual']
        goldenSetId:
          type: string
          format: uuid
        parameters:
          type: object
          additionalProperties: true
        startedAt:
          type: string
          format: date-time

    TrainingCompletedData:
      type: object
      required:
        - trainingId
        - tenantId
        - profileId
        - method
        - bestScore
        - bestParameters
        - iterationsRun
        - improvementPercent
        - durationMs
        - completedAt
      properties:
        trainingId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        profileId:
          type: string
          format: uuid
        method:
          type: string
          enum: ['grid_search', 'bandit', 'whatsapp_session', 'manual']
        bestScore:
          type: number
          format: double
        bestParameters:
          type: object
          additionalProperties: true
        iterationsRun:
          type: integer
        improvementPercent:
          type: number
          format: double
        durationMs:
          type: integer
        completedAt:
          type: string
          format: date-time

    TrainingFailedData:
      type: object
      required:
        - trainingId
        - tenantId
        - profileId
        - method
        - error
        - failedAt
        - iterationsCompleted
      properties:
        trainingId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        profileId:
          type: string
          format: uuid
        method:
          type: string
          enum: ['grid_search', 'bandit', 'whatsapp_session', 'manual']
        error:
          type: string
        failedAt:
          type: string
          format: date-time
        iterationsCompleted:
          type: integer

    EvaluationCompletedData:
      type: object
      required:
        - evaluationId
        - tenantId
        - profileId
        - goldenSetId
        - metrics
        - sampleSize
        - durationMs
      properties:
        evaluationId:
          type: string
          format: uuid
        tenantId:
          type: string
          format: uuid
        profileId:
          type: string
          format: uuid
        goldenSetId:
          type: string
          format: uuid
        metrics:
          type: object
          required:
            - precision
            - recall
            - f1Score
            - ndcg
            - mrr
          properties:
            precision:
              type: number
              format: double
            recall:
              type: number
              format: double
            f1Score:
              type: number
              format: double
            ndcg:
              type: number
              format: double
            mrr:
              type: number
              format: double
        sampleSize:
          type: integer
        durationMs:
          type: integer

    KnowledgeUpdatedData:
      type: object
      required:
        - namespaceId
        - documentId
        - updateType
        - tenantId
      properties:
        namespaceId:
          type: string
          description: Knowledge base namespace identifier
        documentId:
          type: string
          description: Document that was changed
        updateType:
          type: string
          enum:
            - document_added
            - document_updated
            - document_deleted
            - chunk_added
            - chunk_updated
            - chunk_deleted
          description: Type of knowledge base change
        chunkCount:
          type: integer
          description: Number of chunks affected (optional)
        embeddingModel:
          type: string
          description: Embedding model used (optional)
        tenantId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
          description: User who triggered the update (optional)
        metadata:
          type: object
          additionalProperties: true
          description: Additional context about the update

    TenantTrainedData:
      type: object
      required:
        - tenantId
        - specializationId
        - trainingJobId
        - trainingStrategy
        - evaluationMetrics
        - trainingDurationMs
        - costUsd
      properties:
        tenantId:
          type: string
          format: uuid
        specializationId:
          type: string
          description: Specialization profile identifier
        trainingJobId:
          type: string
          description: Training job identifier
        trainingStrategy:
          type: string
          enum:
            - fine-tuning
            - few-shot
            - rag-hybrid
            - custom-gpt
            - prompt-engineering
          description: Training strategy used
        evaluationMetrics:
          type: object
          properties:
            ndcg5:
              type: number
              format: double
              description: Normalized Discounted Cumulative Gain at position 5
            mrr:
              type: number
              format: double
              description: Mean Reciprocal Rank
            map:
              type: number
              format: double
              description: Mean Average Precision
            faithfulness:
              type: number
              format: double
              description: RAGAS faithfulness score
            answerRelevancy:
              type: number
              format: double
              description: RAGAS answer relevancy score
            contextPrecision:
              type: number
              format: double
              description: RAGAS context precision score
            contextRecall:
              type: number
              format: double
              description: RAGAS context recall score
        trainingDurationMs:
          type: integer
          description: Training duration in milliseconds
        costUsd:
          type: number
          format: double
          description: Training cost in USD
        documentCount:
          type: integer
          description: Number of documents used for training (optional)
        goldenSetSize:
          type: integer
          description: Size of the golden evaluation set (optional)
        userId:
          type: string
          format: uuid
          description: User who initiated training (optional)
        metadata:
          type: object
          additionalProperties: true
          description: Additional training context

  securitySchemes:
    saslIam:
      type: plain
      description: AWS MSK IAM authentication
