@ocno/oryn-sdk 0.0.0-stage → 0.1.0

package/docs/api-reference.md

@@ -0,0 +1,280 @@
+# SDK API reference
+
+[SDK overview](../README.md) · [Recipes](recipes.md)
+
+This reference describes the exported website client in `@ocno/oryn-sdk` 0.1.0. Runtime and model availability are determined by Oryn Browser, independently of the installed npm package.
+
+## Client and capabilities
+
+### `createLocalAIClient`
+
+```text
+createLocalAIClient(options?) → LocalAIClient
+```
+
+Creates a lightweight wrapper. Importing the module and creating a client are safe during SSR; they do not start inference, request permission, or download a model.
+
+| Option | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `showOrynBrowserAlert` | `boolean` | `false` | Shows a website-owned explanation once per document outside Oryn; does not grant permission |
+
+The client exposes `sdkVersion`, `getCapabilities`, `models`, `artifacts`, `invoke`, `cancel`, and `subscribe`. `SDK_VERSION` is also exported.
+
+### `client.getCapabilities`
+
+```text
+client.getCapabilities() → Promise<RuntimeCapabilities>
+```
+
+| Field | Meaning |
+| --- | --- |
+| `runtimeAvailable` | Whether Local AI is available now |
+| `runtimeState` | `ready`, `starting`, `unavailable`, or `error` |
+| `sdkVersion` | SDK version reported by the capability surface |
+| `browserApiVersion?` | Version of the injected browser contract |
+| `supportedModelProviders` | Supported model-reference providers; the current type allows `huggingface` |
+| `features` | Feature flags listed below |
+| `scheduler?` | Generation-lane scope and maximum concurrent running jobs |
+
+The flags are `modelRequests`, `modelSubstitution`, `streaming`, `artifacts`, `artifactUrls`, `cancellation`, `queueing`, and `multipleSubmittedJobs`. Newer peers may also report `modelSelection` and `taskProfiles`; treat absent optional flags as unavailable.
+
+Outside Oryn, this method returns unavailable capabilities rather than throwing solely because the bridge is absent. It is not a list of installed models or an exact hardware report.
+
+## Models and sessions
+
+### `client.models.request`
+
+```text
+client.models.request(request, options?) → Promise<ModelSession>
+```
+
+A request has a `role` identifying the site's use case, such as `chat` or `transcription`, and one of three forms:
+
+| Form | Required data | Purpose |
+| --- | --- | --- |
+| Capability request | `requirements.task` and `requirements.outputModalities`; no `preferredModel` | Ask Oryn to resolve an executable match |
+| Explicit request | `preferredModel`; optional requirements and `certifiedModels` | Express a model preference and tested alternatives |
+| Source-checkpoint request | `selection: { version: 1, intent: "source-checkpoint", sourceCheckpoint }` | Let Oryn select an eligible representation of a checkpoint |
+
+`ModelRef` has `provider: "huggingface"`, `repository: "owner/name"`, optional `revision`, and optional `files`. File pins require an immutable revision; they are model-host relative file names, not local paths. `ResolvedModelRef` includes the resolved revision and `sourceUrl`.
+
+#### Requirements
+
+| Field | Purpose |
+| --- | --- |
+| `task` | Model task, for example `text-generation` or `automatic-speech-recognition` |
+| `inputModalities`, `outputModalities` | Required input/output kinds |
+| `capabilities` | Behavioral requirements such as `chat`, `streaming`, or `speechRecognition` |
+| `contract` | Versioned task reference `{ id, revision }` |
+| `requiredFeatures` | Effective task-profile features the application needs |
+| `parameterValues` | Values that must be supported by the negotiated task |
+| `architectures` | Architecture constraints |
+| `parameters` | Optional `minBillions` / `maxBillions` bounds |
+| `minimumContextLength` | Minimum context requirement |
+| `memory.maximumRecommendedBytes` | Memory-related model selection constraint |
+
+Task contract negotiation requires `features.taskProfiles`. Selection intents and file pins require `features.modelSelection`. The SDK rejects unsupported explicit requests rather than silently dropping their requirements.
+
+#### Selection and substitution
+
+`selection.version` is `1`. Its intent is `source-checkpoint`, `preferred-variant`, or `exact-artifact`. `preferred-variant` accompanies a `preferredModel`; `exact-artifact` also requires that model's immutable revision and complete selected `files` set.
+
+| `substitution.automatic` | Meaning |
+| --- | --- |
+| `none` | No automatic replacement of an explicit preferred model |
+| `certified-only` | Automatic alternatives are limited to the site's `certifiedModels` |
+| `same-checkpoint` | Allow eligible representations of the same source checkpoint |
+| `compatible` | Allow a compatible replacement validated by Oryn |
+
+These policies apply to automatic substitution; trusted user choice is separate. The request type constrains which policies apply: capability-only requests accept `compatible`, while source-checkpoint requests accept `none`, `same-checkpoint`, or `compatible`. Always inspect `session.resolution`.
+
+With substitution omitted, an explicit model preference defaults to `none`, a source-checkpoint request defaults to `same-checkpoint`, and a capability-only request uses `compatible` selection.
+
+#### Options and progress
+
+| Option | Type | Behavior |
+| --- | --- | --- |
+| `signal` | `AbortSignal` | Requests cancellation of model resolution/preparation |
+| `onProgress` | `(progress: ModelRequestProgress) => void` | Receives request progress while it is pending |
+
+Stages are `resolving`, `awaiting-permission`, `awaiting-model-choice`, `downloading`, `loading`, and `ready`. Downloading includes `downloadedBytes`, optional `totalBytes`, and the model reference. Loading may include a numeric `progress`. Not every request visits every stage; an installed model may resolve quickly.
+
+#### Returned session
+
+| Field | Meaning |
+| --- | --- |
+| `sessionId` | Opaque handle used in invocations |
+| `role`, `origin` | Role and owning origin |
+| `resolution` | Preferred/resolved models, compatibility, executability, trust, and substitution explanation |
+| `capabilities` | Effective model capabilities |
+| `taskProfile?` | Negotiated task contract, effective features, parameters, and limits |
+
+`resolution.trust` is `oryn-verified` or `user-approved-unverified`. `developerCertified` is a separate declaration about the site's testing. Never present an unverified model as Oryn-certified.
+
+`resolution.selection`, when present, explains whether selection chose the requested artifact, another representation of the same checkpoint, or a different model. Its source/confidence are advisory explanations, not runtime authorization.
+
+### `client.models.releaseSession`
+
+```text
+client.models.releaseSession(sessionId) → Promise<void>
+```
+
+Releases the site's model session. Do not reuse the ID afterward. Session release is separate from explicit job cancellation and artifact release; clean up each resource you own. A browser restart is not a supported session persistence mechanism.
+
+## Jobs and events
+
+### `client.invoke`
+
+```text
+client.invoke<TInput>(request) → Promise<JobReference>
+```
+
+`request` contains `{ sessionId, input }`. `input` is the negotiated task's JSON payload, containing artifact IDs for media. The return value contains `jobId`, `sessionId`, initial `state`, and optional `queue` information. It is an acknowledgement of submission, not the result.
+
+Shared-task inputs known to the SDK are validated before bridge invocation. Browser and Engine still enforce authorization, contract compatibility, artifact bindings, and runtime limits.
+
+### `client.subscribe`
+
+```text
+client.subscribe(listener) → () => void
+```
+
+Registers a job-event listener and returns an unsubscribe function. Outside Oryn it returns a no-op unsubscribe. Subscribe **before** invoking and route by `jobId`; events can arrive before the invocation promise resolves. Helpers handle this early-event buffering for you.
+
+All events have `event`, `timestamp`, `jobId`, `sessionId`, and `sequence`. Sequence values increase within a job. A job has one terminal outcome.
+
+| Event | `data` | Terminal? |
+| --- | --- | --- |
+| `job.state` | `state`, optional `queue` | No |
+| `job.queue.updated` | `lane`, `position`, `jobsAhead`, `reason` | No |
+| `job.progress` | Optional `progress` and `stage` | No |
+| `job.output.delta` | `channel`, `delta` | No |
+| `job.preview` | `artifactId` | No |
+| `job.completed` | `result` | Yes |
+| `job.failed` | Serialized `error` | Yes |
+| `job.cancelled` | Optional `reason` | Yes |
+
+Only consume text deltas when `channel === "text"`; the delta type is `unknown` because channels can carry different data. Render generated text using text nodes or your framework's escaped text rendering.
+
+The current generation lane is global across origins, with one running generation job. Websites only receive their own job events. Use `scheduler` and queue events for UI instead of assuming immediate execution.
+
+### `invokeAndWait`
+
+```text
+invokeAndWait<TInput, TResult>(client, request, options?) → Promise<TResult>
+```
+
+Subscribes, submits, filters to the new job, and waits for a terminal event. `TResult` extends `InferenceResult` and defaults to it.
+
+| Option | Behavior |
+| --- | --- |
+| `signal` | Requests job cancellation after the helper has the job reference |
+| `onEvent` | Receives events for this job, including the terminal event |
+
+- `job.completed`: resolves with its result.
+- `job.failed`: rejects with `LocalAIError`.
+- `job.cancelled`: rejects with `LocalAIError` code `REQUEST_ABORTED`.
+
+Keep event callbacks lightweight and non-throwing. The generic result type is a TypeScript expectation, not a runtime validator for arbitrary returned JSON.
+
+### `invokeStream`
+
+```text
+invokeStream<TInput>(client, request, options?) → AsyncIterable<LocalAIEvent>
+```
+
+Accepts optional `{ signal }`, subscribes before submission, and yields events for this job through its terminal event. **Terminal `job.failed` and `job.cancelled` are yielded, not automatically thrown.** Submission errors can still reject iteration. A signal already aborted when iteration begins causes `REQUEST_ABORTED`.
+
+The iterator starts when consumed. Closing it unsubscribes its listener; it does not cancel the running job. Use the signal while it is active or cancel a known job explicitly.
+
+### `client.cancel`
+
+```text
+client.cancel(jobId) → Promise<void>
+```
+
+Requests cancellation of an owned queued or running job. A successful call is not proof the runtime has already stopped; use the terminal event to settle the UI. Some runtimes interrupt only at safe execution points.
+
+## Results
+
+`InferenceResult` is a discriminated union:
+
+| Kind | Payload | Typical use |
+| --- | --- | --- |
+| `structured` | `{ kind: "structured", value: unknown }` | Text, predictions, timestamps, embeddings |
+| `artifact` | `{ kind: "artifact", artifact: ArtifactMetadata }` | Generated image/audio/video |
+| `multi` | `{ kind: "multi", outputs: InferenceResult[] }` | Multiple images, layers, or media plus metadata |
+
+Check `kind` before accessing fields. Check or validate task-specific structured values at your application boundary. `SharedTaskOutputs` mixes structured **value** types with complete artifact/multi envelopes, depending on the task; do not wrap every mapped type in another `structured` envelope.
+
+## Artifacts
+
+Artifacts are scoped capabilities for binary data. IDs/URLs are opaque and temporary. They do not grant global filesystem access.
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `artifacts.create(input, options?)` | `Promise<ArtifactReference>` | Accepts a `Blob` or `File`; supports `name` and `lifetime: "ephemeral" \| "session"` |
+| `artifacts.get(id)` | `Promise<ArtifactMetadata>` | Reads authorized metadata |
+| `artifacts.getUrl(id)` | `Promise<string>` | Gets a URL usable by media elements or fetching |
+| `artifacts.readBlob(id)` | `Promise<Blob>` | Materializes the complete artifact in renderer memory |
+| `artifacts.saveAs(id, options?)` | `Promise<void>` | Opens trusted save UI; optional `suggestedFilename` |
+| `artifacts.release(id)` | `Promise<void>` | Releases the website's capability |
+
+`ArtifactReference` contains `id`, `mimeType`, `sizeBytes`, and optional `name`. `ArtifactMetadata` adds `createdAt`, optional `expiresAt`, and optional `url`.
+
+The current SDK copies inputs in 256 KiB chunks. Large media belongs in artifacts rather than base64 strings or large number arrays in invocation JSON. A file extension or a file picker's `accept` attribute is not validation of the actual encoding.
+
+Keep an artifact alive while a media element is using its URL. `readBlob()` can be expensive for large videos; prefer direct media URLs for playback. `saveAs()` does not return the chosen local filesystem path. Uploading a blob with `fetch()` is a separate website decision.
+
+## Task profiles and typed validation
+
+`TaskProfile` includes:
+
+- `contract: { id, revision }`, `task`, `profileId`, and `schemaVersion`;
+- input/output modalities and `inputSchemaRef` / `resultSchemaRef` identifiers;
+- feature states: `supported`, `unsupported`, `unknown`, or `requires-input`;
+- parameters with `inputPointer`, `valueSchema`, optional `default`, and `handling`;
+- `limits`, `streamingChannels`, and runtime provenance.
+
+Parameter handling is `honored`, `fixed`, `unsupported`, or `requires-input`. Use this information to build controls that reflect the selected model. Schema references identify negotiated schemas; they are not automatically fetchable website URLs.
+
+### `validateSharedTaskInput`
+
+```text
+validateSharedTaskInput(contract, input) → SharedTaskInputs[contract]
+```
+
+Checks a supported shared-task input against its generated schema, cross-field constraints, and JSON-size bound. Returns the typed input on success. Failure throws a validation error; do not assume every local failure is a `LocalAIError`. It does not request a model, grant permission, validate artifact ownership, or certify execution.
+
+Exports include `SharedTaskInputs`, `SharedTaskOutputs`, `SharedTaskContract`, `SHARED_TASK_CONTRACTS`, and `SHARED_MODEL_TASK_CONTRACTS`. Additional public types include `TaskContractRef`, `TaskFeatureState`, `TaskParameter`, `TaskProfile`, `TaskRequirements`, `ModelSelection`, and `SelectionExplanation`.
+
+## Errors
+
+`LocalAIError` has `name: "LocalAIError"`, a stable `code`, `message`, and optional sanitized `details`. Construct it from a serialized error, for example when converting a `job.failed` event into a thrown exception.
+
+| Category | Representative codes |
+| --- | --- |
+| Availability | `RUNTIME_NOT_AVAILABLE`, `RUNTIME_STARTING`, `RUNTIME_DEPENDENCY_UNAVAILABLE`, `RUNTIME_PROTOCOL_ERROR` |
+| Permission/origin | `USER_DENIED`, `PERMISSION_DENIED`, `UNAUTHORIZED_ORIGIN`, `UNAUTHORIZED_FRAME` |
+| Model selection | `MODEL_NOT_FOUND`, `MODEL_REFERENCE_INVALID`, `NO_EXECUTABLE_MODEL`, `MODEL_NOT_EXECUTABLE` |
+| Model safety | `MODEL_SECURITY_BLOCKED`, `CUSTOM_CODE_REQUIRED`, `UNSAFE_MODEL_FORMAT` |
+| Resources | `RESOURCE_REQUIREMENTS_UNSATISFIABLE`, `RESOURCE_LIMIT_EXCEEDED`, `DISK_SPACE_INSUFFICIENT`, `MODEL_OUT_OF_MEMORY` |
+| Sessions | `SESSION_NOT_FOUND`, `SESSION_ACCESS_DENIED`, `SESSION_RELEASED` |
+| Jobs | `JOB_QUEUE_FULL`, `JOB_INPUT_INVALID`, `JOB_EXECUTION_FAILED`, `JOB_CANCELLED`, `REQUEST_ABORTED` |
+| Artifacts | `ARTIFACT_NOT_FOUND`, `ARTIFACT_ACCESS_DENIED`, `ARTIFACT_EXPIRED`, `ARTIFACT_INVALID` |
+| Task-specific | `AUDIO_FORMAT_UNSUPPORTED`, `ASR_INFERENCE_FAILED`, `MODEL_OUTPUT_FILTERED`, `SONG_GENERATION_FAILED` |
+
+Use the exported `LocalAIErrorCode` union for the complete compile-time list. Keep a fallback for unfamiliar future codes and ordinary JavaScript/network errors. Avoid logging user inputs or complete model outputs simply to diagnose a failure.
+
+## Cancellation and cleanup
+
+Model preparation, job execution, model sessions, and artifacts have separate lifetimes:
+
+1. Abort a pending model request with its `signal`.
+2. Cancel a job with its helper's active signal or `cancel(jobId)`.
+3. Observe the terminal outcome before declaring the job stopped.
+4. Release artifacts after playback, saving, or other consumers finish.
+5. Release the session when the feature no longer needs the model.
+6. Unsubscribe custom listeners when their owner is disposed.
+
+Cleanup in `finally` prevents a successful or failed invocation from leaving an unused session behind. If cleanup itself fails, decide explicitly how to report that without replacing the original user-facing error. A stream `break`, a tab switch, and a session release should not be used as substitutes for explicit cancellation.

