@effect-uai/core 0.16.0 → 0.17.0

package/dist/math/Probability.d.mts

@@ -0,0 +1,21 @@
+declare namespace Probability_d_exports {
+  export { confidence, margin };
+}
+/**
+ * 1 minus normalized Shannon entropy: 1 when all mass sits on one outcome, 0
+ * when spread evenly. Fewer than two outcomes yields 1.
+ *
+ * Conservative on two outcomes, where `[0.94, 0.06]` scores ~0.67, so a
+ * threshold tuned on a long vector does not transfer. {@link margin} is the
+ * more stable gate across vectors of different length.
+ */
+declare const confidence: (probabilities: ReadonlyArray<number>) => number;
+/**
+ * Top mass minus runner-up mass, which unlike {@link confidence} separates a
+ * close second from a flat spread. A single outcome yields its own
+ * probability; empty yields 0.
+ */
+declare const margin: (probabilities: ReadonlyArray<number>) => number;
+//#endregion
+export { confidence, margin, Probability_d_exports as t };
+//# sourceMappingURL=Probability.d.mts.map

package/dist/math/Probability.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Probability.d.mts","names":[],"sources":["../../src/math/Probability.ts"],"mappings":";;;;;;;;;;;cAaa,aAAU,eAAmB;;;;;;cAiB7B,SAAM,eAAmB"}

package/dist/math/Probability.mjs

@@ -0,0 +1,31 @@
+import { n as __exportAll } from "../rolldown-runtime-EAsCxrDo.mjs";
+import { Array, Number, Option, Order, pipe } from "effect";
+//#region src/math/Probability.ts
+/** Certainty measures over a probability vector. */
+var Probability_exports = /* @__PURE__ */ __exportAll({
+	confidence: () => confidence,
+	margin: () => margin
+});
+const descending = Order.flip(Order.Number);
+/**
+* 1 minus normalized Shannon entropy: 1 when all mass sits on one outcome, 0
+* when spread evenly. Fewer than two outcomes yields 1.
+*
+* Conservative on two outcomes, where `[0.94, 0.06]` scores ~0.67, so a
+* threshold tuned on a long vector does not transfer. {@link margin} is the
+* more stable gate across vectors of different length.
+*/
+const confidence = (probabilities) => probabilities.length < 2 ? 1 : 1 - pipe(probabilities, Array.filter((p) => p > 0), Array.map((p) => -p * Math.log(p)), Number.sumAll) / Math.log(probabilities.length);
+/**
+* Top mass minus runner-up mass, which unlike {@link confidence} separates a
+* close second from a flat spread. A single outcome yields its own
+* probability; empty yields 0.
+*/
+const margin = (probabilities) => {
+	const top = pipe(probabilities, Array.sort(descending), Array.take(2));
+	return pipe(Array.get(top, 0), Option.map((first) => pipe(Array.get(top, 1), Option.getOrElse(() => 0), (second) => first - second)), Option.getOrElse(() => 0));
+};
+//#endregion
+export { confidence, margin, Probability_exports as t };
+
+//# sourceMappingURL=Probability.mjs.map

