DecisionModel unstable
Defines the provider-neutral service for structured decisions.
decide encodes one input as JSON, sends its named decisions in one provider
call, and validates the answers. Failures are reported as AiError values.
Constructors
Creates a DecisionModel that encodes inputs as JSON and validates provider answers.
Answers must cover every decision and use its labels. Distributions must
sum to 1 within 1e-6, optional confidence must be in [0, 1], and ratings must be
in [0, criteria.length - 1]. Invalid answers fail with
AiError.InvalidOutputError; encoding failures use AiError.InvalidUserInputError.
Details
Set supportsImages: true to accept images. Otherwise, nonempty image input
fails with AiError.InvalidUserInputError.
Providers that round each probability to probabilityPrecision decimal
places may return distributions whose sum drifts from 1 by up to half a unit
of the last place per label. Setting probabilityPrecision accepts that
drift and rescales the distribution to sum to 1; larger drift still fails.
See
- DecisionModel for the service shape returned by this constructor
- ProviderOptions for the input passed to the provider implementation
- ProviderResponse for the provider response contract consumed by this constructor
Signature
declare function make(params: { readonly decide: (options: ProviderOptions) => Effect<ProviderResponse, AiError>; readonly probabilityPrecision?: number; readonly supportsImages?: boolean;}): Effect<DecisionModel>Decisions
Answers a decision definition using the current DecisionModel service.
Encodes the input with Schema.toCodecJson, requiring the schema's encoding services.
Explicit undefined fields become null; absent fields stay absent.
Custom declarations need a JSON codec annotation or encoding fails.
Returned answers and probability dictionaries have null prototypes.
See
- DecisionModel for the service this function requires
Signature
declare function decide<Input extends Constraint, Decisions extends Record<string, Any>>(definition: Definition<Input, Decisions>, options: DecideOptions<Input>): Effect<DecideResponse<Decisions>, AiError, DecisionModel | Input["EncodingServices"]>Example Triaging a ticket
import { Effect, Schema } from "effect"import { Decision, DecisionModel } from "effect/ai"
const TicketTriage = Decision.make({ input: Schema.String, decisions: { urgent: Decision.probability({ instructions: "The message is time-sensitive", criteria: { false: "No time pressure", true: "Needs action now" } }) }})
const program = Effect.gen(function*() { const { answers, usage } = yield* DecisionModel.decide(TicketTriage, { input: "My card was charged twice, please fix this today" }) return { probability: answers.urgent.probability, usage }})Models
Answers for every decision in a definition together with usage metadata.
See
- DecisionUsage for token usage metadata
Signature
interface DecideResponse<Decisions extends Record<string, Decision.Any>> { readonly answers: Decision.Answers<Decisions>; readonly usage: DecisionUsage;}Decision operations over a definition.
Signature
interface DecisionModel { readonly "~effect/ai/DecisionModel": "~effect/ai/DecisionModel"; readonly decide: <Input extends Constraint, Decisions extends Record<string, Any>>(definition: Definition<Input, Decisions>, options: DecideOptions<Input>) => Effect<DecideResponse<Decisions>, AiError, Input["EncodingServices"]>;}DecisionUsage
unstableProvider-reported token usage. Unreported counts are undefined.
Signature
declare class DecisionUsage extends { readonly inputTokens?: number; readonly outputTokens?: number;} { constructor(...args: [props?: { readonly inputTokens?: number; readonly outputTokens?: number; }, options?: MakeOptions]);}An image sent to the provider with the encoded input.
data is a base64 string, a byte array, or a URL.
Signature
interface Image { readonly data: string | Uint8Array<ArrayBufferLike> | URL; readonly mediaType: string;}Provider answer for any decision kind.
Signature
type ProviderAnswer = ProviderClassifyAnswer | ProviderRateAnswer | ProviderProbabilityAnswerProvider answer for a classify decision.
Signature
interface ProviderClassifyAnswer { readonly _tag: "Classify"; readonly confidence?: number; readonly label: string; readonly probabilities: Readonly<Record<string, number>>;}Provider answer for a probability decision.
Signature
interface ProviderProbabilityAnswer { readonly _tag: "Probability"; readonly probability: number;}Provider answer for a rate decision. The core derives the label from the highest probability, choosing the first criteria entry on ties.
Signature
interface ProviderRateAnswer { readonly _tag: "Rate"; readonly confidence?: number; readonly probabilities: Readonly<Record<string, number>>; readonly rating: number;}Provider response for a decision request.
answers is keyed like the requested decisions. Each answer is validated
against its decision before it is returned to the caller.
Signature
interface ProviderResponse { readonly answers: Readonly<Record<string, ProviderAnswer>>; readonly usage: { readonly inputTokens: number | undefined; readonly outputTokens: number | undefined; };}Options
Options for answering a decision definition.
Signature
interface DecideOptions<Input extends Schema.Constraint> { readonly images?: readonly Array<Image>; readonly input: Input["Type"];}Provider input options for a decision request.
state is encoded with Schema.toCodecJson, not stringified.
All decisions must be answered in one call.
images is omitted when no images are supplied.
Signature
interface ProviderOptions { readonly decisions: Record<string, Decision.Any>; readonly images?: readonly Array<Image>; readonly state: Json;}Services
DecisionModel
unstableService key for answering decisions about an input. Create implementations
with make.
See
- decide for answering a definition through the current service
Signature
declare const DecisionModel: Context.Service<DecisionModel, DecisionModel>