Decisions
Conceptual guide: Typed decisions.
Experimental
Decisions are marked @experimental: the question, answer, and provider shapes may change in a minor release.
decide()
import { decide, noul, choice, score } from "@fifthrevision/axle";
decide(options: DecideParams<TQuestions>): Promise<DecideResult<TQuestions>>Asks a decision model typed questions about one input. One request, one answer per question, no conversation.
interface DecideParams<TQuestions extends DecisionQuestions> {
provider: DecisionProvider;
model: string;
/** The content every question is asked about. */
input: DecisionInput;
/** Questions keyed by a name of your choosing; answers come back under the same keys. */
questions: TQuestions;
signal?: AbortSignal;
span?: Span;
}
interface DecideResult<TQuestions extends DecisionQuestions> {
model: string;
answers: DecisionAnswers<TQuestions>;
usage: Stats;
}
type DecisionInput = string | DecisionJson[] | { [key: string]: DecisionJson };input is a string or a JSON value (TypeSafe's wire name for it is state; Axle names it input because "state" already means agent state). Throws DECISION_ANSWER_MISMATCH when a question's answer is missing or mistyped, and rejects — never resolves ok: false — on request, transport, timeout, or abort failures.
Questions
noul(instructions: string, criteria?: { true: string; false: string }): NoulQuestion
choice<const TOption extends string>(instructions: string, criteria: Record<TOption, string | null>): ChoiceQuestion<TOption>
score(instructions: string, criteria: string[]): ScoreQuestion
type DecisionQuestion = NoulQuestion | ChoiceQuestion | ScoreQuestion;
type DecisionQuestions = Record<string, DecisionQuestion>;choice criteria map each option to its description, or null. score criteria list the ordered levels, lowest first.
Answers
type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer | DecisionRefusal;
interface NoulAnswer { type: "noul"; noul: number }
interface ChoiceAnswer<TOption extends string = string> {
type: "choice";
choice: TOption;
probabilities: Record<TOption, number>;
confidence: number;
}
interface ScoreAnswer {
type: "score";
score: number;
probabilities: Record<string, number>;
legend: Record<string, string>;
confidence: number;
}
interface DecisionRefusal { type: "refusal" }
type AnswerFor<TQuestion extends DecisionQuestion> =
TQuestion extends NoulQuestion ? NoulAnswer | DecisionRefusal
: TQuestion extends ChoiceQuestion<infer TOption> ? ChoiceAnswer<TOption> | DecisionRefusal
: TQuestion extends ScoreQuestion ? ScoreAnswer | DecisionRefusal
: never;confidence summarizes how concentrated a choice or score answer's probabilities are — it is not the probability of the chosen answer, and it is not comparable across models. A refusal belongs to one question; the rest of the decision stands.
DecisionProvider
interface DecisionProvider {
get name(): string;
/** @internal */
createDecisionRequest(model: string, params: DecisionRequestParams): Promise<DecisionResponse>;
}Separate from AIProvider; a provider may implement either or both. typesafe() implements only this one, so passing it to stream(), generate(), or an Agent is a type error.
typesafe()
import { typesafe } from "@fifthrevision/axle";
typesafe(apiKey: string, options?: TypesafeOptions): DecisionProvider
type TypesafeOptions = ProviderClientOptions;baseUrl is the shared client option: the API root serving /v1/systemone (default https://api.typesafe.ai). Point it at https://openrouter.ai/api with an OpenRouter key to route through it. timeoutMs defaults to ten seconds per attempt, matching TypeSafe's own SDKs. A non-2xx response throws DECISION_REQUEST_FAILED with the status and body in details; a body Axle cannot read throws DECISION_RESPONSE_INVALID. The model id is passed through unchanged.