@orkestrel/ollama 0.0.4 → 0.0.6

package/dist/src/server/index.d.cts

@@ -0,0 +1,346 @@
+import { ContextFormatInterface } from '@orkestrel/agent';
+import { MessageInterface } from '@orkestrel/agent';
+import { ProviderDelta } from '@orkestrel/agent';
+import { ProviderInterface } from '@orkestrel/agent';
+import { ProviderResult } from '@orkestrel/agent';
+import { ProviderStreamOptions } from '@orkestrel/agent';
+import { TimeoutInterface } from '@orkestrel/timeout';
+import { ToolDefinition } from '@orkestrel/agent';
+
+/**
+ * Create a local Ollama inference provider — a {@link ProviderInterface} over the
+ * daemon's `POST /api/chat`, supporting non-streaming `generate` and streaming
+ * `stream`.
+ *
+ * @remarks
+ * Only `model` is required; `url` defaults to the local daemon, `keepAlive` to `'5m'`,
+ * `timeout` to `120_000`ms, and `options` is forwarded verbatim as sampling
+ * parameters (`temperature` / `seed` / `num_predict` / …). Both calls take an
+ * `AbortSignal` to bound the request; a `stream` cancelled mid-flight throws a
+ * `ProviderAbortError` carrying the partial result.
+ *
+ * The optional `fetch` + `headers` form a transport seam (see {@link OllamaOptions}):
+ * point `url` at your own server, inject a custom `fetch`, and have `headers` attach a
+ * generated/obfuscated bearer token your server validates — so a browser runtime
+ * reaches the LLM through your middleware WITHOUT this library ever handling the real API
+ * key. Both omitted ⇒ today's behaviour (the global `fetch`, only a JSON content type).
+ *
+ * The optional `format` is the provider's context-framing default — the PROVIDER-DEFAULT
+ * level of `AgentContext`'s format cascade (see [agents.md]; beaten by a manager-options
+ * or per-item override, beating the managers' built-in framing), declaring how this
+ * provider's models prefer context sections framed (e.g. XML group wrappers vs. Markdown
+ * headers). It is EXPOSED on the provider for the Agent's `build()` and is NOT Ollama's
+ * `/api/chat` `format` wire parameter (structured output) — the two are unrelated despite
+ * the shared word. Omitted ⇒ the provider is framing-agnostic (core's built-in defaults).
+ *
+ * @param options - `model` (required), and optional `url` / `keepAlive` / `timeout` /
+ *   `options` / `fetch` / `headers` / `format` (see {@link OllamaOptions})
+ * @returns A working {@link ProviderInterface} backed by Ollama
+ *
+ * @example
+ * ```ts
+ * import { createAbort } from '@orkestrel/abort'
+ * import { createOllama } from '@src/server'
+ *
+ * const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M' })
+ * const abort = createAbort()
+ * const result = await provider.generate(messages, abort.signal)
+ * ```
+ *
+ * @example
+ * Route through your own server with an obfuscated token (deployment scenario S2):
+ * ```ts
+ * const provider = createOllama({
+ *   model: 'qwen3.5:2b-q4_K_M',
+ *   url: 'https://my-app.example.com/llm', // your server, not the daemon
+ *   fetch: myFetch, // optional custom transport
+ *   headers: () => ({ authorization: `Bearer ${myToken}` }), // your server validates this
+ * })
+ * ```
+ *
+ * @example
+ * Declare a context-framing default — wrap the instructions section in an XML group (the
+ * provider-default level of `AgentContext`'s cascade; NOT the wire `format`):
+ * ```ts
+ * const provider = createOllama({
+ *   model: 'qwen3.5:2b-q4_K_M',
+ *   format: {
+ *     instructions: {
+ *       open: '<instructions>',
+ *       render: (i) => `<instruction>${i.content}</instruction>`,
+ *       close: '</instructions>',
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare function createOllama(options: OllamaOptions): ProviderInterface;
+
+/**
+ * How long the model stays resident after a call when `OllamaOptions.keepAlive` is
+ * omitted — Ollama's own `keep_alive` default, expressed as a duration string.
+ */
+export declare const DEFAULT_KEEP_ALIVE = "5m";
+
+/** The local Ollama daemon base URL assumed when `OllamaOptions.url` is omitted. */
+export declare const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+
+/**
+ * The per-call deadline in milliseconds when `OllamaOptions.timeout` is omitted —
+ * generous enough that a cold model load does not trip it.
+ */
+export declare const DEFAULT_PROVIDER_TIMEOUT = 120000;
+
+/**
+ * Whether a value is an {@link OllamaHTTPError}.
+ *
+ * @param value - The value to test
+ * @returns `true` when `value` is an `OllamaHTTPError`
+ */
+export declare function isOllamaHTTPError(value: unknown): value is OllamaHTTPError;
+
+/**
+ * The cap, in characters, on how much of a non-OK response body is
+ * incorporated into a thrown {@link OllamaHTTPError}'s message.
+ *
+ * @remarks
+ * Bounds the excerpt so a defensive proxy or a misbehaving daemon handing
+ * back an unbounded response body cannot inflate the thrown error's message
+ * without limit (§14). `2048` characters is generous enough to carry a
+ * useful diagnostic snippet while staying well short of any practical size
+ * concern.
+ */
+export declare const MAX_ERROR_BODY_LENGTH = 2048;
+
+/**
+ * An error thrown when the Ollama `/api/chat` HTTP transport fails.
+ *
+ * @remarks
+ * Carries the response `status` (0 when no HTTP response was received at all,
+ * e.g. a `null` body). Thrown by {@link OllamaProvider} at its two HTTP
+ * failure sites — the non-OK status branch and the null-body branch — so a
+ * caller can branch on `error.status` instead of parsing the message. Narrow
+ * a caught value with {@link isOllamaHTTPError}.
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	await provider.generate(messages, signal)
+ * } catch (error) {
+ * 	if (isOllamaHTTPError(error) && error.status === 404) {
+ * 		// the configured model isn't pulled
+ * 	}
+ * }
+ * ```
+ */
+export declare class OllamaHTTPError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number, options?: {
+        readonly cause?: unknown;
+    });
+}
+
+/**
+ * Options for `createOllama` — the local Ollama backend's configuration.
+ *
+ * @remarks
+ * Only `model` is required. `url` defaults to the local daemon, `keepAlive` controls
+ * how long the model stays resident after a call, `timeout` is the per-call deadline
+ * in milliseconds, and `options` is a passthrough bag of sampling parameters
+ * (`temperature` / `seed` / `num_predict` / …) forwarded verbatim to the wire.
+ *
+ * The optional `fetch` + `headers` form a **transport seam**: by default the provider
+ * talks straight to a local daemon over `globalThis.fetch` with only a JSON content
+ * type, but a browser-side runtime can inject a custom transport AND a dynamic header
+ * (e.g. an obfuscated bearer token) so requests route through the developer's OWN
+ * server, which validates that header and forwards to the real LLM. Your app never
+ * holds a real API key — the real key lives only on the developer's server; the
+ * `headers` hook supplies whatever short-lived/obfuscated token that server expects.
+ */
+export declare interface OllamaOptions {
+    readonly model: string;
+    /** The daemon base URL; defaults to `'http://localhost:11434'`. */
+    readonly url?: string;
+    /** How long the model stays resident after a call; defaults to `'5m'`. */
+    readonly keepAlive?: string | number;
+    /** The per-call deadline in milliseconds; defaults to `120_000`. */
+    readonly timeout?: number;
+    /** Passthrough sampling options (`temperature` / `seed` / `num_predict` / …). */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * The `/api/chat` `think` wire flag; defaults to `false`. When `true`, a thinking-capable
+     * model (e.g. `qwen3`) separates its reasoning NATIVELY at the wire — the daemon returns it
+     * on the distinct `message.thinking` channel (surfaced on `ProviderResult.thinking`) rather
+     * than inline in `message.content`. The default stays `false` so a general-purpose provider
+     * is backward-compatible and immediate for non-thinking models; the per-call ThinkSplitter
+     * remains the defensive fallback for daemons/models that still inline `<think>` tags either
+     * way. Set it `true` for a thinking model whose reasoning you intend to DISPLAY separately.
+     */
+    readonly think?: boolean;
+    /**
+     * A custom `fetch` implementation for every request; defaults to
+     * `globalThis.fetch`. Lets a runtime inject its own transport (a browser fetch
+     * pointed at the developer's server, an instrumented wrapper, …) without changing
+     * the wire protocol. Omitted ⇒ the global `fetch`.
+     */
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * A dynamic, possibly-async header injector called once per request; its returned
+     * headers are merged into the request on top of the base `Content-Type`. Use it to
+     * attach an authorization header — e.g. an obfuscated/generated bearer token the
+     * developer's server validates before relaying to the real LLM — so a browser
+     * runtime can authenticate WITHOUT your app ever handling a real API key. Async so a
+     * token can be refreshed/fetched per call. A returned `Content-Type` overrides the
+     * default; other headers add to it. Omitted ⇒ only `Content-Type: application/json`.
+     */
+    readonly headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * The provider's OPTIONAL context-framing default — the PROVIDER-DEFAULT level of
+     * `AgentContext`'s format cascade (beaten by a manager-options or per-item override,
+     * beating the managers' built-in framing). Declares how this provider's models prefer
+     * context sections framed (e.g. XML group wrappers vs. Markdown headers). Omitted ⇒
+     * the provider is framing-agnostic and core's built-in defaults apply unchanged. NOTE:
+     * this is the prompt-CONTEXT framing consumed by `AgentContext.build()` — it is NOT
+     * Ollama's `/api/chat` `format` wire parameter (structured-output / JSON schema),
+     * which this provider does not currently send; the two are unrelated despite the
+     * shared word.
+     */
+    readonly format?: ContextFormatInterface;
+}
+
+/**
+ * The local Ollama inference boundary — a {@link ProviderInterface} over Ollama's
+ * `POST /api/chat`, both non-streaming (`generate`) and streaming NDJSON (`stream`).
+ *
+ * @remarks
+ * - **Wire protocol.** Posts `{ model, messages, stream, keep_alive, think }` plus
+ *   passthrough sampling `options` and mapped function `tools`. The `think` flag is
+ *   CONFIGURABLE via {@link OllamaOptions.think} (default `false`). Non-stream parses
+ *   one JSON body; stream consumes NDJSON (one JSON object per `\n`-terminated line) —
+ *   deltas carry `message.content`, the final `done: true` line carries the token usage.
+ * - **Think separation (H4).** The wire `think` flag is configurable
+ *   ({@link OllamaOptions.think}, default `false`). With `think: true` a thinking model's
+ *   daemon separates reasoning NATIVELY — returning it on the distinct `message.thinking`
+ *   channel (read here via `#thinking`) instead of inline in `message.content`. EITHER
+ *   way the per-call {@link ThinkSplitterInterface} is the defensive guarantee: a daemon
+ *   may ignore `think: false` for a thinking model and inline `<think>` tags, so every
+ *   content delta routes through the splitter, only CLEAN content is yielded / assembled,
+ *   and the separated reasoning (plus any daemon-side `message.thinking` deltas) lands on
+ *   `ProviderResult.thinking`, never in the conversation.
+ * - **Boundary narrowing (§14).** Every wire value arrives as `unknown` and is
+ *   narrowed through guards (`isRecord` / `isString` / `isNumber`) — never `as`. A
+ *   missing / malformed field degrades to a sensible default (empty content, no
+ *   usage, `{}` arguments), never a throw.
+ * - **Bounded.** Each call arms a {@link Timeout} for `OllamaOptions.timeout` and
+ *   passes `AbortSignal.any([timeout.signal, signal])` to `fetch`, so the caller's
+ *   signal AND the deadline both cancel the request. The timeout is always cleared —
+ *   in `#fetch` if the request fails/aborts, otherwise in the consuming call's `finally`.
+ * - **Abort recovers partial.** A `stream` cancelled mid-flight throws a
+ *   `ProviderAbortError` carrying the partial result assembled so far; pairing the
+ *   `TextDecoder({ stream: true })` with the {@link NDJSONParser} parser keeps multi-byte
+ *   UTF-8 splits and partial lines honest.
+ * - **Event-free.** A pure functional boundary — no Emitter, no events.
+ * - **Transport seam.** {@link OllamaOptions.fetch} swaps the transport (default
+ *   `globalThis.fetch`) and {@link OllamaOptions.headers} is a per-request, possibly
+ *   async header injector merged over the base `Content-Type` — so a browser runtime
+ *   can route through the developer's own server with an obfuscated bearer token,
+ *   without this library ever handling a real API key. Both omitted ⇒ today's behaviour.
+ *   Orthogonal to the deadline: the hook is awaited inside `#fetch`'s try, so a hook
+ *   rejection clears the armed timer like any other request failure.
+ *
+ * @example
+ * ```ts
+ * const provider = new OllamaProvider({ model: 'qwen3.5:2b-q4_K_M' })
+ * const result = await provider.generate(messages, abort.signal)
+ * ```
+ */
+export declare class OllamaProvider implements ProviderInterface {
+    #private;
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    readonly name = "ollama";
+    constructor(options: OllamaOptions);
+    /**
+     * The provider's context-framing default — the PROVIDER-DEFAULT level of
+     * {@link import('@orkestrel/agent').AgentContextInterface.build}'s format cascade (it BEATS
+     * the managers' built-in framing, is BEATEN by a manager-options or per-item override).
+     * Satisfies the OPTIONAL {@link ProviderInterface.format} contract member: `undefined`
+     * when {@link OllamaOptions.format} was omitted (the framing-agnostic default ⇒ core's
+     * built-in framing applies unchanged), else the exact configured framing the Agent
+     * threads into `build()`.
+     *
+     * @remarks
+     * EXPOSE-ONLY — read by the Agent loop and consumed by core's cascade; it is NEVER sent
+     * on the `/api/chat` wire (it is absent from `#body` / the request). This is NOT Ollama's
+     * structured-output `format` wire parameter — that one IS sent in `#body`, but only when
+     * a per-call `ProviderStreamOptions.schema` is supplied; only the word collides.
+     *
+     * @returns The configured {@link ContextFormatInterface}, or `undefined` when none
+     */
+    get format(): ContextFormatInterface | undefined;
+    generate(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    stream(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+}
+
+/**
+ * A live `fetch` to `/api/chat` with the deadline + combined signal that bound it —
+ * the internal wire-shape `OllamaProvider.#fetch` hands back to a consuming call.
+ *
+ * @remarks
+ * The `response` is the open `POST /api/chat` `Response`; `timeout` is the armed
+ * {@link TimeoutInterface} the consuming call clears once it finishes reading the body
+ * (or that `#fetch` itself clears on a failed/aborted request); `combined` is the
+ * `AbortSignal.any([timeout.signal, callerSignal])` the request was issued under, which
+ * the streaming path checks to tell a mid-stream cancel apart from any other error.
+ */
+export declare interface OllamaResponse {
+    readonly response: Response;
+    readonly timeout: TimeoutInterface;
+    readonly combined: AbortSignal;
+}
+
+/**
+ * The exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed
+ * wire contract.
+ *
+ * @remarks
+ * This is the typed wire shape asserted against the official `ollama` client's
+ * `ChatRequest` by the compile-time parity test; `src/` never imports `ollama` itself.
+ * `messages` mirrors the minimal turn shape `#plain` builds (`role` / `content`, plus
+ * `tool_calls` only on a turn that replays them and `images` only on a multimodal
+ * turn); `options` and `tools` are only present when configured.
+ */
+export declare interface WireChatRequest {
+    readonly model: string;
+    readonly messages: readonly {
+        readonly role: string;
+        readonly content: string;
+        readonly tool_calls?: readonly {
+            readonly function: {
+                readonly name: string;
+                readonly arguments: Readonly<Record<string, unknown>>;
+            };
+        }[];
+        readonly images?: readonly string[];
+    }[];
+    readonly stream: boolean;
+    readonly keep_alive: string | number;
+    readonly think: boolean;
+    readonly options?: Readonly<Record<string, unknown>>;
+    readonly tools?: readonly {
+        readonly type: 'function';
+        readonly function: {
+            readonly name: string;
+            readonly description?: string;
+            readonly parameters?: Readonly<Record<string, unknown>>;
+        };
+    }[];
+    /**
+     * The `/api/chat` structured-output constraint — a JSON-Schema object forwarded
+     * verbatim from the per-call `ProviderStreamOptions.schema`. This is NOT
+     * `OllamaOptions.format` (the unrelated prompt-context framing); only present
+     * when a call supplies a `schema`.
+     */
+    readonly format?: Readonly<Record<string, unknown>>;
+}
+
+export { }