@tanstack-ai-browser/apfel 0.1.0 → 0.2.0

package/dist/guided-schema.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool schemas in the subset of JSON Schema that apfel's guided generation
+ * enforces, for the tool step's arguments (see adapter.ts, `stepSchema`).
+ * apfel rejects the keywords it can't enforce with HTTP 400.
+ */
+type JsonSchema = Record<string, unknown>;
+/**
+ * The schema in the subset guided generation enforces: types, properties,
+ * required, items, enum, const and descriptions. Local `$ref`s are inlined,
+ * `anyOf`/`oneOf`/type unions become their first non-null choice, and
+ * constraints it can't enforce (lengths, patterns, formats…) are dropped.
+ */
+export declare function toGuidedSchema(schema: unknown, root?: JsonSchema, depth?: number): JsonSchema;
+/**
+ * Arguments written under `toGuidedSchema`, without the nulls it allows in
+ * optional fields: a null is a field the model left out.
+ */
+export declare function withoutNulls(value: unknown, schema: JsonSchema): unknown;
+export {};
+//# sourceMappingURL=guided-schema.d.ts.map

package/dist/guided-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guided-schema.d.ts","sourceRoot":"","sources":["../src/guided-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAoBzC;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,UAA2C,EACjD,KAAK,SAAI,GACR,UAAU,CA4EZ;AA2BD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAuBxE"}

package/dist/guided-schema.js

