Router.Decisions SDK Reference

Router.Decisions

Create a Decision

Beta. Evaluate content against named questions and receive structured answers, probabilities, and usage costs. Send the content as state and define each entry in questions as:

noul: estimate the probability that a statement is true.
choice: select an option from a set.
score: rate the content on an ordered scale.
box: locate one target in an image and return its bounding box. Beta, TypeSafe jev-preview only.

Instructions and criteria accept strings or structured JSON. TypeSafe models also accept inline images through assets (beta). Use a native decision model or a supported chat model. Configure ordered fallbacks, optional retry, timeout.call_timeout in milliseconds, and an exact-match cache. Each retry and fallback gets a fresh timeout; omit retry to move directly to the next fallback on timeout. The response identifies the model that answered. Requires the classify API-key permission. PII plugins and guardrails are not applied. See the Decisions guide for supported models, probability interpretation, and refusals.

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.router.decisions.create(model="openai/gpt-6-luna", questions={
        "positive": {
            "criteria": {
                "false": "The customer is unhappy.",
                "true": "The customer is happy.",
            },
            "instructions": "Is the sentiment positive?",
            "type": "noul",
        },
        "rating": {
            "criteria": [
                "Negative",
                "Neutral",
                "Positive",
            ],
            "instructions": "Rate sentiment.",
            "type": "score",
        },
        "sentiment": {
            "criteria": {
                "negative": "Negative sentiment",
                "neutral": "Neutral sentiment",
                "positive": "Positive sentiment",
            },
            "instructions": "Classify sentiment.",
            "type": "choice",
        },
    }, state="The customer says: I love this product. It is wonderful!", fallbacks=[
        {
            "model": "openai/gpt-5.6-luna",
        },
    ], identity={
        "display_name": "Sample customer",
        "id": "customer-demo",
    }, retry={
        "count": 2,
        "on_codes": [
            429,
            502,
            503,
            504,
        ],
    }, timeout={
        "call_timeout": 2000,
    })

    # Handle response
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.router.decisions.create({
    fallbacks: [
      {
        model: "openai/gpt-5.6-luna",
      },
    ],
    identity: {
      displayName: "Sample customer",
      id: "customer-demo",
    },
    model: "openai/gpt-6-luna",
    questions: {
      "positive": {
        criteria: {
          false: "The customer is unhappy.",
          true: "The customer is happy.",
        },
        instructions: "Is the sentiment positive?",
        type: "noul",
      },
      "rating": {
        criteria: [
          "Negative",
          "Neutral",
          "Positive",
        ],
        instructions: "Rate sentiment.",
        type: "score",
      },
      "sentiment": {
        criteria: {
          "negative": "Negative sentiment",
          "neutral": "Neutral sentiment",
          "positive": "Positive sentiment",
        },
        instructions: "Classify sentiment.",
        type: "choice",
      },
    },
    retry: {
      count: 2,
      onCodes: [
        429,
        502,
        503,
        504,
      ],
    },
    state: "The customer says: I love this product. It is wonderful!",
    timeout: {
      callTimeout: 2000,
    },
  });

  console.log(result);
}

run();

Show Parameters

{
    "model": str,  # required
    "questions": Dict[str, Union[QuestionsNoulQuestion, QuestionsChoiceQuestion, QuestionsScoreQuestion, QuestionsBoxQuestion]],  # required
    "state": Union[str, Dict[str, Any], List[Any]],  # required
    "assets": Dict[str, ClassifyAsset],  # optional
    "cache": {  # optional
        "ttl": Optional[int],
        "type": Literal["exact_match"],  # required
    },
    "fallback_on_codes": List[int],  # optional
    "fallbacks": [{  # optional
        "model": str,  # required
    }],
    "identity": {  # optional
        "display_name": Optional[str],
        "email": Optional[str],
        "id": str,  # required
        "metadata": List[Dict[str, Any]],  # optional
        "tags": List[str],  # optional
    },
    "metadata": Dict[str, str],  # optional
    "name": Optional[str],
    "retry": {  # optional
        "count": int,  # required
        "on_codes": List[int],  # optional
    },
    "timeout": {  # optional
        "call_timeout": int,  # required
    },
}

{
  assets?: Record<string, ClassifyAsset>;
  cache?: {
    ttl?: number;
    type: "exact_match";  // required
  };
  fallbackOnCodes?: number[];
  fallbacks?: {
    model: string;  // required
  }[];
  identity?: {
    displayName?: string;
    email?: string;
    id: string;  // required
    metadata?: Record<string, any>[];
    tags?: string[];
  };
  metadata?: Record<string, string>;
  model: string;  // required
  name?: string;
  questions: Record<string, QuestionsNoulQuestion | QuestionsChoiceQuestion | QuestionsScoreQuestion | QuestionsBoxQuestion>;  // required
  retry?: {
    count: number;  // required
    onCodes?: number[];
  };
  state: string | { [k: string]: any } | any[];  // required
  timeout?: {
    callTimeout: number;  // required
  };
}

Show Response

{
    "answers": Dict[str, Union[ClassifyBoxAnswer, ClassifyChoiceAnswer, ClassifyNoulAnswer, ClassifyRefusalAnswer, ClassifyScoreAnswer]],
    "model": str,
    "telemetry": {  # optional
        "span_id": str,
        "trace_id": str,
    },
    "usage": {
        "input_cost": Optional[float],
        "input_tokens": int,
        "input_tokens_details": {  # optional
            "cache_write_tokens": int,
            "cached_tokens": int,
        },
        "output_cost": Optional[float],
        "output_tokens": int,
        "total_cost": Optional[float],
    },
}

{
  answers: Record<string, ClassifyBoxAnswer | ClassifyChoiceAnswer | ClassifyNoulAnswer | ClassifyRefusalAnswer | ClassifyScoreAnswer>;
  model: string;
  telemetry?: {
    spanId: string;
    traceId: string;
  };
  usage: {
    inputCost?: number;
    inputTokens: number;
    inputTokensDetails?: {
      cacheWriteTokens: number;
      cachedTokens: number;
    };
    outputCost?: number;
    outputTokens: number;
    totalCost?: number;
  };
}

Orq SDK

Terminal & Agents

Terraform

Platform APIs

Management APIs