Turn model reasoning into a workflow decision.

Latency

Fast path and fallback

• Conseq targets `1200ms` for normal synchronous pricing checks.
• Clients should treat `1500ms` as the recommended timeout budget.
• If Conseq does not return in time, default to `ESCALATE`.

If Conseq is slow or unavailable, do not auto-approve the pricing action. Escalate it to human review or keep the current price in place.

These values are also exposed by `serviceStatus` and the REST response headers for `POST /api/v2/predict`.

Public mental model

Predict first. Branch second. Execute last.

• Call `predict` before your worker, operator, or workflow makes a costly change.
• If the response is `ALLOW`, continue. If it is `WARN` or `ESCALATE`, stop or review.
• Use the same request envelope in HTTP, the sandbox, and the SDK.
• Keep outcomes, calibration, and connectors behind the same public contract.

Confidence and tail risk are first-class outputs. Do not let polished reasoning text override a low-confidence prediction or a `WARN` or `ESCALATE` decision.

GraphQL compatibility

Backend GraphQL naming still exists underneath

The public product language is `predict`, but the AppSync contract still exposes `predictConsequence` while the HTTP `v2` surface is being generalized.

mutation PredictConsequence($input: ConsequencePredictionInput!) {
  predictConsequence(input: $input) {
    prediction {
      id
      capability
      modelVersion
      reasoningVersion
      actionType
      customerAccountId
      customerAccountName
      requestSource
      requestCallerId
      requestCallerEmail
      requestApiKeyId
      requestApiKeyLabel
      expectedValue
      expectedValueLabel
      tailRisk
      confidence
      actionPolicy
      immediateOutcome
      secondOrderEffects
      thirdOrderEffects
      recommendation
      reasoning
      outcomeStatus
      accuracyStatus
      outcomeSource
      outcomeActorId
      outcomeActorLabel
    }
    job {
      id
      status
      pollAfterMs
      predictionId
    }
    error {
      code
      message
    }
  }
}

Async jobs

Poll background predictions

query GetConsequenceJob($id: ID!) {
  getConsequenceJob(id: $id) {
    id
    status
    pollAfterMs
    predictionId
    lastError
  }
}

Behind The Scenes

Learning infrastructure stays off the critical path.

Customers should be able to understand Conseq as one predict call. Outcome connectors, pattern review, evaluation, and changelog details still exist, but they support model quality rather than define the primary integration story.

`v2` returns a flat decision envelope instead of leaking the internal prediction/job storage shape.

{
  "predictionId": "pred_123",
  "decision": "ESCALATE",
  "expectedValue": -18400,
  "tailRisk": 0.36,
  "confidence": 0.77,
  "immediateOutcome": "$8.7K of short-term revenue lift if the markdown increases unit demand.",
  "secondOrderEffects": [
    "Competitors are more likely to match the lower price and compress category margin."
  ],
  "thirdOrderEffects": [
    "Customers begin anchoring on the lower price and delay future full-price purchases."
  ],
  "recommendedAction": "Require human approval for markdowns above 15%...",
  "reasoning": "This pricing model treats percent markdown as a short-term unit lift tradeoff..."
}

Request observability

Trace each prediction from request to verification.

• Log `predictionId`, `decision`, caller, target, and submitted timestamp for every request.
• Sync predict responses now expose `x-conseq-prediction-id`, `x-conseq-decision`, and `x-conseq-verification-status`.
• Async `v1` responses expose `x-conseq-job-id` so polling can be traced back to the original request.
• `/api/predictions` is the customer-facing trace view for later verification status and history.

Versioning

How contract changes ship

The single-predict HTTP transport now leads with v2. Additive changes can ship within v2. Breaking changes require a new major version path and schema contract.

• `POST /api/v2/predict` is now the canonical HTTP entry point.
• `/api/v1` remains the stable pricing-specific contract during the transition.
• `serviceStatus` still reflects the current GraphQL/AppSync contract version.
• Breaking changes ship only behind a new major version.

Error contract

Stable machine-readable error codes

• `INVALID_INPUT`
• `UNSUPPORTED_CAPABILITY`
• `INSUFFICIENT_CREDITS`
• `RATE_LIMIT_EXCEEDED`
• `DAILY_QUOTA_EXCEEDED`
• `IDEMPOTENCY_CONFLICT`
• `NOT_FOUND`
• `UNAUTHORIZED`
• `INTERNAL_ERROR`

Webhook flow

Push real Stripe outcomes back into Conseq.

• Create a Stripe connector in `/api/connectors`.
• Use the generated webhook URL as a Stripe endpoint.
• Subscribe the endpoint to `checkout.session.completed`.
• Add `conseq_prediction_id` metadata to the checkout session.
• Optionally add `conseq_units` when one session covers multiple units.

Webhook metadata

metadata: {
  conseq_prediction_id: "pred_123",
  conseq_units: "2"
}

Conseq ignores unsupported event types, events without a prediction link, non-USD sessions, and duplicate Stripe event IDs.