@bitbaum/ai-kit 1.4.0 → 1.4.2

package/dist/capability/classify.d.ts

@@ -23,9 +23,10 @@ import type { Classification } from "./types.js";
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export declare function saysToolsUnsupported(body: string): boolean;
 export type ToolAttempt = {

package/dist/capability/classify.js

@@ -4,29 +4,50 @@
  * Every entry names tools or functions explicitly. Deliberately absent:
  * "invalid request", "bad parameter", "unsupported" on its own — each of those
  * appears in vendor 400s for a dozen unrelated reasons, and a match on one of
- * them would silently disable a working model. When in doubt the answer is to
- * record nothing; an unobserved model gets asked again on the next message,
- * whereas a wrongly-negative one does not.
+ * them would silently disable a working model.
+ *
+ * But "when in doubt, record nothing" is only cheap for a caller that can
+ * retry freely, and the real caller cannot. A caller that sends definitions
+ * ALSO drops whatever prose fallback it has, because definitions are supposed
+ * to replace it — so a refusal this list fails to recognise costs a whole turn
+ * in which the model can neither call a tool nor be told how to act without
+ * one, and it costs that turn EVERY turn, forever, because nothing is ever
+ * learned. A missed phrasing is not one wasted request; it is a permanently
+ * mute model.
+ *
+ * So the bar is: does the vendor NAME tools or functions, and NEGATE support?
+ * Both halves, explicitly. Everything meeting that bar belongs here, including
+ * the boring grammatical variants — plural, `are`, `cannot use` — which is
+ * where the first real gap was found (`tools are not supported by this model`
+ * matched nothing at all).
  */
 const TOOLS_UNSUPPORTED_PATTERNS = [
-    /tool[\s_-]?(use|call|calls|calling)\s+(is\s+)?(not|un)[\s_-]?support/i,
+    /tool[\s_-]?(use|call|calls|calling)\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
     /does\s+not\s+support\s+tool/i,
     /doesn'?t\s+support\s+tool/i,
     /no\s+support\s+for\s+tool/i,
-    /function[\s_-]?call(ing)?\s+(is\s+)?(not|un)[\s_-]?support/i,
+    /function[\s_-]?call(ing)?\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
     /does\s+not\s+support\s+function/i,
     /doesn'?t\s+support\s+function/i,
     /model\s+.{0,60}?\s+does\s+not\s+support\s+(the\s+)?(`?tools`?|`?functions`?)/i,
     /unsupported\s+parameter:?\s*'?"?tools?"?'?/i,
     /unknown\s+(field|parameter):?\s*'?"?tools?"?'?/i,
-    /`?tools`?\s+is\s+not\s+(a\s+)?(valid|supported|allowed)/i,
+    // "tools are not supported", "tool is not valid", "functions are unsupported".
+    // The singular-and-`is` form of this was already here; the plural-and-`are`
+    // form is the one vendors actually write, and it matched nothing.
+    /`?(tools?|functions?)`?\s+(is|are)\s+(not\s+(a\s+)?(valid|supported|allowed|available)|unsupported)/i,
+    // "this model cannot use tools" / "can't call functions".
+    /(cannot|can'?t|is\s+unable\s+to)\s+(use|call|handle|execute)\s+(`?tools?`?|`?functions?`?)/i,
+    // "no tool support", "without function support".
+    /no\s+(`?tools?`?|`?functions?`?)\s+support/i,
 ];
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export function saysToolsUnsupported(body) {
     if (!body)

package/dist/complete.d.ts

@@ -59,10 +59,38 @@ import { type Env, type Link, type Provider } from "./chain.js";
 import type { HealthTracker } from "./health.js";
 import { type RateLimitKind } from "./limits.js";
 import { type QuotaReading } from "./meter.js";
-/** One message in the OpenAI chat-completions shape every provider here speaks. */
+/**
+ * A piece of a message, for the models that accept more than text.
+ *
+ * The same shape every provider here already speaks, because it is OpenAI's —
+ * `image_url.url` takes a `data:` URL or an `https:` one.
+ */
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+};
+/**
+ * One message in the OpenAI chat-completions shape every provider here speaks.
+ *
+ * `content` accepts parts as well as a string because the implementation
+ * always carried them: `callLink` forwards `messages` into the request body
+ * untouched, so a multimodal message has worked at runtime since the first
+ * release while the type insisted it could not. A consumer that needed to send
+ * a screenshot therefore had to cast around our own type — and a cast written
+ * to work around a library is a thing the next consumer copies.
+ *
+ * Backward compatible by construction: every existing caller passes a string,
+ * and a string is still a `ChatMessage["content"]`.
+ */
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";
-    content: string;
+    content: string | ContentPart[];
     /** Present on `role: "tool"` replies; passed through untouched. */
     tool_call_id?: string;
     name?: string;

package/dist/grounding/verify.js

@@ -183,7 +183,25 @@ function properNounRuns(text) {
     const out = [];
     // Strip fenced and inline code — quoted identifiers are usually the user's
     // own or a literal under discussion, not a claim about the world.
-    const prose = text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+    //
+    // Markdown table pipes become line breaks for the same reason a full stop is
+    // a boundary: a cell is its own utterance, and a run must not span two of
+    // them. Observed on a live answer that laid its findings out as a table —
+    // the header row `| Category | Item | Status | Notes |` yielded the runs
+    // "Item" and "Item Status Notes Pending", the last of those having run on
+    // into the FIRST CELL OF THE NEXT ROW. The answer was entirely grounded and
+    // was reported as fabricating, which is the worst direction for this check
+    // to fail in: a warning that fires on correct answers teaches the operator
+    // to dismiss the warning.
+    //
+    // Splitting per cell also makes each header word cell-initial, and
+    // sentence-initial single words are already skipped for exactly this reason.
+    // Recall is barely touched: a fabricated name INSIDE a cell still trips its
+    // remaining tokens, the same trade already accepted at sentence starts.
+    const prose = text
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ")
+        .replace(/\|/g, "\n");
     for (const sentence of prose.split(/(?<=[.!?:\n])\s+/)) {
         const tokens = sentence.match(/[A-Za-z][A-Za-z0-9&.'’-]*/g) ?? [];
         let run = [];

package/dist/index.d.ts

@@ -52,7 +52,7 @@
 export { type Provider, type Env, type Link, type CostVerdict, providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
 export { type CatalogVerdict, type CheckCatalogOptions, checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
 export { type ChainAttemptFailure, type TryChainOptions, ChainExhaustedError, tryChain, } from "./attempt.js";
-export { type ChatMessage, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
+export { type ChatMessage, type ContentPart, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
 export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthTracker, createHealthTracker, } from "./health.js";
 export { type LivenessResult, type LivenessOptions, type LivenessProbe, type AiHealthHandlerOptions, createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { type RateLimitKind, classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";

package/dist-cjs/grounding/verify.js

@@ -187,7 +187,25 @@ function properNounRuns(text) {
     const out = [];
     // Strip fenced and inline code — quoted identifiers are usually the user's
     // own or a literal under discussion, not a claim about the world.
-    const prose = text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+    //
+    // Markdown table pipes become line breaks for the same reason a full stop is
+    // a boundary: a cell is its own utterance, and a run must not span two of
+    // them. Observed on a live answer that laid its findings out as a table —
+    // the header row `| Category | Item | Status | Notes |` yielded the runs
+    // "Item" and "Item Status Notes Pending", the last of those having run on
+    // into the FIRST CELL OF THE NEXT ROW. The answer was entirely grounded and
+    // was reported as fabricating, which is the worst direction for this check
+    // to fail in: a warning that fires on correct answers teaches the operator
+    // to dismiss the warning.
+    //
+    // Splitting per cell also makes each header word cell-initial, and
+    // sentence-initial single words are already skipped for exactly this reason.
+    // Recall is barely touched: a fabricated name INSIDE a cell still trips its
+    // remaining tokens, the same trade already accepted at sentence starts.
+    const prose = text
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ")
+        .replace(/\|/g, "\n");
     for (const sentence of prose.split(/(?<=[.!?:\n])\s+/)) {
         const tokens = sentence.match(/[A-Za-z][A-Za-z0-9&.'’-]*/g) ?? [];
         let run = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",
@@ -90,12 +90,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^26.4.1",
-    "eslint": "^10.9.1",
+    "@types/node": "^26.5.0",
+    "eslint": "^10.10.0",
     "globals": "^17.12.0",
     "prettier": "3.9.6",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0"
+    "typescript-eslint": "^8.70.0"
   },
   "dependencies": {
     "ai-forms": "^0.1.2"

package/src/capability/classify.ts

@@ -27,30 +27,51 @@ import type { Classification } from "./types.js";
  * Every entry names tools or functions explicitly. Deliberately absent:
  * "invalid request", "bad parameter", "unsupported" on its own — each of those
  * appears in vendor 400s for a dozen unrelated reasons, and a match on one of
- * them would silently disable a working model. When in doubt the answer is to
- * record nothing; an unobserved model gets asked again on the next message,
- * whereas a wrongly-negative one does not.
+ * them would silently disable a working model.
+ *
+ * But "when in doubt, record nothing" is only cheap for a caller that can
+ * retry freely, and the real caller cannot. A caller that sends definitions
+ * ALSO drops whatever prose fallback it has, because definitions are supposed
+ * to replace it — so a refusal this list fails to recognise costs a whole turn
+ * in which the model can neither call a tool nor be told how to act without
+ * one, and it costs that turn EVERY turn, forever, because nothing is ever
+ * learned. A missed phrasing is not one wasted request; it is a permanently
+ * mute model.
+ *
+ * So the bar is: does the vendor NAME tools or functions, and NEGATE support?
+ * Both halves, explicitly. Everything meeting that bar belongs here, including
+ * the boring grammatical variants — plural, `are`, `cannot use` — which is
+ * where the first real gap was found (`tools are not supported by this model`
+ * matched nothing at all).
  */
 const TOOLS_UNSUPPORTED_PATTERNS: RegExp[] = [
-  /tool[\s_-]?(use|call|calls|calling)\s+(is\s+)?(not|un)[\s_-]?support/i,
+  /tool[\s_-]?(use|call|calls|calling)\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
   /does\s+not\s+support\s+tool/i,
   /doesn'?t\s+support\s+tool/i,
   /no\s+support\s+for\s+tool/i,
-  /function[\s_-]?call(ing)?\s+(is\s+)?(not|un)[\s_-]?support/i,
+  /function[\s_-]?call(ing)?\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
   /does\s+not\s+support\s+function/i,
   /doesn'?t\s+support\s+function/i,
   /model\s+.{0,60}?\s+does\s+not\s+support\s+(the\s+)?(`?tools`?|`?functions`?)/i,
   /unsupported\s+parameter:?\s*'?"?tools?"?'?/i,
   /unknown\s+(field|parameter):?\s*'?"?tools?"?'?/i,
-  /`?tools`?\s+is\s+not\s+(a\s+)?(valid|supported|allowed)/i,
+  // "tools are not supported", "tool is not valid", "functions are unsupported".
+  // The singular-and-`is` form of this was already here; the plural-and-`are`
+  // form is the one vendors actually write, and it matched nothing.
+  /`?(tools?|functions?)`?\s+(is|are)\s+(not\s+(a\s+)?(valid|supported|allowed|available)|unsupported)/i,
+  // "this model cannot use tools" / "can't call functions".
+  /(cannot|can'?t|is\s+unable\s+to)\s+(use|call|handle|execute)\s+(`?tools?`?|`?functions?`?)/i,
+  // "no tool support", "without function support".
+  /no\s+(`?tools?`?|`?functions?`?)\s+support/i,
 ];
 
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export function saysToolsUnsupported(body: string): boolean {
   if (!body) return false;

package/src/complete.ts

@@ -63,10 +63,32 @@ import { classifyRateLimit, retryAfterSeconds, type RateLimitKind } from "./limi
 import { readQuota, readingFromRefusal, type QuotaReading } from "./meter.js";
 import { parseTextToolCalls, stripToolCallLines, toolNamesFrom } from "./tool-protocol.js";
 
-/** One message in the OpenAI chat-completions shape every provider here speaks. */
+/**
+ * A piece of a message, for the models that accept more than text.
+ *
+ * The same shape every provider here already speaks, because it is OpenAI's —
+ * `image_url.url` takes a `data:` URL or an `https:` one.
+ */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string; detail?: "auto" | "low" | "high" } };
+
+/**
+ * One message in the OpenAI chat-completions shape every provider here speaks.
+ *
+ * `content` accepts parts as well as a string because the implementation
+ * always carried them: `callLink` forwards `messages` into the request body
+ * untouched, so a multimodal message has worked at runtime since the first
+ * release while the type insisted it could not. A consumer that needed to send
+ * a screenshot therefore had to cast around our own type — and a cast written
+ * to work around a library is a thing the next consumer copies.
+ *
+ * Backward compatible by construction: every existing caller passes a string,
+ * and a string is still a `ChatMessage["content"]`.
+ */
 export interface ChatMessage {
   role: "system" | "user" | "assistant" | "tool";
-  content: string;
+  content: string | ContentPart[];
   /** Present on `role: "tool"` replies; passed through untouched. */
   tool_call_id?: string;
   name?: string;

package/src/grounding/verify.ts

@@ -201,7 +201,25 @@ function properNounRuns(text: string): string[] {
   const out: string[] = [];
   // Strip fenced and inline code — quoted identifiers are usually the user's
   // own or a literal under discussion, not a claim about the world.
-  const prose = text.replace(/```[\s\S]*?```/g, " ").replace(/`[^`]*`/g, " ");
+  //
+  // Markdown table pipes become line breaks for the same reason a full stop is
+  // a boundary: a cell is its own utterance, and a run must not span two of
+  // them. Observed on a live answer that laid its findings out as a table —
+  // the header row `| Category | Item | Status | Notes |` yielded the runs
+  // "Item" and "Item Status Notes Pending", the last of those having run on
+  // into the FIRST CELL OF THE NEXT ROW. The answer was entirely grounded and
+  // was reported as fabricating, which is the worst direction for this check
+  // to fail in: a warning that fires on correct answers teaches the operator
+  // to dismiss the warning.
+  //
+  // Splitting per cell also makes each header word cell-initial, and
+  // sentence-initial single words are already skipped for exactly this reason.
+  // Recall is barely touched: a fabricated name INSIDE a cell still trips its
+  // remaining tokens, the same trade already accepted at sentence starts.
+  const prose = text
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/`[^`]*`/g, " ")
+    .replace(/\|/g, "\n");
 
   for (const sentence of prose.split(/(?<=[.!?:\n])\s+/)) {
     const tokens = sentence.match(/[A-Za-z][A-Za-z0-9&.'’-]*/g) ?? [];

package/src/index.ts

@@ -84,6 +84,7 @@ export {
 
 export {
   type ChatMessage,
+  type ContentPart,
   type ToolCall,
   type CompleteOptions,
   type CompleteResult,