package/dist/math/Probability.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Probability.mjs","names":["A","N"],"sources":["../../src/math/Probability.ts"],"sourcesContent":["/** Certainty measures over a probability vector. */\nimport { Array as A, Number as N, Option, Order, pipe } from \"effect\"\n\nconst descending = Order.flip(Order.Number)\n\n/**\n * 1 minus normalized Shannon entropy: 1 when all mass sits on one outcome, 0\n * when spread evenly. Fewer than two outcomes yields 1.\n *\n * Conservative on two outcomes, where `[0.94, 0.06]` scores ~0.67, so a\n * threshold tuned on a long vector does not transfer. {@link margin} is the\n * more stable gate across vectors of different length.\n */\nexport const confidence = (probabilities: ReadonlyArray<number>): number =>\n  probabilities.length < 2\n    ? 1\n    : 1 -\n      pipe(\n        probabilities,\n        A.filter((p) => p > 0),\n        A.map((p) => -p * Math.log(p)),\n        N.sumAll,\n      ) /\n        Math.log(probabilities.length)\n\n/**\n * Top mass minus runner-up mass, which unlike {@link confidence} separates a\n * close second from a flat spread. A single outcome yields its own\n * probability; empty yields 0.\n */\nexport const margin = (probabilities: ReadonlyArray<number>): number => {\n  const top = pipe(probabilities, A.sort(descending), A.take(2))\n  return pipe(\n    A.get(top, 0),\n    Option.map((first) =>\n      pipe(\n        A.get(top, 1),\n        Option.getOrElse(() => 0),\n        (second) => first - second,\n      ),\n    ),\n    Option.getOrElse(() => 0),\n  )\n}\n"],"mappings":";;;;;;;;AAGA,MAAM,aAAa,MAAM,KAAK,MAAM,MAAM;;;;;;;;;AAU1C,MAAa,cAAc,kBACzB,cAAc,SAAS,IACnB,IACA,IACA,KACE,eACAA,MAAE,QAAQ,MAAM,IAAI,CAAC,GACrBA,MAAE,KAAK,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,GAC7BC,OAAE,MACJ,IACE,KAAK,IAAI,cAAc,MAAM;;;;;;AAOrC,MAAa,UAAU,kBAAiD;CACtE,MAAM,MAAM,KAAK,eAAeD,MAAE,KAAK,UAAU,GAAGA,MAAE,KAAK,CAAC,CAAC;CAC7D,OAAO,KACLA,MAAE,IAAI,KAAK,CAAC,GACZ,OAAO,KAAK,UACV,KACEA,MAAE,IAAI,KAAK,CAAC,GACZ,OAAO,gBAAgB,CAAC,IACvB,WAAW,QAAQ,MACtB,CACF,GACA,OAAO,gBAAgB,CAAC,CAC1B;AACF"}

package/dist/math/Probability.test.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/math/Probability.test.mjs

