@orkestrel/ollama 0.0.14 → 0.0.16

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

@@ -1,542 +0,0 @@
-import { ContextFormat } from '@orkestrel/agent';
-import { Message } from '@orkestrel/agent';
-import { ProviderDelta } from '@orkestrel/agent';
-import { ProviderInterface } from '@orkestrel/agent';
-import { ProviderResult } from '@orkestrel/agent';
-import { ProviderStreamOptions } from '@orkestrel/agent';
-import { ThinkSplitterInterface } from '@orkestrel/agent';
-import { TimeoutInterface } from '@orkestrel/timeout';
-import { TokenUsage } from '@orkestrel/budget';
-import { ToolCall } from '@orkestrel/tool';
-import { ToolDefinition } from '@orkestrel/tool';
-
-/**
- * Builds a provider result from a turn's content, reasoning, tool calls, and usage.
- *
- * @remarks
- * Only the present optionals are set: no empty `thinking`, no empty `tools`, and no
- * `usage` unless the wire reported one.
- *
- * @param content - The clean assistant content the splitter accumulated
- * @param thinking - The joined reasoning, empty when the turn produced none
- * @param tools - The tool calls collected across the turn
- * @param usage - The token usage, or `undefined` when the wire reported none
- * @returns The result carrying only its populated fields
- *
- * @example
- * ```ts
- * buildResult('ok', '', [], undefined) // { content: 'ok' }
- * ```
- */
-export declare function buildResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined): ProviderResult;
-
-/**
- * Creates 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`, and `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 ⇒ the global `fetch` and only a JSON content type.
- *
- * The optional `format` is the provider's 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), declaring how this
- * provider's models prefer context sections framed (for example 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 '@orkestrel/ollama'
- *
- * 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:
- * ```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;
-
-/**
- * Names 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.
- *
- * @remarks
- * The name mirrors the Ollama `/api/chat` `keep_alive` field this value is sent as, so
- * the constant, the `OllamaOptions.keepAlive` key, and the wire member read as one term.
- */
-export declare const DEFAULT_KEEP_ALIVE = "5m";
-
-/** Names the local Ollama daemon base URL assumed when `OllamaOptions.url` is omitted. */
-export declare const DEFAULT_OLLAMA_URL = "http://localhost:11434";
-
-/**
- * Names 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;
-
-/**
- * Extracts a wire `arguments` value as a record.
- *
- * @remarks
- * Total: an object passes through, a JSON string is parsed when it yields a record, and
- * a malformed string yields `{}` rather than throwing.
- *
- * @param value - The wire's `function.arguments` value, of unknown shape
- * @returns The argument record, or `{}` when the value carries none
- *
- * @example
- * ```ts
- * extractArguments('{"city":"Oslo"}') // { city: 'Oslo' }
- * ```
- */
-export declare function extractArguments(value: unknown): Readonly<Record<string, unknown>>;
-
-/**
- * Extracts the assistant text of one wire record.
- *
- * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
- * @returns The record's `message.content` when it is a string, else `''`
- *
- * @example
- * ```ts
- * extractContent({ message: { content: 'ok' } }) // 'ok'
- * ```
- */
-export declare function extractContent(record: Readonly<Record<string, unknown>>): string;
-
-/**
- * Extracts the daemon-side reasoning of one wire record.
- *
- * @remarks
- * `message.thinking` is the `think: true` wire shape. It is read whatever the configured
- * flag says, because a daemon may separate reasoning on its own.
- *
- * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
- * @returns The record's `message.thinking` when it is a string, else `''`
- *
- * @example
- * ```ts
- * extractThinking({ message: { thinking: 'weighing it' } }) // 'weighing it'
- * ```
- */
-export declare function extractThinking(record: Readonly<Record<string, unknown>>): string;
-
-/**
- * Extracts the tool calls of one wire record's `message.tool_calls`.
- *
- * @remarks
- * Each entry narrows to `{ id, name, arguments }`: the entry and its `function` must be
- * records and `name` a string, else the entry is dropped. An id is minted when the wire
- * omits one.
- *
- * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
- * @returns The narrowed tool calls, empty when the record carries none
- *
- * @example
- * ```ts
- * extractTools({ message: { tool_calls: [{ function: { name: 'weather' } }] } })
- * // [{ id: '…', name: 'weather', arguments: {} }]
- * ```
- */
-export declare function extractTools(record: Readonly<Record<string, unknown>>): readonly ToolCall[];
-
-/**
- * Extracts the token usage of one wire record.
- *
- * @remarks
- * Both counts must be numbers, which is true of the non-stream body and the stream's
- * `done: true` line. A delta line carries neither, so it yields `undefined`.
- *
- * @param record - One parsed `/api/chat` record — a non-stream body or an NDJSON line
- * @returns The `TokenUsage` shape, or `undefined` when either count is absent
- *
- * @example
- * ```ts
- * extractUsage({ prompt_eval_count: 3, eval_count: 4 })
- * // { prompt: 3, completion: 4, total: 7 }
- * ```
- */
-export declare function extractUsage(record: Readonly<Record<string, unknown>>): TokenUsage | undefined;
-
-/**
- * Checks whether a value is an {@link OllamaHTTPError}.
- *
- * @param value - The value to test
- * @returns True if `value` is an `OllamaHTTPError`; false otherwise
- */
-export declare function isOllamaHTTPError(value: unknown): value is OllamaHTTPError;
-
-/**
- * Joins a call's two reasoning carriers into the result's `thinking`.
- *
- * @param splitter - The per-call splitter holding the separated in-content spans
- * @param wired - The accumulated wire-side `message.thinking` text
- * @returns The two carriers separated by a blank line, or whichever one is non-empty
- *
- * @example
- * ```ts
- * joinThinking(createThinkSplitter(), 'from the wire') // 'from the wire'
- * ```
- */
-export declare function joinThinking(splitter: ThinkSplitterInterface, wired: string): string;
-
-/**
- * Maps conversation turns onto the `/api/chat` wire's minimal message shape.
- *
- * @remarks
- * `tool_calls` is emitted only on a turn that replays them and `images` only on a
- * multimodal turn, so an empty optional never reaches the wire.
- *
- * @param messages - The conversation turns to send
- * @returns The wire `messages` array, one entry per turn, in order
- *
- * @example
- * ```ts
- * mapMessages([{ id: '1', role: 'user', content: 'Say hello.' }])
- * // [{ role: 'user', content: 'Say hello.' }]
- * ```
- */
-export declare function mapMessages(messages: readonly Message[]): WireChatRequest['messages'];
-
-/**
- * Names 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. `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;
-
-/**
- * Represents an error thrown when the Ollama `/api/chat` HTTP transport fails.
- *
- * @remarks
- * Carries the machine-readable `code` `'HTTP'` and the response `status` (0 when no
- * HTTP response was received at all, for example a `null` body). Thrown by
- * {@link OllamaProvider} at its HTTP failure sites — the non-OK status branch and the
- * null-body branch — so a caller can branch on `error.code` and read `error.status`
- * for the HTTP number 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 {
-    /**
-     * Names the machine-readable condition this error reports — `'HTTP'`: an `/api/chat`
-     * transport, status, or body failure.
-     */
-    readonly code: "HTTP";
-    readonly status: number;
-    constructor(message: string, status: number, options?: OllamaHTTPErrorOptions);
-}
-
-/**
- * Represents the options a thrown {@link OllamaHTTPError} accepts beside its message and status —
- * the standard error `cause` link, named so a consumer can reference the shape.
- *
- * @remarks
- * `cause` is the underlying value that produced the HTTP failure: the transport or
- * body-read rejection the provider caught before rethrowing. It is `unknown` because a
- * thrown value is unconstrained. Omitted ⇒ the error carries no cause.
- */
-export declare interface OllamaHTTPErrorOptions {
-    readonly cause?: unknown;
-}
-
-/**
- * Represents the configuration `createOllama` accepts for the local Ollama backend.
- *
- * @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`, and `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
- * (for example 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;
-    /** Sets the daemon base URL; defaults to `'http://localhost:11434'`. */
-    readonly url?: string;
-    /**
-     * Sets how long the model stays resident after a call; defaults to `'5m'`. Mirrors the
-     * Ollama `/api/chat` `keep_alive` field, whose value this key carries verbatim onto
-     * {@link WireChatRequest.keep_alive}.
-     */
-    readonly keepAlive?: string | number;
-    /** Sets the per-call deadline in milliseconds; defaults to `120_000`. */
-    readonly timeout?: number;
-    /**
-     * Carries passthrough sampling parameters (`temperature`, `seed`, and `num_predict`).
-     * Mirrors the Ollama `/api/chat` `options` field, whose value this key carries verbatim
-     * onto {@link WireChatRequest.options}.
-     */
-    readonly options?: Readonly<Record<string, unknown>>;
-    /**
-     * Sets the `/api/chat` `think` wire flag; defaults to `false`. When `true`, a thinking-capable
-     * model (for example `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 is `false`, so a non-thinking model needs no
-     * configuration and answers immediately; 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;
-    /**
-     * Sets 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;
-    /**
-     * Sets 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 — for example 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?: () => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
-    /**
-     * Sets 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 (for example 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 sends only when a call supplies a `schema`; the two are unrelated
-     * despite the shared word.
-     */
-    readonly format?: ContextFormat;
-}
-
-/**
- * Implements 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 through {@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.** 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 through `extractThinking`) 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.** 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 ⇒ the global `fetch`
- *   and only a JSON content type.
- *   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 name = "ollama";
-    constructor(options: OllamaOptions);
-    /**
-     * Exposes this instance's identity — a fresh `crypto.randomUUID()` minted at
-     * construction, satisfying the {@link ProviderInterface.id} contract member. A second
-     * provider built from identical options carries a distinct id.
-     *
-     * @returns The instance's minted identifier
-     */
-    get id(): string;
-    /**
-     * Exposes 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 ContextFormat}, or `undefined` when none
-     */
-    get format(): ContextFormat | undefined;
-    generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
-    stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
-}
-
-/**
- * Represents an open `POST /api/chat` response together with the deadline and the
- * combined signal that bound the request.
- *
- * @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 the provider clears on a failed or 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;
-}
-
-/**
- * Parses a non-stream `/api/chat` response body into a wire record.
- *
- * @remarks
- * Total by construction: an empty body, a body that is not JSON, and a body whose JSON is
- * not an object all yield `undefined`, so a malformed daemon response never escapes as a
- * `SyntaxError`. The call site supplies the empty-record default that reads as empty
- * content and no usage.
- *
- * @param response - The 200-OK `/api/chat` response whose body is read as text
- * @returns The parsed record, or `undefined` when the body is empty or malformed
- *
- * @example
- * ```ts
- * await parseBody(new Response('{"message":{"content":"ok"}}'))
- * // { message: { content: 'ok' } }
- * ```
- */
-export declare function parseBody(response: Response): Promise<Readonly<Record<string, unknown>> | undefined>;
-
-/**
- * Represents 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 `mapMessages` 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: ReadonlyArray<{
-        readonly role: string;
-        readonly content: string;
-        readonly tool_calls?: ReadonlyArray<{
-            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?: ReadonlyArray<{
-        readonly type: 'function';
-        readonly function: {
-            readonly name: string;
-            readonly description?: string;
-            readonly parameters?: Readonly<Record<string, unknown>>;
-        };
-    }>;
-    /**
-     * Holds 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 { }