Execute

Run one hybrid ML and rules simulation step

Steps the simulation using the Hybrid Prediction Engine, which blends a deterministic rule-based simulation with a simulated ML-based prediction. The engine uses a confidence threshold to decide how much weight to give each path, and falls back to pure rules when ML confidence is low.

Returns the updated simulation state, step metrics, events, the hybrid decision record (including ML confidence and blending rationale), and the updated cumulative hybrid result object.

Requires write scope and ownership.

post/simulations/{simulationId}/step-hybrid

Request

  • Base URL: https://www.cloudworldmodel.ai/api
  • URL: https://www.cloudworldmodel.ai/api/simulations/{simulationId}/step-hybrid
  • Auth: one of:
    • HTTP bearer
    • API key in header X-PAYMENT
    • API key in header PAYMENT-SIGNATURE

Path parameters

simulationIdstring required

Simulation UUID

Request body

stepsinteger

Number of time steps to advance in a single call (1–500, default 1). Each sub-step evaluates traffic patterns at the correct elapsed time, so a ramp or wave pattern reaches the same final value whether driven as N×1 individual calls or a single batch call of N.

Example request

{
  "config": {
    "mlWeight": 0.6,
    "confidenceThreshold": 0.5
  }
}

Response

Hybrid step result

scenarioHashstring

Canonical SHA-256 of the persisted scenario graph and attached traffic-pattern order.

effectiveConfigHashstring

Versioned prediction SHA-256 over the replay startup-input hash, engine version, and calibration identity. The original replay-only hash remains at replayIdentity.effectiveConfigHash.

predictionEffectiveConfigHashstring

Engine-versioned prediction identity, separate from the replay-input identity.

engineVersionstring

Simulation engine version used to produce the prediction.

appWeight'lean' | 'typical' | 'heavy'

Immutable root-level simulation.create input. Omission selects typical and appWeightDefaulted=true; explicit typical has identical numerical predictions. In the generic fallback at 100 total RPS across two m5.large apps (50 per server), typical targets 20% app-host CPU, P50 18.5 ms and P95 45 ms, not the deliberately lean benchmark's 1.9% CPU. These are placeholder guidance, not AWS measurements; the separately eligible owned typical Node CRUD workload uses its measured 20/100/200 RPS fit instead. Heavy doubles typical load/latency multipliers as an unsupported product assumption.

appWeightDefaultedboolean
expiresAtstring date-time

Present only on x402 (wallet-paying) calls. ISO-8601 timestamp when ownership (and the simulation itself) expires. Reset to now+90 days on every successful step-hybrid call.

Example response