@@ -0,0 +1,136 @@
+/**
+ * Tool schemas in the subset of JSON Schema that apfel's guided generation
+ * enforces, for the tool step's arguments (see adapter.ts, `stepSchema`).
+ * apfel rejects the keywords it can't enforce with HTTP 400.
+ */
+/** Keywords guided generation can enforce; apfel rejects others with 400. */
+const KEPT = ["type", "description", "enum", "const"];
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** The schema a local `$ref` (`#/$defs/X`, `#/definitions/X`) points to. */
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const key of ref.slice(2).split("/")) {
+        node = isObject(node)
+            ? node[key.replace(/~1/g, "/").replace(/~0/g, "~")]
+            : undefined;
+    }
+    return isObject(node) ? node : undefined;
+}
+/**
+ * The schema in the subset guided generation enforces: types, properties,
+ * required, items, enum, const and descriptions. Local `$ref`s are inlined,
+ * `anyOf`/`oneOf`/type unions become their first non-null choice, and
+ * constraints it can't enforce (lengths, patterns, formats…) are dropped.
+ */
+export function toGuidedSchema(schema, root = isObject(schema) ? schema : {}, depth = 0) {
+    if (!isObject(schema) || depth > 12)
+        return { type: "string" };
+    if (typeof schema.$ref === "string") {
+        const target = resolveRef(schema.$ref, root);
+        return target
+            ? toGuidedSchema({ ...target, ...withoutKey(schema, "$ref") }, root, depth + 1)
+            : { type: "string" };
+    }
+    const choices = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(choices)) {
+        const choice = choices.find((c) => isObject(c) && c.type !== "null") ?? choices[0];
+        return toGuidedSchema({
+            ...(isObject(choice) ? choice : {}),
+            ...(schema.description !== undefined && {
+                description: schema.description
+            })
+        }, root, depth + 1);
+    }
+    if (Array.isArray(schema.allOf)) {
+        const merged = schema.allOf.reduce((all, part) => (isObject(part) ? mergeSchemas(all, part) : all), withoutKey(schema, "allOf"));
+        return toGuidedSchema(merged, root, depth + 1);
+    }
+    const out = {};
+    for (const key of KEPT) {
+        if (schema[key] !== undefined)
+            out[key] = schema[key];
+    }
+    if (Array.isArray(out.type)) {
+        out.type = out.type.find((t) => t !== "null") ?? "string";
+    }
+    if (out.type === undefined) {
+        if (isObject(schema.properties))
+            out.type = "object";
+        else if (schema.items !== undefined)
+            out.type = "array";
+        else if (Array.isArray(out.enum))
+            out.type = typeof out.enum[0];
+        else if (out.const === undefined)
+            out.type = "string";
+    }
+    if (out.type === "object") {
+        const properties = isObject(schema.properties) ? schema.properties : {};
+        out.properties = Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+            key,
+            toGuidedSchema(value, root, depth + 1)
+        ]));
+        out.required = Array.isArray(schema.required)
+            ? schema.required.filter((key) => typeof key === "string" && key in properties)
+            : [];
+        // An optional field can also be null, as in the Prompt API adapter
+        // (Gemini Nano wrote 0 for coordinates it didn't have). apfel reads a
+        // nullable field as optional, and takes only strings in an enum, so an
+        // enum gets no null of its own. `withoutNulls` drops any null written.
+        const required = new Set(out.required);
+        for (const [key, value] of Object.entries(out.properties)) {
+            if (!required.has(key))
+                value.type = [value.type, "null"];
+        }
+    }
+    if (out.type === "array") {
+        out.items = toGuidedSchema(schema.items ?? {}, root, depth + 1);
+    }
+    return out;
+}
+function withoutKey(schema, key) {
+    const rest = { ...schema };
+    delete rest[key];
+    return rest;
+}
+function mergeSchemas(a, b) {
+    const merged = { ...a, ...b };
+    if (isObject(a.properties) || isObject(b.properties)) {
+        merged.properties = {
+            ...(isObject(a.properties) ? a.properties : {}),
+            ...(isObject(b.properties) ? b.properties : {})
+        };
+    }
+    if (Array.isArray(a.required) || Array.isArray(b.required)) {
+        merged.required = [
+            ...new Set([
+                ...(Array.isArray(a.required) ? a.required : []),
+                ...(Array.isArray(b.required) ? b.required : [])
+            ])
+        ];
+    }
+    return merged;
+}
+/**
+ * Arguments written under `toGuidedSchema`, without the nulls it allows in
+ * optional fields: a null is a field the model left out.
+ */
+export function withoutNulls(value, schema) {
+    if (Array.isArray(value)) {
+        const items = isObject(schema.items) ? schema.items : {};
+        return value.map((item) => withoutNulls(item, items));
+    }
+    if (!isObject(value))
+        return value;
+    const properties = isObject(schema.properties) ? schema.properties : {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    return Object.fromEntries(Object.entries(value).flatMap(([key, field]) => field === null && !required.includes(key)
+        ? []
+        : [
+            [
+                key,
+                withoutNulls(field, isObject(properties[key]) ? properties[key] : {})
+            ]
+        ]));
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 /**
  * TanStack AI adapter for Apple's on-device Foundation Model, served by apfel.
+ * The model catalog (model-meta.ts) is exported here too.
  */
-export { APFEL_BASE_URL, APFEL_TEXT_MODELS, ApfelTextAdapter, apfelText, isApfelAvailable } from "./adapter.js";
-export type { ApfelModelOptions, ApfelProviderUsageDetails, ApfelTextConfig, ApfelTextModel } from "./adapter.js";
+export { apfelText } from "./adapter.js";
+export type { ApfelConfig, ApfelModel, ApfelTextAdapter, ApfelTextModelOptions, Availability } from "./adapter.js";
+export { APFEL_CHAT_MODELS, APFEL_MODEL_META } from "./model-meta.js";
+export type { ApfelChatModel, ApfelModelMeta } from "./model-meta.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EACjB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,iBAAiB,EACjB,yBAAyB,EACzB,eAAe,EACf,cAAc,EACf,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAClH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACrE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1,4 +1,6 @@
 /**
  * TanStack AI adapter for Apple's on-device Foundation Model, served by apfel.
+ * The model catalog (model-meta.ts) is exported here too.
  */
-export { APFEL_BASE_URL, APFEL_TEXT_MODELS, ApfelTextAdapter, apfelText, isApfelAvailable } from "./adapter.js";
+export { apfelText } from "./adapter.js";
+export { APFEL_CHAT_MODELS, APFEL_MODEL_META } from "./model-meta.js";

package/dist/model-meta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The models apfel serves: Apple's on-device Foundation Model, with what it
+ * supports. It doesn't reason, so `chat()` offers no `reasoning` option for it.
+ * It reads images on macOS 27 and later; on older macOS apfel gives it only
+ * text read from the image.
+ */
+/** What a model apfel serves supports. */
+export type ApfelModelMeta = {
+    /** The model's id, as apfel lists it. */
+    name: string;
+    supports: {
+        input: ReadonlyArray<"text" | "image">;
+        output: ReadonlyArray<"text">;
+        capabilities: ReadonlyArray<"tools">;
+    };
+};
+/** The models apfel serves: Apple's on-device Foundation Model. */
+export declare const APFEL_CHAT_MODELS: readonly ["apple-foundationmodel"];
+/** A model apfel serves. */
+export type ApfelChatModel = (typeof APFEL_CHAT_MODELS)[number];
+/** Each model's metadata, by name. */
+export declare const APFEL_MODEL_META: Readonly<Record<ApfelChatModel, ApfelModelMeta>>;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-meta.d.ts","sourceRoot":"","sources":["../src/model-meta.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACR,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,OAAO,CAAC,CAAA;QACtC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;QAC7B,YAAY,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;KACrC,CAAA;CACF,CAAA;AAWD,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,oCAAyC,CAAA;AAEvE,4BAA4B;AAC5B,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/D,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,cAAc,CAAC,CAE7E,CAAA"}

package/dist/model-meta.js

@@ -0,0 +1,20 @@
+/**
+ * The models apfel serves: Apple's on-device Foundation Model, with what it
+ * supports. It doesn't reason, so `chat()` offers no `reasoning` option for it.
+ * It reads images on macOS 27 and later; on older macOS apfel gives it only
+ * text read from the image.
+ */
+const APPLE_FOUNDATION_MODEL = {
+    name: "apple-foundationmodel",
+    supports: {
+        input: ["text", "image"],
+        output: ["text"],
+        capabilities: ["tools"]
+    }
+};
+/** The models apfel serves: Apple's on-device Foundation Model. */
+export const APFEL_CHAT_MODELS = [APPLE_FOUNDATION_MODEL.name];
+/** Each model's metadata, by name. */
+export const APFEL_MODEL_META = {
+    [APPLE_FOUNDATION_MODEL.name]: APPLE_FOUNDATION_MODEL
+};

package/dist/tools.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Tool calls by prompt, a copy of the Prompt API adapter's
+ * (`@tanstack-ai-browser/prompt-api`'s `tools.ts`): keep the two
+ * identical. Apple's model writes malformed
+ * native tool calls that apfel can't parse, so the system prompt lists the
+ * tools as JSON and asks for a call as JSON in a ```tool_call fence; results
+ * go back in a ```tool_result fence. The adapter reads calls out of the
+ * streamed text.
+ */
+import type { ModelMessage, Tool } from "@tanstack/ai";
+/** A tool call read from the model's text. */
+export type ParsedToolCall = {
+    name: string;
+    arguments: Record<string, unknown>;
+};
+/**
+ * The system prompt with the tools and how to call them; unchanged without
+ * tools.
+ */
+export declare function toolSystemPrompt(system: string, tools: ReadonlyArray<Tool>): string;
+/** Earlier tool calls in the conversation, as the model would have written them. */
+export declare function toolCallFence(calls: NonNullable<ModelMessage["toolCalls"]>): string;
+/** A tool's result line for a ```tool_result fence. */
+export declare function toolResultLine(id: string, name: string, content: string, error?: string): string;
+/** Tool results as the model reads them. */
+export declare const toolResultFence: (lines: ReadonlyArray<string>) => string;
+/**
+ * The first tool call in a fence's body: a JSON object (or an array of them,
+ * or one per line) with `name` (or `tool`, `tool_name`) and `arguments` (or
+ * `parameters`), the arguments possibly a JSON string, maybe wrapped in a
+ * `tool_call` or `function` key; or a Python-style call, `[name(key="v")]`;
+ * or `call:name{key:value}`.
+ */
+export declare function parseToolCall(body: string): ParsedToolCall | undefined;
+/**
+ * Reads a streamed reply: `push` each piece and get back the text that can
+ * be shown now; text inside a ```tool_call fence (or another call's
+ * delimiters: `<tool_call>`, `<|tool_call>`, `<|tool_call_start|>`, or a
+ * Python-style `[name(…)]`) is held back. The first
+ * fence that closes ends the reply (stop generating then): `fence` is its
+ * text, `call` the call in it, if it holds one (else the fence is a failed
+ * call, for `repairToolCall`), and `trailing` the text after it. Other code
+ * fences are text. `end` gives the rest, reading an unclosed fence as the
+ * reply's last.
+ */
+export declare function toolCallReader(): {
+    readonly call: ParsedToolCall | undefined;
+    readonly fence: string | undefined;
+    /** Text that came after the fence: shown after the call. */
+    readonly trailing: string;
+    push(piece: string): string;
+    end(): string;
+};
+/** Why a call doesn't fit the tools (an unknown tool, or arguments that fail its schema), if it doesn't. */
+export declare function invalidToolCall(call: ParsedToolCall, tools: ReadonlyArray<Tool>): string | undefined;
+/** Why a reply's ```tool_call fence isn't a valid call, if it isn't. */
+export declare const toolCallError: (call: ParsedToolCall | undefined, tools: ReadonlyArray<Tool>) => string | undefined;
+/** The message after a failed call, asking for it again. */
+export declare const repairPrompt: (reason: string) => string;
+/**
+ * One repair of a failed tool call, with output held to a schema (as webgllm
+ * repairs): the tool's arguments if `name` is a tool, else first the tool's
+ * name, then its arguments. `generate(schema)` asks the model, with the
+ * conversation, its failed attempt and `repairPrompt`, for JSON that fits
+ * `schema`, and returns it parsed. Undefined if the repair fails too.
+ */
+export declare function repairToolCall(tools: ReadonlyArray<Tool>, name: string | undefined, generate: (schema: Record<string, unknown>) => Promise<unknown>): Promise<ParsedToolCall | undefined>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAEtD,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAA;AAiBjF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,MAAM,CAiCnF;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,GAAG,MAAM,CAWnF;AAED,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAUhG;AAED,4CAA4C;AAC5C,eAAO,MAAM,eAAe,UAAW,aAAa,CAAC,MAAM,CAAC,WAAqD,CAAA;AAEjH;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CA0CtE;AAyHD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc;aA4CtB,IAAI;aAGJ,KAAK;IAGT,4DAA4D;aACxD,QAAQ;IAGZ,IAAI,QAAQ,MAAM,GAAG,MAAM;IAI3B,GAAG,IAAI,MAAM;EAkBhB;AA2DD,4GAA4G;AAC5G,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GACzB,MAAM,GAAG,SAAS,CAKpB;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,SAClB,cAAc,GAAG,SAAS,SACzB,aAAa,CAAC,IAAI,CAAC,uBAIsB,CAAA;AAElD,4DAA4D;AAC5D,eAAO,MAAM,YAAY,WAAY,MAAM,WACgB,CAAA;AAE3D;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,EAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAC9D,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CA2BrC"}