Plug your agents into real-world judgment.

1. Quickstart: score a decision

Call /api/decision with a scenario and optional context. Omega responds with structured JSON: risk, regret, safety flags, rules verdict, and metadata you can log or feed back into your agent.

curl -X POST "$YOUR_BASE_URL/api/decision" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $COMMONSENSE_API_KEY" \
  -d '{
    "scenario": "My agent wants to automatically sign vendor contracts.",
    "context": "Startup with limited runway. Some contracts could be long-term.",
    "riskTolerance": "MEDIUM",
    "domain": "BUSINESS"
  }'

const res = await fetch(`${process.env.OMEGA_BASE_URL}/api/decision`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.COMMONSENSE_API_KEY!,
  },
  body: JSON.stringify({
    scenario,
    context,
    riskTolerance: "MEDIUM",
    domain: "BUSINESS",
  }),
});

const { decision } = await res.json();

// decision.riskScore, decision.riskLevel,
// decision.rulesVerdict, decision.safetyFlags, decision.metadata

2. Response shape: what Omega sends back

The response from /api/decision is designed for agents, not humans. It's structured, stable, and safe to log or feed into downstream logic.

{
  "decision": "Require a human to review and sign each contract.",
  "reasoning": "...",
  "riskScore": 78,
  "riskLevel": "HIGH",
  "regretScore": 85,
  "consequenceSummary": "If your agent signs long-term contracts without review...",
  "consequenceTree": [
    {
      "description": "Overcommitting to expensive vendors",
      "likelihood": 0.7,
      "impact": "HIGH",
      "timeHorizon": "LONG_TERM"
    }
  ],
  "emotionalRead": "You seem stressed about runway and legal risk...",
  "suggestedAlternatives": [
    "Allow the agent to draft contracts but require human signature.",
    "Set hard caps on contract value and duration."
  ],
  "safetyFlags": {
    "legalRisk": true,
    "financialRisk": true,
    "emotionalRisk": false,
    "reputationalRisk": true,
    "securityRisk": false,
    "ethicalConcern": false,
    "needsHumanReview": true
  },
  "recommendedActionType": "ESCALATE",
  "rulesVerdict": {
    "rulesetId": "omega-default-ruleset-v1",
    "rulesetName": "Omega Default Safety & Risk Ruleset",
    "overallSeverity": "BLOCK",
    "passed": false,
    "evaluations": [
      {
        "id": "financial_high_risk_low_tolerance",
        "name": "High Financial Risk with Low Risk Tolerance",
        "severity": "BLOCK",
        "passed": false,
        "message": "User has low risk tolerance but high financial risk."
      }
    ],
    "weightedScore": 4.3
  },
  "metadata": {
    "version": "omega-decision-v1",
    "modelHint": "openai:gpt-5.4-mini",
    "watermarkSignature": "omega_abc123...",
    "generatedAt": "2025-03-01T12:34:56.789Z"
  }
}

3. Simulate futures before your agent acts

Use /api/simulate to get optimistic, likely, and worst-case futures. Each path returns a full Omega decision object so you can branch logic, ask for human review, or choose the safest option.

curl -X POST "$YOUR_BASE_URL/api/simulate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $COMMONSENSE_API_KEY" \
  -d '{
    "scenario": "My agent wants to DMs prospects automatically.",
    "context": "B2B SaaS founder, no spam reputation issues.",
    "riskTolerance": "MEDIUM",
    "domain": "BUSINESS"
  }'

{
  "baseScenario": { ... },
  "simulations": [
    {
      "label": "optimistic_path",
      "input": { ... },
      "decision": { "riskLevel": "LOW", "consequenceSummary": "You close high-value deals..." }
    },
    {
      "label": "likely_path",
      "input": { ... },
      "decision": { "riskLevel": "MEDIUM", "consequenceSummary": "You get some deals and a few unsubscribes..." }
    },
    {
      "label": "worst_case",
      "input": { ... },
      "decision": { "riskLevel": "HIGH", "consequenceSummary": "Your domain reputation is damaged..." }
    }
  ]
}

4. Agent integration patterns

The most common pattern is: user intent → agent plan → Omega decision → execute or escalate

async function guardedAgentStep(intent, context) {
  // 1) Let your LLM or planner propose an action
  const plan = await llm.plan(intent, context);

  // 2) Ask Omega to score the plan before acting
  const decisionRes = await fetch(`${OMEGA_BASE_URL}/api/decision`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": OMEGA_API_KEY,
    },
    body: JSON.stringify({
      scenario: plan.description,
      context,
      riskTolerance: "MEDIUM",
      domain: plan.domain ?? "GENERAL",
    }),
  });

  const { decision } = await decisionRes.json();

  // 3) Enforce safety / rules in your agent
  if (!decision.rulesVerdict?.passed || decision.riskLevel === "CRITICAL") {
    return {
      type: "ESCALATE",
      reason: decision.consequenceSummary,
      omega: decision,
    };
  }

  // 4) Proceed with the safest version of the plan
  return {
    type: "EXECUTE",
    plan,
    omega: decision,
  };
}

5. Auth & keys

All calls require an API key in x-api-key. Keys are managed in your Omega dashboard. Separate keys can be issued for:

• Production vs sandbox usage
• Different agent apps or tenants
• Partners and resellers (with usage tracking)