Router.Classify SDK Reference

Router.Classify

Create a Classify

Beta. Runs typed classification questions (noul, choice, score) against a native classify provider, including OpenAI Decisions with openai/gpt-6-luna, or a chat model that supports classify emulation. Emulated models answer through one structured-output call and their probabilities are model-reported rather than calibrated. Native providers can return refusal for individual questions; refused answers contain only type. The request and response follow the TypeSafe classification contract; model in the response identifies the primary or fallback model that answered and usage carries the computed cost like the Responses API. Both /v3/router/classify and /v3/router/decisions use this contract, including ordered fallbacks, request-level retry, and identity attribution. Both require classify.execute. This endpoint currently does not apply PII plugins or guardrails.

from orq_ai_sdk import Orq
import os

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

    res = orq.router.classify.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,
        ],
    })

    # 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.classify.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!",
  });

  console.log(result);
}

run();

Show Parameters

{
    "model": str,  # required
    "questions": Dict[str, Union[NoulQuestion, ChoiceQuestion, ScoreQuestion]],  # required
    "state": Union[str, Dict[str, Any], List[Any]],  # required
    "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],  # required
    },
}

{
  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, NoulQuestion | ChoiceQuestion | ScoreQuestion>;  // required
  retry?: {
    count: number;  // required
    onCodes: number[];  // required
  };
  state: string | { [k: string]: any } | any[];  // required
}

Show Response

{
    "answers": Dict[str, Union[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, 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

Router.Classify

Create a Classify

​Router.Classify

​Create a Classify

Router.Classify

Create a Classify