@yolk-sdk/agent 0.1.0-canary.95 → 0.1.0-canary.96

package/README.md

@@ -1,6 +1,6 @@
 # @yolk-sdk/agent
 
-Domain-free agent protocol, loop, runtime, Effect-native client, compaction, tools, React, providers, OAuth, skillset, and voice primitives.
+Domain-free agent protocol, loop, runtime, Effect-native client, compaction, classifier models, tools, React, providers, OAuth, skillset, and voice primitives.
 
 Root export is intentionally empty. Import feature APIs from explicit subpaths.
 
@@ -12,46 +12,55 @@ pnpm add @yolk-sdk/agent@canary effect@4.0.0-rc.115
 
 Add `react` if you use `@yolk-sdk/agent/react` or `@yolk-sdk/agent/voice/react`.
 
+Running the experimental `@yolk-sdk/agent/providers/*/conformance` cases? Also add `@yolk-sdk/conformance@canary` (usually as a dev dependency); the cases run through `@yolk-sdk/conformance/runner`.
+
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
 Use the SDK's matching Effect version (`4.0.0-rc.115`) in host code.
 Published package metadata requires Node.js 22+.
 
 ## Subpaths
 
-| Subpath                                                | Purpose                                                        |
-| ------------------------------------------------------ | -------------------------------------------------------------- |
-| `@yolk-sdk/agent/protocol`                             | Wire messages, events, content, usage, tool schemas            |
-| `@yolk-sdk/agent/loop`                                 | Stateless LLM/tool loop                                        |
-| `@yolk-sdk/agent/loop/testing`                         | Faux provider and tool executor test helpers                   |
-| `@yolk-sdk/agent/runtime`                              | Transcript or append-backed runtime orchestration              |
-| `@yolk-sdk/agent/client`                               | HTTP/NDJSON transport, HITL resume, retry/error state helpers  |
-| `@yolk-sdk/agent/compaction`                           | Host-owned compaction budgets, checkpoints, formatting, retry  |
-| `@yolk-sdk/agent/tools`                                | Tool registry, typed inputs, interactions, subagents/questions |
-| `@yolk-sdk/agent/react`                                | Headless React chat hook, reducer, selectors, and render model |
-| `@yolk-sdk/agent/oauth`                                | Provider-neutral OAuth token and broker contracts              |
-| `@yolk-sdk/agent/providers/openai`                     | OpenAI/Codex OAuth and broker helpers                          |
-| `@yolk-sdk/agent/providers/openai/codex`               | OpenAI Codex request and auth helpers                          |
-| `@yolk-sdk/agent/providers/openai/codex-usage`         | Codex subscription-allowance snapshots                         |
-| `@yolk-sdk/agent/providers/openai/codex-provider`      | Codex LLM provider factory                                     |
-| `@yolk-sdk/agent/providers/openai/provider`            | OpenAI-compatible LLM provider factory                         |
-| `@yolk-sdk/agent/providers/openai/realtime`            | OpenAI Realtime session config and event codecs                |
-| `@yolk-sdk/agent/providers/openai/speech`              | OpenAI text-to-speech and transcription adapters               |
-| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider` | Vercel AI Gateway Chat Completions provider factory            |
-| `@yolk-sdk/agent/providers/opencode/go-provider`       | OpenCode Go Chat Completions, Messages, and Responses provider |
-| `@yolk-sdk/agent/providers/opencode/usage`             | OpenCode Go subscription-allowance snapshots                   |
-| `@yolk-sdk/agent/providers/anthropic`                  | Anthropic/Claude OAuth and broker helpers                      |
-| `@yolk-sdk/agent/providers/anthropic/claude`           | Claude request and auth helpers                                |
-| `@yolk-sdk/agent/providers/anthropic/usage`            | Claude subscription-allowance snapshots                        |
-| `@yolk-sdk/agent/providers/anthropic/claude-provider`  | Claude LLM provider factory                                    |
-| `@yolk-sdk/agent/providers/xai`                        | Grok subscription OAuth and token broker helpers               |
-| `@yolk-sdk/agent/providers/xai/grok`                   | Grok subscription request and auth helpers                     |
-| `@yolk-sdk/agent/providers/xai/grok-provider`          | Grok subscription LLM provider factory                         |
-| `@yolk-sdk/agent/providers/xai/usage`                  | Grok subscription-allowance snapshots                          |
-| `@yolk-sdk/agent/providers/subscription-usage`         | Shared allowance snapshot and safe error schemas               |
-| `@yolk-sdk/agent/skillset`                             | Portable skill and slash-command parsing/catalogs              |
-| `@yolk-sdk/agent/voice`                                | Voice protocol, controller, tool handler, projection, speech   |
-| `@yolk-sdk/agent/voice/browser`                        | Browser WebRTC voice transport                                 |
-| `@yolk-sdk/agent/voice/react`                          | Headless browser voice React hook                              |
+| Subpath                                                  | Purpose                                                                                       |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@yolk-sdk/agent/protocol`                               | Wire messages, events, content, usage, tool schemas                                           |
+| `@yolk-sdk/agent/loop`                                   | Stateless LLM/tool loop                                                                       |
+| `@yolk-sdk/agent/loop/testing`                           | Faux provider and tool executor test helpers                                                  |
+| `@yolk-sdk/agent/runtime`                                | Transcript or append-backed runtime orchestration                                             |
+| `@yolk-sdk/agent/client`                                 | HTTP/NDJSON transport, HITL resume, retry/error state helpers                                 |
+| `@yolk-sdk/agent/compaction`                             | Host-owned compaction budgets, checkpoints, formatting, retry                                 |
+| `@yolk-sdk/agent/classification`                         | Classifier model contract: typed questions, answers, usage, errors                            |
+| `@yolk-sdk/agent/tools`                                  | Tool registry, typed inputs, interactions, subagents/questions                                |
+| `@yolk-sdk/agent/react`                                  | Headless React chat hook, reducer, selectors, and render model                                |
+| `@yolk-sdk/agent/oauth`                                  | Provider-neutral OAuth token and broker contracts                                             |
+| `@yolk-sdk/agent/providers/openai`                       | OpenAI/Codex OAuth and broker helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex`                 | OpenAI Codex request and auth helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex-usage`           | Codex subscription-allowance snapshots                                                        |
+| `@yolk-sdk/agent/providers/openai/codex-provider`        | Codex LLM provider factory                                                                    |
+| `@yolk-sdk/agent/providers/openai/provider`              | OpenAI-compatible LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/openai/conformance`           | Synthetic OpenAI chat, Codex Responses, and Codex usage fixtures and conformance cases        |
+| `@yolk-sdk/agent/providers/openai/realtime`              | OpenAI Realtime session config and event codecs                                               |
+| `@yolk-sdk/agent/providers/openai/speech`                | OpenAI text-to-speech and transcription adapters                                              |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider`   | Vercel AI Gateway Chat Completions provider factory                                           |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` | Vercel AI Gateway classifier (`POST /v1/evaluate`) layer                                      |
+| `@yolk-sdk/agent/providers/vercel/conformance`           | Verified Gateway chat fixtures, synthetic classifier fixtures, and conformance cases          |
+| `@yolk-sdk/agent/providers/opencode/go-provider`         | OpenCode Go Chat Completions, Messages, and Responses provider                                |
+| `@yolk-sdk/agent/providers/opencode/usage`               | OpenCode Go subscription-allowance snapshots                                                  |
+| `@yolk-sdk/agent/providers/opencode/conformance`         | Synthetic OpenCode Go (per protocol, commentary replay, usage) fixtures and conformance cases |
+| `@yolk-sdk/agent/providers/anthropic`                    | Anthropic/Claude OAuth and broker helpers                                                     |
+| `@yolk-sdk/agent/providers/anthropic/claude`             | Claude request and auth helpers                                                               |
+| `@yolk-sdk/agent/providers/anthropic/usage`              | Claude subscription-allowance snapshots                                                       |
+| `@yolk-sdk/agent/providers/anthropic/claude-provider`    | Claude LLM provider factory                                                                   |
+| `@yolk-sdk/agent/providers/anthropic/conformance`        | Synthetic Anthropic Messages and Claude usage fixtures and conformance cases                  |
+| `@yolk-sdk/agent/providers/xai`                          | Grok subscription OAuth and token broker helpers                                              |
+| `@yolk-sdk/agent/providers/xai/grok`                     | Grok subscription request and auth helpers                                                    |
+| `@yolk-sdk/agent/providers/xai/grok-provider`            | Grok subscription LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/xai/usage`                    | Grok subscription-allowance snapshots                                                         |
+| `@yolk-sdk/agent/providers/xai/conformance`              | Synthetic Grok Responses and Grok usage fixtures and conformance cases                        |
+| `@yolk-sdk/agent/providers/subscription-usage`           | Shared allowance snapshot and safe error schemas                                              |
+| `@yolk-sdk/agent/skillset`                               | Portable skill and slash-command parsing/catalogs                                             |
+| `@yolk-sdk/agent/voice`                                  | Voice protocol, controller, tool handler, projection, speech                                  |
+| `@yolk-sdk/agent/voice/browser`                          | Browser WebRTC voice transport                                                                |
+| `@yolk-sdk/agent/voice/react`                            | Headless browser voice React hook                                                             |
 
 ## Imports
 
