@combycode/llm-sdk 3.1.0 → 3.3.0

package/dist/wire/response-interpreter.d.ts

@@ -0,0 +1,156 @@
+/** Build a unified response from a provider body, driven by a spec.
+ *
+ *  The request side has been spec-driven since 3.0.0; the parse side is seven
+ *  hand-written `parseResponse` implementations doing the same four things in
+ *  four different spellings. This is the other half.
+ *
+ *  -- what is reused, and why that matters ----------------------------------
+ *  Everything except classification. `evalTemplate`, `evalCond`, `$`, `$map`,
+ *  `$call`, `$table`, `$join`, `$when` and `$default` come from the request
+ *  interpreter unchanged, because that evaluator never cared what the root
+ *  object was: it resolves paths against `ctx.req`, and nothing in it is
+ *  request-shaped. Handing it a response body costs nothing, and means the
+ *  Python port inherits the whole evaluator it has already transposed.
+ *
+ *  -- the one genuinely new thing -------------------------------------------
+ *  Requests map a tree onto another tree. Responses must first CLASSIFY: every
+ *  provider returns a heterogeneous array (Anthropic `content[]`, OpenAI
+ *  `output[]`, Google `parts[]`) whose elements are discriminated by a type
+ *  field and fan out to different destinations. `$map` cannot express that,
+ *  because one element may need to land in TWO places at once.
+ *
+ *  Hence `collect`: walk an array, switch on a discriminator, emit into named
+ *  accumulators. `emit: ['content', 'toolCalls']` places the SAME object
+ *  reference in both, which is what the hand-written adapters do today
+ *  (`content.push(tc); toolCalls.push(tc)`) and is load-bearing: a consumer that
+ *  mutates `response.toolCalls[0]` sees it in `response.content` too.
+ *
+ *  -- the root object -------------------------------------------------------
+ *  Paths resolve against `{ raw, out }`, in BOTH phases:
+ *
+ *      { "$": "raw.stop_reason" }     the provider body
+ *      { "$map": "out.content" }      what has been collected so far
+ *      { "$": "@text" }               the block currently being classified
+ *
+ *  `out` is readable during collection on purpose: Anthropic attaches a tool
+ *  result to the builtin call it belongs to by matching `tool_use_id` against
+ *  calls already collected, and that is a lookup into `out`, not into `raw`.
+ */
+import { type Cond, type Json, type Registry } from './interpreter';
+/** How an accumulator behaves. Declared up front so that "absent" and "empty"
+ *  are a decision in the spec rather than an accident of what the body held:
+ *  `content` is an array even when empty, `files` is absent unless the turn
+ *  produced one, and a response type grows by OPTIONAL fields only. */
+export interface AccumulatorDecl {
+    kind: 'array' | 'scalar';
+    /** Arrays: drop the key entirely when nothing landed in it. */
+    omitEmpty?: boolean;
+    /** Scalars: the value when nothing was emitted. `thinking` is null, not absent. */
+    default?: Json;
+    /** Working state, never assembled into the result.
+     *
+     *  OpenAI's `program` items must carry the reasoning items that preceded them
+     *  in the same output -- the program cannot be sent back without them -- so
+     *  those items are collected as they go and read by a later block. They are
+     *  scaffolding for the build, not a field of the response. */
+    internal?: boolean;
+}
+export interface EmitRule {
+    /** Accumulator name, or several. Several means ONE evaluated value placed in
+     *  each -- the same reference, not copies. Omitted only with `effect`. */
+    emit?: string | string[];
+    /** `push` appends one value (default); `concat` splices an evaluated ARRAY in,
+     *  for a block that yields several (one Anthropic code-execution result can
+     *  carry more than one output file); `scalar` assigns, last write wins. */
+    mode?: 'push' | 'concat' | 'scalar';
+    /** Extra guard beyond the discriminator match. */
+    when?: Cond;
+    as?: Json;
+    /** A named effect run for this block INSTEAD of emitting.
+     *
+     *  Some blocks modify what is already collected rather than adding to it:
+     *  Anthropic's `*_tool_result` attaches its stdout to the `server_tool_use`
+     *  it belongs to, matched on `tool_use_id`. That is a lookup into `out` and a
+     *  write to an object already in it, which no amount of emitting expresses.
+     *  The effect receives the block as `ctx.item` and the accumulators at
+     *  `ctx.req.out`. */
+    effect?: string;
+}
+export interface CollectRule {
+    /** Path to the array to walk, e.g. `raw.content`. A missing or non-array value
+     *  is not an error: a response with no content is a normal response. */
+    from: string;
+    /** Field on each element that selects the case, e.g. `type`.
+     *
+     *  OPTIONAL, because not every provider discriminates by a field. OpenAI's
+     *  `tool_calls` is homogeneous -- every element is a tool call -- and Google's
+     *  `parts[]` discriminates by WHICH KEY EXISTS (`text` vs `functionCall` vs
+     *  `inlineData`) rather than by a type tag. With no `match`, every element
+     *  takes `default`, whose rules carry their own `when`. */
+    match?: string;
+    cases?: Record<string, EmitRule | EmitRule[]>;
+    /** Elements matching no case. Omitted means ignore them, which is the right
+     *  default: providers add block types continuously, and an unknown one must
+     *  not break the whole parse. */
+    default?: EmitRule | EmitRule[];
+}
+export interface ResponseFieldRule {
+    to: string;
+    /** Path in the root object. Mutually exclusive with `value`. */
+    from?: string;
+    value?: Json;
+    when?: Cond;
+    /** Used when `from` resolves to undefined. */
+    default?: Json;
+}
+export interface ResponseSpec {
+    id: string;
+    extends?: string;
+    accumulators?: Record<string, AccumulatorDecl>;
+    fields?: ResponseFieldRule[];
+    /** Emits that are not driven by walking an array, run BEFORE `collect`.
+     *
+     *  OpenAI puts the assistant's text at `message.content` and its spoken audio
+     *  at `message.audio` -- two single values, not elements of anything -- and
+     *  both must sit in `content` ahead of the tool calls, because order inside
+     *  `content` is what a consumer renders. */
+    seed?: EmitRule[];
+    collect?: CollectRule[];
+    /** Emits run AFTER `collect`, for what can only be decided once everything is
+     *  in. OpenAI falls back to the `output_text` convenience field, but only when
+     *  no message item produced text AND nothing else landed in `content` -- a
+     *  condition that does not exist until the walk is over. */
+    finalize?: EmitRule[];
+    /** Computed last, so they can read everything `collect` produced. A derived
+     *  value overrides an accumulator of the same name. */
+    derive?: Record<string, Json>;
+    tables?: Record<string, Record<string, Json>>;
+    _note?: string;
+}
+/** Flatten a spec's `extends` chain.
+ *
+ *  OpenRouter is Chat Completions plus one rule: a `url_citation` annotation is
+ *  the only signal that its `:online` search ran. Copying the OpenAI spec to add
+ *  that rule would leave two files to keep in step, and they would diverge the
+ *  first time only one was edited -- which is the whole argument for specs.
+ *
+ *  Merge rules, one line each:
+ *    accumulators / derive / tables  merge by key, child wins
+ *    fields                          merge by `to`, child replaces, new append
+ *    seed / collect                  APPEND, parent first
+ *
+ *  Append rather than merge for the ordered ones, because their order is their
+ *  meaning: a child adding to `content` adds AFTER what the parent put there.
+ */
+export declare function resolveResponseSpec(id: string, byId: Map<string, ResponseSpec>, seen?: Set<string>): ResponseSpec;
+/** The accumulators, initialised from their declarations. */
+export declare function initAccumulators(decls: Record<string, AccumulatorDecl> | undefined): Record<string, unknown>;
+export declare function emitInto(out: Record<string, unknown>, rule: EmitRule, value: unknown, specId: string): void;
+export interface BuildResponseOptions {
+    /** Merged in before `fields`, for values the spec cannot know: `latencyMs`,
+     *  and `raw` itself. */
+    extra?: Record<string, unknown>;
+    /** Adapter config, for `$config`. */
+    config?: Record<string, unknown>;
+}
+export declare function buildResponse(spec: ResponseSpec, raw: unknown, reg: Registry, opts?: BuildResponseOptions): Record<string, unknown>;

