/openrouter-decisions

name: openrouter-decisions
description: Implement decision models through OpenRouter's Decisions API, which returns probabilities instead of generated text: pick the primitive per judgment, build minimal state, write the questions, pin a model from the live catalog, gate in code, and probe thresholds on real inputs. Use when replacing a prompt-and-parse LLM call, a keyword or similarity heuristic, a human review queue, or a misfiring router, filter, or classifier with a decision model, when asked to find or implement decision-model use cases in an app or agent, and whenever decision models, Jev, TypeSafe, or System One come up. Covers routing, classification, moderation, guardrails, grounding checks, scoring, ranking, dedupe, escalation and approval gates, bounded extraction, and thresholds. Not for chat completions, text generation, or general OpenRouter setup.

OpenRouter Decisions

A decision model reads application state and answers typed questions with probabilities, never text. The model judges, code computes. Code owns the workflow and every deterministic step, and the model fills in the judgments code cannot make. It is not a chat model, a coding agent, or a replacement for the LLM that drives one.

Every decision model on OpenRouter speaks the same Decisions API and the same three primitives, evaluated independently and in parallel within one request.

| Need | Primitive | Returns | | --- | --- | --- | | One option from a defined set | `choice` | `choice`, `probabilities` per option, `confidence` | | Whether a condition holds | `noul` | `noul`, the probability of yes | | Degree along ordered levels | `score` | `score` (probability-weighted position), `probabilities` per level, `confidence` |

Read [references/decisions-api.md](references/decisions-api.md) when writing a request or reading a response. Read [references/models.md](references/models.md) when picking between the decision models the live catalog returns. Read [references/decision-model-limits.md](references/decision-model-limits.md) whenever a question involves quantities, dates, negation, indirection, or untrusted text, since those are the things a decision model does not do.

Steps

1. **Split judgment from computation.** A step fits a decision model when its answer is bounded, needs judgment rather than computation, and a probability lets code act, defer, or escalate; a step that must produce text, values, or code, or whose answer already sits in a field code can read, stays as it is. Arithmetic, counting, date ordering, lookups, threshold comparisons, and string or pattern matching that extracts a fact (a path, an ID format, an amount) stay in code, and a value code already holds is never re-asked of the model. A keyword, regex, token-overlap, or similarity heuristic that stands in for a judgment (does this text mean X, is this the same request, is this relevant) is the judgment itself: the decision model replaces it, and its rules move into the question's inclusion and exclusion criteria rather than staying as a pre-filter. When code-side facts settle the action for an input (a path rule, a hard policy, an amount over a cap, an empty input), code returns that action and skips the model for that input. When code parses a value out of free text before comparing it, write the parser against the formats in real inputs and treat a parse miss as its own outcome. Generation goes to a generative model, and a decision model can then pick among its candidates. Done when every remaining item is a judgment that fits one primitive.

2. **Pick the primitive per judgment.** Mutually exclusive alternatives are a `choice`, which is relative and settles which option. An independently testable condition is a `noul`, which is absolute and can be low for every label, so labels that can co-occur are one `noul` each. A degree along one dimension is a `score` whose levels each describe a situation that stands alone. One unordered label from a written rubric is one `choice` whose criteria restate the labels, not several `noul`s recombined in code. Ordered levels (a 1 to 5 rating, low to critical) are a `score` whose criteria restate the levels in order, even if code stores the result as a label. Split into `noul`s only when code combines them with facts of its own or reuses them elsewhere. Comparable per-item `score`s ranked in code give graded ranking. Done when each judgment has a primitive and a reason.

3. **Build the state.** Send only what the questions read. Source text, identities, relationships, policies, and current facts, each in a named JSON field, filtered and retrieved in code first. Anything only code uses stays out (flags, counts, computed booleans, and any field that feeds a code-side rule such as a plan tier that caps a score), and code applies that rule to the returned answer. Unrelated material costs accuracy. Done when every field in `state` is read by at least one question and nothing a question needs is missing.

4. **Write the questions.** `instructions` states the judgment and carries the task's own inclusion and exclusion rules (what counts, what looks similar but does not). `criteria` defines the possible answers and reads as an extension of the instructions, asked one way with no double negatives. Ask about the fact, not the text. "Is this change breaking" holds where "Does the description mention breaking changes" and "Does the report state that" both fail, so phrase each question as a property of the thing judged ("Is this review promotional") and let the model infer from the state. Point at a nested field with a backticked path such as `` `ticket.messages[0].text` ``. A `choice` lists every viable option plus a no-match option such as `none` or `not_stated` whenever nothing may fit. When the options are runtime candidates, key the state by option name and name the option in its criterion, never an array index. Question keys are for code and are not sent to the model, so each question carries it