@@ -248,7 +257,7 @@ const usageEffect = fetchOpenCodeGoSubscriptionUsage(Redacted.make(hostOpenCodeG
 }).pipe(Effect.provide(FetchHttpClient.layer))
 ```
 
-The fixed API-key endpoint returns used percentages/reset instants for `five-hour`, `seven-day`, and
+The API-key endpoint (default `openCodeGoSubscriptionUsageUrl`) returns used percentages/reset instants for `five-hour`, `seven-day`, and
 `monthly` windows. Monthly resets follow the subscription's anniversary, not the first of the month;
 the adapter preserves the provider's timestamp. Missing/invalid percentages are omitted, not treated
 as zero. Treat snapshots as best-effort; hosts own polling, stale-data policy, persistence, and UI.
@@ -430,7 +439,8 @@ version.
 Provider adapters return an immutable Effect `Chunk` of semantic window ids, percentages, and
 optional reset/duration fields; hosts own labels, polling, persistence, stale-data policy, alert
 thresholds, billing interpretation, and UI. Configure `requestTimeoutMs` at the server integration
-boundary. Endpoint origins stay fixed, and `FetchHttpClient.layer` is configured for manual
+boundary. Each fetcher defaults to its exported URL constant; the optional `url` override is only
+for a trusted proxy or local emulator, because the credential is sent to it. `FetchHttpClient.layer` is configured for manual
 redirects. A custom `HttpClient` must not follow redirects for these credential-bearing requests.
 
 Subscription allowance snapshots are separate from protocol `AgentUsage`, which accounts for tokens
@@ -748,6 +758,47 @@ handler, approval HITL, transcript projection, and one-shot TTS/STT contracts.
   overflow such as `{"n":1e999}` takes the same mapper-specific fallbacks. Approval identifiers,
   gates, deny, and execution schema validation are unchanged.
 
+## Classifier models
+
+`@yolk-sdk/agent/classification` is a provider-neutral contract for classifier models such as
+TypeSafe's Jev: one `state` (a string, JSON object, or JSON array) and named `boolean`, `choice`
+(2-255 options), or `score` (2-10 levels, lowest first) questions, answered together with
+probabilities. `classify` types each answer from its question (a choice answer's `choice` is the
+union of its option keys) and checks every answer against its question. Probabilities are kept as
+returned, never renormalized. Failures are typed (`ClassificationRequestInvalid`,
+`ClassificationProviderError`, `ClassificationResponseInvalid`); a response that fails to decode
+keeps the billed `usage`. Classification is a read; authorization stays host policy.
+
+`@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` calls AI Gateway `POST /v1/evaluate`
+(Gateway calls this evaluation) with `typesafe-ai/jev` by default and the same Gateway credential
+as the chat provider:
+
+```ts
+import { Effect, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
+import { classify } from '@yolk-sdk/agent/classification'
+import { makeVercelAiGatewayClassifierLayer } from '@yolk-sdk/agent/providers/vercel/ai-gateway-classifier'
+
+const program = classify({
+  state: { subject: 'Invoice question', body: 'I was charged twice.' },
+  questions: {
+    route: {
+      type: 'choice',
+      instructions: 'Which team should handle this ticket?',
+      criteria: { billing: 'Payments and refunds.', bug: 'Product defects.' }
+    }
+  }
+}).pipe(
+  Effect.map(result => result.answers.route.choice), // 'billing' | 'bug'
+  Effect.provide(makeVercelAiGatewayClassifierLayer({ apiKey: Redacted.make(gatewayKey) })),
+  Effect.provide(FetchHttpClient.layer)
+)
+```
+
+`providerOptions` passes through unchanged (for example `{ gateway: { zeroDataRetention: true } }`).
+`providerMetadata.gateway.cost` becomes `usage.costUsd`, and `x-ai-gateway-evaluation-fallback-*`
+response headers are kept in `providerMetadata.evaluationFallbackHeaders`.
+
 ## Subagents
 
 `subagent` is the package-owned contract for child-agent delegation. The SDK provides schema,
@@ -838,6 +889,28 @@ Without a host, definitions, approval ids, and inline behavior are unchanged.
 - Hosts own authorization, status/wait tools, cancellation, terminal storage, usage, and delivery.
   Never append a second result for the original call.
 
+## Code mode tool contract
+
+These options are the tool contract that [`@yolk-sdk/codemode`](../codemode/README.md) builds on.
+This package declares them; it does not run scripts.
+
+- `makeTool({ output })` adds declaration-only `ToolDef.outputSchema`, lowered like `parameters`.
+- `callableBy: 'all' | 'model' | 'codemode'` (default `all`) decides who may call a tool. For
+  `codemode` only, `discovery: 'listed' | 'search'` (default `listed`) decides how scripts find it.
+  Codemode-only tools never reach providers. Approval, input, interaction, activated background,
+  `question`, `subagent`, and nested-access tools never run from code mode; `resolveTools` rejects
+  `callableBy: 'codemode'` on them.
+- `nestedToolAccess: true` gives a registration's `execute` a `nested` executor over the other
+  code-mode-callable tools of the same resolution and host context. Nested calls run through the
+  resolved execute path and fail closed with model-visible error results. Assign nested call ids as
+  `<parentToolCallId>/<seq>`.
+- `describe: ({ tools }) => string` on a nested-access registration computes its resolved
+  description from those nested tools; `def.description` stays the static fallback.
+- Report nested calls with protocol `recordNestedToolCall` and `nestedToolCallResultFields`. The
+  bounded `ToolResult.nestedCalls` record and summed `ToolResult.usage` never reach the model:
+  `toolResultMessageFromResult` drops both, and the loop does not add `ToolResult.usage` to run
+  usage. Capture them from the `ToolResult` or tool events when you need audit or billing records.
+
 ## Tool failures
 
 Use `modelVisibleToolError(...)` for expected tool-domain failures the model can recover
@@ -867,12 +940,16 @@ aborts, and implementation bugs outside typed tool execution.
 - Persist/return one `ToolResultMessage` for every host tool call, including `isError` failures.
 - Persist terminal provider failures and clear active run ids where applicable.
 - Provide tools, approval policy, auth, storage, and observability.
+- If you send `ToolDef`s to providers yourself (outside `run`/`runModelTurn`), filter them with
+  protocol `providerToolDefs`; codemode-only tools must never reach providers. Executor decorators
+  outside `ResolvedToolSet.execute` do not see nested code mode calls.
 - Compact context and decide memory/search policy.
 
 ## Boundaries
 
 - Core loop/protocol/runtime/tools have no React, Next.js, provider SDKs, auth, storage drivers, or app concepts.
 - `@yolk-sdk/agent/compaction` combines pure planning/formatting helpers with Effect-native transformer and retry adapters; hosts own thresholds, summaries, compaction payloads, and durable compactor policy.
+- `@yolk-sdk/agent/classification` is provider-neutral (no Node, React, or provider code); provider subpaths supply `ClassifierModel` layers.
 - `@yolk-sdk/agent/react` is headless and uses React as an optional peer.
 - Provider subpaths own vendor wire/auth mechanics only; hosts own token storage, refresh, routing, and policy.
 - `@yolk-sdk/agent/providers/openai/speech` is server integration requiring runtime

package/dist/classification/errors.d.mts

@@ -0,0 +1,57 @@
+import * as Schema from "effect/Schema";
+import { ProviderErrorInfo } from "@yolk-sdk/agent/protocol";
+
+//#region src/classification/errors.d.ts
+/**
+ * Why an answer does not fit its question:
+ *
+ * - `missing_answer`: a question has no answer.
+ * - `unexpected_answer`: an answer names no question that was asked.
+ * - `type_mismatch`: the answer's `type` is not the question's.
+ * - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.
+ * - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.
+ * - `invalid_choice`: a choice answer names no option of its question.
+ * - `invalid_score`: a score answer has no finite `score`.
+ * - `malformed_answer`: the answer is not an object.
+ */
+declare const ClassificationAnswerIssueReason: Schema.Literals<readonly ["missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+type ClassificationAnswerIssueReason = typeof ClassificationAnswerIssueReason.Type;
+/** `malformed_response`: the response body is not the provider's documented envelope. */
+declare const ClassificationResponseIssue: Schema.Literals<readonly ["malformed_response", "missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+type ClassificationResponseIssue = typeof ClassificationResponseIssue.Type;
+declare const ClassificationRequestInvalid_base: Schema.Class<ClassificationRequestInvalid, Schema.TaggedStruct<"ClassificationRequestInvalid", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The request does not satisfy the classification contract; nothing was sent. */
+declare class ClassificationRequestInvalid extends ClassificationRequestInvalid_base {}
+declare const ClassificationProviderError_base: Schema.Class<ClassificationProviderError, Schema.TaggedStruct<"ClassificationProviderError", {
+  readonly message: Schema.String;
+  readonly retryable: Schema.Boolean;
+  readonly provider: typeof ProviderErrorInfo;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The provider could not be reached or rejected the request. `message` is safe to show: it never
+ * carries provider bodies, headers, or credentials. `provider` classifies the failure (status,
+ * provider error code, retry delay).
+ */
+declare class ClassificationProviderError extends ClassificationProviderError_base {}
+declare const ClassificationResponseInvalid_base: Schema.Class<ClassificationResponseInvalid, Schema.TaggedStruct<"ClassificationResponseInvalid", {
+  readonly message: Schema.String; /** Provider id, when a provider (not the typed `classify` check) found the issue. */
+  readonly provider: Schema.optional<Schema.String>;
+  readonly reason: Schema.Literals<readonly ["malformed_response", "missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+  readonly questionId: Schema.optional<Schema.String>;
+  readonly usage: Schema.optional<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly costUsd: Schema.optionalKey<Schema.Finite>;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The provider answered, but the response or one of its answers does not fit the request.
+ * `usage` is kept when the provider reported it, because the request was billed.
+ */
+declare class ClassificationResponseInvalid extends ClassificationResponseInvalid_base {}
+type ClassificationError = ClassificationRequestInvalid | ClassificationProviderError | ClassificationResponseInvalid;
+//#endregion
+export { ClassificationAnswerIssueReason, ClassificationError, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue };
+//# sourceMappingURL=errors.d.mts.map

package/dist/classification/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/classification/errors.ts"],"mappings":";;;;;;AAgBA;;;;AAA4C;AAW5C;;;;AAAyF;cAX5E,+BAAA,EAA+B,MAAA,CAAA,QAAA;AAAA,KAWhC,+BAAA,UAAyC,+BAAA,CAAgC,IAAI;;cAG5E,2BAAA,EAA2B,MAAA,CAAA,QAAA;AAAA,KAK5B,2BAAA,UAAqC,2BAAA,CAA4B,IAAI;AAAA,cAAA,iCAAA;;;;cAGpE,4BAAA,SAAqC,iCAKjD;AAAA,cAAG,gCAAA;;;;;;;;;;cAOS,2BAAA,SAAoC,gCAOhD;AAAA,cAAG,kCAAA;;;;;;;;;;;AAdA;;;;AAAA,cAoBS,6BAAA,SAAsC,kCAUlD;AAAA,KAEW,mBAAA,GACR,4BAAA,GACA,2BAAA,GACA,6BAAA"}

package/dist/classification/errors.mjs

@@ -0,0 +1,56 @@
+import { ClassificationUsage } from "./schema.mjs";
+import * as Schema from "effect/Schema";
+import { ProviderErrorInfo } from "@yolk-sdk/agent/protocol";
+//#region src/classification/errors.ts
+/**
+* Why an answer does not fit its question:
+*
+* - `missing_answer`: a question has no answer.
+* - `unexpected_answer`: an answer names no question that was asked.
+* - `type_mismatch`: the answer's `type` is not the question's.
+* - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.
+* - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.
+* - `invalid_choice`: a choice answer names no option of its question.
+* - `invalid_score`: a score answer has no finite `score`.
+* - `malformed_answer`: the answer is not an object.
+*/
+const ClassificationAnswerIssueReason = Schema.Literals([
+	"missing_answer",
+	"unexpected_answer",
+	"type_mismatch",
+	"invalid_probability",
+	"invalid_confidence",
+	"invalid_choice",
+	"invalid_score",
+	"malformed_answer"
+]);
+/** `malformed_response`: the response body is not the provider's documented envelope. */
+const ClassificationResponseIssue = Schema.Literals(["malformed_response", ...ClassificationAnswerIssueReason.literals]);
+/** The request does not satisfy the classification contract; nothing was sent. */
+var ClassificationRequestInvalid = class extends Schema.TaggedError()("ClassificationRequestInvalid", { message: Schema.String }) {};
+/**
+* The provider could not be reached or rejected the request. `message` is safe to show: it never
+* carries provider bodies, headers, or credentials. `provider` classifies the failure (status,
+* provider error code, retry delay).
+*/
+var ClassificationProviderError = class extends Schema.TaggedError()("ClassificationProviderError", {
+	message: Schema.String,
+	retryable: Schema.Boolean,
+	provider: ProviderErrorInfo
+}) {};
+/**
+* The provider answered, but the response or one of its answers does not fit the request.
+* `usage` is kept when the provider reported it, because the request was billed.
+*/
+var ClassificationResponseInvalid = class extends Schema.TaggedError()("ClassificationResponseInvalid", {
+	message: Schema.String,
+	/** Provider id, when a provider (not the typed `classify` check) found the issue. */
+	provider: Schema.optional(Schema.String),
+	reason: ClassificationResponseIssue,
+	questionId: Schema.optional(Schema.String),
+	usage: Schema.optional(ClassificationUsage)
+}) {};
+//#endregion
+export { ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/classification/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/classification/errors.ts"],"sourcesContent":["import * as Schema from 'effect/Schema'\nimport { ProviderErrorInfo } from '@yolk-sdk/agent/protocol'\nimport { ClassificationUsage } from './schema.ts'\n\n/**\n * Why an answer does not fit its question:\n *\n * - `missing_answer`: a question has no answer.\n * - `unexpected_answer`: an answer names no question that was asked.\n * - `type_mismatch`: the answer's `type` is not the question's.\n * - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.\n * - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.\n * - `invalid_choice`: a choice answer names no option of its question.\n * - `invalid_score`: a score answer has no finite `score`.\n * - `malformed_answer`: the answer is not an object.\n */\nexport const ClassificationAnswerIssueReason = Schema.Literals([\n  'missing_answer',\n  'unexpected_answer',\n  'type_mismatch',\n  'invalid_probability',\n  'invalid_confidence',\n  'invalid_choice',\n  'invalid_score',\n  'malformed_answer'\n])\n\nexport type ClassificationAnswerIssueReason = typeof ClassificationAnswerIssueReason.Type\n\n/** `malformed_response`: the response body is not the provider's documented envelope. */\nexport const ClassificationResponseIssue = Schema.Literals([\n  'malformed_response',\n  ...ClassificationAnswerIssueReason.literals\n])\n\nexport type ClassificationResponseIssue = typeof ClassificationResponseIssue.Type\n\n/** The request does not satisfy the classification contract; nothing was sent. */\nexport class ClassificationRequestInvalid extends Schema.TaggedError<ClassificationRequestInvalid>()(\n  'ClassificationRequestInvalid',\n  {\n    message: Schema.String\n  }\n) {}\n\n/**\n * The provider could not be reached or rejected the request. `message` is safe to show: it never\n * carries provider bodies, headers, or credentials. `provider` classifies the failure (status,\n * provider error code, retry delay).\n */\nexport class ClassificationProviderError extends Schema.TaggedError<ClassificationProviderError>()(\n  'ClassificationProviderError',\n  {\n    message: Schema.String,\n    retryable: Schema.Boolean,\n    provider: ProviderErrorInfo\n  }\n) {}\n\n/**\n * The provider answered, but the response or one of its answers does not fit the request.\n * `usage` is kept when the provider reported it, because the request was billed.\n */\nexport class ClassificationResponseInvalid extends Schema.TaggedError<ClassificationResponseInvalid>()(\n  'ClassificationResponseInvalid',\n  {\n    message: Schema.String,\n    /** Provider id, when a provider (not the typed `classify` check) found the issue. */\n    provider: Schema.optional(Schema.String),\n    reason: ClassificationResponseIssue,\n    questionId: Schema.optional(Schema.String),\n    usage: Schema.optional(ClassificationUsage)\n  }\n) {}\n\nexport type ClassificationError =\n  | ClassificationRequestInvalid\n  | ClassificationProviderError\n  | ClassificationResponseInvalid\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,MAAa,kCAAkC,OAAO,SAAS;CAC7D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAKD,MAAa,8BAA8B,OAAO,SAAS,CACzD,sBACA,GAAG,gCAAgC,QACrC,CAAC;;AAKD,IAAa,+BAAb,cAAkD,OAAO,YAA0C,EACjG,gCACA,EACE,SAAS,OAAO,OAClB,CACF,EAAE,CAAC;;;;;;AAOH,IAAa,8BAAb,cAAiD,OAAO,YAAyC,EAC/F,+BACA;CACE,SAAS,OAAO;CAChB,WAAW,OAAO;CAClB,UAAU;AACZ,CACF,EAAE,CAAC;;;;;AAMH,IAAa,gCAAb,cAAmD,OAAO,YAA2C,EACnG,iCACA;CACE,SAAS,OAAO;;CAEhB,UAAU,OAAO,SAAS,OAAO,MAAM;CACvC,QAAQ;CACR,YAAY,OAAO,SAAS,OAAO,MAAM;CACzC,OAAO,OAAO,SAAS,mBAAmB;AAC5C,CACF,EAAE,CAAC"}

package/dist/classification/index.d.mts

@@ -0,0 +1,4 @@
+import { ClassificationAnswerIssueReason, ClassificationError, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue } from "./errors.mjs";
+import { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationRequest, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestionType, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels } from "./schema.mjs";
+import { ClassificationAnswerIssue, ClassificationRequestFor, ClassificationResultFor, ClassifierAnswerFor, ClassifierAnswersFor, ClassifierModel, ClassifierQuestionsInput, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor } from "./model.mjs";
+export { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, type ClassificationAnswerIssue, ClassificationAnswerIssueReason, type ClassificationError, ClassificationProviderError, ClassificationRequest, type ClassificationRequestFor, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue, ClassificationResult, type ClassificationResultFor, ClassificationUsage, ClassifierAnswer, type ClassifierAnswerFor, type ClassifierAnswersFor, ClassifierCriterion, ClassifierModel, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, type ClassifierQuestionType, ClassifierQuestions, type ClassifierQuestionsInput, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels };

package/dist/classification/index.mjs

@@ -0,0 +1,4 @@
+import { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationRequest, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels } from "./schema.mjs";
+import { ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue } from "./errors.mjs";
+import { ClassifierModel, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor } from "./model.mjs";
+export { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequest, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierModel, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels };

package/dist/classification/model.d.mts

@@ -0,0 +1,74 @@
+import { ClassificationAnswerIssueReason, ClassificationError, ClassificationRequestInvalid } from "./errors.mjs";
+import { BooleanClassifierAnswer, ChoiceClassifierAnswer, ClassificationRequest, ClassificationResult, ClassifierAnswer, ClassifierQuestion, ScoreClassifierAnswer } from "./schema.mjs";
+import { Context, Effect, Result } from "effect";
+
+//#region src/classification/model.d.ts
+declare const ClassifierModel_base: Context.ServiceClass<ClassifierModel, "@yolk-sdk/agent/classification/ClassifierModel", {
+  readonly classify: (request: ClassificationRequest) => Effect.Effect<ClassificationResult, ClassificationError>;
+}>;
+/**
+ * Answers typed questions about one state. Classification is a read: it has no side effects.
+ * Providers supply layers; `classify` is the typed entry point.
+ */
+declare class ClassifierModel extends ClassifierModel_base {}
+/** Named questions, typed for inference. */
+type ClassifierQuestionsInput = {
+  readonly [questionId: string]: ClassifierQuestion;
+};
+/** The answer type a question gets; a choice answer's `choice` is the union of its option keys. */
+type ClassifierAnswerFor<Q extends ClassifierQuestion> = Q extends {
+  readonly type: 'boolean';
+} ? BooleanClassifierAnswer : Q extends {
+  readonly type: 'choice';
+  readonly criteria: infer Criteria;
+} ? ChoiceClassifierAnswer & {
+  readonly choice: Extract<keyof Criteria, string>;
+} : ScoreClassifierAnswer;
+type ClassifierAnswersFor<Q extends ClassifierQuestionsInput> = { readonly [K in keyof Q]: ClassifierAnswerFor<Q[K]> };
+type ClassificationRequestFor<Q extends ClassifierQuestionsInput> = Omit<ClassificationRequest, 'questions'> & {
+  readonly questions: Q;
+};
+type ClassificationResultFor<Q extends ClassifierQuestionsInput> = ClassificationResult & {
+  readonly answers: ClassifierAnswersFor<Q>;
+};
+/** Where an answer leaves its question. */
+type ClassificationAnswerIssue = {
+  readonly reason: ClassificationAnswerIssueReason;
+  readonly questionId: string;
+};
+/**
+ * Decode one raw provider answer against the question it answers. The answer must be an object
+ * whose `type` is the question's; probabilities and confidence must be finite numbers in `[0, 1]`
+ * and are kept exactly as given (never renormalized); a choice must name one of the question's
+ * options; a score must be finite. Only the contract fields are kept.
+ */
+declare const decodeClassifierAnswer: (question: ClassifierQuestion, raw: unknown) => Result.Result<ClassifierAnswer, ClassificationAnswerIssueReason>;
+/**
+ * Decode raw provider answers (a JSON object keyed by question id) against the questions asked:
+ * every question needs exactly one answer of its type, and no answer may name a question that was
+ * not asked. Fails with the first issue, in question order (then unexpected answers); answers that
+ * are not an object fail as the first question's `malformed_answer`.
+ */
+declare const decodeClassifierAnswers: (questions: ClassifierQuestionsInput, raw: unknown) => Result.Result<Record<string, ClassifierAnswer>, ClassificationAnswerIssue>;
+/** The first way `answers` leaves `questions`, or undefined when every answer fits its question. */
+declare const classificationAnswersIssue: (questions: ClassifierQuestionsInput, answers: {
+  readonly [questionId: string]: ClassifierAnswer;
+}) => ClassificationAnswerIssue | undefined;
+/** Narrow a result to the answer types its questions infer, after checking every answer. */
+declare const isClassificationResultFor: <const Q extends ClassifierQuestionsInput>(questions: Q, result: ClassificationResult) => result is ClassificationResultFor<Q>;
+/**
+ * Validate a request against the classification contract before anything is sent. Fails with
+ * `ClassificationRequestInvalid` (for example a choice with more than 255 options, or a score with
+ * more than 10 levels).
+ */
+declare const decodeClassificationRequest: (request: unknown) => Effect.Effect<ClassificationRequest, ClassificationRequestInvalid>;
+/**
+ * Classify with the `ClassifierModel` in context, typing each answer from its question: a choice
+ * answer's `choice` is the union of that question's option keys. Every answer is checked against
+ * its question; a provider that returns a mismatching answer fails with
+ * `ClassificationResponseInvalid` (keeping usage).
+ */
+declare const classify: <const Q extends ClassifierQuestionsInput>(request: ClassificationRequestFor<Q>) => Effect.Effect<ClassificationResultFor<Q>, ClassificationError, ClassifierModel>;
+//#endregion
+export { ClassificationAnswerIssue, ClassificationRequestFor, ClassificationResultFor, ClassifierAnswerFor, ClassifierAnswersFor, ClassifierModel, ClassifierQuestionsInput, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor };
+//# sourceMappingURL=model.d.mts.map

package/dist/classification/model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.mts","names":[],"sources":["../../src/classification/model.ts"],"mappings":";;;;;cAiBoB,oBAAA;sBAUd,OAAA,EAAS,qBAAA,KACN,MAAA,CAAO,MAAA,CAAO,oBAAA,EAAsB,mBAAA;AAAA;;;;;cALhC,eAAA,SAAwB,oBAOgB;;KAGzC,wBAAA;EAAA,UAAuC,UAAA,WAAqB,kBAAkB;AAAA;;KAG9E,mBAAA,WAA8B,kBAAA,IAAsB,CAAA;EAAA,SACrD,IAAA;AAAA,IAEP,uBAAA,GACA,CAAA;EAAA,SAAqB,IAAA;EAAA,SAAyB,QAAA;AAAA,IAC5C,sBAAA;EAAA,SAAoC,MAAA,EAAQ,OAAA,OAAc,QAAA;AAAA,IAC1D,qBAAA;AAAA,KAEM,oBAAA,WAA+B,wBAAA,2BACpB,CAAA,GAAI,mBAAA,CAAoB,CAAA,CAAE,CAAA;AAAA,KAGrC,wBAAA,WAAmC,wBAAA,IAA4B,IAAA,CACzE,qBAAA;EAAA,SAEa,SAAA,EAAW,CAAA;AAAA;AAAA,KAEd,uBAAA,WAAkC,wBAAA,IAA4B,oBAAA;EAAA,SAC/D,OAAA,EAAS,oBAAA,CAAqB,CAAA;AAAA;;KAI7B,yBAAA;EAAA,SACD,MAAA,EAAQ,+BAA+B;EAAA,SACvC,UAAA;AAAA;;;;;;;cAuDE,sBAAA,GACX,QAAA,EAAU,kBAAA,EACV,GAAA,cACC,MAAA,CAAO,MAAA,CAAO,gBAAA,EAAkB,+BAAA;;;;;;;cAwDtB,uBAAA,GACX,SAAA,EAAW,wBAAA,EACX,GAAA,cACC,MAAA,CAAO,MAAA,CAAO,MAAA,SAAe,gBAAA,GAAmB,yBAAA;;cAkCtC,0BAAA,GACX,SAAA,EAAW,wBAAA,EACX,OAAA;EAAA,UAAqB,UAAA,WAAqB,gBAAA;AAAA,MACzC,yBAAA;;cAOU,yBAAA,mBAA6C,wBAAA,EACxD,SAAA,EAAW,CAAA,EACX,MAAA,EAAQ,oBAAA,KACP,MAAA,IAAU,uBAAA,CAAwB,CAAA;;;;;;cAQxB,2BAAA,GACX,OAAA,cACC,MAAA,CAAO,MAAA,CAAO,qBAAA,EAAuB,4BAAA;;AAhMb;AAE3B;;;;cA6Ma,QAAA,mBAA4B,wBAAA,EACvC,OAAA,EAAS,wBAAA,CAAyB,CAAA,MACjC,MAAA,CAAO,MAAA,CAAO,uBAAA,CAAwB,CAAA,GAAI,mBAAA,EAAqB,eAAA"}

package/dist/classification/model.mjs

@@ -0,0 +1,136 @@
+import { ClassificationRequest } from "./schema.mjs";
+import { ClassificationRequestInvalid, ClassificationResponseInvalid } from "./errors.mjs";
+import { Context, Effect, Predicate, Result } from "effect";
+import * as Schema$1 from "effect/Schema";
+//#region src/classification/model.ts
+/**
+* Answers typed questions about one state. Classification is a read: it has no side effects.
+* Providers supply layers; `classify` is the typed entry point.
+*/
+var ClassifierModel = class extends Context.Service()("@yolk-sdk/agent/classification/ClassifierModel") {};
+const isProbability = (value) => Predicate.isNumber(value) && Number.isFinite(value) && value >= 0 && value <= 1;
+const isFieldObject = (value) => Predicate.isObject(value) && !Array.isArray(value);
+/** An own field of a JSON object, never an inherited one (`toString`, `__proto__`). */
+const ownField = (value, key) => Object.hasOwn(value, key) && Predicate.hasProperty(value, key) ? value[key] : void 0;
+const decodeProbabilities = (value) => {
+	if (!isFieldObject(value)) return Result.fail("invalid_probability");
+	const entries = [];
+	for (const key of Object.keys(value)) {
+		const probability = ownField(value, key);
+		if (!isProbability(probability)) return Result.fail("invalid_probability");
+		entries.push([key, probability]);
+	}
+	return Result.succeed(Object.fromEntries(entries));
+};
+const decodeConfidence = (raw, fields) => {
+	if (!Object.hasOwn(raw, "confidence")) return void 0;
+	const confidence = ownField(raw, "confidence");
+	if (!isProbability(confidence)) return "invalid_confidence";
+	fields.confidence = confidence;
+};
+/**
+* Decode one raw provider answer against the question it answers. The answer must be an object
+* whose `type` is the question's; probabilities and confidence must be finite numbers in `[0, 1]`
+* and are kept exactly as given (never renormalized); a choice must name one of the question's
+* options; a score must be finite. Only the contract fields are kept.
+*/
+const decodeClassifierAnswer = (question, raw) => {
+	if (!isFieldObject(raw)) return Result.fail("malformed_answer");
+	if (ownField(raw, "type") !== question.type) return Result.fail("type_mismatch");
+	if (question.type === "boolean") {
+		const probability = ownField(raw, "probability");
+		return isProbability(probability) ? Result.succeed({
+			type: "boolean",
+			probability
+		}) : Result.fail("invalid_probability");
+	}
+	const probabilities = decodeProbabilities(ownField(raw, "probabilities"));
+	if (Result.isFailure(probabilities)) return Result.fail(probabilities.failure);
+	if (question.type === "choice") {
+		const choice = ownField(raw, "choice");
+		if (!Predicate.isString(choice) || !Object.hasOwn(question.criteria, choice)) return Result.fail("invalid_choice");
+		const fields = {
+			type: "choice",
+			choice,
+			probabilities: probabilities.success
+		};
+		const issue = decodeConfidence(raw, fields);
+		return issue === void 0 ? Result.succeed(fields) : Result.fail(issue);
+	}
+	const score = ownField(raw, "score");
+	if (!Predicate.isNumber(score) || !Number.isFinite(score)) return Result.fail("invalid_score");
+	const fields = {
+		type: "score",
+		score,
+		probabilities: probabilities.success
+	};
+	const issue = decodeConfidence(raw, fields);
+	return issue === void 0 ? Result.succeed(fields) : Result.fail(issue);
+};
+/**
+* Decode raw provider answers (a JSON object keyed by question id) against the questions asked:
+* every question needs exactly one answer of its type, and no answer may name a question that was
+* not asked. Fails with the first issue, in question order (then unexpected answers); answers that
+* are not an object fail as the first question's `malformed_answer`.
+*/
+const decodeClassifierAnswers = (questions, raw) => {
+	const questionIds = Object.keys(questions);
+	if (!isFieldObject(raw)) return Result.fail({
+		reason: "malformed_answer",
+		questionId: questionIds[0] ?? ""
+	});
+	const entries = [];
+	for (const [questionId, question] of Object.entries(questions)) {
+		if (!Object.hasOwn(raw, questionId)) return Result.fail({
+			reason: "missing_answer",
+			questionId
+		});
+		const answer = decodeClassifierAnswer(question, ownField(raw, questionId));
+		if (Result.isFailure(answer)) return Result.fail({
+			reason: answer.failure,
+			questionId
+		});
+		entries.push([questionId, answer.success]);
+	}
+	const answers = Object.fromEntries(entries);
+	for (const questionId of Object.keys(raw)) if (!Object.hasOwn(questions, questionId)) return Result.fail({
+		reason: "unexpected_answer",
+		questionId
+	});
+	return Result.succeed(answers);
+};
+/** The first way `answers` leaves `questions`, or undefined when every answer fits its question. */
+const classificationAnswersIssue = (questions, answers) => {
+	const decoded = decodeClassifierAnswers(questions, answers);
+	return Result.isFailure(decoded) ? decoded.failure : void 0;
+};
+/** Narrow a result to the answer types its questions infer, after checking every answer. */
+const isClassificationResultFor = (questions, result) => classificationAnswersIssue(questions, result.answers) === void 0;
+/**
+* Validate a request against the classification contract before anything is sent. Fails with
+* `ClassificationRequestInvalid` (for example a choice with more than 255 options, or a score with
+* more than 10 levels).
+*/
+const decodeClassificationRequest = (request) => Schema$1.decodeUnknownEffect(ClassificationRequest)(request).pipe(Effect.mapError((error) => ClassificationRequestInvalid.make({ message: `Invalid classification request: ${error.message}` })));
+/**
+* Classify with the `ClassifierModel` in context, typing each answer from its question: a choice
+* answer's `choice` is the union of that question's option keys. Every answer is checked against
+* its question; a provider that returns a mismatching answer fails with
+* `ClassificationResponseInvalid` (keeping usage).
+*/
+const classify = (request) => Effect.gen(function* () {
+	const result = yield* (yield* ClassifierModel).classify(request);
+	if (isClassificationResultFor(request.questions, result)) return result;
+	const issue = classificationAnswersIssue(request.questions, result.answers);
+	const reason = issue?.reason ?? "malformed_answer";
+	return yield* Effect.fail(ClassificationResponseInvalid.make({
+		message: `Classification answers do not fit their questions: ${reason}`,
+		reason,
+		questionId: issue?.questionId,
+		usage: result.usage
+	}));
+});
+//#endregion
+export { ClassifierModel, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor };
+
+//# sourceMappingURL=model.mjs.map

package/dist/classification/model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.mjs","names":["Schema"],"sources":["../../src/classification/model.ts"],"sourcesContent":["import { Context, Effect, Predicate, Result } from 'effect'\nimport * as Schema from 'effect/Schema'\nimport {\n  ClassificationRequestInvalid,\n  ClassificationResponseInvalid,\n  type ClassificationAnswerIssueReason,\n  type ClassificationError\n} from './errors.ts'\nimport {\n  ClassificationRequest,\n  type BooleanClassifierAnswer,\n  type ChoiceClassifierAnswer,\n  type ClassificationResult,\n  type ClassifierAnswer,\n  type ClassifierProbabilities,\n  type ClassifierQuestion,\n  type ScoreClassifierAnswer\n} from './schema.ts'\n\n/**\n * Answers typed questions about one state. Classification is a read: it has no side effects.\n * Providers supply layers; `classify` is the typed entry point.\n */\nexport class ClassifierModel extends Context.Service<\n  ClassifierModel,\n  {\n    readonly classify: (\n      request: ClassificationRequest\n    ) => Effect.Effect<ClassificationResult, ClassificationError>\n  }\n>()('@yolk-sdk/agent/classification/ClassifierModel') {}\n\n/** Named questions, typed for inference. */\nexport type ClassifierQuestionsInput = { readonly [questionId: string]: ClassifierQuestion }\n\n/** The answer type a question gets; a choice answer's `choice` is the union of its option keys. */\nexport type ClassifierAnswerFor<Q extends ClassifierQuestion> = Q extends {\n  readonly type: 'boolean'\n}\n  ? BooleanClassifierAnswer\n  : Q extends { readonly type: 'choice'; readonly criteria: infer Criteria }\n    ? ChoiceClassifierAnswer & { readonly choice: Extract<keyof Criteria, string> }\n    : ScoreClassifierAnswer\n\nexport type ClassifierAnswersFor<Q extends ClassifierQuestionsInput> = {\n  readonly [K in keyof Q]: ClassifierAnswerFor<Q[K]>\n}\n\nexport type ClassificationRequestFor<Q extends ClassifierQuestionsInput> = Omit<\n  ClassificationRequest,\n  'questions'\n> & { readonly questions: Q }\n\nexport type ClassificationResultFor<Q extends ClassifierQuestionsInput> = ClassificationResult & {\n  readonly answers: ClassifierAnswersFor<Q>\n}\n\n/** Where an answer leaves its question. */\nexport type ClassificationAnswerIssue = {\n  readonly reason: ClassificationAnswerIssueReason\n  readonly questionId: string\n}\n\nconst isProbability = (value: unknown): value is number =>\n  Predicate.isNumber(value) && Number.isFinite(value) && value >= 0 && value <= 1\n\nconst isFieldObject = (value: unknown): value is object =>\n  Predicate.isObject(value) && !Array.isArray(value)\n\n/** An own field of a JSON object, never an inherited one (`toString`, `__proto__`). */\nconst ownField = (value: object, key: string): unknown =>\n  Object.hasOwn(value, key) && Predicate.hasProperty(value, key) ? value[key] : undefined\n\nconst decodeProbabilities = (\n  value: unknown\n): Result.Result<ClassifierProbabilities, ClassificationAnswerIssueReason> => {\n  if (!isFieldObject(value)) return Result.fail('invalid_probability')\n\n  const entries: Array<readonly [string, number]> = []\n\n  for (const key of Object.keys(value)) {\n    const probability = ownField(value, key)\n\n    if (!isProbability(probability)) return Result.fail('invalid_probability')\n\n    entries.push([key, probability])\n  }\n\n  // `Object.fromEntries` defines own data properties, so keys such as `__proto__` are kept.\n  return Result.succeed(Object.fromEntries(entries))\n}\n\ntype ConfidenceField = { confidence?: number }\n\nconst decodeConfidence = (\n  raw: object,\n  fields: ConfidenceField\n): ClassificationAnswerIssueReason | undefined => {\n  if (!Object.hasOwn(raw, 'confidence')) return undefined\n\n  const confidence = ownField(raw, 'confidence')\n\n  if (!isProbability(confidence)) return 'invalid_confidence'\n\n  fields.confidence = confidence\n\n  return undefined\n}\n\n/**\n * Decode one raw provider answer against the question it answers. The answer must be an object\n * whose `type` is the question's; probabilities and confidence must be finite numbers in `[0, 1]`\n * and are kept exactly as given (never renormalized); a choice must name one of the question's\n * options; a score must be finite. Only the contract fields are kept.\n */\nexport const decodeClassifierAnswer = (\n  question: ClassifierQuestion,\n  raw: unknown\n): Result.Result<ClassifierAnswer, ClassificationAnswerIssueReason> => {\n  if (!isFieldObject(raw)) return Result.fail('malformed_answer')\n\n  if (ownField(raw, 'type') !== question.type) return Result.fail('type_mismatch')\n\n  if (question.type === 'boolean') {\n    const probability = ownField(raw, 'probability')\n\n    return isProbability(probability)\n      ? Result.succeed({ type: 'boolean', probability })\n      : Result.fail('invalid_probability')\n  }\n\n  const probabilities = decodeProbabilities(ownField(raw, 'probabilities'))\n\n  if (Result.isFailure(probabilities)) return Result.fail(probabilities.failure)\n\n  if (question.type === 'choice') {\n    const choice = ownField(raw, 'choice')\n\n    if (!Predicate.isString(choice) || !Object.hasOwn(question.criteria, choice)) {\n      return Result.fail('invalid_choice')\n    }\n\n    const fields: ChoiceClassifierAnswer & ConfidenceField = {\n      type: 'choice',\n      choice,\n      probabilities: probabilities.success\n    }\n\n    const issue = decodeConfidence(raw, fields)\n\n    return issue === undefined ? Result.succeed(fields) : Result.fail(issue)\n  }\n\n  const score = ownField(raw, 'score')\n\n  if (!Predicate.isNumber(score) || !Number.isFinite(score)) return Result.fail('invalid_score')\n\n  const fields: ScoreClassifierAnswer & ConfidenceField = {\n    type: 'score',\n    score,\n    probabilities: probabilities.success\n  }\n\n  const issue = decodeConfidence(raw, fields)\n\n  return issue === undefined ? Result.succeed(fields) : Result.fail(issue)\n}\n\n/**\n * Decode raw provider answers (a JSON object keyed by question id) against the questions asked:\n * every question needs exactly one answer of its type, and no answer may name a question that was\n * not asked. Fails with the first issue, in question order (then unexpected answers); answers that\n * are not an object fail as the first question's `malformed_answer`.\n */\nexport const decodeClassifierAnswers = (\n  questions: ClassifierQuestionsInput,\n  raw: unknown\n): Result.Result<Record<string, ClassifierAnswer>, ClassificationAnswerIssue> => {\n  const questionIds = Object.keys(questions)\n\n  if (!isFieldObject(raw)) {\n    return Result.fail({ reason: 'malformed_answer', questionId: questionIds[0] ?? '' })\n  }\n\n  const entries: Array<readonly [string, ClassifierAnswer]> = []\n\n  for (const [questionId, question] of Object.entries(questions)) {\n    if (!Object.hasOwn(raw, questionId)) {\n      return Result.fail({ reason: 'missing_answer', questionId })\n    }\n\n    const answer = decodeClassifierAnswer(question, ownField(raw, questionId))\n\n    if (Result.isFailure(answer)) return Result.fail({ reason: answer.failure, questionId })\n\n    entries.push([questionId, answer.success])\n  }\n\n  // Own data properties: question ids such as `__proto__` stay answers, not prototypes.\n  const answers: Record<string, ClassifierAnswer> = Object.fromEntries(entries)\n\n  for (const questionId of Object.keys(raw)) {\n    if (!Object.hasOwn(questions, questionId)) {\n      return Result.fail({ reason: 'unexpected_answer', questionId })\n    }\n  }\n\n  return Result.succeed(answers)\n}\n\n/** The first way `answers` leaves `questions`, or undefined when every answer fits its question. */\nexport const classificationAnswersIssue = (\n  questions: ClassifierQuestionsInput,\n  answers: { readonly [questionId: string]: ClassifierAnswer }\n): ClassificationAnswerIssue | undefined => {\n  const decoded = decodeClassifierAnswers(questions, answers)\n\n  return Result.isFailure(decoded) ? decoded.failure : undefined\n}\n\n/** Narrow a result to the answer types its questions infer, after checking every answer. */\nexport const isClassificationResultFor = <const Q extends ClassifierQuestionsInput>(\n  questions: Q,\n  result: ClassificationResult\n): result is ClassificationResultFor<Q> =>\n  classificationAnswersIssue(questions, result.answers) === undefined\n\n/**\n * Validate a request against the classification contract before anything is sent. Fails with\n * `ClassificationRequestInvalid` (for example a choice with more than 255 options, or a score with\n * more than 10 levels).\n */\nexport const decodeClassificationRequest = (\n  request: unknown\n): Effect.Effect<ClassificationRequest, ClassificationRequestInvalid> =>\n  Schema.decodeUnknownEffect(ClassificationRequest)(request).pipe(\n    Effect.mapError(error =>\n      ClassificationRequestInvalid.make({\n        message: `Invalid classification request: ${error.message}`\n      })\n    )\n  )\n\n/**\n * Classify with the `ClassifierModel` in context, typing each answer from its question: a choice\n * answer's `choice` is the union of that question's option keys. Every answer is checked against\n * its question; a provider that returns a mismatching answer fails with\n * `ClassificationResponseInvalid` (keeping usage).\n */\nexport const classify = <const Q extends ClassifierQuestionsInput>(\n  request: ClassificationRequestFor<Q>\n): Effect.Effect<ClassificationResultFor<Q>, ClassificationError, ClassifierModel> =>\n  Effect.gen(function* () {\n    const model = yield* ClassifierModel\n    const result = yield* model.classify(request)\n\n    if (isClassificationResultFor(request.questions, result)) return result\n\n    const issue = classificationAnswersIssue(request.questions, result.answers)\n    const reason = issue?.reason ?? 'malformed_answer'\n\n    return yield* Effect.fail(\n      ClassificationResponseInvalid.make({\n        message: `Classification answers do not fit their questions: ${reason}`,\n        reason,\n        questionId: issue?.questionId,\n        usage: result.usage\n      })\n    )\n  })\n"],"mappings":"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"}