@providerkit/core 0.12.2 → 0.12.3

package/src/types.ts

@@ -10,7 +10,10 @@
 /**
  * How hard the model thinks before answering. Absent = the provider's own
  * default (never sent). Passed through verbatim on OpenAI-shape
- * (`reasoning_effort`); mapped to thinking budgets on Anthropic-shape.
+ * (`reasoning_effort`). On Anthropic-shape, mapped to adaptive thinking and
+ * `output_config.effort` for current Claude models, where `none` is the lowest
+ * effort on a model that cannot stop thinking; and to thinking budgets for
+ * Claude 4.5 and older and for every other vendor on that wire.
  * Support varies per model — an unsupported level comes back as a clean 400.
  *
  * Ordered least → most; the type derives from the array so the runtime guard
@@ -39,7 +42,31 @@ export interface ImagePart {
   data: string;
 }
 
-export type ContentPart = TextPart | ImagePart;
+/** A file's media type: anything but an image's, because an image is an
+ *  `ImagePart`, which every adapter can send. */
+export type FileMimeType =
+  `application/${string}` | `audio/${string}` | `video/${string}` | `text/${string}`;
+
+/**
+ * A file the model reads — a PDF, a recording, a video — as base64 bytes,
+ * never a URL. Only the Gemini adapter sends one, as `inlineData`, the way it
+ * sends an image. Every other adapter refuses it with an `invalid`
+ * ProviderError before any request goes out, rather than drop it: a dropped
+ * attachment is a model answering about a file it never saw.
+ *
+ * Gemini takes inline data up to 100 MB per request, 50 MB for a PDF (Gemini
+ * API "File input methods", read 2026-09-27). The request carries the base64
+ * text, which is a third larger than the file. Past that limit the documented
+ * route is Gemini's File API, which this package does not wrap. Nothing here
+ * enforces the limit; Gemini answers an oversized request itself.
+ */
+export interface FilePart {
+  type: "file";
+  mimeType: FileMimeType;
+  data: string;
+}
+
+export type ContentPart = TextPart | ImagePart | FilePart;
 
 /**
  * A tool the model asked to run. `arguments` is the RAW JSON string, not a
@@ -182,6 +209,83 @@ export interface JsonOutput {
   strict?: boolean;
 }
 
+/**
+ * Read the JSON out of a model's answer. Models wrap it: a ```json fence, an
+ * unmarked fence, a sentence before it, notes after it. This takes the first
+ * fenced block marked `json` or not marked at all. With no such block, it
+ * takes the text from the first `{` or `[` to the bracket that closes it, and
+ * with no bracket either, the whole answer (a bare number, say). Then it
+ * parses that.
+ *
+ * It returns `unknown` on purpose: parsed is not validated, and a model's JSON
+ * has the schema's shape only once the caller has checked it.
+ *
+ * @throws {JsonAnswerError} when that text is not JSON. The error carries the
+ * answer, so a log shows what the model actually said.
+ */
+export function parseJsonAnswer(text: string): unknown {
+  const candidate = fencedJson(text) ?? bracketed(text);
+  try {
+    return JSON.parse(candidate);
+  } catch (error) {
+    throw new JsonAnswerError(text, error);
+  }
+}
+
+/** An answer `parseJsonAnswer` found no JSON in. `text` is the answer, cut to
+ *  2,000 characters like a provider's error body; `cause` is the SyntaxError. */
+export class JsonAnswerError extends Error {
+  readonly text: string;
+
+  constructor(text: string, cause: unknown) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    super(`The model's answer is not JSON: ${reason}`, { cause });
+    this.name = "JsonAnswerError";
+    this.text = text.slice(0, 2_000);
+  }
+}
+
+/** A fenced block, whose fences count only at the start of a line. A JSON
+ *  string can't hold a raw newline, so no line of JSON starts with a fence, and
+ *  a value carrying one (a code sample) never ends the block early. `[^\S\n]`
+ *  is a space, a tab, or the `\r` of a CRLF line. */
+const FENCED_BLOCK = /^[^\S\n]*```[^\S\n]*([^\s`]*)[^\n]*\n([\s\S]*?)^[^\S\n]*```/gm;
+
+function fencedJson(text: string): string | undefined {
+  for (const [, info = "", body = ""] of text.matchAll(FENCED_BLOCK)) {
+    const language = info.toLowerCase();
+    if (language === "" || language === "json") return body;
+  }
+  return undefined;
+}
+
+/** From the first `{` or `[` to the bracket that closes it, skipping brackets
+ *  inside strings. An answer cut off before it closes keeps its tail, and
+ *  JSON.parse says what is wrong with it.
+ *
+ *  ponytail: the FIRST opener wins, so prose with a bracket before the JSON
+ *  ("see [1]: {…}") picks the prose's. The upgrade is to try the next opener
+ *  when one fails to parse, once a model that writes that turns up. */
+function bracketed(text: string): string {
+  const start = text.search(/[[{]/);
+  if (start === -1) return text;
+  let depth = 0;
+  let inString = false;
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+    if (inString) {
+      if (char === "\\") i++;
+      else if (char === '"') inString = false;
+    } else if (char === '"') inString = true;
+    else if (char === "{" || char === "[") depth++;
+    else if (char === "}" || char === "]") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return text.slice(start);
+}
+
 /**
  * How the schema rides on a call that ALSO carries tools.
  *