@@ -0,0 +1,95 @@
+import { confidence, margin } from "./Probability.mjs";
+import { m as it, o as describe } from "../utils-CiH_DjFW.mjs";
+import { n as globalExpect } from "../test.DNmyFkvJ-YPzDR0Co.mjs";
+//#region src/math/Probability.test.ts
+describe("confidence", () => {
+	it("is 1 when all mass sits on one outcome", () => {
+		globalExpect(confidence([
+			1,
+			0,
+			0
+		])).toBeCloseTo(1, 10);
+	});
+	it("is 0 when mass is spread evenly, at any length", () => {
+		globalExpect(confidence([.5, .5])).toBeCloseTo(0, 10);
+		globalExpect(confidence([
+			.25,
+			.25,
+			.25,
+			.25
+		])).toBeCloseTo(0, 10);
+	});
+	it("is 1 for fewer than two outcomes, which have nothing to be uncertain between", () => {
+		globalExpect(confidence([])).toBe(1);
+		globalExpect(confidence([1])).toBe(1);
+	});
+	it("rises as mass concentrates", () => {
+		const spread = confidence([
+			.4,
+			.35,
+			.25
+		]);
+		const leaning = confidence([
+			.6,
+			.25,
+			.15
+		]);
+		const decided = confidence([
+			.9,
+			.07,
+			.03
+		]);
+		globalExpect(spread).toBeLessThan(leaning);
+		globalExpect(leaning).toBeLessThan(decided);
+	});
+	it("is conservative on two outcomes, so a threshold does not transfer across lengths", () => {
+		globalExpect(confidence([.94, .06])).toBeCloseTo(.67, 2);
+	});
+});
+describe("margin", () => {
+	it("is the gap between the top two, whatever order they arrive in", () => {
+		globalExpect(margin([
+			.6,
+			.3,
+			.1
+		])).toBeCloseTo(.3, 10);
+		globalExpect(margin([
+			.1,
+			.6,
+			.3
+		])).toBeCloseTo(.3, 10);
+	});
+	it("is 0 on a tie and 0 when empty", () => {
+		globalExpect(margin([.5, .5])).toBeCloseTo(0, 10);
+		globalExpect(margin([])).toBe(0);
+	});
+	it("yields the lone probability for a single outcome", () => {
+		globalExpect(margin([.7])).toBeCloseTo(.7, 10);
+	});
+});
+describe("confidence and margin disagree, which is why both exist", () => {
+	const closeSecond = [
+		.45,
+		.42,
+		.13
+	];
+	const flatSpread = [
+		.45,
+		.11,
+		.11,
+		.11,
+		.11,
+		.11
+	];
+	it("confidence cannot separate them", () => {
+		globalExpect(Math.abs(confidence(closeSecond) - confidence(flatSpread))).toBeLessThan(.05);
+	});
+	it("margin separates them sharply", () => {
+		globalExpect(margin(closeSecond)).toBeCloseTo(.03, 10);
+		globalExpect(margin(flatSpread)).toBeCloseTo(.34, 10);
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=Probability.test.mjs.map

package/dist/math/Probability.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Probability.test.mjs","names":[],"sources":["../../src/math/Probability.test.ts"],"sourcesContent":["import { describe, expect, it } from \"vitest\"\nimport { confidence, margin } from \"./Probability.js\"\n\ndescribe(\"confidence\", () => {\n  it(\"is 1 when all mass sits on one outcome\", () => {\n    expect(confidence([1, 0, 0])).toBeCloseTo(1, 10)\n  })\n\n  it(\"is 0 when mass is spread evenly, at any length\", () => {\n    expect(confidence([0.5, 0.5])).toBeCloseTo(0, 10)\n    expect(confidence([0.25, 0.25, 0.25, 0.25])).toBeCloseTo(0, 10)\n  })\n\n  it(\"is 1 for fewer than two outcomes, which have nothing to be uncertain between\", () => {\n    expect(confidence([])).toBe(1)\n    expect(confidence([1])).toBe(1)\n  })\n\n  it(\"rises as mass concentrates\", () => {\n    const spread = confidence([0.4, 0.35, 0.25])\n    const leaning = confidence([0.6, 0.25, 0.15])\n    const decided = confidence([0.9, 0.07, 0.03])\n    expect(spread).toBeLessThan(leaning)\n    expect(leaning).toBeLessThan(decided)\n  })\n\n  it(\"is conservative on two outcomes, so a threshold does not transfer across lengths\", () => {\n    expect(confidence([0.94, 0.06])).toBeCloseTo(0.67, 2)\n  })\n})\n\ndescribe(\"margin\", () => {\n  it(\"is the gap between the top two, whatever order they arrive in\", () => {\n    expect(margin([0.6, 0.3, 0.1])).toBeCloseTo(0.3, 10)\n    expect(margin([0.1, 0.6, 0.3])).toBeCloseTo(0.3, 10)\n  })\n\n  it(\"is 0 on a tie and 0 when empty\", () => {\n    expect(margin([0.5, 0.5])).toBeCloseTo(0, 10)\n    expect(margin([])).toBe(0)\n  })\n\n  it(\"yields the lone probability for a single outcome\", () => {\n    expect(margin([0.7])).toBeCloseTo(0.7, 10)\n  })\n})\n\ndescribe(\"confidence and margin disagree, which is why both exist\", () => {\n  // Two plausible answers versus no idea. Same winner, same top mass.\n  const closeSecond = [0.45, 0.42, 0.13]\n  const flatSpread = [0.45, 0.11, 0.11, 0.11, 0.11, 0.11]\n\n  it(\"confidence cannot separate them\", () => {\n    expect(Math.abs(confidence(closeSecond) - confidence(flatSpread))).toBeLessThan(0.05)\n  })\n\n  it(\"margin separates them sharply\", () => {\n    expect(margin(closeSecond)).toBeCloseTo(0.03, 10)\n    expect(margin(flatSpread)).toBeCloseTo(0.34, 10)\n  })\n})\n"],"mappings":";;;;AAGA,SAAS,oBAAoB;CAC3B,GAAG,gDAAgD;EACjD,aAAO,WAAW;GAAC;GAAG;GAAG;EAAC,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,EAAE;CACjD,CAAC;CAED,GAAG,wDAAwD;EACzD,aAAO,WAAW,CAAC,IAAK,EAAG,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,EAAE;EAChD,aAAO,WAAW;GAAC;GAAM;GAAM;GAAM;EAAI,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,EAAE;CAChE,CAAC;CAED,GAAG,sFAAsF;EACvF,aAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;EAC7B,aAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;CAChC,CAAC;CAED,GAAG,oCAAoC;EACrC,MAAM,SAAS,WAAW;GAAC;GAAK;GAAM;EAAI,CAAC;EAC3C,MAAM,UAAU,WAAW;GAAC;GAAK;GAAM;EAAI,CAAC;EAC5C,MAAM,UAAU,WAAW;GAAC;GAAK;GAAM;EAAI,CAAC;EAC5C,aAAO,MAAM,CAAC,CAAC,aAAa,OAAO;EACnC,aAAO,OAAO,CAAC,CAAC,aAAa,OAAO;CACtC,CAAC;CAED,GAAG,0FAA0F;EAC3F,aAAO,WAAW,CAAC,KAAM,GAAI,CAAC,CAAC,CAAC,CAAC,YAAY,KAAM,CAAC;CACtD,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB;CACvB,GAAG,uEAAuE;EACxE,aAAO,OAAO;GAAC;GAAK;GAAK;EAAG,CAAC,CAAC,CAAC,CAAC,YAAY,IAAK,EAAE;EACnD,aAAO,OAAO;GAAC;GAAK;GAAK;EAAG,CAAC,CAAC,CAAC,CAAC,YAAY,IAAK,EAAE;CACrD,CAAC;CAED,GAAG,wCAAwC;EACzC,aAAO,OAAO,CAAC,IAAK,EAAG,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,EAAE;EAC5C,aAAO,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;CAC3B,CAAC;CAED,GAAG,0DAA0D;EAC3D,aAAO,OAAO,CAAC,EAAG,CAAC,CAAC,CAAC,CAAC,YAAY,IAAK,EAAE;CAC3C,CAAC;AACH,CAAC;AAED,SAAS,iEAAiE;CAExE,MAAM,cAAc;EAAC;EAAM;EAAM;CAAI;CACrC,MAAM,aAAa;EAAC;EAAM;EAAM;EAAM;EAAM;EAAM;CAAI;CAEtD,GAAG,yCAAyC;EAC1C,aAAO,KAAK,IAAI,WAAW,WAAW,IAAI,WAAW,UAAU,CAAC,CAAC,CAAC,CAAC,aAAa,GAAI;CACtF,CAAC;CAED,GAAG,uCAAuC;EACxC,aAAO,OAAO,WAAW,CAAC,CAAC,CAAC,YAAY,KAAM,EAAE;EAChD,aAAO,OAAO,UAAU,CAAC,CAAC,CAAC,YAAY,KAAM,EAAE;CACjD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -106,6 +106,14 @@
       "types": "./dist/domain/Turn.d.mts",
       "import": "./dist/domain/Turn.mjs"
     },
+    "./Decision": {
+      "types": "./dist/decision-model/Decision.d.mts",
+      "import": "./dist/decision-model/Decision.mjs"
+    },
+    "./DecisionModel": {
+      "types": "./dist/decision-model/DecisionModel.d.mts",
+      "import": "./dist/decision-model/DecisionModel.mjs"
+    },
     "./Embedding": {
       "types": "./dist/embedding-model/Embedding.d.mts",
       "import": "./dist/embedding-model/Embedding.mjs"
@@ -202,6 +210,10 @@
       "types": "./dist/retry/Retry.d.mts",
       "import": "./dist/retry/Retry.mjs"
     },
+    "./Probability": {
+      "types": "./dist/math/Probability.d.mts",
+      "import": "./dist/math/Probability.mjs"
+    },
     "./Vector": {
       "types": "./dist/math/Vector.d.mts",
       "import": "./dist/math/Vector.mjs"

package/src/decision-model/Decision.test.ts

@@ -0,0 +1,146 @@
+import { describe, it } from "@effect/vitest"
+import { Effect, Layer, Option, Ref, Schema } from "effect"
+import { expect, expectTypeOf } from "vitest"
+import * as AiError from "../domain/AiError.js"
+import * as Decision from "./Decision.js"
+import { decide, DecisionModel, type DecisionModelService } from "./DecisionModel.js"
+
+const triage = Decision.make({
+  inputSchema: Schema.Struct({ message: Schema.String }),
+  decisions: {
+    department: Decision.classify({
+      instructions: "Which team should handle this?",
+      criteria: { billing: "Payments, invoicing", technical: "Bugs, outages" },
+    }),
+    severity: Decision.rate({
+      instructions: "How severe is it?",
+      criteria: ["Cosmetic", "Degraded", "Blocking"],
+    }),
+    urgent: Decision.probability({ instructions: "Does this convey urgency?" }),
+  },
+})
+
+const fixture = {
+  department: { _tag: "Classify", labels: { billing: 0.62, technical: 0.38 } },
+  severity: { _tag: "Rate", levels: [0, 0.7, 0.3], legend: ["Cosmetic", "Degraded", "Blocking"] },
+  urgent: { _tag: "Probability", probability: 0.94 },
+} as const
+
+/**
+ * A fixed fixture cannot prove it satisfies the caller's `Answers<D>`. This is
+ * the boundary a provider casts at too, once it has decoded the wire.
+ */
+const fixed = <D extends Decision.Decisions>(
+  answers: Readonly<Record<string, Decision.Answer>>,
+): Decision.Answers<D> => answers as Decision.Answers<D>
+
+type Call = { readonly input: unknown; readonly model: string }
+
+/** A `DecisionModel` layer that records what reached it. */
+const recording = Effect.gen(function* () {
+  const calls = yield* Ref.make<ReadonlyArray<Call>>([])
+  const service: DecisionModelService = {
+    decide: (_definition, request) =>
+      Effect.as(
+        Ref.update(calls, (seen) => [...seen, { input: request.input, model: request.model }]),
+        { answers: fixed(fixture), usage: {} },
+      ),
+  }
+  return { calls, layer: Layer.succeed(DecisionModel, service) }
+})
+
+describe("the answer map is derived from the definition", () => {
+  it.effect("keeps each decision's label keys and rejects labels it never had", () =>
+    Effect.gen(function* () {
+      const { calls, layer } = yield* recording
+      const result = yield* decide(triage, {
+        model: "jev-latest",
+        input: { message: "hi" },
+      }).pipe(Effect.provide(layer))
+
+      expectTypeOf(result.answers.department.labels).toEqualTypeOf<{
+        readonly billing: number
+        readonly technical: number
+      }>()
+      // @ts-expect-error shipping is not a label of this decision
+      result.answers.department.labels.shipping
+      // @ts-expect-error a Probability answer has no labels
+      result.answers.urgent.labels
+
+      // `decide` forwards both arguments rather than dropping either.
+      expect(yield* Ref.get(calls)).toEqual([{ input: { message: "hi" }, model: "jev-latest" }])
+    }),
+  )
+
+  it("keeps the rubric as a tuple, so levels are positional rather than parsed", () => {
+    type Severity = (typeof triage)["decisions"]["severity"]
+    expectTypeOf<Decision.AnswerFor<Severity>["levels"]>().toEqualTypeOf<
+      readonly [number, number, number]
+    >()
+    expectTypeOf<Decision.AnswerFor<Severity>["legend"]>().toEqualTypeOf<
+      readonly ["Cosmetic", "Degraded", "Blocking"]
+    >()
+  })
+})
+
+describe("reading an answer", () => {
+  it("derives a Probability answer's distribution as [p, 1 - p]", () => {
+    const [yes, no] = Decision.probabilitiesOf(fixture.urgent)
+    expect(yes).toBeCloseTo(0.94, 10)
+    expect(no).toBeCloseTo(0.06, 10)
+  })
+
+  it("ranks labels best first and names the winner", () => {
+    expect(Decision.ranked(fixture.department)).toEqual([
+      { label: "billing", probability: 0.62 },
+      { label: "technical", probability: 0.38 },
+    ])
+    expect(Decision.winner(fixture.department)).toStrictEqual(Option.some("billing"))
+  })
+
+  it("has no winner for an empty label set", () => {
+    expect(Decision.winner({ _tag: "Classify", labels: {} })).toStrictEqual(Option.none())
+  })
+
+  it("reads a rubric by index and by expected value", () => {
+    expect(Decision.topLevel(fixture.severity)).toBe(1)
+    expect(Decision.expectedLevel(fixture.severity)).toBeCloseTo(1.3, 10)
+    expect(fixture.severity.legend[Decision.topLevel(fixture.severity)]).toBe("Degraded")
+  })
+
+  it("resolves a level tie to the lowest index", () => {
+    expect(Decision.topLevel({ _tag: "Rate", levels: [0.5, 0.5], legend: ["a", "b"] })).toBe(0)
+  })
+
+  it("computes certainty for every kind, including Probability", () => {
+    expect(Decision.confidence(fixture.urgent)).toBeCloseTo(0.67, 2)
+    expect(Decision.margin(fixture.urgent)).toBeCloseTo(0.88, 10)
+    expect(Decision.margin(fixture.department)).toBeCloseTo(0.24, 10)
+  })
+})
+
+describe("assertKinds", () => {
+  const supported = ["Classify", "Probability"] as const
+
+  it.effect("passes when every kind is supported", () => {
+    const { department, urgent } = triage.decisions
+    return Decision.assertKinds({ department, urgent }, supported, "nli")
+  })
+
+  it.effect("fails Unsupported and names every offender at once", () =>
+    Effect.gen(function* () {
+      const decisions = {
+        ...triage.decisions,
+        impact: Decision.rate({ instructions: "How bad?", criteria: ["low", "high"] }),
+      }
+      const error = yield* Effect.flip(Decision.assertKinds(decisions, supported, "nli"))
+
+      expect(error).toBeInstanceOf(AiError.Unsupported)
+      if (error._tag !== "Unsupported") return
+
+      expect(error.reason).toContain('"severity" is a Rate')
+      expect(error.reason).toContain('"impact" is a Rate')
+      expect(error.reason).not.toContain("department")
+    }),
+  )
+})

package/src/decision-model/Decision.ts

@@ -0,0 +1,273 @@
+/**
+ * Typed questions about one input, answered with probabilities.
+ *
+ * A {@link Definition} pairs the shape being read with the questions asked of
+ * it. Build one at module scope and apply it per call with
+ * `DecisionModel.decide`.
+ *
+ * @experimental The model class this abstracts is new and the shape may change.
+ */
+import {
+  Array as A,
+  Effect,
+  Match,
+  Number as N,
+  Option,
+  Order,
+  Record,
+  type Schema,
+  pipe,
+} from "effect"
+import * as AiError from "../domain/AiError.js"
+import * as Probability from "../math/Probability.js"
+
+// ---------------------------------------------------------------------------
+// Criteria
+// ---------------------------------------------------------------------------
+
+/** Labels mapped to what each one means. */
+export type Labels = Readonly<Record<string, string>>
+
+/** An ordered rubric, lowest level first. */
+export type Levels = readonly [string, string, ...ReadonlyArray<string>]
+
+/** What a true and a false answer mean, when the boundary is subtle. */
+export type Boundary = { readonly true?: string; readonly false?: string }
+
+// ---------------------------------------------------------------------------
+// Decisions
+// ---------------------------------------------------------------------------
+
+export type ClassifyDecision<L extends Labels = Labels> = {
+  readonly _tag: "Classify"
+  readonly instructions: string
+  readonly criteria: L
+}
+
+export type RateDecision<V extends Levels = Levels> = {
+  readonly _tag: "Rate"
+  readonly instructions: string
+  readonly criteria: V
+}
+
+export type ProbabilityDecision = {
+  readonly _tag: "Probability"
+  readonly instructions: string
+  readonly criteria?: Boundary
+}
+
+export type Decision = ClassifyDecision | RateDecision | ProbabilityDecision
+
+/** Pick one label. Use {@link rate} when the options form a spectrum. */
+export const classify = <const L extends Labels>(decision: {
+  readonly instructions: string
+  readonly criteria: L
+}): ClassifyDecision<L> => ({ _tag: "Classify", ...decision })
+
+/** Place the input on an ordered rubric. */
+export const rate = <const V extends Levels>(decision: {
+  readonly instructions: string
+  readonly criteria: V
+}): RateDecision<V> => ({ _tag: "Rate", ...decision })
+
+/**
+ * How likely a statement is to hold. Named for its answer rather than for an
+ * act, unlike its siblings, so nobody reads the result as a boolean.
+ */
+export const probability = (decision: {
+  readonly instructions: string
+  readonly criteria?: Boundary
+}): ProbabilityDecision => ({ _tag: "Probability", ...decision })
+
+/** Decisions keyed by the name their answer comes back under. */
+export type Decisions = { readonly [name: string]: Decision }
+
+// ---------------------------------------------------------------------------
+// Definition
+// ---------------------------------------------------------------------------
+
+/**
+ * A reusable decision set bound to the shape it reads.
+ *
+ * `inputSchema` encodes the input on the way out, so a schema that omits a
+ * field keeps it from the model. That projection is the supported way to hold
+ * irrelevant or sensitive context out of a request.
+ */
+export type Definition<A_, D extends Decisions = Decisions> = {
+  readonly inputSchema: Schema.Codec<A_, unknown, any, never>
+  readonly decisions: D
+}
+
+/**
+ * Build a decision set. Declare it once at module scope: the questions and
+ * their rubrics are the reviewed artifact, the input changes per call.
+ *
+ * @example
+ * ```ts
+ * const triage = Decision.make({
+ *   inputSchema: Schema.Struct({ message: Schema.String }),
+ *   decisions: {
+ *     department: Decision.classify({
+ *       instructions: "Which team should handle this?",
+ *       criteria: { billing: "Payments, invoicing", technical: "Bugs, outages" },
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export const make = <
+  S extends Schema.Codec<any, any, any, never>,
+  const D extends Decisions,
+>(definition: {
+  readonly inputSchema: S
+  readonly decisions: D
+}): Definition<S["Type"], D> => definition
+
+// ---------------------------------------------------------------------------
+// Answers
+// ---------------------------------------------------------------------------
+
+/**
+ * Score contract for {@link ClassifyAnswer.labels} and
+ * {@link RateAnswer.levels}: probabilities sum to 1 within floating-point
+ * error and are comparable within one answer. Whether they are *calibrated*,
+ * so a stated 0.8 means right about 80% of the time, is a property of the
+ * Layer and is documented per provider. No implementor promises calibration
+ * across requests, across decision kinds, or between a statement and its
+ * negation: `P(claim) != 1 - P(not claim)`. A threshold fitted against one
+ * model does not transfer to another.
+ */
+export type ClassifyAnswer<L extends Labels = Labels> = {
+  readonly _tag: "Classify"
+  readonly labels: Readonly<Record<keyof L & string, number>>
+}
+
+export type RateAnswer<V extends Levels = Levels> = {
+  readonly _tag: "Rate"
+  /** Index-aligned with {@link RateAnswer.legend}. */
+  readonly levels: { readonly [K in keyof V]: number }
+  /** The rubric, echoed so an index reads back as prose. */
+  readonly legend: Readonly<V>
+}
+
+export type ProbabilityAnswer = {
+  readonly _tag: "Probability"
+  readonly probability: number
+}
+
+export type Answer = ClassifyAnswer | RateAnswer | ProbabilityAnswer
+
+/** The answer a decision determines, keeping its labels or rubric. */
+export type AnswerFor<D> = D extends {
+  readonly _tag: "Classify"
+  readonly criteria: infer L extends Labels
+}
+  ? ClassifyAnswer<L>
+  : D extends { readonly _tag: "Rate"; readonly criteria: infer V extends Levels }
+    ? RateAnswer<V>
+    : ProbabilityAnswer
+
+/** Answers keyed by their decision's name. */
+export type Answers<D extends Decisions> = { readonly [K in keyof D]: AnswerFor<D[K]> }
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Fail `AiError.Unsupported` naming every decision whose kind this provider
+ * cannot express. Bucket 1: omitting an answer would leave a hole where
+ * {@link Answers} promises a key.
+ *
+ * Reports all offenders at once, since the definition is known up front.
+ */
+export const assertKinds = (
+  decisions: Decisions,
+  supported: ReadonlyArray<Decision["_tag"]>,
+  provider: string,
+): Effect.Effect<void, AiError.AiError> => {
+  const offenders = pipe(
+    Record.toEntries(decisions),
+    A.filter(([, decision]) => !supported.includes(decision._tag)),
+    A.map(([name, decision]) => `"${name}" is a ${decision._tag}`),
+  )
+  return offenders.length === 0
+    ? Effect.void
+    : Effect.fail(
+        new AiError.Unsupported({
+          provider,
+          capability: "decision",
+          reason: `${provider} answers ${supported.join(" / ")} only; ${offenders.join(", ")}.`,
+        }),
+      )
+}
+
+// ---------------------------------------------------------------------------
+// Reading an answer
+// ---------------------------------------------------------------------------
+
+/** A `Probability` answer's implied distribution is `[p, 1 - p]`. */
+export const probabilitiesOf: (answer: Answer) => ReadonlyArray<number> = Match.type<Answer>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    Classify: (answer) => Record.values(answer.labels),
+    Rate: (answer) => answer.levels,
+    Probability: (answer) => [answer.probability, 1 - answer.probability],
+  }),
+)
+
+/** See {@link Probability.confidence}. Defined for every kind. */
+export const confidence = (answer: Answer): number =>
+  Probability.confidence(probabilitiesOf(answer))
+
+/** See {@link Probability.margin}. Defined for every kind. */
+export const margin = (answer: Answer): number => Probability.margin(probabilitiesOf(answer))
+
+const byProbability = Order.mapInput(
+  Order.flip(Order.Number),
+  (outcome: { readonly probability: number }) => outcome.probability,
+)
+
+/**
+ * Labels best first. Ties keep first-seen order. Also the bridge to rank
+ * fusion: map to `label` and pass alongside another retriever's ordering.
+ */
+export const ranked = <L extends Labels>(
+  answer: ClassifyAnswer<L>,
+): ReadonlyArray<{ readonly label: keyof L & string; readonly probability: number }> =>
+  pipe(
+    Record.toEntries(answer.labels),
+    A.map(([label, probability]) => ({ label, probability })),
+    A.sort(byProbability),
+  )
+
+/** Highest-probability label. `None` only when the label set is empty. */
+export const winner = <L extends Labels>(
+  answer: ClassifyAnswer<L>,
+): Option.Option<keyof L & string> =>
+  pipe(
+    ranked(answer),
+    A.head,
+    Option.map((outcome) => outcome.label),
+  )
+
+/** Index of the highest-probability level. Ties resolve to the lowest. */
+export const topLevel = (answer: RateAnswer): number =>
+  pipe(
+    answer.levels as ReadonlyArray<number>,
+    A.reduce({ index: 0, probability: -Infinity }, (best, probability, index) =>
+      probability > best.probability ? { index, probability } : best,
+    ),
+    (best) => best.index,
+  )
+
+/**
+ * Probability-weighted mean of the level indices, so it can land between
+ * them. Weakly calibrated in practice: a summary, not a magnitude to
+ * interpolate. Use {@link topLevel} with `legend` to name a level instead.
+ */
+export const expectedLevel = (answer: RateAnswer): number =>
+  pipe(
+    answer.levels as ReadonlyArray<number>,
+    A.map((probability, index) => index * probability),
+    N.sumAll,
+  )

