@combycode/llm-sdk 2.3.0 → 3.1.0

package/dist/catalog/catalog.d.ts

@@ -73,27 +73,6 @@ export interface TokenizerInfo {
     countApiAvailable: boolean;
     tiktokenEncoding?: string;
 }
-/** Per-model WIRE traits: how to say a thing to this model, as opposed to
- *  `capabilities` / `reasoning`, which say what the model can do.
- *
- *  This is the gap that produced two shipped bugs. The catalog knew a model
- *  supported reasoning; nothing knew which of two incompatible `thinking` shapes
- *  it accepted, so adapters parsed the model id with regexes and got it wrong
- *  twice (2.2.1, and the 4.0 date-suffix defect fixed in 039 A1).
- *
- *  Adapters read these through `NormalizedRequest.wire`, which `LLMClient`
- *  resolves from the catalog. When the catalog has no entry the adapters fall
- *  back to parsing the id, so a catalog-less engine still works — the fallback
- *  is what a future release removes once every model is pinned. */
-export interface ModelWire {
-    /** Which `thinking` shape the wire accepts.
-     *  Anthropic: `adaptive` (4.6+) vs `budgeted` (pre-4.6, needs budget_tokens).
-     *  Google: `level` (3.x, thinkingLevel enum) vs `budget` (2.5, token count). */
-    thinking?: 'adaptive' | 'budgeted' | 'budget' | 'level';
-    /** Whether the model accepts a top-k sampling parameter. Anthropic retired it
-     *  after Opus 4.6 and 400s on models that no longer take it. */
-    topK?: boolean;
-}
 export interface ModelInfo {
     provider: string;
     /** Catalog key — our canonical (normalised) slug, e.g. `claude-opus-4.8`. */
@@ -115,8 +94,6 @@ export interface ModelInfo {
     /** Other callable ids that resolve to this model (dated snapshots, the bare
      *  callable form). Indexed for lookup + accepted as model strings. */
     aliases?: string[];
-    /** Per-model wire traits — see ModelWire. */
-    wire?: ModelWire;
     /** Which wire spec builds this model's requests, e.g. `anthropic/messages@4.7`.
      *
      *  The specs live in `src/wire/specs` and are the artifact the Python and Rust
@@ -164,14 +141,26 @@ export declare class ModelCatalog {
     /** `provider/alias` → `provider/canonical-slug`. Lets get()/resolveModelId
      *  accept any callable id (providerModelName, dated snapshot) AND the slug. */
     private aliasIndex;
+    /** `provider/normalized-id` → `provider/canonical-slug`. The last resort, so a
+     *  user's spelling of a version never decides whether the model is found. */
+    private normIndex;
     private key;
+    private normKey;
     set(provider: string, model: string, info: Partial<Omit<ModelInfo, 'provider' | 'model'>> & {
         pricing: ModelPricing;
     }): void;
     get(provider: string, model: string): ModelInfo | null;
-    /** The exact id to SEND to the provider for a given model string. Translates
-     *  our slug → providerModelName; passes an already-callable id (alias) through
-     *  verbatim (respects an explicit choice); unknown model → verbatim passthrough. */
+    /** The exact id to SEND to the provider for a given model string.
+     *
+     *  Three cases, and the difference between them is what the caller ASKED for:
+     *    - our slug            → translate to providerModelName (the pinned snapshot)
+     *    - an id the provider itself accepts (a listed alias, e.g. a dated snapshot
+     *      or anthropic's undated name) → verbatim, because it is a deliberate choice
+     *      and rewriting it would pin a caller who asked to float
+     *    - a spelling variant that is NOT callable (`gemini-2-5-flash`) → the
+     *      canonical entry's providerModelName, since forwarding it verbatim only
+     *      produces a 404 with the user's typo in it
+     *    - unknown → verbatim, so a model we have never heard of still works */
     resolveModelId(provider: string, model: string): string;
     getPricing(provider: string, model: string): ModelPricing | null;
     getPreferredApi(provider: string, model: string): ApiType | null;
@@ -190,6 +179,14 @@ export declare class ModelCatalog {
     isStateModelBound(provider: string, model: string): boolean;
     list(provider?: string): ModelInfo[];
     load(data: Record<string, unknown>): void;
+    /** A catalog with every bundled provider entry already loaded.
+     *
+     *  This is what the engine and the client build when nobody says otherwise. A
+     *  fresh instance each time rather than a shared one: the catalog is mutable
+     *  (`set()` is public and examples use it), so sharing would let one engine's
+     *  edit reach another's request. Indexing all 427 entries costs about a
+     *  millisecond, against a network call. */
+    static withProviderDefaults(): ModelCatalog;
     /** Load every provider's `catalog.json` shipped with the SDK. Synchronous —
      *  the JSON files are bundled via static import so no I/O at runtime. */
     loadProviderDefaults(): void;

package/dist/helpers/client-resolver.d.ts

@@ -46,8 +46,27 @@ export declare class ClientResolver {
 export declare function parseModelId(modelId: string): [ProviderName, string];
 export declare function isNamespacedModelId(modelId: string): boolean;
 /** Resolve a model + optional provider to a concrete { provider, model }.
- *  A namespaced id ("provider/model") yields its own provider; a bare model
- *  requires an explicit `provider`. `label` names the caller in the error. */
+ *
+ *  An EXPLICIT provider always wins. It used to lose to the model's prefix, and
+ *  that is not a preference — every OpenRouter model id is `vendor/model`, so
+ *  `createLLM({ provider: 'openrouter', model: 'openai/gpt-5.4-nano' })` resolved
+ *  to the provider `openai` and sent the **OpenRouter key to api.openai.com**.
+ *  Ids whose vendor is not one of our five (`qwen/qwen3`) fared differently and no
+ *  better: the prefix was cast to a ProviderName and failed later as "no default
+ *  adapter for provider 'qwen'".
+ *
+ *  With a provider given, a leading `<provider>/` on the model is redundant and is
+ *  stripped — `openrouter` + `openrouter/openai/gpt-5.4-nano` is the catalog's own
+ *  slug form and means the OpenRouter model `openai/gpt-5.4-nano`.
+ *
+ *  Without one, the `provider/model` prefix is still the documented sugar, and it
+ *  stays permissive about the prefix on purpose: the pricing paths (`estimate`,
+ *  `estimator`) resolve models that are catalogued under a provider nobody can
+ *  CALL — a private deployment, a test fixture — and rejecting those would break
+ *  costing a model you never send. A prefix that is not callable fails where it
+ *  matters, in the adapter factory, naming the provider it could not build.
+ *
+ *  `label` names the caller in the error. */
 export declare function resolveModel(model: string, provider: ProviderName | undefined, label: string): {
     provider: ProviderName;
     model: string;

package/dist/helpers/count-tokens.d.ts

@@ -17,7 +17,7 @@ export interface CountTokensOptions {
     provider?: ProviderName;
     /** Text or messages to count. */
     input: string | Message[];
-    /** Key for the exact count-API path (Anthropic/Google). Falls back to engine.apiKeys. */
+    /** Key for the exact count-API path (Anthropic, Google, xAI). Falls back to engine.apiKeys. */
     apiKey?: string;
     /** Use the precise counter where available (default true). false = sync estimate. */
     exact?: boolean;

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

package/dist/helpers/select-model.d.ts

@@ -34,6 +34,41 @@ declare const DEFAULT_THRESHOLDS: {
     'context.small': number;
     'context.large': number;
 };
+/** One filter a UI can offer, and what it accepts. */
+export interface FilterFacet {
+    /** The DSL key, e.g. `price`. Write it as `key:value`. */
+    key: string;
+    /** Group heading for a picker. */
+    category: 'what it is' | 'cost' | 'thinking' | 'inputs' | 'hosted tools' | 'availability';
+    /** Short human label. */
+    label: string;
+    /** The values this key accepts. Empty when the key is a bare flag (`vision`),
+     *  which the parser reads as `key:yes`. */
+    values: string[];
+    /** True when the key also accepts `> N` / `< N`, so a picker can offer a number. */
+    numeric: boolean;
+    /** True when a bare `key` (no value) is meaningful — the parser expands it to
+     *  `key:yes`. */
+    bare: boolean;
+}
+/** Every clause the query parser understands, as data.
+ *
+ *  Exported because the alternative is a UI hand-listing the same tags: a second
+ *  copy of this vocabulary, drifting from the parser the first time either moves,
+ *  and drifting invisibly because a wrong tag reads as "no models matched" rather
+ *  than as an error. Here the picker and the parser cannot disagree — both come
+ *  from `KNOWN_KEYS`, `CAP_KEYS` and `BUILTIN_TOOL_KEYS` above.
+ *
+ *  `type`, `provider`, `status` and `tier` take their values from the CATALOG
+ *  when one is passed, because those are open sets: a provider ships a new model
+ *  type and a hard-coded list is wrong that day. Without a catalog they come back
+ *  empty rather than guessed — an empty list is honest, a stale list is not. */
+export declare function filterFacets(catalog?: {
+    list(): ModelInfo[];
+}): FilterFacet[];
+/** The shorthand tags the parser expands before matching (`cheap` → `price:low`).
+ *  A picker can show these as one-click presets. */
+export declare function filterAliases(): Record<string, string>;
 /** All matching models, ranked cheapest-first (tiebreak: newest version). */
 export declare function selectModels(query: string | string[], opts?: SelectOptions): ModelInfo[];
 /** The single best match as a `provider/slug` string (feedable to complete), or null. */