VoiceRun Decisions
primfunctions.decisions asks a decision model named, typed questions about a state (a transcript, a record, or any JSON) and returns calibrated answers: probabilities, not generated text. Use it where your handler needs a judgment it can branch on, such as "does the caller want a quote?", "which department is this for?" or "how urgent is this?".
It ships as part of the primfunctions package and is available in every agent runtime. Calls go through the VoiceRun completions proxy on your session's auth, tracing and billing, the same way primfunctions.completions does.
Providers and models#
| Provider | Models | Notes |
|---|---|---|
typesafe | jev-1.14.0, jev-1.13.0, jev-latest, jev-preview | Any number of questions |
cloudflare | clef, clef-flash | Up to 64 questions. A state that might exceed the model's context window is refused rather than truncated |
openai | gpt-6-luna | Up to 400 questions. Can refuse individual questions |
google | gemini-decision-1 | Up to 1,000 questions. Up to 255 score levels. No served_model |
Register a provider#
Register each provider once per session, usually on StartEvent:
from primfunctions.decisions import configure_provider configure_provider("typesafe", voicerun_managed=True) # VoiceRun's key, billed per token configure_provider("openai", api_key=context.variables["OPENAI_KEY"]) # your key, never billed by VoiceRun configure_provider("google", api_key=context.variables["GEMINI_KEY"]) # a Gemini API key from Google AI Studio configure_provider( "cloudflare", api_key=context.variables["CF_TOKEN"], credentials={"account_id": context.variables["CF_ACCOUNT_ID"]}, )
Decision registrations are independent of primfunctions.completions registrations: registering openai here does not change how completions call OpenAI, and vice versa.
voicerun_managed=True is available only for models that have VoiceRun decision pricing. A request for any other model fails with DecisionModelNotAllowedError; bring your own key for that model instead.
Ask questions#
from primfunctions.decisions import choice, generate_decisions, predicate, score result = await generate_decisions({ "provider": "google", "model": "gemini-decision-1", "state": transcript_text, # a string, or any JSON object/array "questions": { "wants_quote": predicate( "Does the caller want a quote?", true="They ask for or accept a price", false="They decline or ask about something else", ), "coverage": choice( "Which coverage did the caller ask for?", {"auto": "Vehicles and trucks", "liability": "General liability", "unclear": None}, ), "urgency": score("How urgent is the request?", ["Can wait", "This week", "Today"]), }, "timeout": 10, # optional, seconds per provider attempt "max_retries": 1, # optional, 0-3; transport errors and retryable statuses only })
There are three question types:
predicate: is a statement true?trueandfalseoptionally describe each outcome.choice: which one of your options applies? Each option maps to a description, orNoneto judge it by its name.score: where on your ordered rubric does it fall? List the levels lowest first. Levels are indexed from 0.
Question names may use letters, digits, _, . and - (up to 100 characters). The same question set works on every provider.
Read answers#
result.answers is keyed by your question names.
| Question | Answer | Fields |
|---|---|---|
predicate | PredicateAnswer | probability (0–1 that it is true) |
choice | ChoiceAnswer | choice, probabilities (per option), confidence (or None) |
score | ScoreAnswer | score (probability-weighted, may fall between levels), probabilities (per level index), confidence (or None) |
| any (OpenAI only) | RefusalAnswer | the model declined that question |
result.provider and result.model name the model that answered. result.served_model is the model the provider actually ran (aliases like jev-latest resolve to a versioned id); it is None when the provider doesn't report one, as with google. result.usage has the tokens.
Thresholds, default answers and side effects belong in your handler. The SDK reports what the model said and never decides for you:
from primfunctions.decisions import ChoiceAnswer coverage = result.answers["coverage"] if isinstance(coverage, ChoiceAnswer) and (coverage.confidence or 0) >= 0.6: route(coverage.choice) else: ask_clarifying_question()
A low-confidence answer or a refusal is not an error. It is a successful decision that your code chooses how to act on.
Provider differences#
The same request works on every provider, within each one's limits:
typesafe | cloudflare | openai | google | |
|---|---|---|---|---|
| Questions per request | Any | 64 | 400 | 1,000 |
Options per choice | 1–255 | 2–255 | 2–255 | 2–255 |
Levels per score | 1–10 | 2–10 | 2–10 | 2–255 |
| Refuses single questions | No | No | Yes | No |
A request outside a provider's limits fails with DecisionValidationError before anything is sent.
Notes for google (gemini-decision-1):
- State. Sent as text. An object or array
stateis sent as its JSON text. - Descriptions. Option descriptions and score levels are sent as text. An option with
Noneis judged by its name. - Option names. Up to 128 characters, with no leading or trailing space and no control characters.
- Safety blocks. Gemini blocks a whole request, not a single question. A blocked request raises
DecisionProviderErrorwithupstream_status400, and a fallback model is tried if you listed one. - Long inputs. A request over the model's 262,144-token context window is rejected, not truncated. It raises
DecisionProviderError. - Usage. Billed on input tokens only;
output_tokensis always 0.
Fall back to other models#
fallbacks works like completions fallbacks:
- Order. Each entry is tried in order when the model before it fails for any reason, after that model's own
max_retries. - Inheritance. A field you leave unset inherits from the main request:
provider,model,state,questions,timeoutandmax_retries. - Credentials. Register every fallback provider with
configure_providerfirst. Each fallback is sent with its own provider's key.
from primfunctions.decisions import DecisionFallback, configure_provider, generate_decisions configure_provider("google", voicerun_managed=True) configure_provider("typesafe", voicerun_managed=True) result = await generate_decisions({ "provider": "google", "model": "gemini-decision-1", "state": transcript_text, "questions": questions, "fallbacks": [ DecisionFallback(provider="typesafe", model="jev-1.14.0"), {"provider": "typesafe", "model": "jev-latest", "timeout": 20}, ], }) result.provider, result.model # the model that answered
The whole chain is checked before any model is called. A fallback whose provider isn't registered, a malformed entry, a provider with no VoiceRun-managed key, or a VoiceRun-managed model without decision pricing fails the request up front, even if the primary would have answered.
Every attempt, including failed ones, is traced and metered on its own:
- A provider that answered with an invalid answer set charged for it, so that attempt is billed even when a fallback then answers.
- When every model fails, you get
DecisionFallbackExhaustedError. It carriesproviders_tried,last_error_typeand the last model'supstream_statusandusage. - A request with no
fallbacksraises its model's own error.
Errors#
Every failure is a DecisionsProxyError subclass with error_type, status_code and request_id:
| Exception | Meaning |
|---|---|
DecisionValidationError | The request can't be sent (shape or a provider limit). Nothing was billed. |
DecisionAuthError | No usable key for the provider. |
DecisionModelNotAllowedError | No VoiceRun decision pricing for that model; bring your own key. |
DecisionProviderError | The provider returned an error (upstream_status). |
DecisionTransportError | The provider or proxy could not be reached, or timed out. |
DecisionResponseSchemaError | The provider answered, but not with a valid answer for every question. The provider charged for it, so its usage is still billed. |
DecisionFallbackExhaustedError | Every model in fallbacks failed (providers_tried, last_error_type). |
Two setup errors are raised before any request is made: DecisionsNotConfiguredError (the session was never configured) and DecisionsProviderNotConfiguredError (the provider, or a fallback's provider, was not registered with configure_provider).