package/src/decision-model/DecisionModel.ts

@@ -0,0 +1,53 @@
+import { Context, Effect } from "effect"
+import type * as AiError from "../domain/AiError.js"
+import type * as Decision from "./Decision.js"
+
+/** Optional throughout: not every backing reports token counts. */
+export type DecideUsage = {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+}
+
+export type DecideResponse<D extends Decision.Decisions = Decision.Decisions> = {
+  readonly answers: Decision.Answers<D>
+  readonly usage: DecideUsage
+}
+
+/**
+ * Cross-provider decide request. The input is billed once for the whole
+ * definition, so batching decisions is cheaper than repeating the input.
+ */
+export type CommonDecideRequest<A> = {
+  readonly input: A
+  /** Each provider narrows this to its typed literal union. */
+  readonly model: string
+}
+
+export type DecisionModelService = {
+  readonly decide: <A, D extends Decision.Decisions>(
+    definition: Decision.Definition<A, D>,
+    request: CommonDecideRequest<A>,
+  ) => Effect.Effect<DecideResponse<D>, AiError.AiError>
+}
+
+/**
+ * Answering typed questions about an input with probabilities instead of
+ * generating text. The model reports beliefs; the decision stays in the
+ * caller's code.
+ *
+ * Implementor contract: answer every decision or fail. Omitting one leaves a
+ * hole where {@link DecideResponse} promises a key, so a kind the backing
+ * cannot express is rejected up front with `Decision.assertKinds`.
+ *
+ * @experimental The model class this abstracts is new and the shape may change.
+ */
+export class DecisionModel extends Context.Service<DecisionModel, DecisionModelService>()(
+  "@betalyra/effect-uai/DecisionModel",
+) {}
+
+/** Answer a definition's decisions about one input in one call. */
+export const decide = <A, D extends Decision.Decisions>(
+  definition: Decision.Definition<A, D>,
+  request: CommonDecideRequest<A>,
+): Effect.Effect<DecideResponse<D>, AiError.AiError, DecisionModel> =>
+  Effect.flatMap(DecisionModel, (m) => m.decide(definition, request))