package/docs/images/request-lifecycle.svg

@@ -0,0 +1,59 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="1150" viewBox="0 0 1120 1150" role="img" aria-labelledby="title description">
+<title id="title">Oryn SDK request lifecycle</title><desc id="description">Detect capabilities; request a model and allow Browser consent and Engine preparation; receive a session; submit a queued job; consume events and a completed, failed, or cancelled terminal outcome; release sessions and artifacts. Failures or cancellation can also occur during preparation.</desc>
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="#b2adff"/></marker></defs>
+<rect width="1120" height="1150" rx="24" fill="#0c0e14"/>
+<g font-family="Arial, Helvetica, sans-serif">
+<text x="48" y="52" font-size="15" font-weight="700" fill="#b2adff" letter-spacing="2">ORYN SDK  /  REQUEST LIFECYCLE</text>
+<text x="48" y="111" font-size="40" font-weight="700" fill="#f1f3fa" >From intent to a local result.</text>
+<text x="48" y="151" font-size="21" font-weight="400" fill="#b4bed2" >The website asks. Oryn mediates. The user stays in control.</text>
+<path d="M 80 289 V 333" fill="none" stroke="#b2adff" stroke-width="2" marker-end="url(#arrow)"/>
+<circle cx="80" cy="237" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="244" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">01</text>
+<rect x="134" y="201" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="235" font-size="24" font-weight="700" fill="#f1f3fa" >Detect</text>
+<text x="1048" y="233" font-size="12" font-weight="700" fill="#b2adff" text-anchor="end" letter-spacing="1">WEBSITE</text>
+<text x="158" y="266" font-size="18" font-weight="400" fill="#b2adff" font-family="Menlo, Consolas, monospace">getCapabilities()</text>
+<text x="158" y="297" font-size="18" font-weight="400" fill="#b4bed2" >Check availability; offer a fallback.</text>
+<path d="M 80 426 V 470" fill="none" stroke="#b2adff" stroke-width="2" marker-end="url(#arrow)"/>
+<circle cx="80" cy="374" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="381" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">02</text>
+<rect x="134" y="338" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="372" font-size="24" font-weight="700" fill="#f1f3fa" >Resolve</text>
+<text x="1048" y="370" font-size="12" font-weight="700" fill="#b2adff" text-anchor="end" letter-spacing="1">BROWSER + ENGINE</text>
+<text x="158" y="403" font-size="18" font-weight="400" fill="#b2adff" font-family="Menlo, Consolas, monospace">models.request(...)</text>
+<text x="158" y="434" font-size="18" font-weight="400" fill="#b4bed2" >Permission, model choice, download and load.</text>
+<path d="M 80 563 V 607" fill="none" stroke="#b2adff" stroke-width="2" marker-end="url(#arrow)"/>
+<circle cx="80" cy="511" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="518" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">03</text>
+<rect x="134" y="475" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="509" font-size="24" font-weight="700" fill="#f1f3fa" >Receive a session</text>
+<text x="1048" y="507" font-size="12" font-weight="700" fill="#b2adff" text-anchor="end" letter-spacing="1">WEBSITE</text>
+<text x="158" y="540" font-size="18" font-weight="400" fill="#b2adff" font-family="Menlo, Consolas, monospace">ModelSession</text>
+<text x="158" y="571" font-size="18" font-weight="400" fill="#b4bed2" >Inspect the resolved model and task profile.</text>
+<path d="M 80 700 V 744" fill="none" stroke="#b2adff" stroke-width="2" marker-end="url(#arrow)"/>
+<circle cx="80" cy="648" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="655" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">04</text>
+<rect x="134" y="612" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="646" font-size="24" font-weight="700" fill="#f1f3fa" >Submit a job</text>
+<text x="1048" y="644" font-size="12" font-weight="700" fill="#b2adff" text-anchor="end" letter-spacing="1">SDK + ENGINE</text>
+<text x="158" y="677" font-size="18" font-weight="400" fill="#b2adff" font-family="Menlo, Consolas, monospace">invokeAndWait() / invokeStream()</text>
+<text x="158" y="708" font-size="18" font-weight="400" fill="#b4bed2" >Helpers subscribe before submitting; work may queue.</text>
+<path d="M 80 837 V 881" fill="none" stroke="#b2adff" stroke-width="2" marker-end="url(#arrow)"/>
+<circle cx="80" cy="785" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="792" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">05</text>
+<rect x="134" y="749" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="783" font-size="24" font-weight="700" fill="#f1f3fa" >Observe the outcome</text>
+<text x="1048" y="781" font-size="12" font-weight="700" fill="#98ddc5" text-anchor="end" letter-spacing="1">WEBSITE</text>
+<text x="158" y="814" font-size="18" font-weight="400" fill="#98ddc5" font-family="Menlo, Consolas, monospace">LocalAIEvent / InferenceResult</text>
+<text x="158" y="845" font-size="18" font-weight="400" fill="#b4bed2" >Progress, text deltas, previews, then one terminal event.</text>
+<circle cx="80" cy="922" r="29" fill="#24243e" stroke="#655e9b"/>
+<text x="80" y="929" font-size="20" font-weight="700" fill="#b2adff" text-anchor="middle">06</text>
+<rect x="134" y="886" width="938" height="115" rx="18" fill="#151923" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="920" font-size="24" font-weight="700" fill="#f1f3fa" >Release resources</text>
+<text x="1048" y="918" font-size="12" font-weight="700" fill="#b2adff" text-anchor="end" letter-spacing="1">WEBSITE</text>
+<text x="158" y="951" font-size="18" font-weight="400" fill="#b2adff" font-family="Menlo, Consolas, monospace">releaseSession() / artifacts.release()</text>
+<text x="158" y="982" font-size="18" font-weight="400" fill="#b4bed2" >Clean up when the feature and media consumers finish.</text>
+<rect x="134" y="1034" width="938" height="77" rx="18" fill="#1a2230" stroke="#333b50" stroke-width="1.5"/>
+<text x="158" y="1066" font-size="20" font-weight="700" fill="#98ddc5" >Terminal outcomes: completed · failed · cancelled</text>
+<text x="158" y="1094" font-size="17" font-weight="400" fill="#b4bed2" >Requests can also fail or be cancelled before a session or job is created.</text>
+</g></svg>

