asyncapi: 2.6.0

info:
  title: eventml-svc Kafka Events
  version: 1.0.0
  description: |
    AsyncAPI specification for the eventml-svc (ML Model Management) service.
    All events use the CloudEvents 1.0 envelope and are partitioned by tenant_id.
  contact:
    name: EventZR Platform Team
  license:
    name: UNLICENSED

servers:
  staging:
    url: boot-gpm4u49z.c2.kafka-serverless.us-east-1.amazonaws.com:9098
    protocol: kafka-secure
    description: Amazon MSK Serverless (staging)

defaultContentType: application/cloudevents+json

channels:
  # ---------------------------------------------------------------------------
  # PRODUCED TOPICS (21)
  # ---------------------------------------------------------------------------

  eventzr.ml.model-registered:
    description: Emitted when a new ML model is registered in the model registry.
    publish:
      operationId: publishModelRegistered
      message:
        name: ModelRegistered
        title: Model Registered
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.model-registered.v1
            ce_source:
              type: string
              const: eventml-svc
            ce_specversion:
              type: string
              const: '1.0'
            ce_partitionkey:
              type: string
              description: tenant_id used as Kafka partition key
        payload:
          type: object
          required:
            - modelId
            - modelName
            - framework
            - frameworkVersion
          properties:
            modelId:
              type: string
              format: uuid
            modelName:
              type: string
            framework:
              type: string
              description: ML framework (e.g. pytorch, tensorflow, sklearn)
            frameworkVersion:
              type: string
            description:
              type: string
            tags:
              type: array
              items:
                type: string

  eventzr.ml.model-version-created:
    description: Emitted when a new version of a model is created.
    publish:
      operationId: publishModelVersionCreated
      message:
        name: ModelVersionCreated
        title: Model Version Created
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.model-version-created.v1
        payload:
          type: object
          required:
            - versionId
            - modelId
            - version
            - status
          properties:
            versionId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            version:
              type: string
            runId:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - pending
                - ready
                - failed
            metrics:
              type: object
              additionalProperties: true

  eventzr.ml.model-promoted:
    description: Emitted when a model is promoted from one stage to another.
    publish:
      operationId: publishModelPromoted
      message:
        name: ModelPromoted
        title: Model Promoted
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.model-promoted.v1
        payload:
          type: object
          required:
            - tenantId
            - modelId
            - fromStage
            - toStage
            - promotedAt
          properties:
            tenantId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            versionId:
              type: string
              format: uuid
            fromStage:
              type: string
              enum:
                - none
                - staging
                - canary
                - production
                - archived
            toStage:
              type: string
              enum:
                - none
                - staging
                - canary
                - production
                - archived
            promotedAt:
              type: string
              format: date-time

  eventzr.ml.training-started:
    description: Emitted when a model training job begins.
    publish:
      operationId: publishTrainingStarted
      message:
        name: TrainingStarted
        title: Training Started
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.training-started.v1
        payload:
          type: object
          required:
            - modelId
            - modelName
            - algorithm
            - startedAt
          properties:
            modelId:
              type: string
              format: uuid
            modelName:
              type: string
            algorithm:
              type: string
            hyperparameters:
              type: object
              additionalProperties: true
            datasetUri:
              type: string
              format: uri
            estimatedDuration:
              type: integer
              description: Estimated duration in seconds
            startedAt:
              type: string
              format: date-time

  eventzr.ml.training-completed:
    description: Emitted when a model training job completes successfully.
    publish:
      operationId: publishTrainingCompleted
      message:
        name: TrainingCompleted
        title: Training Completed
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.training-completed.v1
        payload:
          type: object
          required:
            - tenantId
            - jobId
            - metrics
            - artifactUri
            - completedAt
          properties:
            tenantId:
              type: string
              format: uuid
            jobId:
              type: string
              format: uuid
            metrics:
              type: object
              additionalProperties: true
              description: Training metrics (accuracy, loss, etc.)
            artifactUri:
              type: string
              format: uri
            duration:
              type: integer
              description: Actual duration in seconds
            completedAt:
              type: string
              format: date-time

  eventzr.ml.training-failed:
    description: Emitted when a model training job fails.
    publish:
      operationId: publishTrainingFailed
      message:
        name: TrainingFailed
        title: Training Failed
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.training-failed.v1
        payload:
          type: object
          required:
            - tenantId
            - jobId
            - error
            - failedAt
          properties:
            tenantId:
              type: string
              format: uuid
            jobId:
              type: string
              format: uuid
            error:
              type: object
              required:
                - code
                - message
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type: string
                stackTrace:
                  type: string
            duration:
              type: integer
              description: Duration in seconds before failure
            failedAt:
              type: string
              format: date-time

  eventzr.ml.endpoint-deployed:
    description: Emitted when a model endpoint is deployed for inference.
    publish:
      operationId: publishEndpointDeployed
      message:
        name: EndpointDeployed
        title: Endpoint Deployed
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.endpoint-deployed.v1
        payload:
          type: object
          required:
            - endpointName
            - modelId
            - deployedAt
          properties:
            endpointName:
              type: string
            modelId:
              type: string
              format: uuid
            modelVersionId:
              type: string
              format: uuid
            instanceType:
              type: string
              description: Compute instance type (e.g. ml.m5.large)
            instanceCount:
              type: integer
              minimum: 1
            autoScaling:
              type: boolean
            endpointUrl:
              type: string
              format: uri
            deployedAt:
              type: string
              format: date-time

  eventzr.ml.endpoint-deleted:
    description: Emitted when a model endpoint is deleted.
    publish:
      operationId: publishEndpointDeleted
      message:
        name: EndpointDeleted
        title: Endpoint Deleted
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.endpoint-deleted.v1
        payload:
          type: object
          required:
            - tenantId
            - endpointId
            - endpointName
            - deletedAt
          properties:
            tenantId:
              type: string
              format: uuid
            endpointId:
              type: string
              format: uuid
            endpointName:
              type: string
            deletedAt:
              type: string
              format: date-time

  eventzr.ml.inference-completed:
    description: Emitted after each model inference request completes.
    publish:
      operationId: publishInferenceCompleted
      message:
        name: InferenceCompleted
        title: Inference Completed
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.inference-completed.v1
        payload:
          type: object
          required:
            - tenantId
            - requestId
            - endpointId
            - latency
            - completedAt
          properties:
            tenantId:
              type: string
              format: uuid
            requestId:
              type: string
              format: uuid
            endpointId:
              type: string
              format: uuid
            latency:
              type: number
              description: Inference latency in milliseconds
            inputSize:
              type: integer
              description: Input payload size in bytes
            outputSize:
              type: integer
              description: Output payload size in bytes
            completedAt:
              type: string
              format: date-time

  eventzr.ml.experiment-started:
    description: Emitted when an A/B experiment begins.
    publish:
      operationId: publishExperimentStarted
      message:
        name: ExperimentStarted
        title: Experiment Started
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.experiment-started.v1
        payload:
          type: object
          required:
            - experimentName
            - variants
            - successMetric
            - startedAt
          properties:
            experimentName:
              type: string
            description:
              type: string
            variants:
              type: array
              items:
                type: object
                additionalProperties: true
              description: Experiment variant definitions
            successMetric:
              type: string
            duration:
              type: integer
              description: Planned experiment duration in seconds
            sampleSize:
              type: integer
              description: Target sample size per variant
            startedAt:
              type: string
              format: date-time

  eventzr.ml.experiment-concluded:
    description: Emitted when an A/B experiment is concluded with results.
    publish:
      operationId: publishExperimentConcluded
      message:
        name: ExperimentConcluded
        title: Experiment Concluded
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.experiment-concluded.v1
        payload:
          type: object
          required:
            - tenantId
            - experimentId
            - analysis
            - concludedAt
          properties:
            tenantId:
              type: string
              format: uuid
            experimentId:
              type: string
              format: uuid
            winner:
              type: string
              description: Winning variant identifier (null if inconclusive)
            analysis:
              type: object
              additionalProperties: true
              description: Statistical analysis results
            concludedAt:
              type: string
              format: date-time

  eventzr.ml.drift-detected:
    description: Emitted when model or data drift is detected by a monitor.
    publish:
      operationId: publishDriftDetected
      message:
        name: DriftDetected
        title: Drift Detected
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.drift-detected.v1
        payload:
          type: object
          required:
            - tenantId
            - modelId
            - driftType
            - severity
            - metrics
            - detectedAt
          properties:
            tenantId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            endpointId:
              type: string
              format: uuid
            driftType:
              type: string
              enum:
                - data
                - concept
                - prediction
                - feature
            severity:
              type: string
              enum:
                - low
                - medium
                - high
                - critical
            metrics:
              type: object
              additionalProperties: true
              description: Drift metrics and scores
            detectedAt:
              type: string
              format: date-time

  eventzr.ml.drift-alert:
    description: Emitted as an actionable alert when drift exceeds thresholds.
    publish:
      operationId: publishDriftAlert
      message:
        name: DriftAlert
        title: Drift Alert
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.ml.drift-alert.v1
        payload:
          type: object
          required:
            - modelId
            - driftType
            - severity
            - message
            - recommendedActions
            - alertedAt
          properties:
            modelId:
              type: string
              format: uuid
            driftType:
              type: string
              enum:
                - data
                - concept
                - prediction
                - feature
            severity:
              type: string
              enum:
                - low
                - medium
                - high
                - critical
            message:
              type: string
            recommendedActions:
              type: array
              items:
                type: string
            affectedFeatures:
              type: array
              items:
                type: string
            alertedAt:
              type: string
              format: date-time

  eventzr.eventml.feature.materialized.v1:
    description: Emitted when a feature group materialization job completes.
    publish:
      operationId: publishFeatureMaterialized
      message:
        name: FeatureMaterialized
        title: Feature Materialized
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.feature.materialized.v1
        payload:
          type: object
          required:
            - featureGroupId
            - featureGroupName
            - tenantId
            - rowsProcessed
            - startDate
            - endDate
            - durationMs
            - status
          properties:
            featureGroupId:
              type: string
              format: uuid
            featureGroupName:
              type: string
            tenantId:
              type: string
              format: uuid
            rowsProcessed:
              type: integer
            startDate:
              type: string
              format: date-time
            endDate:
              type: string
              format: date-time
            durationMs:
              type: integer
              description: Materialization duration in milliseconds
            status:
              type: string
              enum:
                - success
                - partial
                - failed
            errorMessage:
              type: string

  eventzr.eventml.feature.freshness-alert.v1:
    description: Emitted when a feature group exceeds its freshness threshold.
    publish:
      operationId: publishFeatureFreshnessAlert
      message:
        name: FeatureFreshnessAlert
        title: Feature Freshness Alert
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.feature.freshness-alert.v1
        payload:
          type: object
          required:
            - featureGroupId
            - featureGroupName
            - tenantId
            - lastMaterializedAt
            - thresholdMinutes
            - currentAgeMinutes
            - severity
          properties:
            featureGroupId:
              type: string
              format: uuid
            featureGroupName:
              type: string
            tenantId:
              type: string
              format: uuid
            lastMaterializedAt:
              type: string
              format: date-time
            thresholdMinutes:
              type: integer
            currentAgeMinutes:
              type: integer
            severity:
              type: string
              enum:
                - warning
                - critical

  eventzr.eventml.retrain.started.v1:
    description: Emitted when an automatic retrain pipeline is triggered.
    publish:
      operationId: publishRetrainStarted
      message:
        name: RetrainStarted
        title: Retrain Started
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.retrain.started.v1
        payload:
          type: object
          required:
            - tenantId
            - retrainJobId
            - modelId
            - triggerType
          properties:
            tenantId:
              type: string
              format: uuid
            retrainJobId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            triggerType:
              type: string
              enum:
                - drift
                - scheduled
                - manual
            driftMonitorId:
              type: string
              format: uuid
            driftReportId:
              type: string
              format: uuid

  eventzr.eventml.retrain.training-complete.v1:
    description: Emitted when the training phase of a retrain pipeline completes.
    publish:
      operationId: publishRetrainTrainingComplete
      message:
        name: RetrainTrainingComplete
        title: Retrain Training Complete
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.retrain.training-complete.v1
        payload:
          type: object
          required:
            - tenantId
            - retrainJobId
            - trainingJobId
            - modelId
            - modelVersionId
            - metrics
            - validationPassed
          properties:
            tenantId:
              type: string
              format: uuid
            retrainJobId:
              type: string
              format: uuid
            trainingJobId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            modelVersionId:
              type: string
              format: uuid
            metrics:
              type: object
              additionalProperties: true
            validationPassed:
              type: boolean

  eventzr.eventml.retrain.canary-started.v1:
    description: Emitted when a canary deployment begins for a retrained model.
    publish:
      operationId: publishRetrainCanaryStarted
      message:
        name: RetrainCanaryStarted
        title: Retrain Canary Started
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.retrain.canary-started.v1
        payload:
          type: object
          required:
            - tenantId
            - retrainJobId
            - deploymentId
            - modelVersionId
            - canaryPercentage
            - validationWindowMinutes
          properties:
            tenantId:
              type: string
              format: uuid
            retrainJobId:
              type: string
              format: uuid
            deploymentId:
              type: string
              format: uuid
            modelVersionId:
              type: string
              format: uuid
            canaryPercentage:
              type: number
              minimum: 0
              maximum: 100
            validationWindowMinutes:
              type: integer

  eventzr.eventml.retrain.promoted.v1:
    description: Emitted when a retrained model is promoted to full production traffic.
    publish:
      operationId: publishRetrainPromoted
      message:
        name: RetrainPromoted
        title: Retrain Promoted
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.retrain.promoted.v1
        payload:
          type: object
          required:
            - tenantId
            - retrainJobId
            - modelVersionId
            - oldVersionId
            - canaryMetrics
            - productionMetrics
          properties:
            tenantId:
              type: string
              format: uuid
            retrainJobId:
              type: string
              format: uuid
            modelVersionId:
              type: string
              format: uuid
            oldVersionId:
              type: string
              format: uuid
            canaryMetrics:
              type: object
              additionalProperties: true
            productionMetrics:
              type: object
              additionalProperties: true

  eventzr.eventml.retrain.rolled-back.v1:
    description: Emitted when a retrained model canary is rolled back.
    publish:
      operationId: publishRetrainRolledBack
      message:
        name: RetrainRolledBack
        title: Retrain Rolled Back
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.retrain.rolled-back.v1
        payload:
          type: object
          required:
            - tenantId
            - retrainJobId
            - reason
          properties:
            tenantId:
              type: string
              format: uuid
            retrainJobId:
              type: string
              format: uuid
            reason:
              type: string
            canaryMetrics:
              type: object
              additionalProperties: true
            validationResults:
              type: object
              additionalProperties: true

  eventzr.eventml.shadow.completed.v1:
    description: Emitted when a shadow deployment comparison run completes.
    publish:
      operationId: publishShadowCompleted
      message:
        name: ShadowCompleted
        title: Shadow Deployment Completed
        headers:
          type: object
          properties:
            ce_type:
              type: string
              const: com.eventzr.eventml.shadow.completed.v1
        payload:
          type: object
          required:
            - tenantId
            - shadowDeploymentId
            - productionModelVersionId
            - shadowModelVersionId
            - totalPredictions
            - agreementRate
            - recommendation
            - comparisonResults
          properties:
            tenantId:
              type: string
              format: uuid
            shadowDeploymentId:
              type: string
              format: uuid
            productionModelVersionId:
              type: string
              format: uuid
            shadowModelVersionId:
              type: string
              format: uuid
            totalPredictions:
              type: integer
            agreementRate:
              type: number
              minimum: 0
              maximum: 1
              description: Fraction of predictions where shadow agreed with production
            recommendation:
              type: string
              enum:
                - promote
                - extend
                - reject
            comparisonResults:
              type: object
              additionalProperties: true

  # ---------------------------------------------------------------------------
  # CONSUMED TOPICS (5)
  # ---------------------------------------------------------------------------

  eventzr.aibrain.ml-commands:
    description: ML command requests from aibrain-svc (train, deploy, evaluate, etc.).
    subscribe:
      operationId: consumeMLCommands
      bindings:
        kafka:
          groupId: eventml-svc-ml-commands
      message:
        name: MLCommand
        title: ML Command
        payload:
          type: object
          required:
            - commandType
            - tenantId
          properties:
            commandType:
              type: string
              enum:
                - train
                - deploy
                - evaluate
                - predict
                - retrain
                - undeploy
            tenantId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            modelName:
              type: string
            parameters:
              type: object
              additionalProperties: true
            requestedBy:
              type: string
              format: uuid

  eventzr.analytics.dataset-ready:
    description: Notification from analytics-svc that a dataset is prepared and available.
    subscribe:
      operationId: consumeDatasetReady
      bindings:
        kafka:
          groupId: eventml-svc-dataset-ready
      message:
        name: DatasetReady
        title: Dataset Ready
        payload:
          type: object
          required:
            - tenantId
            - datasetId
            - datasetName
            - datasetUri
            - datasetType
            - format
            - timestamp
          properties:
            tenantId:
              type: string
              format: uuid
            datasetId:
              type: string
              format: uuid
            datasetName:
              type: string
            datasetUri:
              type: string
              format: uri
            datasetType:
              type: string
              enum:
                - training
                - validation
                - test
                - inference
            format:
              type: string
              enum:
                - csv
                - parquet
                - json
                - avro
            rowCount:
              type: integer
            columnCount:
              type: integer
            sizeBytes:
              type: integer
            metadata:
              type: object
              additionalProperties: true
            preparedFor:
              type: string
              description: Model or experiment this dataset was prepared for
            timestamp:
              type: string
              format: date-time

  eventzr.analytics.feature-updates:
    description: Real-time feature updates from analytics-svc for online feature store ingestion.
    subscribe:
      operationId: consumeFeatureUpdates
      bindings:
        kafka:
          groupId: eventml-svc-feature-updates
      message:
        name: FeatureUpdate
        title: Feature Update
        payload:
          type: object
          required:
            - tenantId
            - entityId
            - entityType
            - features
            - timestamp
          properties:
            tenantId:
              type: string
              format: uuid
            entityId:
              type: string
              format: uuid
            entityType:
              type: string
              description: Entity type (e.g. user, event, venue)
            features:
              type: object
              additionalProperties: true
              description: Key-value map of feature names to values
            timestamp:
              type: string
              format: date-time
            version:
              type: integer
              description: Feature schema version for backward compatibility

  eventzr.eventml.drift.detected.v1:
    description: |
      Internal drift detection event consumed by the retrain pipeline to
      trigger automatic retraining when drift severity exceeds thresholds.
    subscribe:
      operationId: consumeDriftDetected
      bindings:
        kafka:
          groupId: eventml-retrain-group
      message:
        name: DriftDetectedInternal
        title: Drift Detected (Retrain Trigger)
        payload:
          type: object
          required:
            - tenantId
            - monitorId
            - reportId
            - modelId
            - severity
            - driftScore
            - driftType
            - timestamp
          properties:
            tenantId:
              type: string
              format: uuid
            monitorId:
              type: string
              format: uuid
            reportId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            severity:
              type: string
              enum:
                - low
                - medium
                - high
                - critical
            driftScore:
              type: number
              minimum: 0
              maximum: 1
            driftType:
              type: string
              enum:
                - data
                - concept
                - prediction
                - feature
            timestamp:
              type: string
              format: date-time

  eventzr.events.prediction-request:
    description: Inference prediction requests from other services.
    subscribe:
      operationId: consumePredictionRequest
      bindings:
        kafka:
          groupId: eventml-svc-prediction-requests
      message:
        name: PredictionRequest
        title: Prediction Request
        payload:
          type: object
          required:
            - tenantId
            - requestId
            - modelId
            - input
            - options
            - timestamp
          properties:
            tenantId:
              type: string
              format: uuid
            requestId:
              type: string
              format: uuid
            modelId:
              type: string
              format: uuid
            endpointId:
              type: string
              format: uuid
            input:
              type: object
              additionalProperties: true
              description: Model input payload
            features:
              type: object
              additionalProperties: true
              description: Pre-computed features to supplement input
            options:
              type: object
              additionalProperties: true
              description: Inference options (timeout, format, explain, etc.)
            callbackTopic:
              type: string
              description: Kafka topic to publish the prediction result to
            requestedBy:
              type: string
              format: uuid
            timestamp:
              type: string
              format: date-time
