@tanstack-ai-browser/apfel 0.0.1 → 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 localhost: start it with `apfel --serve --cors`.
+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,11 +10,40 @@ npm install @tanstack-ai-browser/apfel @tanstack/ai
 
 ```ts
 import { chat } from "@tanstack/ai"
-import { apfel, isApfelAvailable } from "@tanstack-ai-browser/apfel"
+import { apfelText } from "@tanstack-ai-browser/apfel"
+
+const adapter = apfelText()
 
-if (await isApfelAvailable()) {
-  const stream = chat({ adapter: apfel(), messages, threadId })
+if ((await adapter.availability()) === "available") {
+  const stream = chat({ adapter, messages, threadId, tools })
 }
 ```
 
-**Status:** early (0.0.x); the API may change. See the [repository README](https://github.com/daveycodez/tanstack-ai-browser#readme).
+Start apfel with `apfel --serve --cors`.
+
+## Images
+
+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.
+
+## Config
+
+- `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.
+
+## Availability
+
+- `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.
+
+## 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.x). The API may change.

package/dist/adapter.d.ts

@@ -1,91 +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 --serve` listens by default. */
-export declare const APFEL_BASE_URL = "http://127.0.0.1:11434/v1";
-/** The model id apfel serves Apple's Foundation Model under. */
-export declare const APFEL_MODEL = "apple-foundationmodel";
-/**
- * A model call's token counts and timings. apfel reports token counts only
- * in the usage at the end of the stream; counts it doesn't report are left
- * out.
- */
-export type ApfelStats = {
-    /** Tokens of the prompt. */
-    inputTokens?: number;
-    /** Prompt tokens served from a cache, if apfel reports them. */
-    cachedTokens?: number;
-    /** Tokens the model generated. */
-    outputTokens?: number;
-    /** From sending the request to the first generated token, in ms. */
-    firstTokenMs?: number;
-    /** Tokens generated after the first chunk (estimated, see below). */
-    decodeTokens?: number;
-    /** From the first generated chunk to the last, in ms. */
-    decodeMs?: number;
-};
-export type ApfelOptions = {
-    /** apfel's OpenAI-compatible API, up to `/v1`. */
-    baseUrl?: string;
-    /** The model id to ask apfel for. */
-    model?: string;
-    /**
-     * The call's stats at its first token (`done: false`, time to first token
-     * only) and when it ends (`done: true`). `callId` is unique per model
-     * call; `chat()` makes one per step of its agent loop.
-     */
-    onStats?: (stats: ApfelStats, run: {
-        threadId: string;
-        runId: string;
-        callId: string;
-        done: boolean;
-    }) => void;
+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>;
 };
-/**
- * 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 extends BaseTextAdapter<string, ApfelModelOptions, readonly ["text"], MetadataByModality, ReadonlyArray<string>, unknown, never, ApfelReasoning> {
-    readonly name: "apfel";
-    readonly api: "apfel";
-    private readonly baseUrl;
-    private readonly onStats;
-    constructor(options?: ApfelOptions);
-    chatStream(options: TextOptions<ApfelModelOptions>): AsyncIterable<AdapterYieldChunk>;
-    /**
-     * 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 adapter for Apple's on-device Foundation Model through
- * apfel (`apfel --serve --cors`).
+ * An adapter for a model apfel serves: Apple's on-device model by default.
  *
  * @example
  * ```ts
- * chat({ adapter: apfel(), messages, threadId })
+ * const adapter = apfelText()
+ * if ((await adapter.availability()) === "available") {
+ *   chat({ adapter, messages, tools })
+ * }
  * ```
  */
-export declare function apfel(options?: ApfelOptions): ApfelTextAdapter;
-/**
- * Whether apfel is running and serves the model: true if `GET /v1/models`
- * lists it within 10 seconds.
- */
-export declare function isApfelAvailable(options?: Pick<ApfelOptions, "baseUrl" | "model">): 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,EAEZ,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,uBAAuB,CAAA;AAQ9B,gDAAgD;AAChD,eAAO,MAAM,cAAc,8BAA8B,CAAA;AACzD,gEAAgE;AAChE,eAAO,MAAM,WAAW,0BAA0B,CAAA;AAElD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,CACR,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KACpE,IAAI,CAAA;CACV,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;AAmOD,qBAAa,gBAAiB,SAAQ,eAAe,CACnD,MAAM,EACN,iBAAiB,EACjB,SAAS,CAAC,MAAM,CAAC,EACjB,kBAAkB,EAClB,aAAa,CAAC,MAAM,CAAC,EACrB,OAAO,EACP,KAAK,EACL,cAAc,CACf;IACC,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAS;IAChC,SAAkB,GAAG,EAAG,OAAO,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,OAAO,GAAE,YAAiB;IAM/B,UAAU,CACf,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,GACtC,aAAa,CAAC,iBAAiB,CAAC;IAmUnC;;;;OAIG;IACG,gBAAgB,CACpB,OAAO,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,GAClD,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;CAsE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,oBAE3C;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,OAAO,CAAM,oBActD"}
+{"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"}