package/docs/recipes.md

@@ -0,0 +1,288 @@
+# SDK recipes
+
+[SDK overview](../README.md) · [API reference](api-reference.md)
+
+These examples use the website API. They require a compatible Oryn Browser, an executable model, and the user's permission. Functions are intended to be called from your application's user actions; connect their progress and cancellation callbacks to your own UI.
+
+## Choose a model
+
+Prefer a task-only request when the exact model does not matter. If your application has a tested preference, declare it and an explicit substitution policy:
+
+```ts
+import type { LocalAIClient } from "@ocno/oryn-sdk";
+
+export async function requestChat(localAI: LocalAIClient, signal: AbortSignal) {
+  const session = await localAI.models.request(
+    {
+      role: "chat",
+      preferredModel: {
+        provider: "huggingface",
+        repository: "Qwen/Qwen3.5-0.8B",
+      },
+      requirements: {
+        task: "text-generation",
+        inputModalities: ["text"],
+        outputModalities: ["text"],
+        capabilities: { chat: true, streaming: true },
+      },
+      substitution: { automatic: "compatible" },
+    },
+    { signal, onProgress: (progress) => console.info(progress.stage) },
+  );
+
+  console.info({
+    model: session.resolution.resolvedModel.repository,
+    revision: session.resolution.resolvedModel.revision,
+    substituted: session.resolution.substituted,
+    trust: session.resolution.trust,
+  });
+  return session; // The caller owns and must eventually release this session.
+}
+```
+
+The model name illustrates intent; it is not a guarantee that this checkpoint runs on every installation. Oryn may choose a compatible substitute or reject the request. Only put alternatives in `certifiedModels` when your application has actually tested them.
+
+### Select a checkpoint or an exact artifact
+
+When `features.modelSelection` is available, `source-checkpoint` allows selection of an eligible representation of the same checkpoint. `preferred-variant` accompanies a preferred model. `exact-artifact` additionally pins an immutable revision and a complete selected file list.
+
+```ts
+import type { LocalAIClient, ModelRef } from "@ocno/oryn-sdk";
+
+export async function requestExactChat(
+  localAI: LocalAIClient,
+  model: ModelRef,
+  signal: AbortSignal,
+) {
+  if (!(await localAI.getCapabilities()).features.modelSelection) {
+    throw new Error("This browser does not support exact model selection.");
+  }
+  if (!model.files?.length || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(model.revision ?? "")) {
+    throw new Error("Supply an immutable model revision and its selected files.");
+  }
+  return localAI.models.request(
+    {
+      role: "chat",
+      preferredModel: model,
+      selection: { version: 1, intent: "exact-artifact" },
+      requirements: { task: "text-generation", capabilities: { chat: true } },
+      substitution: { automatic: "none" },
+    },
+    { signal },
+  );
+}
+```
+
+The caller supplies a real model identity and owns the returned session. Inspect the returned resolution even for an exact preference: automatic substitution policy and the person's trusted model choice are separate concerns.
+
+## Require an effective task feature
+
+Use a versioned contract when the feature is essential. Fail visibly on older browsers instead of silently downgrading requirements:
+
+```ts
+import type { LocalAIClient } from "@ocno/oryn-sdk";
+
+export async function requestStreamingChat(localAI: LocalAIClient) {
+  if (!(await localAI.getCapabilities()).features.taskProfiles) {
+    throw new Error("This feature requires task-profile support in Oryn.");
+  }
+  const session = await localAI.models.request({
+    role: "chat",
+    requirements: {
+      task: "text-generation",
+      outputModalities: ["text"],
+      contract: { id: "chat-v1", revision: 1 },
+      requiredFeatures: ["streaming"],
+    },
+  });
+  console.info(session.taskProfile?.streamingChannels);
+  console.info(session.taskProfile?.parameters);
+  return session; // Release when the conversation UI is disposed.
+}
+```
+
+A profile can mark a parameter as fixed or unsupported. Render only controls the profile can honor. Feature states of `unknown` or `requires-input` are not unconditional support.
+
+## Transcribe a WAV file
+
+This recipe expects a PCM WAV file. The header check catches obvious container mismatches; Engine validates the actual audio format. It requests transcription, creates an input artifact, reads a structured text result, and cleans up both resources.
+
+```ts
+import {
+  createLocalAIClient,
+  invokeAndWait,
+} from "@ocno/oryn-sdk";
+
+export async function transcribeWav(file: File, signal: AbortSignal): Promise<string> {
+  const header = new Uint8Array(await file.slice(0, 12).arrayBuffer());
+  const ascii = new TextDecoder("ascii");
+  if (
+    header.length < 12 ||
+    ascii.decode(header.subarray(0, 4)) !== "RIFF" ||
+    ascii.decode(header.subarray(8, 12)) !== "WAVE"
+  ) {
+    throw new Error("Choose a PCM WAV recording.");
+  }
+
+  const localAI = createLocalAIClient();
+  const capabilities = await localAI.getCapabilities();
+  if (!capabilities.runtimeAvailable) throw new Error("Local AI is unavailable.");
+
+  const session = await localAI.models.request(
+    {
+      role: "transcription",
+      preferredModel: { provider: "huggingface", repository: "openai/whisper-small" },
+      requirements: {
+        task: "automatic-speech-recognition",
+        inputModalities: ["audio"],
+        outputModalities: ["text"],
+      },
+    },
+    { signal },
+  );
+
+  let inputId: string | undefined;
+  try {
+    const input = await localAI.artifacts.create(file, { lifetime: "session" });
+    inputId = input.id;
+    const result = await invokeAndWait(localAI, {
+      sessionId: session.sessionId,
+      input: { audioArtifactId: input.id, language: "auto", timestamps: false },
+    }, { signal });
+
+    if (
+      result.kind !== "structured" ||
+      typeof result.value !== "object" || result.value === null ||
+      !("text" in result.value) || typeof result.value.text !== "string"
+    ) {
+      throw new Error("Unexpected transcription result.");
+    }
+    return result.value.text;
+  } finally {
+    try {
+      if (inputId) await localAI.artifacts.release(inputId);
+    } finally {
+      await localAI.models.releaseSession(session.sessionId);
+    }
+  }
+}
+```
+
+Timestamps are disabled here. If your product requires word timestamps, negotiate `transcription-v1` with `requiredFeatures: ["wordTimestamps"]` and compatible parameters, then inspect the returned profile. A text-only task match does not promise word timing.
+
+## Use a typed task contract
+
+The SDK exports typed input/output mappings for additional tasks. For zero-shot classification, the mapped output is the **value inside** a structured result:
+
+```ts
+import {
+  invokeAndWait,
+  validateSharedTaskInput,
+  type LocalAIClient,
+  type SharedTaskInputs,
+  type SharedTaskOutputs,
+} from "@ocno/oryn-sdk";
+
+type ClassificationResult = {
+  kind: "structured";
+  value: SharedTaskOutputs["zero-shot-classification-v1"];
+};
+
+export async function classify(localAI: LocalAIClient, text: string) {
+  if (!(await localAI.getCapabilities()).features.taskProfiles) {
+    throw new Error("This feature requires task-profile support in Oryn.");
+  }
+  const input: SharedTaskInputs["zero-shot-classification-v1"] = {
+    text,
+    labels: ["support", "sales", "feedback"],
+    multiLabel: false,
+  };
+  validateSharedTaskInput("zero-shot-classification-v1", input);
+
+  const session = await localAI.models.request({
+    role: "classification",
+    requirements: {
+      task: "zero-shot-classification",
+      outputModalities: ["structured"],
+      contract: { id: "zero-shot-classification-v1", revision: 1 },
+    },
+  });
+  try {
+    const result = await invokeAndWait<typeof input, ClassificationResult>(localAI, {
+      sessionId: session.sessionId,
+      input,
+    });
+    return result.value.predictions;
+  } finally {
+    await localAI.models.releaseSession(session.sessionId);
+  }
+}
+```
+
+The generic result annotation is a compile-time expectation. Add runtime checks if your application accepts other result contracts. Other mapped outputs already contain an artifact or multi-result envelope; check the type for the task you are using.
+
+## Display, save, and upload an output
+
+A generated image or audio file can be displayed directly from its artifact URL. The following helper accepts an existing `ArtifactResult` from your chosen generation task and returns a cleanup function. Keep the artifact alive until the media element is finished with it.
+
+```ts
+import type { ArtifactResult, LocalAIClient } from "@ocno/oryn-sdk";
+
+export async function displayOutput(
+  localAI: LocalAIClient,
+  result: ArtifactResult,
+  element: HTMLImageElement | HTMLAudioElement | HTMLVideoElement,
+): Promise<() => Promise<void>> {
+  element.src = await localAI.artifacts.getUrl(result.artifact.id);
+  return async () => {
+    if (element instanceof HTMLMediaElement) element.pause();
+    element.removeAttribute("src");
+    if (element instanceof HTMLMediaElement) element.load();
+    await localAI.artifacts.release(result.artifact.id);
+  };
+}
+
+export async function saveOutput(localAI: LocalAIClient, result: ArtifactResult) {
+  await localAI.artifacts.saveAs(result.artifact.id, {
+    suggestedFilename: result.artifact.name ?? "oryn-output",
+  });
+}
+```
+
+Call `saveOutput` from a Save button. Use a MIME-appropriate filename if the result has no name. For `multi` results, walk the `outputs` array and handle each envelope by its `kind`.
+
+If your application also offers upload, make that a separate user action and clearly identify the destination. This function intentionally reads and uploads the complete artifact:
+
+```ts
+import type { ArtifactResult, LocalAIClient } from "@ocno/oryn-sdk";
+
+export async function uploadOutput(localAI: LocalAIClient, result: ArtifactResult) {
+  const blob = await localAI.artifacts.readBlob(result.artifact.id);
+  const body = new FormData();
+  body.append("file", blob, result.artifact.name ?? "oryn-output");
+  const response = await fetch("/api/uploads", { method: "POST", body });
+  if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
+  return response;
+}
+```
+
+`/api/uploads` is an endpoint your website must implement; it is not an Oryn service. The caller still owns the artifact and should release it when all display/save/upload consumers have finished. `readBlob()` holds the whole output in renderer memory, which matters for large media.
+
+## Build a cancellation UI
+
+For the streaming quickstart, create an `AbortController` per submission and pass its signal to `streamReply`. Wire the Cancel button to `controller.abort()`. For multiple jobs, keep separate controllers so one click does not cancel unrelated work.
+
+Keep queue and model-preparation states visible. Cancelling a request and cancelling an already submitted job are separate operations. A cancellation request can take time to stop the runtime; wait for the terminal outcome before reporting that it has finished. If you manage submission yourself, retain the `jobId` and use `localAI.cancel(jobId)`.
+
+Unsubscribing or breaking out of an async iterator only stops your event consumer. It does not stop inference. A page should clean up event listeners, then release sessions and artifacts according to their actual lifetime.
+
+## Integrate with a framework
+
+The package has no framework dependency. Create a client in a module or component, run feature work only on the client, and let the framework own rendering.
+
+- **React / Vue / Svelte:** keep active controllers and sessions in component-owned state; use lifecycle cleanup for subscriptions and resource release.
+- **SSR:** import and client creation are safe, but server execution reports no browser runtime. Detect again after hydration instead of caching a server-side availability result.
+- **Rich text:** treat model output as untrusted text. Use escaped text rendering or your application's established sanitization before rendering markup.
+- **Fallback:** explain when Local AI is unavailable. If you offer a cloud alternative, make its data destination and user choice clear.
+
+The reference applications in the source distribution show full page UI and progress handling. These recipes focus on the SDK calls that those applications share.