@yolk-sdk/emulators 0.1.0-canary.96

package/dist/chat-completions.d.mts

@@ -0,0 +1,288 @@
+import { EmulatorEvidence, EmulatorRouteEvidence } from "./route-evidence.mjs";
+import { EmulatorApi, EmulatorCoverage, EmulatorFaultState, EmulatorRouteCoverage } from "./emulator-kernel.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/chat-completions.d.ts
+/** Optional fault filter; an omitted field matches every request. `path` ending in `*` is a prefix. */
+declare const ChatFaultMatch: Schema.Struct<{
+  readonly path: Schema.optionalKey<Schema.String>;
+  readonly model: Schema.optionalKey<Schema.String>;
+}>;
+type ChatFaultMatch = typeof ChatFaultMatch.Type;
+/**
+ * Wire faults for emulated routes:
+ *
+ * - `status`: answer with this status, headers, and body instead of a
+ *   completion (for example 429 with `retry-after`). The body defaults to the
+ *   emulator's error envelope. Statuses that cannot carry a body (1xx, 204,
+ *   205, 304) and redirects (3xx) are rejected, as are invalid header names or
+ *   values and a `location` header; scripted errors follow the same rules.
+ * - `error-after-chunks`: send `chunks` body chunks, then error the body
+ *   stream (a dropped connection).
+ * - `truncate-after-chunks`: send `chunks` body chunks, then close the body
+ *   cleanly (for example without `data: [DONE]`).
+ *
+ * A whole JSON body counts as one chunk. A chunk fault that cannot take
+ * effect (`error-after-chunks` beyond the chunk count, or
+ * `truncate-after-chunks` at or beyond it) answers 500 with an emulator error
+ * instead of silently doing nothing, and is not consumed.
+ */
+declare const ChatFault: Schema.Union<readonly [Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly status: Schema.Int;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>]>;
+type ChatFault = typeof ChatFault.Type;
+type ChatFaultKind = ChatFault['kind'];
+/** Usage for a scripted turn (sent as the wire `usage` object). */
+declare const ChatScriptedUsage: Schema.Struct<{
+  readonly promptTokens: Schema.Int;
+  readonly completionTokens: Schema.Int;
+  readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+}>;
+type ChatScriptedUsage = typeof ChatScriptedUsage.Type;
+/** One scripted tool call; its JSON arguments stream as these fragments. */
+declare const ChatScriptedToolCall: Schema.Struct<{
+  readonly name: Schema.NonEmptyString;
+  readonly argumentFragments: Schema.$Array<Schema.String>;
+  readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type ChatScriptedToolCall = typeof ChatScriptedToolCall.Type;
+/** Scripted completion fields every Chat Completions emulator accepts. */
+declare const chatScriptedCompletionFields: {
+  text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  toolCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly promptTokens: Schema.Int;
+    readonly completionTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  finishReason: Schema.optionalKey<Schema.NonEmptyString>;
+};
+/** Scripted completion fields for emulators that emulate streamed reasoning. */
+declare const chatScriptedReasoningFields: {
+  reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  reasoningField: Schema.optionalKey<Schema.Literals<readonly ["reasoning_content", "reasoning"]>>;
+  order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+};
+/**
+ * The reasoning variant of a scripted completion (the Gateway's shape; `/openai` uses the
+ * reasoning-free `OpenAiScriptedCompletion`). Every field is exact (nothing is
+ * filled in) except: `usage` omitted is synthesized when the request asks for
+ * usage, and `null` drops it; `finishReason` omitted is `tool_calls` with tool
+ * calls, else `stop`. `order` defaults to `reasoning-first`; `reasoningField`
+ * defaults to the emulator's wire profile field (`reasoning` for the Gateway,
+ * as recorded live; `reasoning_content` is the DeepSeek-native alternative).
+ */
+declare const ChatScriptedReasoningCompletion: Schema.Struct<{
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly reasoningField: Schema.optionalKey<Schema.Literals<readonly ["reasoning_content", "reasoning"]>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly toolCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly promptTokens: Schema.Int;
+    readonly completionTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly finishReason: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+type ChatScriptedReasoningCompletion = typeof ChatScriptedReasoningCompletion.Type;
+/** A scripted error response: status, body (a string is sent as is), and optional headers. */
+declare const ChatScriptedError: Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>;
+type ChatScriptedError = typeof ChatScriptedError.Type;
+/**
+ * The reasoning variant of a scripted turn, queued for the next chat completion request. It is
+ * also the widest turn shape, so it bounds every emulator's turn type.
+ */
+declare const ChatScriptedReasoningTurn: Schema.Union<readonly [Schema.Struct<{
+  readonly error: Schema.Struct<{
+    readonly status: Schema.Int;
+    readonly body: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  }>;
+}>, Schema.Struct<{
+  readonly text: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly reasoning: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly reasoningField: Schema.optionalKey<Schema.Literals<readonly ["reasoning_content", "reasoning"]>>;
+  readonly order: Schema.optionalKey<Schema.Literals<readonly ["reasoning-first", "text-first"]>>;
+  readonly toolCalls: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly name: Schema.NonEmptyString;
+    readonly argumentFragments: Schema.$Array<Schema.String>;
+    readonly id: Schema.optionalKey<Schema.NonEmptyString>;
+  }>>>;
+  readonly usage: Schema.optionalKey<Schema.NullOr<Schema.Struct<{
+    readonly promptTokens: Schema.Int;
+    readonly completionTokens: Schema.Int;
+    readonly reasoningTokens: Schema.optionalKey<Schema.Int>;
+  }>>>;
+  readonly finishReason: Schema.optionalKey<Schema.NonEmptyString>;
+}>]>;
+type ChatScriptedReasoningTurn = typeof ChatScriptedReasoningTurn.Type;
+type ChatLedgerEntry = {
+  /** 1-based arrival order since the last ledger clear or reset. */readonly seq: number;
+  readonly method: string;
+  readonly path: string; /** Parsed JSON request body, when it was valid JSON. */
+  readonly body?: Schema.Json;
+  readonly model?: string;
+  readonly stream?: boolean;
+  /**
+   * The output-token limit from the emulator's completion-token request field (`max_tokens` or
+   * `max_completion_tokens`), when it is a number. Recorded as sent; never validated.
+   */
+  readonly maxCompletionTokens?: number;
+  readonly reasoningEffort?: string;
+  readonly thinking?: Schema.Json;
+  readonly toolNames: ReadonlyArray<string>; /** Kind of the fault that shaped the response. */
+  readonly fault?: ChatFaultKind; /** Why a matching fault could not take effect (the response was a 500 emulator error). */
+  readonly faultError?: string;
+  /**
+   * Set when the emulator could not build the planned response; the request was
+   * answered with a 500 emulator error (still evidence-tagged) and no fault was used up.
+   */
+  readonly responseError?: string; /** Set when a scripted turn answered the request. */
+  readonly scripted?: 'completion' | 'error'; /** Evidence of the matched route; `unknown-route` for requests that failed closed. */
+  readonly evidence: EmulatorEvidence | 'unknown-route';
+  readonly status: number; /** Body chunks handed to the transport so far (each produced when pulled). */
+  readonly bodyChunks: number;
+};
+type ChatFaultState = EmulatorFaultState<ChatFault>;
+type ChatRouteCoverage = EmulatorRouteCoverage;
+type ChatCoverage = EmulatorCoverage;
+type ChatCompletionsEmulator<Turn> = EmulatorApi<Turn, ChatFault, ChatLedgerEntry>;
+/** One wire error: the emulator's envelope renders it. */
+type ChatWireError = {
+  readonly message: string;
+  readonly type: string;
+  readonly code: string;
+};
+/** The id and model every chunk of one emulated response repeats. */
+type ChatResponseIdentity = {
+  readonly id: string;
+  readonly model: string;
+};
+/** Token counts behind a wire `usage` object. */
+type ChatUsageCounts = {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  readonly reasoningTokens: number | undefined;
+};
+/**
+ * Per-service response details on top of the shared framing. Every field is optional; an omitted
+ * field keeps the plain OpenAI Chat Completions wire (the `/openai` emulator passes no profile).
+ */
+type ChatWireProfile = {
+  /**
+   * SSE events per network (body) chunk; default 1. Events are packed counting from the end, so
+   * the last chunk carries the finish event together with `data: [DONE]` and the first chunk may
+   * carry fewer. Chunk faults count these network chunks.
+   */
+  readonly eventsPerChunk?: number;
+  /**
+   * Where streamed usage goes when `stream_options.include_usage` is set: a trailing chunk with
+   * empty `choices` (`usage-chunk`, default) or the finish event itself (`finish-event`).
+   */
+  readonly streamUsage?: 'usage-chunk' | 'finish-event'; /** The first streamed delta; default `{ role: 'assistant', content: '' }`. */
+  readonly openingDelta?: Schema.JsonObject; /** Extra fields on every streamed choice, placed before `finish_reason` (for example `logprobs`). */
+  readonly choiceFields?: Schema.JsonObject; /** The default reasoning field for default and scripted output; default `reasoning_content`. */
+  readonly reasoningField?: 'reasoning_content' | 'reasoning'; /** Streamed `reasoning` deltas also carry `reasoning_details` (`reasoning.text` entries). */
+  readonly reasoningDetails?: boolean; /** Extra top-level fields on every streamed chunk (for example `system_fingerprint`). */
+  readonly chunkFields?: (identity: ChatResponseIdentity) => Schema.JsonObject; /** Extra fields on the finish event: top-level (`chunk`) and inside its `delta`. */
+  readonly finishFields?: (identity: ChatResponseIdentity) => {
+    readonly chunk: Schema.JsonObject;
+    readonly delta: Schema.JsonObject;
+  }; /** Renders token counts as the wire `usage` object (streamed and JSON). */
+  readonly usage?: (counts: ChatUsageCounts) => Schema.JsonObject;
+};
+/**
+ * What differs between Chat Completions emulators. The core owns everything else (framing,
+ * faults, scripting, ledger, control plane, evidence).
+ */
+type ChatCompletionsEmulatorConfig<Turn extends ChatScriptedReasoningTurn> = {
+  /** The chat completions path, for example `/v1/chat/completions`. */readonly path: string; /** Route evidence manifest; must list exactly the chat completions route. */
+  readonly routes: ReadonlyArray<EmulatorRouteEvidence>;
+  readonly knownModels: ReadonlyArray<string>;
+  /**
+   * Streamed reasoning: `undefined` when the emulator does not emulate reasoning (default plans
+   * never reason and `/_emulate/state` omits `reasoningModels`); otherwise the models that stream
+   * reasoning when a request asks for it.
+   */
+  readonly reasoningModels: ReadonlyArray<string> | undefined; /** Renders a wire error as the service's JSON error envelope. */
+  readonly errorEnvelope: (error: ChatWireError) => Schema.Json;
+  /**
+   * Status and answer for an unknown (or missing) model id: an `error` rendered with
+   * `errorEnvelope`, or a `body` built from the requested id (for a service whose unknown-model
+   * envelope differs from its other errors).
+   */
+  readonly unknownModel: {
+    readonly status: number;
+    readonly error: ChatWireError;
+  } | {
+    readonly status: number;
+    readonly body: (model: string | undefined) => Schema.Json;
+  };
+  /**
+   * Requests authenticate with a non-empty `Authorization: Bearer` credential, never checked or
+   * stored; anything else answers 401 with `unauthorized`.
+   */
+  readonly auth: {
+    readonly unauthorized: ChatWireError;
+  }; /** Request field carrying the output-token limit, recorded in the ledger. */
+  readonly completionTokenField: 'max_tokens' | 'max_completion_tokens'; /** Response id prefix; ids are `${prefix}-${seq}`. */
+  readonly responseIdPrefix: string; /** Default answer text deltas. */
+  readonly defaultText: ReadonlyArray<string>; /** The emulator's scripted-turn schema (decoded strictly). */
+  readonly turnSchema: Schema.Decoder<Turn>; /** Builds the error thrown by the JS API (`faults.add`, `script.enqueue`) for invalid input. */
+  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error; /** Per-service wire details; omitted: the plain OpenAI Chat Completions wire. */
+  readonly wire?: ChatWireProfile;
+};
+/**
+ * Create a Chat Completions emulator from its config. Each call has
+ * independent ledger, fault, and script state.
+ *
+ * Precedence per chat request: authentication and JSON validation, then the
+ * first matching fault if it is a `status` fault, then the next scripted
+ * turn, then model validation and defaults; a first matching chunk fault then
+ * shapes the body. Only the first matching fault (in insertion order)
+ * applies. Credential headers are never recorded, and the bearer value is
+ * never checked or stored.
+ */
+declare const makeChatCompletionsEmulator: <Turn extends ChatScriptedReasoningTurn>(config: ChatCompletionsEmulatorConfig<Turn>) => ChatCompletionsEmulator<Turn>;
+//#endregion
+export { ChatCompletionsEmulator, ChatCompletionsEmulatorConfig, ChatCoverage, ChatFault, ChatFaultKind, ChatFaultMatch, ChatFaultState, ChatLedgerEntry, ChatResponseIdentity, ChatRouteCoverage, ChatScriptedError, ChatScriptedReasoningCompletion, ChatScriptedReasoningTurn, ChatScriptedToolCall, ChatScriptedUsage, ChatUsageCounts, ChatWireError, ChatWireProfile, chatScriptedCompletionFields, chatScriptedReasoningFields, makeChatCompletionsEmulator };
+//# sourceMappingURL=chat-completions.d.mts.map

package/dist/chat-completions.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-completions.d.mts","names":[],"sources":["../src/chat-completions.ts"],"mappings":"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"}