@effect-uai/core 0.15.0 → 0.17.0

package/README.md

@@ -6,22 +6,36 @@ The core thesis: **the user owns the loop**. State is a plain record;
 `Loop` events control iteration; the body is a `Stream`. There is no
 agent runtime, no orchestrator, no provider lock-in.
 
-This package exposes:
-
-- **Domain types** - `Items`, `Turn`, `AiError`
-- **Provider contract** - `LanguageModel`
-- **Loop primitive** - `Loop` (`loop`, `loopWithState`, `value`, `next`, `stop`, `nextAfter`, `onTurnComplete`)
-- **Tools** - `Tool`, `Toolkit`, `Outcome`, `ToolEvent`, `Resolvers`, `HistoryCheck`
-- **Streaming codecs** - `SSE`, `JSONL`, `Lines`
-- **Structured output** - `StructuredFormat`
-- **Observability** - `Metrics`
-- **Testing** - `testing/MockProvider`
-
-No provider deps. Pair with one of:
-
-- [`@effect-uai/responses`](https://www.npmjs.com/package/@effect-uai/responses) - OpenAI Responses API
-- [`@effect-uai/anthropic`](https://www.npmjs.com/package/@effect-uai/anthropic) - Anthropic Messages
-- [`@effect-uai/google`](https://www.npmjs.com/package/@effect-uai/google) - Google Gemini
+## Capabilities
+
+Each is a service tag that provider packages implement, so switching
+provider is swapping a Layer:
+
+- **Language models** - `LanguageModel`, with `Loop`, `Items`, `Turn`,
+  `Tool`, `Toolkit` and `StructuredFormat`
+- **Speech** - `Transcriber` (file and streaming STT),
+  `SpeechSynthesizer` (finished and incremental TTS)
+- **Realtime** - `RealtimeSession`: a live conversation with a realtime
+  model, voice both ways and camera frames where the provider takes them
+- **Embeddings and retrieval** - `EmbeddingModel`, `Reranker`,
+  `Chunker`, `Tokenizer`
+- **Images and music** - `ImageGenerator`, `MusicGenerator`
+- **Web** - `WebSearch`, `WebRead`, `DeepResearch`, `Browser`
+- **Runtime** - `Sandbox` for running model-written code
+- **Messaging** - `Messenger`: the agent as a Telegram, Discord or
+  Slack bot
+
+Plus the pieces underneath: `AiError` (typed failures across every
+capability), streaming codecs (`SSE`, `JSONL`, `Lines`), `Settle` for
+acting on a pause in a stream of arrivals, `Metrics`, and a mock layer
+per capability under `testing/`.
+
+No provider deps. Pair with one or more provider packages:
+[`@effect-uai/openai`](https://www.npmjs.com/package/@effect-uai/openai),
+[`@effect-uai/anthropic`](https://www.npmjs.com/package/@effect-uai/anthropic),
+[`@effect-uai/google`](https://www.npmjs.com/package/@effect-uai/google),
+[`@effect-uai/mistral`](https://www.npmjs.com/package/@effect-uai/mistral)
+and [the rest](https://effect-uai.betalyra.com/providers/).
 
 ## Install
 

package/dist/{AiError-eLV9t1lU.d.mts → AiError-DvhLIbmd.d.mts}

@@ -1,6 +1,6 @@
 import { Duration } from "effect";
 declare namespace AiError_d_exports {
-  export { AiError, AuthFailed, AuthSubtype, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Scope$1 as Scope, Timeout, Unavailable, Unsupported, describe };
+  export { AiError, AuthFailed, AuthSubtype, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Scope$1 as Scope, SessionExpired, Timeout, Unavailable, Unsupported, describe };
 }
 type Scope$1 = "rpm" | "tpm" | "rpd" | "tpd";
 declare const RateLimited_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
@@ -122,12 +122,23 @@ declare class Unsupported extends Unsupported_base<{
   capability: string;
   reason?: string;
 }> {}
-type AiError = RateLimited | Unavailable | Timeout | ContentFiltered | ContextLengthExceeded | InvalidRequest | AuthFailed | Cancelled | IncompleteTurn | GenerationFailed | Unsupported;
+declare const SessionExpired_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "SessionExpired";
+} & Readonly<A>;
+/**
+ * A long-lived session hit the provider's lifetime cap. Distinct from
+ * `Unavailable`: reconnecting works, retrying the same session does not.
+ */
+declare class SessionExpired extends SessionExpired_base<{
+  provider: string;
+  raw?: unknown;
+}> {}
+type AiError = RateLimited | Unavailable | Timeout | ContentFiltered | ContextLengthExceeded | InvalidRequest | AuthFailed | Cancelled | IncompleteTurn | GenerationFailed | Unsupported | SessionExpired;
 /**
  * Short human-readable description of an error, for logs and model-facing
  * failure messages. Prose, not a contract; branch on `_tag` instead.
  */
 declare const describe: (e: AiError) => string;
 //#endregion
-export { Cancelled as a, GenerationFailed as c, RateLimited as d, Scope$1 as f, describe as g, Unsupported as h, AuthSubtype as i, IncompleteTurn as l, Unavailable as m, AiError_d_exports as n, ContentFiltered as o, Timeout as p, AuthFailed as r, ContextLengthExceeded as s, AiError as t, InvalidRequest as u };
-//# sourceMappingURL=AiError-eLV9t1lU.d.mts.map
+export { describe as _, Cancelled as a, GenerationFailed as c, RateLimited as d, Scope$1 as f, Unsupported as g, Unavailable as h, AuthSubtype as i, IncompleteTurn as l, Timeout as m, AiError_d_exports as n, ContentFiltered as o, SessionExpired as p, AuthFailed as r, ContextLengthExceeded as s, AiError as t, InvalidRequest as u };
+//# sourceMappingURL=AiError-DvhLIbmd.d.mts.map

package/dist/{AiError-eLV9t1lU.d.mts.map → AiError-DvhLIbmd.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"AiError-eLV9t1lU.d.mts","names":[],"sources":["../src/domain/AiError.ts"],"mappings":";;;;KAEY;;;;cAEC,oBAAoB;EAC/B;EACA,aAAa,SAAS;EACtB,QAAQ;EACR;EACA;;;;;cAGW,oBAAoB;EAC/B;EACA,aAAa,SAAS;EACtB;EACA;EACA;;;;;cAGW,gBAAgB;EAC3B;EACA;EACA;;;;;cAGW,wBAAwB;EACnC;EACA;EACA;EACA;;;;;cAGW,8BAA8B;EACzC;EACA;EACA;EACA;;;;;cAGW,uBAAuB;EAClC;EACA;EACA;EACA;;KAGU;;;;cAEC,mBAAmB;EAC9B;EACA,SAAS;EACT;;;;;cAGW,kBAAkB;EAC7B;;;;;;;;;;;cASW,yBAAyB;EACpC;EACA;EACA;EACA;EACA;;;;;;;;;;cAQW,uBAAuB;EAClC;;;;;;;;;;;;;;;;;;;cAiBW,oBAAoB;EAC/B;EACA;EACA;;KAGU,UACR,cACA,cACA,UACA,kBACA,wBACA,iBACA,aACA,YACA,iBACA,mBACA;;;;;cASS,WAAW,GAAG"}
+{"version":3,"file":"AiError-DvhLIbmd.d.mts","names":[],"sources":["../src/domain/AiError.ts"],"mappings":";;;;KAEY;;;;cAEC,oBAAoB;EAC/B;EACA,aAAa,SAAS;EACtB,QAAQ;EACR;EACA;;;;;cAGW,oBAAoB;EAC/B;EACA,aAAa,SAAS;EACtB;EACA;EACA;;;;;cAGW,gBAAgB;EAC3B;EACA;EACA;;;;;cAGW,wBAAwB;EACnC;EACA;EACA;EACA;;;;;cAGW,8BAA8B;EACzC;EACA;EACA;EACA;;;;;cAGW,uBAAuB;EAClC;EACA;EACA;EACA;;KAGU;;;;cAEC,mBAAmB;EAC9B;EACA,SAAS;EACT;;;;;cAGW,kBAAkB;EAC7B;;;;;;;;;;;cASW,yBAAyB;EACpC;EACA;EACA;EACA;EACA;;;;;;;;;;cAQW,uBAAuB;EAClC;;;;;;;;;;;;;;;;;;;cAiBW,oBAAoB;EAC/B;EACA;EACA;;;;;;;;;cAOW,uBAAuB;EAClC;EACA;;KAGU,UACR,cACA,cACA,UACA,kBACA,wBACA,iBACA,aACA,YACA,iBACA,mBACA,cACA;;;;;cASS,WAAW,GAAG"}

package/dist/{Loop-B54AB1ME.d.mts → Loop-ChpaO-ya.d.mts}

@@ -1,4 +1,4 @@
-import { l as IncompleteTurn } from "./AiError-eLV9t1lU.mjs";
+import { l as IncompleteTurn } from "./AiError-DvhLIbmd.mjs";
 import { Turn, TurnEvent } from "./domain/Turn.mjs";
 import { Data, Effect, Stream, SubscriptionRef } from "effect";
 declare namespace Loop_d_exports {
@@ -168,4 +168,4 @@ declare const loopWithState: <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>
 }>;
 //#endregion
 export { StopWith as a, loopOver as c, onTurnComplete as d, stop as f, Stop as i, loopWithState as l, Next as n, Value as o, value as p, Step as r, loop as s, Loop_d_exports as t, next as u };
-//# sourceMappingURL=Loop-B54AB1ME.d.mts.map
+//# sourceMappingURL=Loop-ChpaO-ya.d.mts.map

package/dist/{Loop-B54AB1ME.d.mts.map → Loop-ChpaO-ya.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"Loop-B54AB1ME.d.mts","names":[],"sources":["../src/loop/Loop.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;KAwDY,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB;EACA;aAAqB,OAAO;;;;;;;;;;;cAiBf,QAAK,GAAA,GAAA;;;;;GAAE,OAAI,GAAA,GAAA;;;;;GAAE,OAAI,GAAA,GAAA;;GAAE,WAAQ,GAAA,GAAA;;;;;;;cAG7B,QAAS,GAAC,GAAK,MAAI,KAAK;;;;;;cAOxB,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;;;;;;;cAUhD,OAAQ,WAAS,QAAU,MAAI,OAAO,OAAO,YAAY;;;;;;;;;;;;;;;;;;;;;;;;KA8BjE,iBAAiB,GAAG,GAAG,IAAI,MAC5B,OAAO,OAAO,KAAK,GAAG,IAAI,IAAI,MAC9B,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;cAE5C;GACV,GAAG,GAAG,YAAY,YACjB,OAAO,MAAM,SAAS,iBAAiB,GAAG,GAAG,IAAI,OAC/C,GAAG,GACL,QAAQ,OAAO,OAAO,WAAW,GAAG,OACjC,OAAO,OAAO,KAAK,YAAY,GAAG,IAAI,IAAI,KAAK,gBAAgB,IAAI;GACvE,GAAG,GAAG,GAAG,GAAG,YAAY,YACvB,QAAQ,OAAO,OAAO,WAAW,GAAG,IACpC,OAAO,MAAM,SAAS,iBAAiB,GAAG,GAAG,IAAI,MAChD,OAAO,OAAO,KAAK,YAAY,GAAG,IAAI,IAAI,KAAK,gBAAgB,IAAI;;KA2EnE,SAAS,GAAG,GAAG,GAAG,MACrB,OAAO,MACJ,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,KAAK,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG;;;;;;;;;;cAW5E;GACV,GAAG,GAAG,GAAG,GAAG,MAAM,SAAS,GAAG,GAAG,GAAG,MAAM,SAAS,MAAM,OAAO,OAAO,GAAG,GAAG;GAC7E,GAAG,GAAG,GAAG,GAAG,SAAS,GAAG,MAAM,SAAS,GAAG,GAAG,GAAG,KAAK,OAAO,OAAO,GAAG,GAAG;;KA2FvE,aAAa,GAAG,GAAG,GAAG,GAAG,MAC5B,OAAO,GACP,OAAO,MACJ,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,KAAK,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;cAyB5E;GACV,GAAG,GAAG,GAAG,GAAG,GACX,SAAS,GACT,MAAM,aAAa,GAAG,GAAG,GAAG,GAAG,MAC7B,IAAI,IAAI,OAAO,OAAO,OAAO,GAAG,IAAI,QAAQ,OAAO,OAAO,GAAG,IAAI,IAAI,IAAI;GAC5E,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,IAClB,OAAO,OAAO,OAAO,GAAG,IAAI,KAC5B,SAAS,GACT,MAAM,aAAa,GAAG,GAAG,GAAG,GAAG,KAC9B,OAAO,OAAO,GAAG,IAAI,IAAI,IAAI;;;;;;;;;;;;;;;;;;;;;;cAmErB,gBAAiB,GAAG,GAAG,GAAG,GAAC,SAC7B,GAAC,MACJ,SAAS,GAAG,GAAG,GAAG,OACvB,OAAO;WACC,QAAQ,OAAO,OAAO,GAAG,GAAG;WAC5B,OAAO,gBAAgB,gBAAgB"}
+{"version":3,"file":"Loop-ChpaO-ya.d.mts","names":[],"sources":["../src/loop/Loop.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;KAwDY,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB;EACA;aAAqB,OAAO;;;;;;;;;;;cAiBf,QAAK,GAAA,GAAA;;;;;GAAE,OAAI,GAAA,GAAA;;;;;GAAE,OAAI,GAAA,GAAA;;GAAE,WAAQ,GAAA,GAAA;;;;;;;cAG7B,QAAS,GAAC,GAAK,MAAI,KAAK;;;;;;cAOxB,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;;;;;;;cAUhD,OAAQ,WAAS,QAAU,MAAI,OAAO,OAAO,YAAY;;;;;;;;;;;;;;;;;;;;;;;;KA8BjE,iBAAiB,GAAG,GAAG,IAAI,MAC5B,OAAO,OAAO,KAAK,GAAG,IAAI,IAAI,MAC9B,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;cAE5C;GACV,GAAG,GAAG,YAAY,YACjB,OAAO,MAAM,SAAS,iBAAiB,GAAG,GAAG,IAAI,OAC/C,GAAG,GACL,QAAQ,OAAO,OAAO,WAAW,GAAG,OACjC,OAAO,OAAO,KAAK,YAAY,GAAG,IAAI,IAAI,KAAK,gBAAgB,IAAI;GACvE,GAAG,GAAG,GAAG,GAAG,YAAY,YACvB,QAAQ,OAAO,OAAO,WAAW,GAAG,IACpC,OAAO,MAAM,SAAS,iBAAiB,GAAG,GAAG,IAAI,MAChD,OAAO,OAAO,KAAK,YAAY,GAAG,IAAI,IAAI,KAAK,gBAAgB,IAAI;;KA2EnE,SAAS,GAAG,GAAG,GAAG,MACrB,OAAO,MACJ,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,KAAK,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG;;;;;;;;;;cAW5E;GACV,GAAG,GAAG,GAAG,GAAG,MAAM,SAAS,GAAG,GAAG,GAAG,MAAM,SAAS,MAAM,OAAO,OAAO,GAAG,GAAG;GAC7E,GAAG,GAAG,GAAG,GAAG,SAAS,GAAG,MAAM,SAAS,GAAG,GAAG,GAAG,KAAK,OAAO,OAAO,GAAG,GAAG;;KA2FvE,aAAa,GAAG,GAAG,GAAG,GAAG,MAC5B,OAAO,GACP,OAAO,MACJ,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,KAAK,OAAO,OAAO,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG;;;;;;;;;;;;;;;;;;;;;;;;cAyB5E;GACV,GAAG,GAAG,GAAG,GAAG,GACX,SAAS,GACT,MAAM,aAAa,GAAG,GAAG,GAAG,GAAG,MAC7B,IAAI,IAAI,OAAO,OAAO,OAAO,GAAG,IAAI,QAAQ,OAAO,OAAO,GAAG,IAAI,IAAI,IAAI;GAC5E,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,IAClB,OAAO,OAAO,OAAO,GAAG,IAAI,KAC5B,SAAS,GACT,MAAM,aAAa,GAAG,GAAG,GAAG,GAAG,KAC9B,OAAO,OAAO,GAAG,IAAI,IAAI,IAAI;;;;;;;;;;;;;;;;;;;;;;cAmErB,gBAAiB,GAAG,GAAG,GAAG,GAAC,SAC7B,GAAC,MACJ,SAAS,GAAG,GAAG,GAAG,OACvB,OAAO;WACC,QAAQ,OAAO,OAAO,GAAG,GAAG;WAC5B,OAAO,gBAAgB,gBAAgB"}

package/dist/{Toolkit-DAjJ9Tvl.d.mts → Toolkit-tlL0F2YR.d.mts}

@@ -1,7 +1,7 @@
 import { o as HistoryItem, y as ToolCall } from "./Items-C7MyrYPX.mjs";
 import { a as Emit, c as SignalTool, d as ToolE, h as ToolR, l as Tool, n as AnyTool, o as InteractionTool, p as ToolFailed, s as ProviderTool, u as ToolDescriptor } from "./Tool-BF78QWtn.mjs";
 import { Turn } from "./domain/Turn.mjs";
-import { r as Step } from "./Loop-B54AB1ME.mjs";
+import { r as Step } from "./Loop-ChpaO-ya.mjs";
 import { t as ToolResult } from "./ToolResult-BsYQRjmW.mjs";
 import { t as ToolEvent } from "./ToolEvent-Di4a723B.mjs";
 import { Cause, Effect, Stream } from "effect";
@@ -190,4 +190,4 @@ declare const continueWithResults: {
 };
 //#endregion
 export { wrap as S, fromArray as _, ToolMap as a, namespace as b, ToolkitR as c, appendToolResults as d, collectResults as f, descriptors as g, describeFailures as h, NoDuplicateNames as i, Toolkit_d_exports as l, continueWithResults as m, ExecuteOptions as n, Toolkit as o, compose as p, Middleware as r, ToolkitE as s, DuplicateToolName as t, UniqueTools as u, make as v, run as x, makeNamespaced as y };
-//# sourceMappingURL=Toolkit-DAjJ9Tvl.d.mts.map
+//# sourceMappingURL=Toolkit-tlL0F2YR.d.mts.map

package/dist/{Toolkit-DAjJ9Tvl.d.mts.map → Toolkit-tlL0F2YR.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"Toolkit-DAjJ9Tvl.d.mts","names":[],"sources":["../src/tool/Toolkit.ts"],"mappings":";;;;;;;;;;KAqDY,UAAU,eAAe;KAEzB,QAAQ,cAAc,UAAU,WAAW;cAgB1C,aAAc,cAAc,cAAc,aAAQ,OACnD,YAAY,WACrB,WAAW,KAAK,iBAAiB,YAAY;;;;;;;cAQnC,YAAS,OAAW,cAAc,aAAW;;cAG7C,cAAW,SAAa,YAAU,cAAc;;;;;;;;;;KAYjD,SAAS,UAAU,WAAW,gBAAgB,YAAY,MAAM,QAAQ;;;;;;;;KASxE,SAAS,UAAU,WAAW,gBAAgB,YAAY,MAAM,QAAQ;KAY/E,cACH,cAAc,cAAc,UAC5B,+BACE,8BACI,aAAa,kBACV,aAAa,cAAc,YAElC,qBAAqB,OACnB,eACA,cAAc,MAAM,OAAO;KAG5B,mBAAmB;WACb,iCAAiC;;KAGhC,iBAAiB,cAAc,cAAc,aACvD,cAAc,oCAGZ,mBAAmB,cAAc;;KAGzB,YAAY,cAAc,cAAc,YAAY,QAAQ,iBAAiB;KAIpF,oBACH,aAAa,cAAc,UAC3B,+BACE,6BAA6B,aAAa,kBAAkB,aAAa,cAAc,iCAClE,OACnB,oBAAoB,MAAM,QAC1B,cAAc,eAAe,sBAC3B,oBAAoB,MAAM,cAAc,kBACxC,cAAc,eAAe;KAGhC,wBAAwB,aAAa,cAAc,aACtD,oBAAoB,mCAGlB,mBAAmB,oBAAoB;KAEtC,oBAAoB,MAAM,qBAAqB,GAAG,8BACrD,SAAS,cAEP;KAGC,SAAS,aAAa,cAAc,YACvC,oBAAoB,6BAA4B,MAAK,UAAU,UAAU,IAAI,WAAW;;;;;;;;;;cAU7E,0BAA0B;WAC5B;WACA,SAAS;;KAKf,WAAW,uBAAuB,0BAA0B,WAAW;KAEvE,WAAW,uBAAuB,UAAU,WAC/C,UAAU,WAAW,SAAS,SAAS,UAAU,SAAS,SAAS,KAC/D,KAAK,WAAW,QAAQ,IAAI,GAAG,IAAI,GAAG,GAAG,KACzC,UAAU,mBAAmB,SAAS,SAAS,SAAS,KACtD,aAAa,WAAW,QAAQ,IAAI,GAAG,GAAG,KAC1C,UAAU,iBAAiB,SAAS,KAClC,WAAW,WAAW,QAAQ,IAAI,KAClC,UAAU,sBAAsB,SAAS,KACvC,gBAAgB,WAAW,QAAQ,IAAI,KACvC;KAEP,WAAW,uBAAuB,UAAU,uBACrC,WAAW,cAAc,WAAW,QAAQ,KAAK,EAAE,WAAW,UACpE,WAAW,QAAQ,EAAE;;;;;;;cAUd,kBAAmB,6BAA6B,UAAU,SAAO,QACpE,QAAM,SACL,QAAQ,OAChB,QAAQ,WAAW,QAAQ;;cASjB,uBACL,6BACA,cAAc,cAAc,UAAQ,QAElC,WAAM,OACJ,YAAY,WACrB,QAAQ,WAAW,WAAW,KAAK,iBAAiB,YAAY;;;;;;;;cAYtD,gBAAiB,aAAa,cAAc,aAAQ,UAClD,OAAO,wBAAwB,UAC3C,OAAO,OAAO,QAAQ,SAAS,QAAQ;KA6BrC,QAAQ,OAAO,OAAO,QAAQ,GAAG,MACpC,OAAO,OACP,MAAM,KAAK,WACR,OAAO,OAAO,QAAQ,GAAG;;;;;;KAOlB,WAAW,YAAY,eAAe,OAAO,OAAO,QAAQ,GAAG,GACzE,KAAK,QAAQ,OAAO,OAAO,QAAQ,GAAG,IACtC,iBACG,QAAQ,OAAO,OAAO,QAAQ,IAAI,IAAI,IAAI;KAE1C,SAAS,UAAU,SAAS,IAAI,MACnC,UAAU,WAAW,SAAS,SAAS,UAAU,SAAS,SAAS,KAC/D,KAAK,GAAG,GAAG,IAAI,GAAG,IAAI,IAAI,IAAI,MAC9B;KAED,YAAY,UAAU,SAAS,IAAI,kBAC5B,WAAW,IAAI,EAAE,WAAW,UAAU,SAAS,EAAE,IAAI,IAAI,MAAM,EAAE;;;;;;;;;;;;;;;;cAkBhE;GACV,IAAI,IACH,YAAY,WAAW,IAAI,OACzB,UAAU,SAAS,SAAS,MAAM,YAAY,GAAG,IAAI;GACxD,UAAU,SAAS,IAAI,IAAI,SAAS,GAAG,YAAY,WAAW,IAAI,MAAM,YAAY,GAAG,IAAI;;KAezF,aAAa,UAAU,WAC1B,UAAU,WAAW,SAAS,SAAS,UAAU,cAAc,KAC3D,KAAK,GAAG,GAAG,IAAI,WAAW,KAC1B;KAED,gBAAgB,UAAU,uBACnB,WAAW,IAAI,EAAE,WAAW,UAAU,aAAa,EAAE,MAAM,EAAE;;;;;;;;;;;;cAc5D;GACV,GAAG,WAAW,GAAG,gBAAgB,UAAU,SAAS,SAAS,MAAM,gBAAgB;GACnF,UAAU,SAAS,SAAS,GAAG,WAAW,GAAG,SAAS,gBAAgB,gBAAgB;;KAoB7E;WACD;;;;;;;;;;;;cAaE,MAAO,UAAU,SAAO,SAC1B,GAAC,OACH,cAAc,WAAS,UACpB,mBACT,OAAO,OAAO,WAAW,QAAQ,SAAS,aAAa,aAAa,SAAS;;;;;;;;;;;;;cA2InE,oBACV;WAAqB,SAAS,cAAc;GAAc,OAAS,GAAC,MAAQ,UAAI,SACvE,cAAc,gBAAc;;;;;;;;;;;;cAc3B,iBAAkB,GAAG,GAAC,QACzB,OAAO,OAAO,WAAW,GAAG,OACnC,OAAO,OAAO,cAAc,aAAa,GAAG;;;;;;;;;;;;;;;;;cAuBlC;GACV,GACC,QAAQ,SAAS,cAAc,gBAAgB,KAC7C,GAAG,GAAG,QAAQ,OAAO,OAAO,WAAW,GAAG,OAAO,OAAO,OAAO,KAAU,WAAW,IAAI,GAAG;GAC9F,GAAG,GAAG,GACL,QAAQ,OAAO,OAAO,WAAW,GAAG,IACpC,QAAQ,SAAS,cAAc,gBAAgB,IAC9C,OAAO,OAAO,KAAU,WAAW,IAAI,GAAG"}
+{"version":3,"file":"Toolkit-tlL0F2YR.d.mts","names":[],"sources":["../src/tool/Toolkit.ts"],"mappings":"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"}

package/dist/chunker/Chunker.d.mts

@@ -1,4 +1,4 @@
-import { t as AiError } from "../AiError-eLV9t1lU.mjs";
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
 import { Context, Effect } from "effect";
 declare namespace Chunker_d_exports {
   export { Chunk, Chunker, ChunkerService, chunk };

package/dist/decision-model/Decision.d.mts

@@ -0,0 +1,155 @@
+import { t as AiError } from "../AiError-DvhLIbmd.mjs";
+import { Effect, Option, Schema } from "effect";
+declare namespace Decision_d_exports {
+  export { Answer, AnswerFor, Answers, Boundary, ClassifyAnswer, ClassifyDecision, Decision, Decisions, Definition, Labels, Levels, ProbabilityAnswer, ProbabilityDecision, RateAnswer, RateDecision, assertKinds, classify, confidence, expectedLevel, make, margin, probabilitiesOf, probability, ranked, rate, topLevel, winner };
+}
+/** Labels mapped to what each one means. */
+type Labels = Readonly<Record<string, string>>;
+/** An ordered rubric, lowest level first. */
+type Levels = readonly [string, string, ...ReadonlyArray<string>];
+/** What a true and a false answer mean, when the boundary is subtle. */
+type Boundary = {
+  readonly true?: string;
+  readonly false?: string;
+};
+type ClassifyDecision<L extends Labels = Labels> = {
+  readonly _tag: "Classify";
+  readonly instructions: string;
+  readonly criteria: L;
+};
+type RateDecision<V extends Levels = Levels> = {
+  readonly _tag: "Rate";
+  readonly instructions: string;
+  readonly criteria: V;
+};
+type ProbabilityDecision = {
+  readonly _tag: "Probability";
+  readonly instructions: string;
+  readonly criteria?: Boundary;
+};
+type Decision = ClassifyDecision | RateDecision | ProbabilityDecision;
+/** Pick one label. Use {@link rate} when the options form a spectrum. */
+declare const classify: <const L extends Labels>(decision: {
+  readonly instructions: string;
+  readonly criteria: L;
+}) => ClassifyDecision<L>;
+/** Place the input on an ordered rubric. */
+declare const rate: <const V extends Levels>(decision: {
+  readonly instructions: string;
+  readonly criteria: V;
+}) => RateDecision<V>;
+/**
+ * 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.
+ */
+declare const probability: (decision: {
+  readonly instructions: string;
+  readonly criteria?: Boundary;
+}) => ProbabilityDecision;
+/** Decisions keyed by the name their answer comes back under. */
+type Decisions = {
+  readonly [name: string]: Decision;
+};
+/**
+ * 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.
+ */
+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" },
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+declare 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>;
+/**
+ * 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.
+ */
+type ClassifyAnswer<L extends Labels = Labels> = {
+  readonly _tag: "Classify";
+  readonly labels: Readonly<Record<keyof L & string, number>>;
+};
+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>;
+};
+type ProbabilityAnswer = {
+  readonly _tag: "Probability";
+  readonly probability: number;
+};
+type Answer = ClassifyAnswer | RateAnswer | ProbabilityAnswer;
+/** The answer a decision determines, keeping its labels or rubric. */
+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. */
+type Answers<D extends Decisions> = { readonly [K in keyof D]: AnswerFor<D[K]>; };
+/**
+ * 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.
+ */
+declare const assertKinds: (decisions: Decisions, supported: ReadonlyArray<Decision["_tag"]>, provider: string) => Effect.Effect<void, AiError>;
+/** A `Probability` answer's implied distribution is `[p, 1 - p]`. */
+declare const probabilitiesOf: (answer: Answer) => ReadonlyArray<number>;
+/** See {@link Probability.confidence}. Defined for every kind. */
+declare const confidence: (answer: Answer) => number;
+/** See {@link Probability.margin}. Defined for every kind. */
+declare const margin: (answer: Answer) => number;
+/**
+ * Labels best first. Ties keep first-seen order. Also the bridge to rank
+ * fusion: map to `label` and pass alongside another retriever's ordering.
+ */
+declare const ranked: <L extends Labels>(answer: ClassifyAnswer<L>) => ReadonlyArray<{
+  readonly label: keyof L & string;
+  readonly probability: number;
+}>;
+/** Highest-probability label. `None` only when the label set is empty. */
+declare const winner: <L extends Labels>(answer: ClassifyAnswer<L>) => Option.Option<keyof L & string>;
+/** Index of the highest-probability level. Ties resolve to the lowest. */
+declare const topLevel: (answer: RateAnswer) => number;
+/**
+ * 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.
+ */
+declare const expectedLevel: (answer: RateAnswer) => number;
+//#endregion
+export { Answer, AnswerFor, Answers, Boundary, ClassifyAnswer, ClassifyDecision, Decision, Decisions, Definition, Labels, Levels, ProbabilityAnswer, ProbabilityDecision, RateAnswer, RateDecision, assertKinds, classify, confidence, expectedLevel, make, margin, probabilitiesOf, probability, ranked, rate, Decision_d_exports as t, topLevel, winner };
+//# sourceMappingURL=Decision.d.mts.map

package/dist/decision-model/Decision.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decision.d.mts","names":[],"sources":["../../src/decision-model/Decision.ts"],"mappings":";;;;;;KA4BY,SAAS,SAAS;;KAGlB,sCAAsC;;KAGtC;WAAsB;WAAwB;;KAM9C,iBAAiB,UAAU,SAAS;WACrC;WACA;WACA,UAAU;;KAGT,aAAa,UAAU,SAAS;WACjC;WACA;WACA,UAAU;;KAGT;WACD;WACA;WACA,WAAW;;KAGV,WAAW,mBAAmB,eAAe;;cAG5C,iBAAkB,UAAU,QAAM;WACpC;WACA,UAAU;MACjB,iBAAiB;;cAGR,aAAc,UAAU,QAAM;WAChC;WACA,UAAU;MACjB,aAAa;;;;;cAMJ,cAAW;WACb;WACA,WAAW;MAClB;;KAGQ;YAAwB,eAAe;;;;;;;;;KAavC,WAAW,IAAI,UAAU,YAAY;WACtC,aAAa,OAAO,MAAM;WAC1B,WAAW;;;;;;;;;;;;;;;;;;;cAoBT,OACX,UAAU,OAAO,mCACX,UAAU,WAAS;WAEhB,aAAa;WACb,WAAW;MAClB,WAAW,WAAW;;;;;;;;;;;KAgBd,eAAe,UAAU,SAAS;WACnC;WACA,QAAQ,SAAS,aAAa;;KAG7B,WAAW,UAAU,SAAS;WAC/B;;WAEA,oBAAoB,WAAW;;WAE/B,QAAQ,SAAS;;KAGhB;WACD;WACA;;KAGC,SAAS,iBAAiB,aAAa;;KAGvC,UAAU,KAAK;WAChB;WACA,gBAAgB,UAAU;IAEjC,eAAe,KACf;WAAqB;WAAuB,gBAAgB,UAAU;IACpE,WAAW,KACX;;KAGM,QAAQ,UAAU,yBAAyB,WAAW,IAAI,UAAU,EAAE;;;;;;;;cAarE,cAAW,WACX,WAAS,WACT,cAAc,mBAAiB,qBAEzC,OAAO,aAAa;;cAsBV,kBAAkB,QAAQ,WAAW;;cASrC,aAAU,QAAY;;cAItB,SAAM,QAAY;;;;;cAWlB,SAAU,UAAU,QAAM,QAC7B,eAAe,OACtB;WAAyB,aAAa;WAAqB;;;cAQjD,SAAU,UAAU,QAAM,QAC7B,eAAe,OACtB,OAAO,aAAa;;cAQV,WAAQ,QAAY;;;;;;cAcpB,gBAAa,QAAY"}

package/dist/decision-model/Decision.mjs

@@ -0,0 +1,118 @@
+import { n as __exportAll } from "../rolldown-runtime-EAsCxrDo.mjs";
+import { Unsupported } from "../domain/AiError.mjs";
+import { confidence as confidence$1, margin as margin$1 } from "../math/Probability.mjs";
+import { Array, Effect, Match, Number, Option, Order, Record, pipe } from "effect";
+//#region src/decision-model/Decision.ts
+/**
+* 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.
+*/
+var Decision_exports = /* @__PURE__ */ __exportAll({
+	assertKinds: () => assertKinds,
+	classify: () => classify,
+	confidence: () => confidence,
+	expectedLevel: () => expectedLevel,
+	make: () => make,
+	margin: () => margin,
+	probabilitiesOf: () => probabilitiesOf,
+	probability: () => probability,
+	ranked: () => ranked,
+	rate: () => rate,
+	topLevel: () => topLevel,
+	winner: () => winner
+});
+/** Pick one label. Use {@link rate} when the options form a spectrum. */
+const classify = (decision) => ({
+	_tag: "Classify",
+	...decision
+});
+/** Place the input on an ordered rubric. */
+const rate = (decision) => ({
+	_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.
+*/
+const probability = (decision) => ({
+	_tag: "Probability",
+	...decision
+});
+/**
+* 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" },
+*     }),
+*   },
+* })
+* ```
+*/
+const make = (definition) => definition;
+/**
+* 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.
+*/
+const assertKinds = (decisions, supported, provider) => {
+	const offenders = pipe(Record.toEntries(decisions), Array.filter(([, decision]) => !supported.includes(decision._tag)), Array.map(([name, decision]) => `"${name}" is a ${decision._tag}`));
+	return offenders.length === 0 ? Effect.void : Effect.fail(new Unsupported({
+		provider,
+		capability: "decision",
+		reason: `${provider} answers ${supported.join(" / ")} only; ${offenders.join(", ")}.`
+	}));
+};
+/** A `Probability` answer's implied distribution is `[p, 1 - p]`. */
+const probabilitiesOf = Match.type().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. */
+const confidence = (answer) => confidence$1(probabilitiesOf(answer));
+/** See {@link Probability.margin}. Defined for every kind. */
+const margin = (answer) => margin$1(probabilitiesOf(answer));
+const byProbability = Order.mapInput(Order.flip(Order.Number), (outcome) => 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.
+*/
+const ranked = (answer) => pipe(Record.toEntries(answer.labels), Array.map(([label, probability]) => ({
+	label,
+	probability
+})), Array.sort(byProbability));
+/** Highest-probability label. `None` only when the label set is empty. */
+const winner = (answer) => pipe(ranked(answer), Array.head, Option.map((outcome) => outcome.label));
+/** Index of the highest-probability level. Ties resolve to the lowest. */
+const topLevel = (answer) => pipe(answer.levels, Array.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.
+*/
+const expectedLevel = (answer) => pipe(answer.levels, Array.map((probability, index) => index * probability), Number.sumAll);
+//#endregion
+export { assertKinds, classify, confidence, expectedLevel, make, margin, probabilitiesOf, probability, ranked, rate, Decision_exports as t, topLevel, winner };
+
+//# sourceMappingURL=Decision.mjs.map

package/dist/decision-model/Decision.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Decision.mjs","names":["A","AiError.Unsupported","Probability.confidence","Probability.margin","N"],"sources":["../../src/decision-model/Decision.ts"],"sourcesContent":["/**\n * Typed questions about one input, answered with probabilities.\n *\n * A {@link Definition} pairs the shape being read with the questions asked of\n * it. Build one at module scope and apply it per call with\n * `DecisionModel.decide`.\n *\n * @experimental The model class this abstracts is new and the shape may change.\n */\nimport {\n  Array as A,\n  Effect,\n  Match,\n  Number as N,\n  Option,\n  Order,\n  Record,\n  type Schema,\n  pipe,\n} from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport * as Probability from \"../math/Probability.js\"\n\n// ---------------------------------------------------------------------------\n// Criteria\n// ---------------------------------------------------------------------------\n\n/** Labels mapped to what each one means. */\nexport type Labels = Readonly<Record<string, string>>\n\n/** An ordered rubric, lowest level first. */\nexport type Levels = readonly [string, string, ...ReadonlyArray<string>]\n\n/** What a true and a false answer mean, when the boundary is subtle. */\nexport type Boundary = { readonly true?: string; readonly false?: string }\n\n// ---------------------------------------------------------------------------\n// Decisions\n// ---------------------------------------------------------------------------\n\nexport type ClassifyDecision<L extends Labels = Labels> = {\n  readonly _tag: \"Classify\"\n  readonly instructions: string\n  readonly criteria: L\n}\n\nexport type RateDecision<V extends Levels = Levels> = {\n  readonly _tag: \"Rate\"\n  readonly instructions: string\n  readonly criteria: V\n}\n\nexport type ProbabilityDecision = {\n  readonly _tag: \"Probability\"\n  readonly instructions: string\n  readonly criteria?: Boundary\n}\n\nexport type Decision = ClassifyDecision | RateDecision | ProbabilityDecision\n\n/** Pick one label. Use {@link rate} when the options form a spectrum. */\nexport const classify = <const L extends Labels>(decision: {\n  readonly instructions: string\n  readonly criteria: L\n}): ClassifyDecision<L> => ({ _tag: \"Classify\", ...decision })\n\n/** Place the input on an ordered rubric. */\nexport const rate = <const V extends Levels>(decision: {\n  readonly instructions: string\n  readonly criteria: V\n}): RateDecision<V> => ({ _tag: \"Rate\", ...decision })\n\n/**\n * How likely a statement is to hold. Named for its answer rather than for an\n * act, unlike its siblings, so nobody reads the result as a boolean.\n */\nexport const probability = (decision: {\n  readonly instructions: string\n  readonly criteria?: Boundary\n}): ProbabilityDecision => ({ _tag: \"Probability\", ...decision })\n\n/** Decisions keyed by the name their answer comes back under. */\nexport type Decisions = { readonly [name: string]: Decision }\n\n// ---------------------------------------------------------------------------\n// Definition\n// ---------------------------------------------------------------------------\n\n/**\n * A reusable decision set bound to the shape it reads.\n *\n * `inputSchema` encodes the input on the way out, so a schema that omits a\n * field keeps it from the model. That projection is the supported way to hold\n * irrelevant or sensitive context out of a request.\n */\nexport type Definition<A_, D extends Decisions = Decisions> = {\n  readonly inputSchema: Schema.Codec<A_, unknown, any, never>\n  readonly decisions: D\n}\n\n/**\n * Build a decision set. Declare it once at module scope: the questions and\n * their rubrics are the reviewed artifact, the input changes per call.\n *\n * @example\n * ```ts\n * const triage = Decision.make({\n *   inputSchema: Schema.Struct({ message: Schema.String }),\n *   decisions: {\n *     department: Decision.classify({\n *       instructions: \"Which team should handle this?\",\n *       criteria: { billing: \"Payments, invoicing\", technical: \"Bugs, outages\" },\n *     }),\n *   },\n * })\n * ```\n */\nexport const make = <\n  S extends Schema.Codec<any, any, any, never>,\n  const D extends Decisions,\n>(definition: {\n  readonly inputSchema: S\n  readonly decisions: D\n}): Definition<S[\"Type\"], D> => definition\n\n// ---------------------------------------------------------------------------\n// Answers\n// ---------------------------------------------------------------------------\n\n/**\n * Score contract for {@link ClassifyAnswer.labels} and\n * {@link RateAnswer.levels}: probabilities sum to 1 within floating-point\n * error and are comparable within one answer. Whether they are *calibrated*,\n * so a stated 0.8 means right about 80% of the time, is a property of the\n * Layer and is documented per provider. No implementor promises calibration\n * across requests, across decision kinds, or between a statement and its\n * negation: `P(claim) != 1 - P(not claim)`. A threshold fitted against one\n * model does not transfer to another.\n */\nexport type ClassifyAnswer<L extends Labels = Labels> = {\n  readonly _tag: \"Classify\"\n  readonly labels: Readonly<Record<keyof L & string, number>>\n}\n\nexport type RateAnswer<V extends Levels = Levels> = {\n  readonly _tag: \"Rate\"\n  /** Index-aligned with {@link RateAnswer.legend}. */\n  readonly levels: { readonly [K in keyof V]: number }\n  /** The rubric, echoed so an index reads back as prose. */\n  readonly legend: Readonly<V>\n}\n\nexport type ProbabilityAnswer = {\n  readonly _tag: \"Probability\"\n  readonly probability: number\n}\n\nexport type Answer = ClassifyAnswer | RateAnswer | ProbabilityAnswer\n\n/** The answer a decision determines, keeping its labels or rubric. */\nexport type AnswerFor<D> = D extends {\n  readonly _tag: \"Classify\"\n  readonly criteria: infer L extends Labels\n}\n  ? ClassifyAnswer<L>\n  : D extends { readonly _tag: \"Rate\"; readonly criteria: infer V extends Levels }\n    ? RateAnswer<V>\n    : ProbabilityAnswer\n\n/** Answers keyed by their decision's name. */\nexport type Answers<D extends Decisions> = { readonly [K in keyof D]: AnswerFor<D[K]> }\n\n// ---------------------------------------------------------------------------\n// Guards\n// ---------------------------------------------------------------------------\n\n/**\n * Fail `AiError.Unsupported` naming every decision whose kind this provider\n * cannot express. Bucket 1: omitting an answer would leave a hole where\n * {@link Answers} promises a key.\n *\n * Reports all offenders at once, since the definition is known up front.\n */\nexport const assertKinds = (\n  decisions: Decisions,\n  supported: ReadonlyArray<Decision[\"_tag\"]>,\n  provider: string,\n): Effect.Effect<void, AiError.AiError> => {\n  const offenders = pipe(\n    Record.toEntries(decisions),\n    A.filter(([, decision]) => !supported.includes(decision._tag)),\n    A.map(([name, decision]) => `\"${name}\" is a ${decision._tag}`),\n  )\n  return offenders.length === 0\n    ? Effect.void\n    : Effect.fail(\n        new AiError.Unsupported({\n          provider,\n          capability: \"decision\",\n          reason: `${provider} answers ${supported.join(\" / \")} only; ${offenders.join(\", \")}.`,\n        }),\n      )\n}\n\n// ---------------------------------------------------------------------------\n// Reading an answer\n// ---------------------------------------------------------------------------\n\n/** A `Probability` answer's implied distribution is `[p, 1 - p]`. */\nexport const probabilitiesOf: (answer: Answer) => ReadonlyArray<number> = Match.type<Answer>().pipe(\n  Match.discriminatorsExhaustive(\"_tag\")({\n    Classify: (answer) => Record.values(answer.labels),\n    Rate: (answer) => answer.levels,\n    Probability: (answer) => [answer.probability, 1 - answer.probability],\n  }),\n)\n\n/** See {@link Probability.confidence}. Defined for every kind. */\nexport const confidence = (answer: Answer): number =>\n  Probability.confidence(probabilitiesOf(answer))\n\n/** See {@link Probability.margin}. Defined for every kind. */\nexport const margin = (answer: Answer): number => Probability.margin(probabilitiesOf(answer))\n\nconst byProbability = Order.mapInput(\n  Order.flip(Order.Number),\n  (outcome: { readonly probability: number }) => outcome.probability,\n)\n\n/**\n * Labels best first. Ties keep first-seen order. Also the bridge to rank\n * fusion: map to `label` and pass alongside another retriever's ordering.\n */\nexport const ranked = <L extends Labels>(\n  answer: ClassifyAnswer<L>,\n): ReadonlyArray<{ readonly label: keyof L & string; readonly probability: number }> =>\n  pipe(\n    Record.toEntries(answer.labels),\n    A.map(([label, probability]) => ({ label, probability })),\n    A.sort(byProbability),\n  )\n\n/** Highest-probability label. `None` only when the label set is empty. */\nexport const winner = <L extends Labels>(\n  answer: ClassifyAnswer<L>,\n): Option.Option<keyof L & string> =>\n  pipe(\n    ranked(answer),\n    A.head,\n    Option.map((outcome) => outcome.label),\n  )\n\n/** Index of the highest-probability level. Ties resolve to the lowest. */\nexport const topLevel = (answer: RateAnswer): number =>\n  pipe(\n    answer.levels as ReadonlyArray<number>,\n    A.reduce({ index: 0, probability: -Infinity }, (best, probability, index) =>\n      probability > best.probability ? { index, probability } : best,\n    ),\n    (best) => best.index,\n  )\n\n/**\n * Probability-weighted mean of the level indices, so it can land between\n * them. Weakly calibrated in practice: a summary, not a magnitude to\n * interpolate. Use {@link topLevel} with `legend` to name a level instead.\n */\nexport const expectedLevel = (answer: RateAnswer): number =>\n  pipe(\n    answer.levels as ReadonlyArray<number>,\n    A.map((probability, index) => index * probability),\n    N.sumAll,\n  )\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,MAAa,YAAoC,cAGrB;CAAE,MAAM;CAAY,GAAG;AAAS;;AAG5D,MAAa,QAAgC,cAGrB;CAAE,MAAM;CAAQ,GAAG;AAAS;;;;;AAMpD,MAAa,eAAe,cAGA;CAAE,MAAM;CAAe,GAAG;AAAS;;;;;;;;;;;;;;;;;;AAsC/D,MAAa,QAGX,eAG8B;;;;;;;;AA4DhC,MAAa,eACX,WACA,WACA,aACyC;CACzC,MAAM,YAAY,KAChB,OAAO,UAAU,SAAS,GAC1BA,MAAE,QAAQ,GAAG,cAAc,CAAC,UAAU,SAAS,SAAS,IAAI,CAAC,GAC7DA,MAAE,KAAK,CAAC,MAAM,cAAc,IAAI,KAAK,SAAS,SAAS,MAAM,CAC/D;CACA,OAAO,UAAU,WAAW,IACxB,OAAO,OACP,OAAO,KACL,IAAIC,YAAoB;EACtB;EACA,YAAY;EACZ,QAAQ,GAAG,SAAS,WAAW,UAAU,KAAK,KAAK,EAAE,SAAS,UAAU,KAAK,IAAI,EAAE;CACrF,CAAC,CACH;AACN;;AAOA,MAAa,kBAA6D,MAAM,KAAa,CAAC,CAAC,KAC7F,MAAM,yBAAyB,MAAM,CAAC,CAAC;CACrC,WAAW,WAAW,OAAO,OAAO,OAAO,MAAM;CACjD,OAAO,WAAW,OAAO;CACzB,cAAc,WAAW,CAAC,OAAO,aAAa,IAAI,OAAO,WAAW;AACtE,CAAC,CACH;;AAGA,MAAa,cAAc,WACzBC,aAAuB,gBAAgB,MAAM,CAAC;;AAGhD,MAAa,UAAU,WAA2BC,SAAmB,gBAAgB,MAAM,CAAC;AAE5F,MAAM,gBAAgB,MAAM,SAC1B,MAAM,KAAK,MAAM,MAAM,IACtB,YAA8C,QAAQ,WACzD;;;;;AAMA,MAAa,UACX,WAEA,KACE,OAAO,UAAU,OAAO,MAAM,GAC9BH,MAAE,KAAK,CAAC,OAAO,kBAAkB;CAAE;CAAO;AAAY,EAAE,GACxDA,MAAE,KAAK,aAAa,CACtB;;AAGF,MAAa,UACX,WAEA,KACE,OAAO,MAAM,GACbA,MAAE,MACF,OAAO,KAAK,YAAY,QAAQ,KAAK,CACvC;;AAGF,MAAa,YAAY,WACvB,KACE,OAAO,QACPA,MAAE,OAAO;CAAE,OAAO;CAAG,aAAa;AAAU,IAAI,MAAM,aAAa,UACjE,cAAc,KAAK,cAAc;CAAE;CAAO;AAAY,IAAI,IAC5D,IACC,SAAS,KAAK,KACjB;;;;;;AAOF,MAAa,iBAAiB,WAC5B,KACE,OAAO,QACPA,MAAE,KAAK,aAAa,UAAU,QAAQ,WAAW,GACjDI,OAAE,MACJ"}

package/dist/decision-model/Decision.test.mjs

@@ -0,0 +1,164 @@
+import { Unsupported } from "../domain/AiError.mjs";
+import { assertKinds, classify, confidence, expectedLevel, make, margin, probabilitiesOf, probability, ranked, rate, topLevel, winner } from "./Decision.mjs";
+import { DecisionModel, decide } from "./DecisionModel.mjs";
+import { o as describe } from "../utils-CiH_DjFW.mjs";
+import { n as globalExpect } from "../test.DNmyFkvJ-YPzDR0Co.mjs";
+import { t as import_dist } from "../dist-BaenoU1A.mjs";
+import { t as it } from "../dist-nohcnkD6.mjs";
+import { Effect, Layer, Option, Ref, Schema } from "effect";
+//#region src/decision-model/Decision.test.ts
+const triage = make({
+	inputSchema: Schema.Struct({ message: Schema.String }),
+	decisions: {
+		department: classify({
+			instructions: "Which team should handle this?",
+			criteria: {
+				billing: "Payments, invoicing",
+				technical: "Bugs, outages"
+			}
+		}),
+		severity: rate({
+			instructions: "How severe is it?",
+			criteria: [
+				"Cosmetic",
+				"Degraded",
+				"Blocking"
+			]
+		}),
+		urgent: probability({ instructions: "Does this convey urgency?" })
+	}
+});
+const fixture = {
+	department: {
+		_tag: "Classify",
+		labels: {
+			billing: .62,
+			technical: .38
+		}
+	},
+	severity: {
+		_tag: "Rate",
+		levels: [
+			0,
+			.7,
+			.3
+		],
+		legend: [
+			"Cosmetic",
+			"Degraded",
+			"Blocking"
+		]
+	},
+	urgent: {
+		_tag: "Probability",
+		probability: .94
+	}
+};
+/**
+* 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 = (answers) => answers;
+/** A `DecisionModel` layer that records what reached it. */
+const recording = Effect.gen(function* () {
+	const calls = yield* Ref.make([]);
+	return {
+		calls,
+		layer: Layer.succeed(DecisionModel, { decide: (_definition, request) => Effect.as(Ref.update(calls, (seen) => [...seen, {
+			input: request.input,
+			model: request.model
+		}]), {
+			answers: fixed(fixture),
+			usage: {}
+		}) })
+	};
+});
+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));
+		(0, import_dist.expectTypeOf)(result.answers.department.labels).toEqualTypeOf();
+		result.answers.department.labels.shipping;
+		result.answers.urgent.labels;
+		globalExpect(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", () => {
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+		(0, import_dist.expectTypeOf)().toEqualTypeOf();
+	});
+});
+describe("reading an answer", () => {
+	it("derives a Probability answer's distribution as [p, 1 - p]", () => {
+		const [yes, no] = probabilitiesOf(fixture.urgent);
+		globalExpect(yes).toBeCloseTo(.94, 10);
+		globalExpect(no).toBeCloseTo(.06, 10);
+	});
+	it("ranks labels best first and names the winner", () => {
+		globalExpect(ranked(fixture.department)).toEqual([{
+			label: "billing",
+			probability: .62
+		}, {
+			label: "technical",
+			probability: .38
+		}]);
+		globalExpect(winner(fixture.department)).toStrictEqual(Option.some("billing"));
+	});
+	it("has no winner for an empty label set", () => {
+		globalExpect(winner({
+			_tag: "Classify",
+			labels: {}
+		})).toStrictEqual(Option.none());
+	});
+	it("reads a rubric by index and by expected value", () => {
+		globalExpect(topLevel(fixture.severity)).toBe(1);
+		globalExpect(expectedLevel(fixture.severity)).toBeCloseTo(1.3, 10);
+		globalExpect(fixture.severity.legend[topLevel(fixture.severity)]).toBe("Degraded");
+	});
+	it("resolves a level tie to the lowest index", () => {
+		globalExpect(topLevel({
+			_tag: "Rate",
+			levels: [.5, .5],
+			legend: ["a", "b"]
+		})).toBe(0);
+	});
+	it("computes certainty for every kind, including Probability", () => {
+		globalExpect(confidence(fixture.urgent)).toBeCloseTo(.67, 2);
+		globalExpect(margin(fixture.urgent)).toBeCloseTo(.88, 10);
+		globalExpect(margin(fixture.department)).toBeCloseTo(.24, 10);
+	});
+});
+describe("assertKinds", () => {
+	const supported = ["Classify", "Probability"];
+	it.effect("passes when every kind is supported", () => {
+		const { department, urgent } = triage.decisions;
+		return assertKinds({
+			department,
+			urgent
+		}, supported, "nli");
+	});
+	it.effect("fails Unsupported and names every offender at once", () => Effect.gen(function* () {
+		const decisions = {
+			...triage.decisions,
+			impact: rate({
+				instructions: "How bad?",
+				criteria: ["low", "high"]
+			})
+		};
+		const error = yield* Effect.flip(assertKinds(decisions, supported, "nli"));
+		globalExpect(error).toBeInstanceOf(Unsupported);
+		if (error._tag !== "Unsupported") return;
+		globalExpect(error.reason).toContain("\"severity\" is a Rate");
+		globalExpect(error.reason).toContain("\"impact\" is a Rate");
+		globalExpect(error.reason).not.toContain("department");
+	}));
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=Decision.test.mjs.map