apple-llm 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,690 @@
+interface Progress {
+    status: string;
+    percent?: number;
+}
+type OnProgress = (p: Progress) => void;
+/**
+ * Where the compiled helper is cached.
+ *
+ * Deliberately not namespaced per language binding: the npm and the pip package
+ * embed byte-identical Swift, so they derive the same fingerprint and share one
+ * compiled binary. Installing both costs one compile, not two.
+ */
+declare function cacheDir(): string;
+/**
+ * The cache key: sha256 over the Swift source, a newline, and the target triple,
+ * truncated to 12 hex characters.
+ *
+ * The exact recipe is load-bearing — the Python package computes the same string
+ * and must agree byte for byte, or the two would each compile their own copy.
+ * A helper edit or an OS upgrade changes it, so both rebuild automatically.
+ */
+declare function fingerprint(source: string, triple: string): string;
+/** The embedded Swift source, shipped as package data beside the built output. */
+declare function helperSource(): Promise<string>;
+/**
+ * Compile the helper on first use and cache it. Never called at install time —
+ * importing this package on Linux, an Intel Mac or macOS 25 must not fail.
+ *
+ * `force` bypasses the in-process memo, so a caller can rebuild after the cached
+ * binary is removed or found corrupt without restarting the program.
+ *
+ * The memo is fingerprint-aware: a helper edit or OS upgrade changes the
+ * fingerprint, so a stale in-process memo is discarded rather than reused.
+ */
+declare function ensureBinary(onProgress?: OnProgress, options?: {
+    force?: boolean;
+}): Promise<string>;
+
+/**
+ * Apple's `GenerationSchema` is `Decodable` from JSON Schema, but only accepts a
+ * restricted dialect. These rules were established empirically in api-scribe, by
+ * decoding a real schema against macOS 26 and 27 until it was accepted:
+ *
+ *  1. Union types are rejected — `type: ['string','null']` fails with
+ *     "Expected value of type String". Nullability is expressed by leaving the
+ *     property out of `required` instead.
+ *  2. Every object schema requires an `x-order` array naming its properties in
+ *     generation order. Omitting it fails with "Key 'x-order' not found".
+ *  3. `enum` is not recognized. A node may only carry `type`, `const`, `$ref` or
+ *     `anyOf`, so enums become `anyOf` of `const` branches.
+ *  4. Every object schema *and* every `anyOf` schema requires a `title`, and
+ *     `$ref` resolves by that title rather than by JSON pointer — so a
+ *     definition's title must equal the key it is referenced by.
+ *  5. Every object schema must state `additionalProperties`; omitting it fails
+ *     with "Key 'additionalProperties' not found". macOS 26's decoder tolerated
+ *     its absence, so this one only surfaced on macOS 27.
+ *
+ *  6. `const` is decoded as a String, always. A numeric member (`const: 200`)
+ *     fails with "Expected value of type String". Stringifying it is accepted
+ *     but changes the output type — the model then emits `"200"` rather than
+ *     `200` — so a numeric enum is converted to its underlying type instead and
+ *     the literal constraint is dropped. api-scribe reached the same conclusion
+ *     the hard way: it settled on a plain `integer` for HTTP status after a
+ *     string-typed union produced junk like `": 201"`.
+ *  7. An object with no properties still needs an explicit `properties: {}`.
+ *     Without it Apple reads `additionalProperties` in its other JSON Schema
+ *     sense — a schema for the values — and fails with "Expected value of type
+ *     Dictionary<String, Any>". Supplying a dictionary there is accepted but
+ *     turns the field into a free-form map the model fills with invented keys.
+ *
+ *  8. A `title` on a `type: "string"` node is rejected: Apple reads it as a
+ *     "named string type" and fails with "Named string types must have a
+ *     non-empty enum field". Other primitives (integer, number, boolean) and
+ *     arrays accept a title happily. Titles are therefore stripped from plain
+ *     strings. This matters most for pydantic, whose `model_json_schema()`
+ *     titles every single property.
+ *
+ * Rules 6, 7 and 8 were found by decoding this package's own fixture corpus
+ * against macOS 27. api-scribe hit none of them: it had only string enums, no
+ * empty objects, and hand-written schemas that never titled a string.
+ *
+ * `$ref` / `$defs` are otherwise supported and pass through untouched.
+ *
+ * Why this matters more than it looks: constrained decoding makes a schema
+ * mistake invisible but total. Collapsing a `["number","string"]` union to
+ * `"string"` made it physically impossible for the model to emit a status code —
+ * it wrote `": 201"` and the literal `"default"` instead. Never collapse a
+ * multi-type union to one branch; convert it to `anyOf`.
+ */
+type JsonSchema = Record<string, unknown>;
+/**
+ * Translate a standard JSON Schema into the dialect Apple's `GenerationSchema`
+ * accepts. Constrained decoding then makes the shape of the reply a guarantee
+ * rather than a request.
+ */
+declare function toAppleSchema(schema: JsonSchema, rootName?: string): JsonSchema;
+
+/**
+ * Sampling temperature. Not zero on purpose.
+ *
+ * Constrained decoding already guarantees the schema, so greedy decoding buys
+ * nothing and reliably degenerates: at 0 the model padded an unbounded array
+ * forever, then ran away *inside a single string*, emitting 2.7KB of
+ * "tasks-tasks-tasks-…". A 2s call became 20s. Apple honours `maxItems` but
+ * ignores `maxLength`, so bounding strings is not available as a fix — a little
+ * sampling is. Nothing about this is a quality/creativity tradeoff.
+ */
+declare const DEFAULT_TEMPERATURE = 0.4;
+/**
+ * Cap on generated tokens. Left uncapped, the model occasionally runs away and
+ * only stops when it exhausts the context window — one observed run burned
+ * ~206s before failing. This bounds that to well under a minute while leaving
+ * room for a few paragraphs of prose.
+ */
+declare const DEFAULT_MAX_TOKENS = 2048;
+/** What the model can actually do, as reported by the framework (macOS 27+). */
+interface ModelCapabilities {
+    vision: boolean;
+    guidedGeneration: boolean;
+    reasoning: boolean;
+    toolCalling: boolean;
+}
+/** Siri-parity feature flags reported by --probe (absent on older helpers). */
+interface HelperFeatures {
+    streaming: boolean;
+    sessions: boolean;
+    history: boolean;
+    labelledAttachments: boolean;
+    builtInTools: string[];
+}
+/** An image attachment: a bare path, or a path with a Siri-style label. */
+type ImageAttachment = string | {
+    path: string;
+    label?: string;
+};
+/** Apple's built-in on-device tools (all macOS 27+, all local). */
+type BuiltInTool = 'ocr' | 'barcode' | 'spotlight';
+/** A history turn mirrored by the helper for a named session. */
+interface HistoryTurn {
+    role: string;
+    content: string;
+}
+/**
+ * Private Cloud Compute quota, read from the framework without calling it.
+ *
+ * PCC *inference* needs an entitlement no installable package can ship, which is
+ * why the cloud tier goes through Shortcuts — but `quotaUsage` is readable from
+ * an unentitled process, so this is real first-party quota state rather than a
+ * guess parsed out of an error message.
+ */
+interface CloudQuota {
+    isAvailable: boolean;
+    status: 'belowLimit' | 'limitReached' | 'unknown';
+    approachingLimit?: boolean;
+    resetDate?: string;
+}
+interface DeviceProbe {
+    available: boolean;
+    reason?: string;
+    contextSize?: number;
+    variant?: string;
+    /** macOS 27+ only; absent on macOS 26. */
+    capabilities?: ModelCapabilities;
+    useCases?: string[];
+    /** Helper feature flags; absent when the cached binary predates them. */
+    features?: HelperFeatures;
+    /** PCC quota, surfaced here because the on-device helper is what can read it. */
+    cloud?: CloudQuota;
+}
+/**
+ * How tokens are chosen.
+ *
+ * `greedy` is deterministic but degenerates under guided generation — it is the
+ * `temperature: 0` trap by another name. The seeded modes give the same
+ * reproducibility *without* that failure: `{ mode: 'topK', k: 50, seed: 42 }`
+ * returned byte-identical output across three runs here. Determinism relies on
+ * a fresh session per request, which is the default.
+ */
+type SamplingMode = {
+    mode: 'greedy';
+} | {
+    mode: 'topK';
+    k?: number;
+    seed?: number;
+} | {
+    mode: 'threshold';
+    p?: number;
+    seed?: number;
+};
+/** Apple ships a use case specialised for tagging and topic extraction. */
+type UseCase = 'general' | 'contentTagging';
+/**
+ * `permissive` selects `permissiveContentTransformations`, which relaxes the
+ * guardrails for content *transformation* — rewriting or summarising text the
+ * default guardrails would refuse to touch.
+ */
+type Guardrails = 'default' | 'permissive';
+interface DeviceRequest {
+    system?: string;
+    prompt: string;
+    schema?: JsonSchema | null;
+    temperature?: number;
+    maxTokens?: number;
+    /** Image attachments. Entries may carry a label for follow-up turns. */
+    images?: ImageAttachment[];
+    /** Text documents inlined into the prompt client-side (see inlineDocuments). */
+    documents?: string[];
+    /** Named multi-turn conversation; the helper keeps the native transcript. */
+    sessionId?: string;
+    /** Built-in Apple tools: on-device OCR, barcode reading, Spotlight RAG. */
+    tools?: BuiltInTool[];
+    useCase?: UseCase;
+    guardrails?: Guardrails;
+    sampling?: SamplingMode;
+    /** Send the schema in the prompt as well as to the decoder. See helper.swift. */
+    includeSchemaInPrompt?: boolean;
+    /**
+     * Reuse one session across calls, as api-scribe did. Off by default: it makes
+     * unrelated calls share a transcript. See the note in helper.swift.
+     * Prefer sessionId for conversations; this flag is the legacy single slot.
+     */
+    reuseSession?: boolean;
+}
+/** Assert every requested tool is one the helper knows, before spending a call. */
+declare function assertTools(tools: BuiltInTool[] | undefined): void;
+/** Probe the on-device model without constructing a client. */
+declare function probeDevice(onProgress?: OnProgress): Promise<DeviceProbe>;
+/**
+ * The on-device tier: Apple's `FoundationModels` framework, reached through a
+ * self-compiled Swift helper. Nothing leaves the machine.
+ */
+interface DeviceClientOptions {
+    useCase?: UseCase;
+    guardrails?: Guardrails;
+}
+declare class DeviceClient {
+    private readonly options;
+    private binary?;
+    private probeResult?;
+    private server?;
+    constructor(options?: DeviceClientOptions);
+    get label(): string;
+    get contextSize(): number | undefined;
+    ensureReady(onProgress?: OnProgress): Promise<void>;
+    getProbe(): DeviceProbe | undefined;
+    /** Send one envelope and return the parsed reply, raising a typed error on failure. */
+    private exchange;
+    /** One request. Returns the helper's `content` string, unparsed. */
+    complete(request: DeviceRequest): Promise<string>;
+    /**
+     * Streaming text. Deltas arrive via onDelta as the model generates; the
+     * promise resolves with the full text. Text only: the helper rejects
+     * schema+stream, because partial JSON is not a usable delta.
+     */
+    stream(prompt: string, options?: Omit<DeviceRequest, 'prompt' | 'schema'> & {
+        onDelta?: (delta: string) => void;
+    }): Promise<string>;
+    /**
+     * Conversation history for a named session: the mirrored turns the helper
+     * persisted, oldest first. Survives helper restarts; the native transcript
+     * does not, so treat a restart as a context break, not a loss.
+     */
+    history(sessionId: string): Promise<{
+        instructions: string;
+        history: HistoryTurn[];
+    }>;
+    /** Drop a named session (and its persisted history), or all of them. */
+    resetSession(sessionId?: string): Promise<void>;
+    /**
+     * How many tokens a prompt costs, before sending it.
+     *
+     * The point is to turn a ContextLengthError into an arithmetic check: compare
+     * against `contextSize` and trim, rather than discovering the ceiling by
+     * hitting it. Counts the instructions too, since they share the window.
+     */
+    countTokens(prompt: string, options?: {
+        system?: string;
+        images?: ImageAttachment[];
+        tools?: BuiltInTool[];
+    }): Promise<{
+        tokens: number;
+        contextSize: number;
+    }>;
+    /**
+     * Load the model assets now so the first real call does not pay for it.
+     *
+     * Cheap and idempotent, but do not expect much on a warm machine: with the
+     * assets already resident this measured 0.31s against 0.36s for an
+     * unprewarmed first call — inside the noise. The win is on a genuinely cold
+     * system, where the very first call to the framework here took 7.8s. Worth
+     * calling at startup when you know a request is coming; not worth building
+     * around.
+     */
+    prewarm(system?: string): Promise<void>;
+    text(prompt: string, options?: Omit<DeviceRequest, 'prompt' | 'schema'>): Promise<string>;
+    json(prompt: string, options: Omit<DeviceRequest, 'prompt'> & {
+        schema: JsonSchema;
+    }): Promise<unknown>;
+    /** Shut the helper process down. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * Inline text documents into the prompt client-side.
+ *
+ * The helper's vision path handles images; plain-text sources (.txt/.md/.json
+ * and friends) are cheaper to splice here than to teach the Swift side about.
+ * Binary files are refused loudly — silently skipping a document the caller
+ * asked about would be the vision-drop trap by another name.
+ */
+declare function withDocuments(prompt: string, documents: string[] | undefined): Promise<string>;
+/** Parse a CLI --image value: "path" or "path::label". */
+declare function parseImageFlag(value: string): ImageAttachment;
+
+/**
+ * Apple's Private Cloud Compute model, reached through the Shortcuts action
+ * `is.workflow.actions.askllm`.
+ *
+ * Why this route rather than the framework: macOS 27 exposes
+ * `FoundationModels.PrivateCloudComputeLanguageModel` as public API and it even
+ * reports `isAvailable: true`, but every call fails with `ModelManagerError
+ * 1046` unless the process carries `com.apple.developer.private-cloud-compute`.
+ * That entitlement is AMFI-restricted — an ad-hoc-signed binary carrying it is
+ * SIGKILLed (exit 137), and wrapping it in a signed .app with a real bundle ID
+ * does not help. It needs a paid Developer Program provisioning profile, which
+ * no installable package can ship. Shortcuts.app already holds the entitlement
+ * and `/usr/bin/shortcuts` is public, so a generated shortcut is the only route
+ * that works. Do not spend time re-confirming this.
+ *
+ * This tier sends your prompt off the machine. It is not local.
+ *
+ * Measured on an M4 Air: ~2s typical, ~11s at 14k tokens.
+ */
+/** Distinctive, so `shortcuts run` cannot match a shortcut the user wrote. */
+declare const CLOUD_SHORTCUT_NAME = "Apple LLM Cloud";
+/** Web search is fixed in the shortcut at install time, so it needs its own copy. */
+declare const CLOUD_SHORTCUT_NAME_WEB = "Apple LLM Cloud Web";
+/** Context window, measured empirically: 14.4k succeeds, ~33.5k is refused. */
+declare const CLOUD_CONTEXT_TOKENS = 32768;
+interface CloudProbe {
+    available: boolean;
+    reason?: string;
+    installed?: boolean;
+    contextSize?: number;
+    /**
+     * Real quota state, read from `PrivateCloudComputeLanguageModel.quotaUsage`
+     * by the on-device helper. Absent when the helper could not run (macOS 26, or
+     * no on-device model), since that is the only thing that can read it.
+     */
+    quota?: CloudQuota;
+}
+/**
+ * The shortcut definition, as plain JSON.
+ *
+ * Every key here was confirmed against a shortcut built in the Shortcuts GUI and
+ * exported, rather than guessed — the difference matters because a wrong
+ * parameter name does not fail loudly. Shortcuts imports the action, silently
+ * discards the unrecognised parameter, and the action then blocks on its
+ * interactive prompt at run time, forever. This is the single most expensive
+ * mistake available on this path.
+ *
+ * In particular the prompt key is `WFLLMPrompt`, *not* the `WFInput` that the
+ * action's own localised strings suggest.
+ *
+ * The model key is deliberately absent: with no model key the action uses its
+ * default, which is the Cloud (Private Cloud Compute) tier.
+ */
+declare function shortcutDefinition(webSearch?: boolean): Record<string, unknown>;
+declare function cloudSetupHint(): string;
+/**
+ * Generate, sign and install the shortcut. Idempotent unless `force` is set.
+ *
+ * Signing needs no developer account and no signing identity: `shortcuts sign -m
+ * anyone` issues a per-signature certificate that chains to Apple Root CA - G3
+ * on the device. Every user signs their own copy, so nothing has to be
+ * pre-signed, hosted, or shipped in the package.
+ */
+declare function installCloudShortcut(onProgress?: OnProgress, options?: {
+    force?: boolean;
+    webSearch?: boolean;
+}): Promise<void>;
+/** Probe the cloud tier without constructing a client. */
+declare function probeCloud(): Promise<CloudProbe>;
+interface CloudRequest {
+    system?: string;
+    prompt: string;
+    /** Run with "Use Broad World Knowledge" — needs the web shortcut installed. */
+    webSearch?: boolean;
+}
+/**
+ * The Private Cloud Compute tier. Free but quota'd, and text-out only: there is
+ * no constrained decoding here, so `json()` asks for JSON in the prompt and
+ * recovers it from prose rather than guaranteeing it.
+ */
+declare class CloudClient {
+    private ready;
+    /** Last known quota, set by `probe()` so a call can fail fast. */
+    private quota?;
+    /**
+     * Tell the client what the framework reported about the quota.
+     *
+     * Worth doing because a `shortcuts run` against an exhausted quota costs a
+     * full round trip to find out; this turns that into an immediate typed error.
+     */
+    setQuota(quota: CloudQuota | undefined): void;
+    private assertQuota;
+    get label(): string;
+    get contextSize(): number;
+    ensureReady(onProgress?: OnProgress): Promise<void>;
+    text(request: CloudRequest): Promise<string>;
+    /**
+     * There is no constrained decoding on this tier, so the schema is spelled out
+     * in the prompt and the reply is mined for JSON. The shape is a request here,
+     * not a guarantee — unlike on device.
+     */
+    json(request: CloudRequest & {
+        schema: JsonSchema;
+    }): Promise<unknown>;
+    close(): void;
+}
+
+/**
+ * Recover JSON from free text.
+ *
+ * Only the cloud tier needs this. On device, constrained decoding guarantees the
+ * shape and the reply is already JSON. Private Cloud Compute returns prose, so
+ * the object has to be dug out of whatever the model wrapped around it.
+ *
+ * api-scribe's version only stripped fences when the reply *started* with one,
+ * which fails on the common "Here is the JSON:\n```json\n{...}\n```". This one
+ * also scans for a balanced object or array.
+ */
+/** Strip a Markdown code fence anywhere in the text, preferring a json-tagged one. */
+declare function stripCodeFences(text: string): string;
+/**
+ * The first balanced `{...}` or `[...]` in the text, respecting strings and
+ * escapes so a brace inside a string value cannot end the scan early.
+ */
+declare function extractJsonSpan(text: string): string | null;
+/**
+ * Parse a model reply as JSON, tolerating fences and surrounding prose.
+ * Throws with a truncated echo of the reply, which is what a caller needs to see.
+ */
+declare function parseLlmJson(raw: string): unknown;
+
+/**
+ * True when this machine could plausibly run Apple's on-device model: Apple
+ * Silicon on macOS. Availability itself is confirmed by probing the helper.
+ */
+declare function isAppleSiliconMac(): boolean;
+/**
+ * Build the compile target from an SDK version string, e.g. `27.0` ->
+ * `arm64-apple-macos27.0`.
+ *
+ * swiftc's own default triple carries a patch component
+ * (`arm64-apple-macosx27.0.0`) that no shipped stdlib matches, so the target has
+ * to be spelled out. Pure so it can be tested against captured `xcrun` output on
+ * any machine.
+ */
+declare function targetTripleFrom(versionOutput: string, arch?: string): string | null;
+/** Ask the SDK, then the OS, for a version to build the triple from. */
+declare function hostTarget(): Promise<string | null>;
+
+/**
+ * Typed errors, so callers branch on a class rather than matching a message.
+ * Apple rewords its diagnostics between OS releases; the helper classifies
+ * failures at the Swift boundary and this module names them.
+ */
+type Tier$1 = 'device' | 'cloud';
+declare class AppleLLMError extends Error {
+    readonly tier?: Tier$1 | undefined;
+    constructor(message: string, tier?: Tier$1 | undefined);
+}
+/** Why the on-device model cannot be used. Distinguishable, because the fix differs. */
+type UnavailableReason = 'appleIntelligenceNotEnabled' | 'modelNotReady' | 'deviceNotEligible' | 'unsupportedPlatform' | 'unsupportedOSVersion' | 'noSwiftCompiler' | 'unknown';
+declare class ModelUnavailableError extends AppleLLMError {
+    readonly reason: UnavailableReason;
+    constructor(message: string, reason: UnavailableReason, tier?: Tier$1);
+}
+/** Apple's `GenerationSchema` decoder refused the schema. Almost always a dialect rule. */
+declare class SchemaRejectedError extends AppleLLMError {
+}
+/** The prompt (plus transcript) exceeded the model's context window. */
+declare class ContextLengthError extends AppleLLMError {
+    readonly contextSize?: number | undefined;
+    constructor(message: string, tier?: Tier$1, contextSize?: number | undefined);
+}
+/** Private Cloud Compute is rate limited, or the on-device model reported `rateLimited`. */
+declare class QuotaError extends AppleLLMError {
+    readonly resetDate?: Date | undefined;
+    constructor(message: string, tier?: Tier$1, resetDate?: Date | undefined);
+}
+declare class TimeoutError extends AppleLLMError {
+}
+/** A one-time setup step has not been run — currently only the cloud shortcut. */
+declare class SetupRequiredError extends AppleLLMError {
+    readonly step: string;
+    constructor(message: string, step: string, tier?: Tier$1);
+}
+/** The model declined to answer (guardrail or refusal). */
+declare class RefusalError extends AppleLLMError {
+}
+
+/**
+ * apple-llm — one library for Apple's on-device and Private Cloud Compute models.
+ *
+ * macOS 26+ on Apple Silicon only. No API key, no account, no developer program.
+ * Extracted from api-scribe (MIT), which discovered and shipped both routes.
+ */
+
+type Tier = 'device' | 'cloud' | 'auto';
+interface ProbeResult {
+    device: DeviceProbe;
+    cloud: CloudProbe;
+}
+/**
+ * What this machine can actually do. Never throws: on Linux, an Intel Mac or
+ * macOS 25 it returns `available: false` with a reason naming the fix.
+ */
+declare function probe(onProgress?: OnProgress): Promise<ProbeResult>;
+interface AppleLLMOptions {
+    tier?: Tier;
+    /** Default sampling temperature. See DEFAULT_TEMPERATURE — do not set 0. */
+    temperature?: number;
+    maxTokens?: number;
+    /** Called for the one-time compile and the shortcut install; both take seconds. */
+    onProgress?: OnProgress;
+    /** `contentTagging` selects Apple's tagging-specialised model. Device tier only. */
+    useCase?: UseCase;
+    /** `permissive` relaxes guardrails for rewriting tasks. Device tier only. */
+    guardrails?: Guardrails;
+    /** Default sampling mode; a seeded one makes output reproducible. */
+    sampling?: SamplingMode;
+}
+interface TextOptions {
+    system?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Cloud tier only: run with "Use Broad World Knowledge". */
+    webSearch?: boolean;
+    /** Image attachments; entries may carry a label for follow-up turns. */
+    images?: ImageAttachment[];
+    /** Text documents inlined into the prompt (device tier). */
+    documents?: string[];
+    /** Named multi-turn conversation (device tier). */
+    sessionId?: string;
+    /** Built-in Apple tools: ocr, barcode, spotlight (device, macOS 27+). */
+    tools?: BuiltInTool[];
+    useCase?: UseCase;
+    guardrails?: Guardrails;
+    sampling?: SamplingMode;
+}
+interface StreamOptions extends TextOptions {
+    onDelta?: (delta: string) => void;
+}
+interface JsonOptions extends TextOptions {
+    schema: JsonSchema;
+}
+/**
+ * The main entry point.
+ *
+ *   const llm = new AppleLLM({ tier: 'device' });
+ *   await llm.text('Summarize this');
+ *   await llm.json('Extract the fields', { schema });
+ *   llm.close();
+ */
+declare class AppleLLM {
+    private device?;
+    private cloud?;
+    /** Which tier `auto` settled on, once resolved. */
+    private resolved?;
+    private readonly options;
+    constructor(options?: AppleLLMOptions);
+    /** Per-call device settings, falling back to the constructor defaults. */
+    private deviceDefaults;
+    get tier(): Tier;
+    /** Human-readable name of the tier in use, for logs. */
+    get label(): string;
+    /**
+     * Resolve the tier and do any one-time setup. Called automatically, but
+     * exposed so a caller can pay the compile cost up front with a progress bar.
+     */
+    ensureReady(onProgress?: OnProgress): Promise<void>;
+    text(prompt: string, options?: TextOptions): Promise<string>;
+    /**
+     * Streaming text (device tier only). Deltas arrive via onDelta as the model
+     * generates; the promise resolves with the full text. The Siri-app shape:
+     * partials first, final answer at the end.
+     */
+    stream(prompt: string, options?: StreamOptions): Promise<string>;
+    /** Conversation history for a named session (device tier only). */
+    history(sessionId: string): Promise<{
+        instructions: string;
+        history: HistoryTurn[];
+    }>;
+    /** Drop a named session, or all sessions when omitted (device tier only). */
+    resetSession(sessionId?: string): Promise<void>;
+    /**
+     * A named conversation: text/stream calls sharing one native transcript,
+     * like one thread in the Siri app. History persists across helper restarts;
+     * the native transcript does not (treated as a context break, not a loss).
+     */
+    conversation(sessionId: string, options?: {
+        system?: string;
+    }): Conversation;
+    /**
+     * Write with Siri, anywhere you type: drafting, rewriting and feedback
+     * built on the permissive-content-transformation guardrails. Device tier
+     * only — these are transformation tasks the default guardrails refuse.
+     */
+    rewrite(text: string, options?: {
+        instruction?: string;
+        system?: string;
+    } & TextOptions): Promise<string>;
+    proofread(text: string, options?: TextOptions): Promise<string>;
+    summarize(text: string, options?: {
+        length?: string;
+    } & TextOptions): Promise<string>;
+    draft(topic: string, options?: {
+        kind?: string;
+    } & TextOptions): Promise<string>;
+    tone(text: string, tone: string, options?: TextOptions): Promise<string>;
+    /**
+     * Ask about what's on screen: captures a screenshot (interactive selection
+     * by default, like Cmd+Shift+Space Visual Intelligence) and asks the model
+     * about it with vision. Device tier, macOS 27+.
+     */
+    askScreen(question: string, options?: {
+        mode?: 'interactive' | 'window' | 'fullscreen';
+    } & TextOptions): Promise<string>;
+    /**
+     * Ask for JSON. On device the schema is *guaranteed* by constrained decoding.
+     * On cloud it is requested in the prompt and recovered from the reply — the
+     * cloud tier has no constrained decoding, so a bad shape is possible there.
+     */
+    json(prompt: string, options: JsonOptions): Promise<unknown>;
+    /**
+     * api-scribe's `LlmClient` shape, so it can drop its four files and depend on
+     * this instead. Not used internally.
+     */
+    completeJson(system: string, user: string, schema: JsonSchema): Promise<unknown>;
+    /**
+     * How many tokens a prompt costs, before sending it. Device tier only.
+     *
+     * Turns a ContextLengthError into arithmetic: compare against `contextSize`
+     * and trim, rather than finding the ceiling by hitting it.
+     */
+    countTokens(prompt: string, options?: {
+        system?: string;
+        images?: ImageAttachment[];
+        tools?: BuiltInTool[];
+    }): Promise<{
+        tokens: number;
+        contextSize: number;
+    }>;
+    /**
+     * Load the model assets now so the first real call does not pay for it.
+     * Device tier only; a no-op elsewhere. See `DeviceClient.prewarm` for what it
+     * is actually worth (little, on a warm machine).
+     */
+    prewarm(system?: string): Promise<void>;
+    /** Release the long-lived helper process. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * One thread in the Siri-app sense: every call carries the same sessionId,
+ * so the helper's native transcript accumulates across turns.
+ */
+declare class Conversation {
+    private readonly llm;
+    readonly sessionId: string;
+    private readonly defaults;
+    constructor(llm: AppleLLM, sessionId: string, defaults?: {
+        system?: string;
+    });
+    text(prompt: string, options?: TextOptions): Promise<string>;
+    stream(prompt: string, options?: StreamOptions): Promise<string>;
+    history(): Promise<{
+        instructions: string;
+        history: HistoryTurn[];
+    }>;
+    reset(): Promise<void>;
+}
+/**
+ * Capture a screenshot to a temp file. Interactive selection mirrors the
+ * Visual Intelligence entry point (Cmd+Shift+Space): drag to select, and the
+ * path comes back ready to pass as an image attachment.
+ */
+declare function captureScreenshot(mode?: 'interactive' | 'window' | 'fullscreen'): Promise<string>;
+
+export { AppleLLM, AppleLLMError, type AppleLLMOptions, type BuiltInTool, CLOUD_CONTEXT_TOKENS, CLOUD_SHORTCUT_NAME, CLOUD_SHORTCUT_NAME_WEB, CloudClient, type CloudProbe, type CloudQuota, type CloudRequest, ContextLengthError, Conversation, DEFAULT_MAX_TOKENS, DEFAULT_TEMPERATURE, DeviceClient, type DeviceClientOptions, type DeviceProbe, type DeviceRequest, type Guardrails, type HelperFeatures, type HistoryTurn, type ImageAttachment, type JsonOptions, type JsonSchema, type ModelCapabilities, ModelUnavailableError, type OnProgress, type ProbeResult, type Progress, QuotaError, RefusalError, type SamplingMode, SchemaRejectedError, SetupRequiredError, type StreamOptions, type TextOptions, type Tier, TimeoutError, type UnavailableReason, type UseCase, assertTools, cacheDir, captureScreenshot, cloudSetupHint, ensureBinary, extractJsonSpan, fingerprint, helperSource, hostTarget, installCloudShortcut, isAppleSiliconMac, parseImageFlag, parseLlmJson, probe, probeCloud, probeDevice, shortcutDefinition, stripCodeFences, targetTripleFrom, toAppleSchema, withDocuments };