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#

ProviderModelsNotes
typesafejev-1.14.0, jev-1.13.0, jev-latest, jev-previewAny number of questions
cloudflareclef, clef-flashUp to 64 questions. A state that might exceed the model's context window is refused rather than truncated
openaigpt-6-lunaUp to 400 questions. Can refuse individual questions
googlegemini-decision-1Up 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? true and false optionally describe each outcome.
  • choice: which one of your options applies? Each option maps to a description, or None to 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.

QuestionAnswerFields
predicatePredicateAnswerprobability (0–1 that it is true)
choiceChoiceAnswerchoice, probabilities (per option), confidence (or None)
scoreScoreAnswerscore (probability-weighted, may fall between levels), probabilities (per level index), confidence (or None)
any (OpenAI only)RefusalAnswerthe 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:

typesafecloudflareopenaigoogle
Questions per requestAny644001,000
Options per choice1–2552–2552–2552–255
Levels per score1–102–102–102–255
Refuses single questionsNoNoYesNo

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 state is sent as its JSON text.
  • Descriptions. Option descriptions and score levels are sent as text. An option with None is 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 DecisionProviderError with upstream_status 400, 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_tokens is 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, timeout and max_retries.
  • Credentials. Register every fallback provider with configure_provider first. 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 carries providers_tried, last_error_type and the last model's upstream_status and usage.
  • A request with no fallbacks raises its model's own error.

Errors#

Every failure is a DecisionsProxyError subclass with error_type, status_code and request_id:

ExceptionMeaning
DecisionValidationErrorThe request can't be sent (shape or a provider limit). Nothing was billed.
DecisionAuthErrorNo usable key for the provider.
DecisionModelNotAllowedErrorNo VoiceRun decision pricing for that model; bring your own key.
DecisionProviderErrorThe provider returned an error (upstream_status).
DecisionTransportErrorThe provider or proxy could not be reached, or timed out.
DecisionResponseSchemaErrorThe provider answered, but not with a valid answer for every question. The provider charged for it, so its usage is still billed.
DecisionFallbackExhaustedErrorEvery 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).

overviewpythondecisions