@orkestrel/ollama 0.0.15 → 0.0.17

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

@@ -0,0 +1,355 @@
+import { AgentProvider } from '@orkestrel/agent';
+import type { AgentProviderInterface } from '@orkestrel/agent';
+import type { Message } from '@orkestrel/agent';
+import type { ProviderIncrement } from '@orkestrel/agent';
+import type { ProviderInterface } from '@orkestrel/agent';
+import type { ProviderOptions } from '@orkestrel/agent';
+import type { ProviderParserInterface } from '@orkestrel/agent';
+import type { ProviderRequest } from '@orkestrel/agent';
+import type { TokenUsage } from '@orkestrel/budget';
+import type { ToolCall } from '@orkestrel/tool';
+
+/**
+ * Creates a local Ollama inference provider — a {@link ProviderInterface} over the
+ * daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `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`). Each call takes 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 framing default and that
+ * wire parameter 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 createOllama + generate
+ * ```ts
+ * import { createAbort } from '@orkestrel/abort'
+ * import type { TokenUsage } from '@orkestrel/budget'
+ * import { createOllama } from '@orkestrel/ollama'
+ *
+ * declare function charge(usage: TokenUsage): void // your billing integration
+ *
+ * const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M', options: { temperature: 0 } })
+ * const abort = createAbort()
+ * const messages = [
+ * 	{ id: '1', role: 'user', content: 'Summarize the release notes for version 2.0.' },
+ * ] as const
+ *
+ * const result = await provider.generate(messages, abort.signal)
+ * console.log(result.content)
+ * if (result.usage) charge(result.usage) // fold into a token budget
+ * ```
+ *
+ * @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 — `'5m'` 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, `'http://localhost:11434'`, assumed when
+ * `OllamaOptions.url` is omitted.
+ */
+export declare const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+
+/**
+ * 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` NDJSON record
+ * @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` NDJSON record
+ * @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` NDJSON record
+ * @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 stream's `done: true` line. A
+ * delta line carries neither, so it yields `undefined`.
+ *
+ * @param record - One parsed `/api/chat` NDJSON record
+ * @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;
+
+/**
+ * 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 Ollama chat endpoint appended to the configured base URL. */
+export declare const OLLAMA_CHAT_PATH = "/api/chat";
+
+/**
+ * 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 both 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 extends ProviderOptions {
+    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;
+    /**
+     * 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;
+}
+
+/**
+ * Implements the Ollama `/api/chat` wire over the shared {@link AgentProvider} engine.
+ *
+ * @remarks
+ * Every request uses NDJSON streaming. The base assembles complete turns, separates
+ * reasoning, and bounds requests; this class supplies Ollama framing and projections.
+ * Usage comes only from a `done: true` record carrying the token counts.
+ *
+ * @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 extends AgentProvider implements AgentProviderInterface {
+    #private;
+    readonly name = "ollama";
+    constructor(options: OllamaOptions);
+    /**
+     * Creates fresh NDJSON framing state for a call.
+     *
+     * @returns The parser that buffers incomplete Ollama records
+     */
+    frame(): ProviderParserInterface;
+    /**
+     * Projects conversation turns and per-call options onto the Ollama request body.
+     *
+     * @remarks
+     * A tool's `title` and `annotations` are never sent: the `/api/chat` tool function
+     * object carries no field for either.
+     *
+     * @param request - The conversation, advertised tools, and per-call overrides
+     * @returns The `/api/chat` body with streaming enabled
+     */
+    body(request: ProviderRequest): WireChatRequest;
+    /**
+     * Extracts a record's content, reasoning, tools, and completed usage report.
+     *
+     * @param record - One parsed Ollama NDJSON record
+     * @returns The turn increment, omitting usage until `done` and the counts are present
+     */
+    read(record: Readonly<Record<string, unknown>>): ProviderIncrement;
+    /**
+     * Recovers a final NDJSON record that arrived without its line terminator.
+     *
+     * @param parser - The call's parser holding any unterminated input
+     * @returns The records completed by the final newline
+     */
+    finish(parser: ProviderParserInterface): ReadonlyArray<Readonly<Record<string, unknown>>>;
+}
+
+/**
+ * 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. `format` carries the
+ * `/api/chat` structured-output constraint, forwarded verbatim from the per-call
+ * `ProviderStreamOptions.schema` and absent when no schema is supplied.
+ */
+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 { }