package/dist/wire/response-specs.d.ts

@@ -0,0 +1,7 @@
+import { type ResponseSpec } from './response-interpreter';
+export declare const RESPONSE_SPECS: Map<string, ResponseSpec>;
+/** The spec id for a corpus/runtime target key, e.g. `openai/completions`. */
+export declare const responseSpecId: (target: string) => string;
+/** The spec FLATTENED: `extends` is walked here, so no caller ever sees a delta
+ *  and mistakes it for the whole thing. */
+export declare function getResponseSpec(id: string): ResponseSpec;

package/dist/wire/stream-interpreter.d.ts

@@ -0,0 +1,94 @@
+/** Turn a provider's SSE events into unified stream events, driven by a spec.
+ *
+ *  The buffered interpreter gets the whole body at once and builds one object.
+ *  A stream arrives in fragments, and the parse is a small state machine: an
+ *  Anthropic `server_tool_use` accumulates its input JSON across several deltas
+ *  before it can be paired with the `*_tool_result` that completes it; OpenAI
+ *  correlates tool-call fragments by index because only the first carries an id;
+ *  Google emits its hosted-tool events once per stream and has to remember that.
+ *
+ *  -- how little of this is actually new ------------------------------------
+ *  Measured across the five hand-written parsers: 518 lines of code, of which
+ *  38 touch state. The other 93% is dispatch and mapping -- the same thing the
+ *  buffered specs express -- so this driver is the buffered one with two
+ *  differences:
+ *
+ *    1. `out` is created ONCE for the stream, not per call, so an accumulator
+ *       is how the state machine remembers.
+ *    2. One reserved accumulator, `events`, is drained and returned after each
+ *       SSE event. Emitting a unified event means emitting into it.
+ *
+ *  Everything else -- `EmitRule`, `emit`/`mode`/`when`/`as`/`effect`, the whole
+ *  evaluator -- is shared verbatim.
+ *
+ *  -- the root object -------------------------------------------------------
+ *  Paths resolve against `{ raw, out, event }`:
+ *
+ *      { "$": "raw.delta.text" }        the parsed event payload
+ *      { "$": "out.current.tool" }      state carried across events
+ *      { "eq": ["event.name", "ping"] } the SSE envelope, for keep-alives
+ *
+ *  `event.data` is the payload as it arrived, so a spec can match a sentinel
+ *  like `[DONE]` that is not JSON at all.
+ */
+import { type AccumulatorDecl, type EmitRule } from './response-interpreter';
+import { type Cond, type Json, type Registry } from './interpreter';
+/** The accumulator every stream spec emits into. Declared by the driver, not by
+ *  the spec, because a stream that cannot emit is not a stream. */
+export declare const EVENTS = "events";
+export interface EventRule {
+    /** Guard on the whole event, before any discrimination. */
+    when?: Cond;
+    /** Handle this rule and then stop: no later rule sees the event.
+     *
+     *  Two shapes need it. Anthropic's `ping` keep-alives mean nothing and must
+     *  not fall through to the type switch, so the rule has no body at all.
+     *  OpenAI's moderation and usage-only chunks emit and THEN return early,
+     *  which is why `stop` fires after the body rather than before it. */
+    stop?: boolean;
+    /** Walk an array inside the payload and apply this rule to EACH element,
+     *  with the element as `ctx.item` so `@`-paths address it.
+     *
+     *  Google sends `candidates[0].content.parts[]` on every chunk, and each part
+     *  is a different kind of thing decided by which key it has -- the same shape
+     *  `collect` handles on the buffered side. Without this the whole loop would
+     *  collapse into one effect, which is code where it could be data. */
+    each?: string;
+    /** Field of the parsed payload (or of the current element, under `each`) that
+     *  selects the case, e.g. `type`.
+     *
+     *  A LIST means "whichever of these is present", first defined wins. Google's
+     *  Interactions stream discriminates on `event_type ?? type`, and writing that
+     *  as two rules would fire both whenever the first was present. */
+    match?: string | string[];
+    cases?: Record<string, EmitRule | EmitRule[]>;
+    /** Payloads matching no case. Omitted means ignore them, which is right:
+     *  providers add event types continuously and an unknown one must not break
+     *  the stream. */
+    default?: EmitRule | EmitRule[];
+}
+export interface StreamSpec {
+    id: string;
+    extends?: string;
+    /** Carried for the LIFETIME OF THE STREAM. This is the state machine's memory:
+     *  the open tool call, the map of ids awaiting their result, the emit-once
+     *  flags. `events` is added by the driver and must not be declared here. */
+    state?: Record<string, AccumulatorDecl>;
+    /** Applied in order to each SSE event. */
+    on?: EventRule[];
+    tables?: Record<string, Record<string, Json>>;
+    _note?: string;
+}
+/** One SSE event as the transport delivers it. Structural on purpose: `wire`
+ *  does not import from `network`. */
+export interface StreamInput {
+    event?: string;
+    data: string;
+}
+export interface StreamBuildOptions {
+    /** Adapter config, for `$config`. */
+    config?: Record<string, unknown>;
+}
+/** Build a stream parser: call the returned function per SSE event, and it
+ *  returns the unified events that event produced (often none). */
+export declare function createStreamBuilder(spec: StreamSpec, reg: Registry, opts?: StreamBuildOptions): (event: StreamInput) => unknown[];

