@combycode/llm-sdk 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to `@combycode/llm-sdk` are documented here. The format foll
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [3.1.0] — 2026-08-25
+
+### Added
+
+- **A provider can declare a hosted tool it will not run beside certain content** (`toolConstraints`
+  in a wire spec, plus a `hasPartType` condition). Measured 2026-08-25: Google answers 400 `The mime
+  type: video/mp4 is not supported for code execution` when `code_interpreter` accompanies a PDF or a
+  video. Images are fine, `web_search` is fine, and OpenAI accepts every combination — so it is one
+  provider's rule, and it lives in that provider's spec as data rather than as an `if` in the builder.
+
+  A matched constraint drops the tool — `hasTool` reports it absent, so the spec's existing guard
+  omits it with no further edit — and records why on the built request. `LLMClient` emits each as
+  `onWarning` with code `request_adjusted`, on both `complete()` and `stream()`. Dropping it quietly
+  would trade a confusing error for the silent loss of a capability the caller asked for.
+
+- **Any spelling of a model id finds the model, and every helper resolves it the same way.**
+  Providers spell one version several ways and users copy whichever they saw: `gpt-4.1` / `gpt-4-1`,
+  `gemini-2.5-flash` / `gemini-2-5-flash`, `claude-haiku-4.5` / `claude-haiku-4-5`. Only some are
+  callable, and the rest missed the catalog outright — no price, no capabilities — and were then
+  forwarded to the provider verbatim, turning a spelling difference into a 404.
+
+  Catalog lookups are now insensitive to the separator between two digits and to case, so ~556
+  previously-unresolvable spellings reach their entry. The rule is deliberately narrow — only a
+  separator between two DIGITS moves — and is verified across the shipped catalogs to merge nothing:
+  1016 normalized keys, zero collisions.
+
+  `resolveModelId()` now always returns something callable. A spelling the provider itself accepts is
+  sent unchanged; one it would reject is corrected to the canonical id instead of being forwarded;
+  an unknown id still passes through verbatim, so fine-tunes and same-day releases keep working.
+
+### Fixed
+
+- **`createRealtime()` never translated the model id.** It parsed the provider but skipped the
+  catalog step every other helper performs, so a realtime session was the one path that sent our
+  slug instead of the provider's id. All helpers now share the single resolution step, and a test
+  calls each one and reads the wire so a helper that forgets fails CI rather than a user's request.
+
+- **An Anthropic model is reachable by the name Anthropic documents.** `claude-haiku-4-5` — the
+  spelling in Anthropic's own docs, and one the API accepts — matched no catalog key and no alias,
+  because `/v1/models` lists only the dated snapshot (`claude-haiku-4-5-20251001`) while our slug
+  dots the version (`claude-haiku-4.5`). `get()` and `getPricing()` missed in silence, and an
+  unpriced model is indistinguishable from a free one: reported from production as 72k tokens
+  billed at $0.00.
+
+  The undated form is now carried as an alias for the four affected entries (`claude-haiku-4-5`,
+  `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-opus-4-1`), derived in the catalog pipeline so a
+  regeneration keeps it. Anthropic-only, and deliberately so — the same date-stripping applied to
+  other providers invents ids that do not exist (`imagen-4.0-generate`, `command-r7b-12`), since
+  only there is the undated form a truncation rather than a real alias. Each was probed live.
+
+  `providerModelName` is untouched, so **what goes on the wire is unchanged**: a slug still
+  translates to its pinned snapshot, and an alias is still sent verbatim as the floating id the
+  caller chose. This widens what the catalog recognises, never what it calls.
+
 ## [3.0.0] — 2026-08-24
 
 ### Added

package/dist/catalog/catalog.d.ts

@@ -141,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;

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. */