@combycode/llm-sdk 2.3.0 → 3.0.0

package/dist/helpers/engine.d.ts

@@ -65,6 +65,9 @@ export interface EngineHandle {
      *  createMediaOutput, complete) read these to wire LLM clients without
      *  the caller passing apiKey explicitly. */
     apiKeys: Partial<Record<ProviderName, string>>;
+    /** Whether clients built from this engine check response shapes. Read by
+     *  `createLLM`; see `checkResponseShapes` on the options. */
+    checkResponseShapes: boolean;
     /** Build an LLMClient bound to this engine.
      *
      *  Exists so lower layers can obtain a client without importing the helpers
@@ -100,12 +103,31 @@ export interface EngineConfig {
     /** Custom low-level fetch transport — forwarded to the NetworkEngine's queue
      *  (so retry/rate-limit/hooks still apply). Defaults to globalThis.fetch. */
     fetch?: FetchFn;
-    /** Catalog wiring. Pass:
-     *    - `true` / 'defaults' → load every bundled provider catalog.json
+    /** Warn when a provider's response stops looking like the one we learned to
+     *  read: a field never seen before, a field that was always present and is now
+     *  absent, or a discriminator carrying a value nothing branches on.
+     *
+     *  OFF by default. It never changes what is parsed — it only emits `onWarning`,
+     *  so subscribe with `hooks.on('onWarning', …)` and look for codes starting
+     *  `response_shape_`. Each distinct finding is reported ONCE per client.
+     *
+     *  Worth turning on in staging and in your test suite: response drift is the
+     *  failure this library gives you the least warning about, because a renamed
+     *  field still parses — into `undefined`. */
+    checkResponseShapes?: boolean;
+    /** Catalog wiring. **Defaults to the bundled provider catalogs.**
+     *
+     *  The catalog is what the adapters read per model: which wire spec builds the
+     *  request, what the model costs, which tokenizer counts it. Starting empty
+     *  meant every one of those silently fell back — the id-derived spec, an
+     *  unknown price, an estimated token count — and nothing said so. The data is
+     *  statically imported either way, so leaving it unloaded saved no bytes.
+     *
+     *    - undefined (default) / `true` / 'defaults' → every bundled catalog.json
      *    - existing ModelCatalog instance → use as-is
-     *    - `{ entries: {...} }` → build empty + load() the entries
-     *    - undefined → empty catalog */
-    catalog?: ModelCatalog | true | 'defaults' | {
+     *    - `{ entries: {...} }` → the given entries only
+     *    - `false` / 'empty' → no entries. Everything falls back; say so on purpose. */
+    catalog?: ModelCatalog | boolean | 'defaults' | 'empty' | {
         entries: Record<string, unknown>;
     };
     /** Per-provider API keys. Helpers consult this when no apiKey is passed