package/dist/wire/stream-specs.d.ts

@@ -0,0 +1,8 @@
+import type { StreamSpec } from './stream-interpreter';
+export declare const STREAM_SPECS: Map<string, StreamSpec>;
+/** The stream spec id for a corpus/runtime target key. */
+export declare const streamSpecId: (target: string) => string;
+/** Flattened: `extends` is walked here, so no caller sees a delta and mistakes
+ *  it for the whole thing. Merge rules mirror the response side -- `state` by
+ *  key, `on` appended parent-first, since rule order is rule meaning. */
+export declare function getStreamSpec(id: string, seen?: Set<string>): StreamSpec;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,6 +34,8 @@
     "prepublishOnly": "bun run build",
     "test": "bun test",
     "test:unit": "bun test tests/unit",
+    "test:coverage": "bun test tests/unit --coverage",
+    "coverage:gate": "bun run scripts/coverage-gate.ts",
     "test:integration": "bun test tests/integration",
     "test:helpers": "bun test tests/helpers",
     "test:live": "bun test tests/live",
@@ -44,11 +46,11 @@
     "check": "biome check src tests",
     "check:fix": "biome check --write src tests",
     "gen:registry": "bun run scripts/gen-wire-registry.ts",
-    "gate": "bun run scripts/gate.ts",
+    "gate": "bun run scripts/gate.ts --config .quality-gate/config.json",
     "gate:selftest": "node ../../quality-gate/selftest.mjs",
     "record:responses": "bun run scripts/record-responses.ts",
-    "derive:shapes": "bun run scripts/derive-response-shapes.ts",
-    "gate:snapshot": "bun run scripts/gate.ts --only api-snapshot --update"
+    "gate:snapshot": "bun run scripts/gate.ts --config .quality-gate/config.json --only api-snapshot --update",
+    "derive:shapes": "bun run scripts/derive-response-shapes.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",