@orkestrel/ollama 0.0.14 → 0.0.16

package/dist/src/server/index.js

@@ -1,612 +0,0 @@
-import { isNumber, isRecord, isString, parseJSONAs } from "@orkestrel/contract";
-import { ProviderAbortError, createThinkSplitter } from "@orkestrel/agent";
-import { createNDJSONParser } from "@orkestrel/ndjson";
-import { Timeout } from "@orkestrel/timeout";
-//#region src/server/constants.ts
-/** Names the local Ollama daemon base URL assumed when `OllamaOptions.url` is omitted. */
-var DEFAULT_OLLAMA_URL = "http://localhost:11434";
-/**
-* 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.
-*/
-var DEFAULT_KEEP_ALIVE = "5m";
-/**
-* Names the per-call deadline in milliseconds when `OllamaOptions.timeout` is omitted —
-* generous enough that a cold model load does not trip it.
-*/
-var DEFAULT_PROVIDER_TIMEOUT = 12e4;
-/**
-* 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.
-*/
-var MAX_ERROR_BODY_LENGTH = 2048;
-//#endregion
-//#region src/server/errors.ts
-/**
-* 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
-* 	}
-* }
-* ```
-*/
-var OllamaHTTPError = class extends Error {
-	/**
-	* Names the machine-readable condition this error reports — `'HTTP'`: an `/api/chat`
-	* transport, status, or body failure.
-	*/
-	code = "HTTP";
-	status;
-	constructor(message, status, options) {
-		super(message, options);
-		this.name = "OllamaHTTPError";
-		this.status = status;
-	}
-};
-/**
-* Checks whether a value is an {@link OllamaHTTPError}.
-*
-* @param value - The value to test
-* @returns True if `value` is an `OllamaHTTPError`; false otherwise
-*/
-function isOllamaHTTPError(value) {
-	return value instanceof OllamaHTTPError;
-}
-//#endregion
-//#region src/server/helpers.ts
-/**
-* 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.' }]
-* ```
-*/
-function mapMessages(messages) {
-	return messages.map((message) => ({
-		role: message.role,
-		content: message.content,
-		...message.calls !== void 0 && message.calls.length > 0 ? { tool_calls: message.calls.map((call) => ({ function: {
-			name: call.name,
-			arguments: call.arguments
-		} })) } : {},
-		...message.images !== void 0 && message.images.length > 0 ? { images: [...message.images] } : {}
-	}));
-}
-/**
-* 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' }
-* ```
-*/
-function buildResult(content, thinking, tools, usage) {
-	const result = { content };
-	if (thinking.length > 0) result.thinking = thinking;
-	if (tools.length > 0) result.tools = tools;
-	if (usage !== void 0) result.usage = usage;
-	return result;
-}
-/**
-* 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'
-* ```
-*/
-function extractContent(record) {
-	const message = Reflect.get(record, "message");
-	if (!isRecord(message)) return "";
-	const content = Reflect.get(message, "content");
-	return isString(content) ? content : "";
-}
-/**
-* 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'
-* ```
-*/
-function extractThinking(record) {
-	const message = Reflect.get(record, "message");
-	if (!isRecord(message)) return "";
-	const thinking = Reflect.get(message, "thinking");
-	return isString(thinking) ? thinking : "";
-}
-/**
-* 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'
-* ```
-*/
-function joinThinking(splitter, wired) {
-	if (splitter.thinking.length === 0) return wired;
-	if (wired.length === 0) return splitter.thinking;
-	return `${splitter.thinking}\n\n${wired}`;
-}
-/**
-* 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 }
-* ```
-*/
-function extractUsage(record) {
-	const prompt = Reflect.get(record, "prompt_eval_count");
-	const completion = Reflect.get(record, "eval_count");
-	if (!isNumber(prompt) || !isNumber(completion)) return void 0;
-	return {
-		prompt,
-		completion,
-		total: prompt + completion
-	};
-}
-/**
-* 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: {} }]
-* ```
-*/
-function extractTools(record) {
-	const message = Reflect.get(record, "message");
-	if (!isRecord(message)) return [];
-	const calls = Reflect.get(message, "tool_calls");
-	if (!Array.isArray(calls)) return [];
-	const out = [];
-	for (const entry of calls) {
-		if (!isRecord(entry)) continue;
-		const callable = Reflect.get(entry, "function");
-		if (!isRecord(callable)) continue;
-		const name = Reflect.get(callable, "name");
-		if (!isString(name)) continue;
-		const id = Reflect.get(entry, "id");
-		out.push({
-			id: isString(id) ? id : crypto.randomUUID(),
-			name,
-			arguments: extractArguments(Reflect.get(callable, "arguments"))
-		});
-	}
-	return out;
-}
-/**
-* 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' }
-* ```
-*/
-function extractArguments(value) {
-	if (isRecord(value)) return value;
-	if (isString(value)) return parseJSONAs(value, isRecord) ?? {};
-	return {};
-}
-//#endregion
-//#region src/server/parsers.ts
-/**
-* 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' } }
-* ```
-*/
-async function parseBody(response) {
-	return parseJSONAs(await response.text(), isRecord);
-}
-//#endregion
-//#region src/server/OllamaProvider.ts
-/**
-* 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)
-* ```
-*/
-var OllamaProvider = class {
-	name = "ollama";
-	#id;
-	#model;
-	#url;
-	#keepAlive;
-	#timeout;
-	#think;
-	#options;
-	#transport;
-	#headers;
-	#format;
-	constructor(options) {
-		this.#id = crypto.randomUUID();
-		this.#model = options.model;
-		this.#url = options.url ?? "http://localhost:11434";
-		this.#keepAlive = options.keepAlive ?? "5m";
-		this.#timeout = options.timeout ?? 12e4;
-		this.#think = options.think ?? false;
-		this.#options = options.options;
-		this.#transport = options.fetch ?? globalThis.fetch.bind(globalThis);
-		this.#headers = options.headers;
-		this.#format = options.format;
-	}
-	/**
-	* 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() {
-		return this.#id;
-	}
-	/**
-	* 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() {
-		return this.#format;
-	}
-	async generate(messages, signal, tools, options) {
-		const { response, timeout } = await this.#fetch(messages, false, signal, tools, options);
-		try {
-			const record = await parseBody(response) ?? {};
-			const splitter = createThinkSplitter();
-			splitter.split(extractContent(record));
-			splitter.flush();
-			const thinking = joinThinking(splitter, extractThinking(record));
-			return buildResult(splitter.content, thinking, extractTools(record), extractUsage(record));
-		} finally {
-			timeout.clear();
-		}
-	}
-	async *stream(messages, signal, tools, options) {
-		const { response, timeout, combined } = await this.#fetch(messages, true, signal, tools, options);
-		const body = response.body;
-		if (body === null) {
-			timeout.clear();
-			throw new OllamaHTTPError("Ollama API error: no response body", 0);
-		}
-		const reader = body.getReader();
-		const decoder = new TextDecoder();
-		const parser = createNDJSONParser();
-		const splitter = createThinkSplitter();
-		let wired = "";
-		const calls = [];
-		let usage;
-		try {
-			for (;;) {
-				const { value, done } = await reader.read();
-				if (done) break;
-				for (const record of parser.parse(decoder.decode(value, { stream: true }))) {
-					const increment = yield* this.#deltas(record, splitter, usage);
-					wired += increment.thinking;
-					calls.push(...increment.calls);
-					usage = increment.usage;
-				}
-			}
-			const decoderTail = decoder.decode();
-			for (const record of parser.parse(decoderTail.length > 0 ? `${decoderTail}\n` : "\n")) {
-				const increment = yield* this.#deltas(record, splitter, usage);
-				wired += increment.thinking;
-				calls.push(...increment.calls);
-				usage = increment.usage;
-			}
-			const tail = splitter.flush();
-			if (tail.length > 0) yield {
-				channel: "content",
-				text: tail
-			};
-		} catch (error) {
-			if (combined.aborted) {
-				splitter.flush();
-				throw new ProviderAbortError(buildResult(splitter.content, joinThinking(splitter, wired), calls, usage));
-			}
-			throw error;
-		} finally {
-			try {
-				await reader.cancel();
-			} catch {}
-			parser.clear();
-			timeout.clear();
-		}
-		return buildResult(splitter.content, joinThinking(splitter, wired), calls, usage);
-	}
-	*#deltas(record, splitter, usage) {
-		const delta = splitter.split(extractContent(record));
-		if (delta.length > 0) yield {
-			channel: "content",
-			text: delta
-		};
-		const thinking = extractThinking(record);
-		if (thinking.length > 0) yield {
-			channel: "thinking",
-			text: thinking
-		};
-		return {
-			thinking,
-			calls: extractTools(record),
-			usage: Reflect.get(record, "done") === true ? extractUsage(record) : usage
-		};
-	}
-	async #fetch(messages, stream, signal, tools, options) {
-		const timeout = new Timeout({ ms: this.#timeout });
-		timeout.start();
-		const combined = AbortSignal.any([timeout.signal, signal]);
-		try {
-			const response = await this.#transport(`${this.#url}/api/chat`, {
-				method: "POST",
-				headers: await this.#requestHeaders(),
-				body: JSON.stringify(this.#body(messages, stream, tools, options)),
-				signal: combined
-			});
-			if (!response.ok) {
-				let detail;
-				try {
-					const text = await response.text();
-					detail = text.length > 2048 ? text.slice(0, MAX_ERROR_BODY_LENGTH) : text;
-				} catch (cause) {
-					throw new OllamaHTTPError(`Ollama API error: ${response.status} - (error body unavailable)`, response.status, { cause });
-				}
-				throw new OllamaHTTPError(`Ollama API error: ${response.status} - ${detail}`, response.status);
-			}
-			return {
-				response,
-				timeout,
-				combined
-			};
-		} catch (error) {
-			timeout.clear();
-			throw error;
-		}
-	}
-	async #requestHeaders() {
-		const headers = { "Content-Type": "application/json" };
-		if (this.#headers !== void 0) for (const [key, value] of Object.entries(await this.#headers())) headers[key] = value;
-		return headers;
-	}
-	#body(messages, stream, tools, options) {
-		return {
-			model: this.#model,
-			messages: mapMessages(messages),
-			stream,
-			keep_alive: this.#keepAlive,
-			think: options?.think ?? this.#think,
-			...this.#options !== void 0 ? { options: this.#options } : {},
-			...options?.schema !== void 0 ? { format: options.schema } : {},
-			...tools !== void 0 && tools.length > 0 ? { tools: tools.map((tool) => ({
-				type: "function",
-				function: {
-					name: tool.name,
-					...tool.description === void 0 ? {} : { description: tool.description },
-					...tool.parameters === void 0 ? {} : { parameters: tool.parameters }
-				}
-			})) } : {}
-		};
-	}
-};
-//#endregion
-//#region src/server/factories.ts
-/**
-* 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>',
-*     },
-*   },
-* })
-* ```
-*/
-function createOllama(options) {
-	return new OllamaProvider(options);
-}
-//#endregion
-export { DEFAULT_KEEP_ALIVE, DEFAULT_OLLAMA_URL, DEFAULT_PROVIDER_TIMEOUT, MAX_ERROR_BODY_LENGTH, OllamaHTTPError, OllamaProvider, buildResult, createOllama, extractArguments, extractContent, extractThinking, extractTools, extractUsage, isOllamaHTTPError, joinThinking, mapMessages, parseBody };
-
-//# sourceMappingURL=index.js.map