{
  "simulation": {
    "resources": [
      {
        "id": "ec2-1",
        "type": "compute",
        "name": "Web Server 1",
        "provider": "aws",
        "location": {
          "regionKey": "us-east-2"
        },
        "characteristics": {
          "workload": "crud",
          "appRuntime": "node",
          "appWorkerCount": 2,
          "appDbPoolSize": 250,
          "workloadDatabaseVersion": "8.0",
          "workloadDatabaseEngine": "mysql",
          "rdsSqlServerBilling": {
            "instanceClass": "db.t3.micro",
            "storageType": "gp2",
            "allocatedStorageGiB": 20,
            "durationHours": 480,
            "sustainedCpuPercent": 43
          },
          "serviceFamily": "ec2",
          "containerCpu": 0.5,
          "containerMemoryGiB": 1,
          "runtimeMemoryProfile": {
            "workingSetGiB": 0.78125
          },
          "concurrency": 80,
          "requestDurationSeconds": 0.25,
          "requestServingTargetUtilizationPct": 70,
          "billingState": "stopped",
          "size": "m5.large",
          "instanceType": "t3.medium",
          "ocpus": 4,
          "maxThroughput": 2000,
          "capacityRps": 100,
          "baseLatency": 3,
          "maxConnections": 800,
          "capacityGB": 500,
          "maxIops": 3000,
          "inferenceMode": true,
          "accelerator": "a10g",
          "managedComputePlatform": "nvidia-dgx-cloud",
          "openshiftOffering": "rosa-hcp",
          "topology": {
            "intraNode": "nvlink-nvswitch",
            "interNode": "infiniband"
          },
          "intraNode": "nvlink-nvswitch",
          "interNode": "infiniband",
          "includesControlPlane": true,
          "bundledNetworking": true,
          "trainingMode": true,
          "tokensPerRequest": 500,
          "inputTokensPerRequest": 1000,
          "cacheHitRate": 0.85,
          "cacheableRequestShare": 0.75,
          "asynchronousRequestShare": 0.15,
          "queueConsumerCount": 4,
          "queueDrainRatePerConsumerRps": 125,
          "queueCapacityMessages": 20000,
          "queueSimulationStepSeconds": 1,
          "autoscaling": true,
          "maxInstances": 5,
          "minInstances": 2,
          "scaleOutCpuThreshold": 60,
          "scaleInCpuThreshold": 25,
          "nodeCount": 2,
          "workerVcpu": 4,
          "minNodes": 2,
          "maxNodes": 10,
          "perNodeRate": 3.2,
          "pricingModel": "on-demand",
          "nodePools": [
            {
              "name": "general",
              "nodeCount": 2,
              "workerVcpu": 8,
              "minNodes": 2,
              "maxNodes": 10,
              "perNodeRate": 0.096,
              "maxThroughput": 10000
            }
          ],
          "streamShardsCount": 4,
          "streamWriteRps": 3500,
          "eventNotificationsEnabled": true,
          "partitionCount": 8,
          "streamPartitions": 4,
          "partitionWriteRps": 5000,
          "warmupSteps": 5,
          "warmupSeverity": 0.8
        },
        "routedRps": 15,
        "availabilityState": "available",
        "isRoutable": true,
        "failureParkStepsRemaining": 3,
        "recoveryPolicy": {
          "criticalCpuThreshold": 75,
          "criticalSteps": 2,
          "warningCpuThreshold": 60,
          "warningSteps": 1,
          "failureParkSteps": 2
        }
      }
    ],
    "normalizedConfig": {
      "resources": [
        {
          "rdsSqlServerBilling": {
            "input": {
              "instanceClass": "db.t3.micro",
              "storageType": "gp2",
              "allocatedStorageGiB": 20,
              "durationHours": 480,
              "sustainedCpuPercent": 43
            }
          },
          "rateProvenance": {
            "sku": "m7g.large",
            "source": "AWS EC2 Price List API (Linux, shared tenancy, on-demand)"
          },
          "dynamoDbBilling": {
            "referenceRequestRateRps": 50000
          },
          "requestServing": {
            "serviceFamily": "lambda"
          },
          "behaviorModel": {
            "latencyPath": "gpu-inference/ttft-decode",
            "description": "Token-economics model: TTFT + decode, weighted by throughput and batch pressure.",
            "modelingNote": "TTFT and decode-throughput figures are CWM simulation-model estimates, not externally measured hardware benchmarks.",
            "topologyThroughputFactor": 0.92,
            "topologyThroughputCalibrationStatus": "estimated",
            "ibNetworkingCostPerNodePerHour": 2
          },
          "inferenceWarnings": [
            "Resource has inference/GPU characteristics (accelerator: h100, tokensPerRequest: 512) but inferenceMode is not enabled. The generic-kubernetes/load-saturation latency model will be used. Set characteristics.inferenceMode: true to activate gpu-inference/ttft-decode."
          ]
        }
      ]
    },
    "resilienceConfig": {
      "dependencies": [
        {
          "id": "web-to-db",
          "sourceId": "web-1",
          "targetId": "db-1",
          "requestRatio": 1,
          "authDependencyId": "gateway-to-token-service",
          "retryPolicy": {
            "maxRetries": 3,
            "backoffMs": 100,
            "backoffMultiplier": 2,
            "jitterRatio": 0.1,
            "timeoutMs": 2000,
            "retryBudgetRatio": 2,
            "retryBudgetRps": 1000,
            "retryActorId": "gateway_optimistic_retries"
          },
          "capacity": {
            "maxRps": 10000,
            "maxConcurrent": 200,
            "meanServiceTimeMs": 100
          },
          "protection": {
            "circuitBreaker": {
              "failureRateThreshold": 0.5,
              "minimumRequests": 20,
              "openSteps": 3,
              "halfOpenMaxRequests": 10
            },
            "rateLimitRps": 5000
          }
        }
      ],
      "scheduledFaults": [
        {
          "id": "db-capacity-fault",
          "targetResourceId": "db-1",
          "dependencyId": "web-to-db",
          "startStep": 5,
          "endStep": 15,
          "capacityPercent": 30,
          "maxConcurrent": 5,
          "addedLatencyMs": 500,
          "errorRate": 0.3,
          "trafficMultiplier": 2.25
        }
      ],
      "maxCascadeDepth": 4,
      "maxGeneratedRps": 100000,
      "maxStepWork": 512
    }
  },
  "hybridDecision": {
    "timestamp": 12,
    "mlPrediction": {
      "overallConfidence": 0.78
    },
    "comparisons": [
      {
        "field": "costPerHour",
        "ruleValue": 0.84,
        "mlValue": 1.13,
        "hybridValue": 0.98,
        "deviation": 0.29
      }
    ],
    "agreement": {
      "score": 0.82,
      "level": "high",
      "largestDisagreement": "cost",
      "normalizationBasis": "absolute_safety_bounds"
    },
    "behaviorMismatch": {
      "detected": true,
      "cause": "Rule engine used generic-kubernetes/load-saturation for resource(s) that carry GPU/inference characteristics (accelerator, tokensPerRequest, or inputTokensPerRequest) but have inferenceMode: false. If this simulation is intended to model GPU inference workloads, setting characteristics.inferenceMode: true would activate the gpu-inference/ttft-decode latency model in the rule engine, which may change the rule/ML agreement score."
    },
    "rulesBehaviorModel": "gpu-inference/ttft-decode",
    "mlBehaviorModel": "gpu-inference/ttft-decode-ml",
    "behaviorAlignment": "aligned",
    "modelingNote": "TTFT and decode-throughput figures are CWM simulation-model estimates, not externally measured hardware benchmarks."
  },
  "coverageSummary": {
    "level": "partial",
    "modeledCount": 12,
    "estimatedCount": 2,
    "knownGapCount": 3,
    "modeledCostShareOfTotal": 0.9834,
    "notObservableCategories": [
      "Support plan costs"
    ],
    "structuralLimitations": [
      "IAM",
      "CloudWatch",
      "AWS Support"
    ],
    "billingPolicyCoverage": {
      "exclusions": [
        {
          "policy": "RDS Extended Support"
        }
      ]
    },
    "resources": [
      {
        "name": "Web Server",
        "resourceType": "compute",
        "shareOfSimulatedCost": 0.42,
        "shareExcluded": true,
        "reason": "CPU, latency, autoscaling, warm-up, and hourly cost follow deterministic provider-calibrated rules."
      }
    ]
  },
  "hybridResult": {
    "decisions": [
      {
        "timestamp": 12,
        "mlPrediction": {
          "overallConfidence": 0.78
        },
        "comparisons": [
          {
            "field": "costPerHour",
            "ruleValue": 0.84,
            "mlValue": 1.13,
            "hybridValue": 0.98,
            "deviation": 0.29
          }
        ],
        "agreement": {
          "score": 0.82,
          "level": "high",
          "largestDisagreement": "cost",
          "normalizationBasis": "absolute_safety_bounds"
        },
        "behaviorMismatch": {
          "detected": true,
          "cause": "Rule engine used generic-kubernetes/load-saturation for resource(s) that carry GPU/inference characteristics (accelerator, tokensPerRequest, or inputTokensPerRequest) but have inferenceMode: false. If this simulation is intended to model GPU inference workloads, setting characteristics.inferenceMode: true would activate the gpu-inference/ttft-decode latency model in the rule engine, which may change the rule/ML agreement score."
        },
        "rulesBehaviorModel": "gpu-inference/ttft-decode",
        "mlBehaviorModel": "gpu-inference/ttft-decode-ml",
        "behaviorAlignment": "aligned",
        "modelingNote": "TTFT and decode-throughput figures are CWM simulation-model estimates, not externally measured hardware benchmarks."
      }
    ],
    "summary": {
      "totalSteps": 50,
      "mlConfidenceAvg": 0.74,
      "blendedSteps": 38,
      "fallbackSteps": 12,
      "bottlenecksDetected": 5,
      "eventsDetected": 3
    }
  },
  "expiresAt": "2026-10-17T22:00:00.000Z",
  "ownership": {
    "type": "wallet",
    "wallet": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "expiresAt": "2026-10-17T22:00:00.000Z",
    "retentionDays": 90
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.