@blockrun/llm 3.23.2 → 3.24.0

package/README.md

@@ -444,10 +444,13 @@ picked:
 **Search and routing.** xAI search (`x_search` / `web_search` tools, or
 `search` / `searchParameters` not set to `mode: 'off'`) runs on `xai/*` models
 only. When a routed call asks for search, the candidate chain is narrowed to
-its `xai/*` models in the router's order; when the route has none, `route()` /
-`smartChat()` / `smartChatCompletion()` throw before anything is sent or paid.
-For search, calling an `xai/*` model directly (e.g. `xai/grok-4.3`) is the
-dependable path.
+its `xai/*` models in the router's order. The router seldom ranks xAI, so when
+the route has none, the call falls back to the catalog's search-capable xAI
+models (those `/v1/models` tags `search`): cheapest first on `eco` / `auto`,
+most capable first on `premium`. `routing.reasoning` says when that happened.
+Only a catalog with no `xai/*` chat model at all makes `route()` /
+`smartChat()` / `smartChatCompletion()` throw, before anything is sent or paid.
+Pin an `xai/*` model yourself when you want a specific one.
 
 ### TypeScript Types
 

package/dist/index.cjs

@@ -4359,6 +4359,24 @@ function requestsSearch(options) {
   if (options.searchParameters !== void 0) return options.searchParameters.mode !== "off";
   return options.search === true;
 }
+var searchModelsByCatalog = /* @__PURE__ */ new WeakMap();
+function registerSearchModels(pricing, models) {
+  const xaiChat = models.filter(
+    (m) => m.id.startsWith("xai/") && m.available !== false && Array.isArray(m.categories) && m.categories.includes("chat") && pricing.has(m.id)
+  );
+  const tagged = xaiChat.filter((m) => m.categories.includes("search"));
+  searchModelsByCatalog.set(pricing, (tagged.length > 0 ? tagged : xaiChat).map((m) => m.id));
+}
+function searchFallbackChain(modelPricing, routingProfile) {
+  const pool = searchModelsByCatalog.get(modelPricing) ?? [...modelPricing.keys()].filter((id) => id.startsWith("xai/"));
+  const price = (id) => {
+    const p = modelPricing.get(id);
+    return p ? p.inputPrice + p.outputPrice : Number.POSITIVE_INFINITY;
+  };
+  const sorted = [...pool].sort((a, b) => price(a) - price(b) || b.localeCompare(a, void 0, { numeric: true }));
+  if (routingProfile !== "premium") return sorted;
+  return [...pool].sort((a, b) => price(b) - price(a) || b.localeCompare(a, void 0, { numeric: true }));
+}
 function routingProfileForModel(model) {
   return AUTO_ROUTING_PROFILES[model.toLowerCase()];
 }
@@ -4406,11 +4424,16 @@ function routeWithCatalog(prompt, systemPrompt, maxOutputTokens, modelPricing, o
     const resolved = !id.startsWith("free/") ? id : modelPricing.has(`nvidia/${id.slice(5)}`) ? `nvidia/${id.slice(5)}` : null;
     if (resolved && !callable.includes(resolved)) callable.push(resolved);
   }
