@tanstack-ai-browser/apfel 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # @tanstack-ai-browser/apfel
 
-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.
+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.
+
+It's a thin pass-through: TanStack's OpenAI-compatible Chat Completions adapter (`@tanstack/ai-openai/compatible`) pointed at apfel. Tool calls go to apfel as `tools` and come back as apfel parses them; structured output goes as `response_format`, which apfel holds the model to with Apple's guided generation. The adapter adds an availability check and renames `modelOptions` for the request.
 
 ```sh
 npm install @tanstack-ai-browser/apfel @tanstack/ai
@@ -8,41 +10,40 @@ 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
-  })
+import { apfelText } from "@tanstack-ai-browser/apfel"
+
+const adapter = apfelText()
+
+if ((await adapter.availability()) === "available") {
+  const stream = chat({ adapter, messages, threadId, tools })
 }
 ```
 
-`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.
+Start apfel with `apfel --serve --cors`.
 
-## Tool calls
+## Images
 
-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:
+Image parts go to apfel as OpenAI `image_url` parts, so `adapter.inputModalities` lists `"image"` for Apple's model. Apple's model reads images natively on macOS 27 and later; on older macOS, apfel passes it only the text and labels it reads from the image.
 
-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.
+## Config
 
-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`.
+- `baseURL`: apfel's API, up to `/v1`. It defaults to `http://127.0.0.1:11434/v1`.
+- `defaultHeaders`: headers for every request, such as a bearer token.
 
-## Usage
+## Availability
 
-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`).
+- `adapter.availability()` resolves to `"available"` when apfel lists the model within 10 seconds, and to `"unavailable"` otherwise.
+- `adapter.create({ signal? })` makes the same check. It resolves to the adapter, or rejects. Nothing loads, since apfel runs the model outside the page.
 
-```ts
-// For example, in chat() middleware:
-const stats = { name: "stats", onUsage: (ctx, usage) => console.log(usage) }
-```
+## Model options
+
+`modelOptions` are the request fields apfel takes, with OpenAI's names, sent as given (as TanStack's adapters do with their provider's fields): `max_tokens`, `temperature`, `top_p` and `seed`.
+
+## Exports
+
+- `@tanstack-ai-browser/apfel`:
+  - `apfelText(config?)` for Apple's model, or `apfelText(model, config?)` for another model apfel serves
+  - the types `ApfelConfig`, `ApfelModel`, `ApfelTextAdapter`, `ApfelTextModelOptions` and `Availability`
+  - the catalog: `APFEL_CHAT_MODELS` and `APFEL_MODEL_META`, with the types `ApfelChatModel` and `ApfelModelMeta`
 
-**Status:** early (0.0.x); the API may change. See the [repository README](https://github.com/daveycodez/tanstack-ai-browser#readme).
+**Status:** early (0.x). The API may change.

package/dist/adapter.d.ts

@@ -1,98 +1,45 @@
-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. */
+import type { OpenAICompatibleChatAdapter } from "@tanstack/ai-openai/compatible";
+import type { ApfelChatModel } from "./model-meta.js";
+export type ApfelConfig = {
+    /** apfel's OpenAI-compatible API, up to `/v1`. `http://127.0.0.1:11434/v1` 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;
+/** Per-call `modelOptions`: the request fields apfel takes, with OpenAI's names, sent as given. */
+export type ApfelTextModelOptions = {
+    /** Most tokens to generate. */
     max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
     seed?: number;
 };
-type ApfelReasoning = never;
-type MetadataByModality = {
-    text: unknown;
-    image: unknown;
-    audio: unknown;
-    video: unknown;
-    document: unknown;
+/** The Prompt API's availability values; apfel's model is "available" or "unavailable". */
+export type Availability = "unavailable" | "downloadable" | "downloading" | "available";
+/** TanStack's OpenAI-compatible adapter for apfel, with apfel's availability. */
+export type ApfelTextAdapter = OpenAICompatibleChatAdapter<ApfelModel, ApfelTextModelOptions> & {
+    /** Text and images for Apple's model; not known for another model. */
+    readonly inputModalities: ReadonlyArray<"text" | "image"> | undefined;
+    /** "available" if apfel answers and serves the model, else "unavailable". */
+    availability(signal?: AbortSignal): Promise<Availability>;
+    /** Resolves to this adapter if apfel serves the model, else rejects. Nothing loads. */
+    create(options?: {
+        signal?: AbortSignal;
+    }): Promise<ApfelTextAdapter>;
 };
-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 model apfel serves: Apple's ("apple-foundationmodel", the default), or any other name. */
+export type ApfelModel = ApfelChatModel | (string & {});
 /**
- * A TanStack AI text adapter for Apple's on-device Foundation Model, served
- * by apfel.
+ * An adapter for a model apfel serves: Apple's on-device model by default.
  *
  * @example
  * ```ts
- * chat({
- *   adapter: apfelText("apple-foundationmodel", { baseURL: APFEL_BASE_URL }),
- *   messages,
- *   threadId
- * })
+ * const adapter = apfelText()
+ * if ((await adapter.availability()) === "available") {
+ *   chat({ adapter, messages, tools })
+ * }
  * ```
  */
-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 {};
+export declare function apfelText(config?: ApfelConfig): ApfelTextAdapter;
+export declare function apfelText(model: ApfelModel, config?: ApfelConfig): ApfelTextAdapter;
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAA;AAGjF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAErD,MAAM,MAAM,WAAW,GAAG;IACxB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC,CAAA;AAED,mGAAmG;AACnG,MAAM,MAAM,qBAAqB,GAAG;IAClC,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,2FAA2F;AAC3F,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,CAAA;AAEvF,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,2BAA2B,CAAC,UAAU,EAAE,qBAAqB,CAAC,GAAG;IAC9F,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,aAAa,CAAC,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,CAAA;IACrE,6EAA6E;IAC7E,YAAY,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IACzD,uFAAuF;IACvF,MAAM,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;CACtE,CAAA;AAID,+FAA+F;AAC/F,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CAAA;AACjE,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CAAA"}