@tanstack-ai-browser/apfel 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daveycodez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# @tanstack-ai-browser/apfel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [TanStack AI](https://tanstack.com/ai) adapter for Apple's on-device Foundation Model, served on your Mac by [apfel](https://apfel.franzai.com)'s OpenAI-compatible server. The browser streams straight from apfel's server, at the `baseURL` you give it.
+
+```sh
+npm install @tanstack-ai-browser/apfel @tanstack/ai
+```
+
+```ts
+import { chat } from "@tanstack/ai"
+import {
+  APFEL_BASE_URL,
+  apfelText,
+  isApfelAvailable
+} from "@tanstack-ai-browser/apfel"
+
+const config = { baseURL: APFEL_BASE_URL }
+
+if (await isApfelAvailable("apple-foundationmodel", config)) {
+  const stream = chat({
+    adapter: apfelText("apple-foundationmodel", config),
+    messages,
+    threadId
+  })
+}
+```
+
+`baseURL` is apfel's OpenAI-compatible API, up to `/v1`; `APFEL_BASE_URL` is apfel's default address. `defaultHeaders` adds headers to every request, such as a bearer token. Apple's model doesn't reason, so `chat({ reasoning })` is a type error with this adapter.
+
+## Tool calls
+
+Tools work as with any adapter: pass them to `chat({ tools })`, MCP tools included, and `chat()` runs them. Apple's model picks the right tool but often gets its arguments wrong, renaming fields (`limit` for `numResults`) or dropping optional ones it was asked to set. So the adapter repairs every tool call before `chat()` runs it, using only the tool's JSON Schema:
+
+1. For each optional field, apfel's guided generation answers yes or no: does the request give it a value?
+2. The arguments are written again, constrained to the schema, with those fields required. Fields the model already named and typed right are kept as it wrote them.
+
+Schema keywords the on-device model can't enforce (`minLength`, `pattern`, `format`…) are dropped for the repair, `$ref`s are inlined, and `anyOf`/`oneOf` take their first non-null choice. If a repair request fails, the model's own arguments are used. Repair adds two short requests per tool call (one for a tool without optional fields), about a second and a half in all; it's in `usage.providerUsageDetails.toolRepairMs`.
+
+## Usage
+
+Each call's token counts are in `RUN_FINISHED`'s `usage`, as with any TanStack AI adapter, with timings the adapter measured in `usage.providerUsageDetails` (`ApfelProviderUsageDetails`: `firstTokenMs`, `decodeMs`, `decodeTokens`, `toolRepairMs`).
+
+```ts
+// For example, in chat() middleware:
+const stats = { name: "stats", onUsage: (ctx, usage) => console.log(usage) }
+```
+
+**Status:** early (0.0.x); the API may change. See the [repository README](https://github.com/daveycodez/tanstack-ai-browser#readme).

package/dist/adapter.d.ts

@@ -0,0 +1,98 @@
+import type { AdapterYieldChunk, TextOptions } from "@tanstack/ai";
+import { BaseTextAdapter } from "@tanstack/ai/adapters";
+import type { StructuredOutputOptions, StructuredOutputResult } from "@tanstack/ai/adapters";
+/** Where apfel's server listens by default. */
+export declare const APFEL_BASE_URL = "http://127.0.0.1:11434/v1";
+/** The models apfel serves: Apple's on-device Foundation Model. */
+export declare const APFEL_TEXT_MODELS: readonly ["apple-foundationmodel"];
+/** A model apfel serves. */
+export type ApfelTextModel = (typeof APFEL_TEXT_MODELS)[number] | (string & {});
+export type ApfelTextConfig = {
+    /** apfel's OpenAI-compatible API, up to `/v1`. `APFEL_BASE_URL` by default. */
+    baseURL?: string;
+    /** Headers sent with every request, such as apfel's bearer token. */
+    defaultHeaders?: Record<string, string>;
+};
+/**
+ * Timings of one model call, in milliseconds, in `RUN_FINISHED`'s
+ * `usage.providerUsageDetails`. The adapter measures them as the stream
+ * arrives; apfel itself reports token counts only.
+ */
+export type ApfelProviderUsageDetails = {
+    /** From sending the request to the first generated text. */
+    firstTokenMs?: number;
+    /** From the first generated text to the last. */
+    decodeMs?: number;
+    /**
+     * Tokens generated after the first chunk, estimated: apfel streams a few
+     * tokens per chunk, and the first chunk's share of the characters stands
+     * in for its share of the tokens.
+     */
+    decodeTokens?: number;
+    /**
+     * Time spent rewriting the tool calls' arguments under their schemas,
+     * after the reply ended (see the README's "Tool calls").
+     */
+    toolRepairMs?: number;
+};
+/**
+ * Request fields apfel takes for Apple's model. apfel rejects parameters
+ * the model doesn't support (stop, penalties, n…) with HTTP 400.
+ */
+export type ApfelModelOptions = {
+    temperature?: number;
+    max_tokens?: number;
+    seed?: number;
+};
+type ApfelReasoning = never;
+type MetadataByModality = {
+    text: unknown;
+    image: unknown;
+    audio: unknown;
+    video: unknown;
+    document: unknown;
+};
+export declare class ApfelTextAdapter<TModel extends string> extends BaseTextAdapter<TModel, ApfelModelOptions, readonly ["text"], MetadataByModality, ReadonlyArray<string>, unknown, never, ApfelReasoning> {
+    readonly kind: "text";
+    readonly name: "apfel";
+    readonly provider: "apfel";
+    readonly api: "openai-completions";
+    readonly inputModalities: readonly ["text"];
+    private readonly baseURL;
+    private readonly headers;
+    constructor(config: ApfelTextConfig, model: TModel);
+    chatStream(options: TextOptions<ApfelModelOptions>): AsyncIterable<AdapterYieldChunk>;
+    /**
+     * A tool call's arguments, written again under the tool's schema with
+     * guided generation. Undefined if the tool takes no arguments or a request
+     * failed: the model's own arguments are used then.
+     */
+    private repairArguments;
+    /**
+     * A JSON answer for `chat({ outputSchema })`, from apfel's JSON mode:
+     * `response_format: json_schema` constrains Apple's model to the schema
+     * (guided generation). `chat()` validates the result.
+     */
+    structuredOutput(options: StructuredOutputOptions<ApfelModelOptions>): Promise<StructuredOutputResult<unknown>>;
+}
+/**
+ * A TanStack AI text adapter for Apple's on-device Foundation Model, served
+ * by apfel.
+ *
+ * @example
+ * ```ts
+ * chat({
+ *   adapter: apfelText("apple-foundationmodel", { baseURL: APFEL_BASE_URL }),
+ *   messages,
+ *   threadId
+ * })
+ * ```
+ */
+export declare function apfelText<TModel extends ApfelTextModel>(model: TModel, config?: ApfelTextConfig): ApfelTextAdapter<TModel>;
+/**
+ * Whether apfel is running and serves the model: true if `GET /v1/models`
+ * lists it within 10 seconds.
+ */
+export declare function isApfelAvailable(model: ApfelTextModel, config?: ApfelTextConfig): Promise<boolean>;
+export {};
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,iBAAiB,EAEjB,WAAW,EAGZ,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,uBAAuB,CAAA;AAU9B,+CAA+C;AAC/C,eAAO,MAAM,cAAc,8BAA8B,CAAA;AAEzD,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,oCAAqC,CAAA;AAEnE,4BAA4B;AAC5B,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAE/E,MAAM,MAAM,eAAe,GAAG;IAC5B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,KAAK,cAAc,GAAG,KAAK,CAAA;AAE3B,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AA0OD,qBAAa,gBAAgB,CAAC,MAAM,SAAS,MAAM,CAAE,SAAQ,eAAe,CAC1E,MAAM,EACN,iBAAiB,EACjB,SAAS,CAAC,MAAM,CAAC,EACjB,kBAAkB,EAClB,aAAa,CAAC,MAAM,CAAC,EACrB,OAAO,EACP,KAAK,EACL,cAAc,CACf;IACC,SAAkB,IAAI,EAAG,MAAM,CAAS;IACxC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,SAAkB,QAAQ,EAAG,OAAO,CAAS;IAC7C,SAAkB,GAAG,EAAG,oBAAoB,CAAS;IACrD,SAAkB,eAAe,oBAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;gBAEpC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM;IAS3C,UAAU,CACf,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,GACtC,aAAa,CAAC,iBAAiB,CAAC;IAyUnC;;;;OAIG;YACW,eAAe;IAgE7B;;;;OAIG;IACG,gBAAgB,CACpB,OAAO,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,GAClD,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;CAsE5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAS,cAAc,EACrD,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,eAAoB,GAC3B,gBAAgB,CAAC,MAAM,CAAC,CAE1B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,cAAc,EACrB,MAAM,GAAE,eAAoB,oBAc7B"}