Consequence decision support

Consequence adds a structured decision lifecycle to a Neutron Nucleus. Your application can compare bounded options, enforce constraints, record the chosen scenario, attach observed outcomes, and create reviewable calibration lessons. It never returns hidden chain-of-thought and does not execute an option by default.

Choose the integration model

Use Neutron's deterministic domain adapters when your product needs a generic bounded comparison. If your application already has a specialist solver, send its options through the versioned external-solver contract. This keeps domain logic in the product that owns it while Neutron provides validation, scoring, history, idempotency, retention, and decision/outcome records.

Application-supplied candidates require:

• externalSolver.schemaVersion set to "1" and stable adapter/version identifiers;
• at least one structured objective;
• bounded options with source references and a depth-1 projection;
• declared constraints and metric definitions for any referenced IDs;
• explicit Nucleus and scope IDs derived by your server.

const response = await fetch("https://neutronai.dev/api/v1/consequence/plan", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.NEUTRON_API_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    nucleusId: "product-agent",
    scopeIds: ["workflow:decision-123"],
    task: "Compare the application's verified options",
    domain: "route_choice",
    externalSolver: {
      schemaVersion: "1",
      adapterId: "route-planner",
      adapterVersion: "2.4.0",
    },
    idempotencyKey: "decision-123-v1",
    retentionDays: 30,
    objectives: [{
      objectiveId: "arrival_time",
      name: "Arrival time",
      description: "Minimise arrival time within the safety constraints.",
      direction: "minimize",
      weight: 1,
      unit: "minutes",
      sourceRefs: ["solver:route-planner-2.4.0"],
    }],
    metricDefinitions: [{
      metricKey: "arrival_minutes",
      label: "Arrival time",
      direction: "minimize",
      unit: "minutes",
      weight: 1,
      minimum: 0,
      maximum: 180,
    }],
    candidateOptions: [{
      optionId: "safe-route",
      label: "Safe route",
      summary: "Use the verified low-risk route.",
      actionType: "route_choice",
      sourceRefs: ["solver:route-planner-2.4.0"],
      confidence: 0.88,
      riskLevel: "low",
      consequenceProjections: [{
        depth: 1,
        category: "operational",
        summary: "Estimated arrival in 42 minutes.",
        metricKey: "arrival_minutes",
        magnitude: 42,
        unit: "minutes",
        likelihood: 0.82,
        confidence: 0.88,
        positive: true,
        negative: false,
        sourceRefs: ["solver:route-planner-2.4.0"],
      }],
    }],
    policy: {
      depth: 3,
      searchStrategy: "solver_guided",
      allowExecution: false,
    },
  }),
});

Treat external projections as untrusted estimates. A hard blocking constraint that is violated or cannot be established is never recommended.

Complete the learning loop

1. Plan and compare options with POST /v1/consequence/plan.
2. Record the selected scenario with POST /v1/consequence/decide.
3. Record bounded observed metrics with POST /v1/consequence/observe.
4. Compare predicted and observed values with POST /v1/consequence/reflect.

Only send derived, necessary facts. Keep secrets, raw location trails, credentials, and unnecessary personal data in your application.

Retention and deletion

Retention is 90 days by default and can be set from 1 to 365 days. Use POST /v1/consequence/delete for one run or POST /v1/consequence/delete-scoped for all runs owned by one application user or scope set. Deletion tombstones the run before erasing its decision artifacts, so delayed work and idempotent retries cannot recreate it.

Keep the bearer token server-side. Derive nucleusId, scopeIds, and user ownership from trusted application context rather than browser claims.

For complete memory-to-decision examples, see Memory + Consequence Agents, the end-to-end SDK flow, and the industry use cases.