+  let searchFallback = false;
   if (requestsSearch(options)) {
-    const searchable = callable.filter((id) => id.startsWith("xai/"));
+    let searchable = callable.filter((id) => id.startsWith("xai/"));
+    if (searchable.length === 0) {
+      searchable = searchFallbackChain(modelPricing, options.routingProfile);
+      searchFallback = true;
+    }
     if (searchable.length === 0) {
       throw new Error(
-        `Search (x_search / web_search tools or searchParameters) runs on xai/* models only, and the ${options.routingProfile ?? "auto"} route has no xai/* candidate for this request. Call an xai/* model directly (e.g. xai/grok-4.3) or drop the search options.`
+        `Search (x_search / web_search tools or searchParameters) runs on xai/* models only, and the catalog lists no available xai/* chat model. Call an xai/* model directly or drop the search options.`
       );
     }
     callable.splice(0, callable.length, ...searchable);
@@ -4447,7 +4470,7 @@ function routeWithCatalog(prompt, systemPrompt, maxOutputTokens, modelPricing, o
     costEstimate,
     savings,
     model,
-    reasoning: model === decision.model ? decision.reasoning : `${decision.reasoning} | catalog fallback: ${model}`,
+    reasoning: searchFallback ? `${decision.reasoning} | search runs on xai/* only; the route had none, so the ${options.routingProfile === "premium" ? "most capable" : "cheapest"} search-capable xAI model: ${model}` : model === decision.model ? decision.reasoning : `${decision.reasoning} | catalog fallback: ${model}`,
     candidates: availableCandidates,
     candidateScores: decision.candidateScores?.filter(
       (score) => availableCandidates.includes(score.model)
@@ -4833,7 +4856,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.2";
+var SDK_VERSION = "3.24.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -5104,6 +5127,7 @@ var LLMClient = class _LLMClient {
         pricing.set(model.id, { inputPrice, outputPrice });
       }
     }
+    registerSearchModels(pricing, models);
     return pricing;
   }
   /**
@@ -12567,6 +12591,7 @@ var SolanaLLMClient = class {
           ...(model.billingMode ?? raw.billing_mode) === "flat" && flatPrice > 0 ? { flatPrice } : {}
         });
       }
+      registerSearchModels(pricing, models);
       return pricing;
     })();
     try {

package/dist/index.d.cts

@@ -2953,8 +2953,9 @@ interface SolanaBatchOptions {
      * re-read, in addition to the one-line log the SDK writes to stderr for each.
      * A callback that throws, or returns a promise that rejects, is logged and
      * ignored; it never affects the payment, and its promise is not awaited.
+     * Any other return value is ignored, so `(e) => events.push(e)` is fine.
      */
