Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Decision unstable

Defines decisions that a DecisionModel answers over a single input. Pair an input schema with named classification, rating, or probability decisions using make, then answer them with DecisionModel.decide.

See

  • make for building a definition from an input schema and decisions
17 exports Since v4.0.0 Source

Constructors

classify

unstable
Since v4.0.0

Creates a classification decision from labelled criteria. Descriptions can be null when the label needs no explanation. Throws if fewer than two labels are supplied.

See

Signature

declare function classify<Label extends string>(options: {
  readonly criteria: { [L in string]: Description | null };
  readonly instructions: Description;
}): Classify<Label>

Example Choosing a department 

import { Decision } from "effect/ai"


const department = Decision.classify({
  instructions: "Which team should handle this",
  criteria: {
    billing: "payments",
    technical: "bugs",
    sales: "pricing"
  }
})

make

unstable
Since v4.0.0

Creates a decision definition from an input schema and named decisions. DecisionModel.decide encodes the input with Schema.toCodecJson before calling the provider. Answer keys and types are inferred from the decisions. Throws if decisions is empty.

See

Signature

declare function make<Input extends Constraint, Decisions extends Record<string, Any>>(options: {
  readonly decisions: Decisions;
  readonly input: Input;
}): Definition<Input, Decisions>

Example Defining ticket triage 

import { Schema } from "effect"
import { Decision } from "effect/ai"


const Ticket = Schema.Struct({
  subject: Schema.String,
  body: Schema.String
})


const TicketTriage = Decision.make({
  input: Ticket,
  decisions: {
    department: Decision.classify({
      instructions: "Which team should handle this",
      criteria: { billing: "payments", technical: "bugs" }
    }),
    urgent: Decision.probability({
      instructions: "The message is time-sensitive",
      criteria: { false: "No time pressure", true: "Needs action now" }
    })
  }
})

probability

unstable
Since v4.0.0

Creates a probability decision from instructions and optional outcome descriptions. When criteria is supplied, descriptions for both false and true are required.

See

Signature

declare function probability(options: {
  readonly criteria?: {
    readonly false: Description;
    readonly true: Description;
  };
  readonly instructions: Description;
}): Probability

Example Estimating urgency 

import { Decision } from "effect/ai"


const urgent = Decision.probability({
  instructions: "The message is time-sensitive"
})

Example Providing outcome descriptions 

import { Decision } from "effect/ai"


const urgent = Decision.probability({
  instructions: "The message is time-sensitive",
  criteria: {
    false: "The message can wait",
    true: "The message needs immediate attention"
  }
})

rate

unstable
Since v4.0.0

Creates a rating decision from an ordered list of criteria. Strings serve as both label and description; use { label, description } to separate them. Answers use the label. Throws if fewer than two levels or duplicate labels are supplied.

See

Signature

declare function rate<Level extends string>(options: {
  readonly criteria: readonly Array<Level | {
    readonly description: Description;
    readonly label: Level;
  }>;
  readonly instructions: Description;
}): Rate<Level>

Example Rating frustration 

import { Decision } from "effect/ai"


const frustration = Decision.rate({
  instructions: "How frustrated",
  criteria: ["calm", "frustrated", "angry"]
})

Example Describing levels with structure 

import { Decision } from "effect/ai"


const severity = Decision.rate({
  instructions: "How severe is the reported issue?",
  criteria: [
    "cosmetic",
    {
      label: "degraded",
      description: {
        what: "Broken or degraded feature, but workaround exists",
        examples: ["export fails in one browser but works in another"]
      }
    },
    {
      label: "blocking",
      description: {
        what: "Blocking issue; no workaround exists",
        examples: ["cannot log in", "data loss"]
      }
    }
  ]
})

Models

Any

type unstable
Since v4.0.0

Union of every decision kind.

Signature

type Any = Classify<string> | Rate<string> | Probability

Classify

interface unstable
Since v4.0.0

Decision that assigns the input one label out of a set of criteria. criteria maps labels to descriptions; use null for a label without a description.

See

Signature

interface Classify<Label extends string> {
  readonly _tag: "Classify";
  readonly criteria: { [L in string]: Description | null };
  readonly instructions: Description;
}

ClassifyAnswer

interface unstable
Since v4.0.0

Answer to a Classify decision. label is chosen by the provider and need not have the highest probability. confidence is an optional, provider-defined measure in [0, 1].

Signature

interface ClassifyAnswer<Label extends string> {
  readonly confidence?: number;
  readonly label: Label;
  readonly probabilities: { [L in string]: number };
}

Definition

interface unstable
Since v4.0.0

Input schema and named decisions that run together in one provider call.

See

  • make for the constructor

Signature

interface Definition<Input extends Schema.Constraint, Decisions extends Record<string, Any>> {
  readonly "~effect/ai/Decision": "~effect/ai/Decision";
  readonly decisions: Decisions;
  readonly input: Input;
}

Description

type unstable
Since v4.0.5

Decision instructions or descriptions: a string, JSON object, or JSON array.

Details

TypeScript interfaces lack the index signature required by Schema.JsonObject; use object literals, type aliases, or Schema types instead.

Signature

type Description = string | Schema.JsonObject | Schema.JsonArray

Probability

interface unstable
Since v4.0.0

Decision that estimates how likely a statement about the input is to hold. Optional criteria describes both outcomes when supplied. The answer is the probability of true.

See

Signature

interface Probability {
  readonly _tag: "Probability";
  readonly criteria?: {
    readonly false: Description;
    readonly true: Description;
  };
  readonly instructions: Description;
}

ProbabilityAnswer

interface unstable
Since v4.0.0

Answer to a Probability decision.

Signature

interface ProbabilityAnswer {
  readonly probability: number;
}

Rate

interface unstable
Since v4.0.0

Decision that places the input on an ordered scale of criteria. criteria lists levels from lowest to highest, with labels for answers and descriptions for the provider.

See

  • rate for the constructor
  • RateAnswer for the answer produced by this decision

Signature

interface Rate<Level extends string> {
  readonly _tag: "Rate";
  readonly criteria: readonly Array<{
    readonly description: Description;
    readonly label: Level;
  }>;
  readonly instructions: Description;
}

RateAnswer

interface unstable
Since v4.0.0

Answer to a Rate decision. rating is the probability-weighted position on the scale and may fall between two levels, within [0, criteria.length - 1]. label is the label of the level with the highest probability, choosing the first criteria entry on ties. confidence is an optional, provider-defined measure in [0, 1].

Signature

interface RateAnswer<Level extends string> {
  readonly confidence?: number;
  readonly label: Level;
  readonly probabilities: { [L in string]: number };
  readonly rating: number;
}

Type IDs

TypeId

unstable
Since v4.0.0

Brand for decision definitions.

Signature

declare const TypeId: "~effect/ai/Decision"

TypeId

type unstable
Since v4.0.0

Brand type for decision definitions.

Signature

type TypeId = "~effect/ai/Decision"

Utility Types

Answer

type unstable
Since v4.0.0

Answer type for a single decision.

Signature

type Answer<D extends Any> = D extends Classify<infer Label> ? ClassifyAnswer<Label> : D extends Rate<infer Level> ? RateAnswer<Level> : D extends Probability ? ProbabilityAnswer : never

Answers

type unstable
Since v4.0.0

Answers keyed by decision name.

Signature

type Answers<Decisions extends Record<string, Any>> = { [K in keyof Decisions]: Answer<Decisions[K]> }