-    onEvent?: (event: SolanaBatchEvent) => void | PromiseLike<void>;
+    onEvent?: (event: SolanaBatchEvent) => unknown;
 }
 /** Default {@link SolanaBatchOptions.rateLimit}. */
 declare const DEFAULT_BATCH_RATE_LIMIT: {

package/dist/index.d.ts

@@ -2953,8 +2953,9 @@ interface SolanaBatchOptions {
      * re-read, in addition to the one-line log the SDK writes to stderr for each.
      * A callback that throws, or returns a promise that rejects, is logged and
      * ignored; it never affects the payment, and its promise is not awaited.
+     * Any other return value is ignored, so `(e) => events.push(e)` is fine.
      */
-    onEvent?: (event: SolanaBatchEvent) => void | PromiseLike<void>;
+    onEvent?: (event: SolanaBatchEvent) => unknown;
 }
 /** Default {@link SolanaBatchOptions.rateLimit}. */
 declare const DEFAULT_BATCH_RATE_LIMIT: {

package/dist/index.js

@@ -4228,6 +4228,24 @@ function requestsSearch(options) {
   if (options.searchParameters !== void 0) return options.searchParameters.mode !== "off";
   return options.search === true;
 }
+var searchModelsByCatalog = /* @__PURE__ */ new WeakMap();
+function registerSearchModels(pricing, models) {
+  const xaiChat = models.filter(
+    (m) => m.id.startsWith("xai/") && m.available !== false && Array.isArray(m.categories) && m.categories.includes("chat") && pricing.has(m.id)
+  );
+  const tagged = xaiChat.filter((m) => m.categories.includes("search"));
+  searchModelsByCatalog.set(pricing, (tagged.length > 0 ? tagged : xaiChat).map((m) => m.id));
+}
+function searchFallbackChain(modelPricing, routingProfile) {
+  const pool = searchModelsByCatalog.get(modelPricing) ?? [...modelPricing.keys()].filter((id) => id.startsWith("xai/"));
+  const price = (id) => {
+    const p = modelPricing.get(id);
+    return p ? p.inputPrice + p.outputPrice : Number.POSITIVE_INFINITY;
+  };
+  const sorted = [...pool].sort((a, b) => price(a) - price(b) || b.localeCompare(a, void 0, { numeric: true }));
+  if (routingProfile !== "premium") return sorted;
+  return [...pool].sort((a, b) => price(b) - price(a) || b.localeCompare(a, void 0, { numeric: true }));
+}
 function routingProfileForModel(model) {
   return AUTO_ROUTING_PROFILES[model.toLowerCase()];
 }
@@ -4275,11 +4293,16 @@ function routeWithCatalog(prompt, systemPrompt, maxOutputTokens, modelPricing, o
     const resolved = !id.startsWith("free/") ? id : modelPricing.has(`nvidia/${id.slice(5)}`) ? `nvidia/${id.slice(5)}` : null;
     if (resolved && !callable.includes(resolved)) callable.push(resolved);
   }
+  let searchFallback = false;
   if (requestsSearch(options)) {
-    const searchable = callable.filter((id) => id.startsWith("xai/"));
+    let searchable = callable.filter((id) => id.startsWith("xai/"));
+    if (searchable.length === 0) {
+      searchable = searchFallbackChain(modelPricing, options.routingProfile);
+      searchFallback = true;
+    }
     if (searchable.length === 0) {
       throw new Error(
-        `Search (x_search / web_search tools or searchParameters) runs on xai/* models only, and the ${options.routingProfile ?? "auto"} route has no xai/* candidate for this request. Call an xai/* model directly (e.g. xai/grok-4.3) or drop the search options.`
+        `Search (x_search / web_search tools or searchParameters) runs on xai/* models only, and the catalog lists no available xai/* chat model. Call an xai/* model directly or drop the search options.`
       );
     }
     callable.splice(0, callable.length, ...searchable);
@@ -4316,7 +4339,7 @@ function routeWithCatalog(prompt, systemPrompt, maxOutputTokens, modelPricing, o
     costEstimate,
     savings,
     model,
-    reasoning: model === decision.model ? decision.reasoning : `${decision.reasoning} | catalog fallback: ${model}`,
+    reasoning: searchFallback ? `${decision.reasoning} | search runs on xai/* only; the route had none, so the ${options.routingProfile === "premium" ? "most capable" : "cheapest"} search-capable xAI model: ${model}` : model === decision.model ? decision.reasoning : `${decision.reasoning} | catalog fallback: ${model}`,
     candidates: availableCandidates,
     candidateScores: decision.candidateScores?.filter(
       (score) => availableCandidates.includes(score.model)
@@ -4702,7 +4725,7 @@ function getCostSummary() {
 }
 
 // src/version.ts
-var SDK_VERSION = "3.23.2";
+var SDK_VERSION = "3.24.0";
 var USER_AGENT = `blockrun-ts/${SDK_VERSION}`;
 
 // src/client.ts
@@ -4973,6 +4996,7 @@ var LLMClient = class _LLMClient {
         pricing.set(model.id, { inputPrice, outputPrice });
       }
     }
+    registerSearchModels(pricing, models);
     return pricing;
   }
   /**
@@ -12436,6 +12460,7 @@ var SolanaLLMClient = class {
           ...(model.billingMode ?? raw.billing_mode) === "flat" && flatPrice > 0 ? { flatPrice } : {}
         });
       }
+      registerSearchModels(pricing, models);
       return pricing;
     })();
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/llm",
-  "version": "3.23.2",
+  "version": "3.24.0",
   "type": "module",
   "description": "TypeScript SDK for BlockRun - every frontier model behind one OpenAI-compatible client. Pay with a BlockRun API key or per-call in USDC. Smart routing picks the cheapest capable model. No rate limits.",
   "main": "dist/index.cjs",