@nemesis-oss/ollama-sdk 1.0.0

package/dist/compose-DC11aDJn.d.ts

@@ -0,0 +1,430 @@
+import { z } from 'zod';
+
+/**
+ * Core protocol and message types for the Ollama REST API.
+ */
+type Role = 'system' | 'user' | 'assistant' | 'tool' | 'thought';
+interface ToolCallFunction {
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+/**
+ * Unlike OpenAI, Ollama's native `/api/chat` protocol does not assign an identifier to a
+ * tool call on the wire — a model turn's `tool_calls` array has no per-call ID from
+ * Ollama's side. `id` here is a **client-side synthesized value** (see
+ * `src/tools/tool-call-id.ts`), generated the first time the SDK sees a call without one
+ * and reused consistently afterward, so consumers get OpenAI-style `tool_call_id`
+ * correlation without the SDK depending on Ollama ever providing one. It carries no
+ * meaning to Ollama or the model — `ToolRegistry.executeToolCalls` still fundamentally
+ * dispatches by array position/order (straightforwardly parallel via `Promise.all` by
+ * default, or concurrency-bounded via `maxConcurrency`); `id` is a convenience layered on
+ * top for correlation/logging, not the underlying execution model. See ADR 0007.
+ */
+interface ToolCall {
+    /** Client-synthesized; see the type-level doc above. Always present once returned by this SDK. */
+    readonly id?: string | undefined;
+    readonly function: ToolCallFunction;
+}
+interface Message {
+    readonly role: Role;
+    readonly content: string;
+    readonly images?: readonly string[] | undefined;
+    readonly tool_calls?: readonly ToolCall[] | undefined;
+    /** Set on a `role: 'tool'` message to identify which {@link ToolCall.id} this answers. */
+    readonly tool_call_id?: string | undefined;
+    readonly thinking?: string | undefined;
+}
+interface ToolProperty {
+    readonly type: string;
+    readonly description?: string | undefined;
+    readonly enum?: readonly string[] | undefined;
+    readonly items?: Record<string, unknown> | undefined;
+    readonly properties?: Record<string, unknown> | undefined;
+    readonly required?: readonly string[] | undefined;
+}
+interface ToolFunctionDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: {
+        readonly type: 'object';
+        readonly properties: Record<string, ToolProperty>;
+        readonly required?: readonly string[] | undefined;
+    };
+}
+interface ToolDefinition {
+    readonly type: 'function';
+    readonly function: ToolFunctionDefinition;
+}
+type FormatOption = 'json' | Record<string, unknown>;
+interface ModelOptions {
+    readonly num_keep?: number | undefined;
+    readonly seed?: number | undefined;
+    readonly num_predict?: number | undefined;
+    readonly top_k?: number | undefined;
+    readonly top_p?: number | undefined;
+    readonly min_p?: number | undefined;
+    readonly tfs_z?: number | undefined;
+    readonly typical_p?: number | undefined;
+    readonly repeat_last_n?: number | undefined;
+    readonly temperature?: number | undefined;
+    readonly repeat_penalty?: number | undefined;
+    readonly presence_penalty?: number | undefined;
+    readonly frequency_penalty?: number | undefined;
+    readonly mirostat?: number | undefined;
+    readonly mirostat_tau?: number | undefined;
+    readonly mirostat_eta?: number | undefined;
+    readonly penalize_newline?: boolean | undefined;
+    readonly stop?: readonly string[] | undefined;
+    readonly num_ctx?: number | undefined;
+    readonly num_batch?: number | undefined;
+    readonly num_gpu?: number | undefined;
+    readonly main_gpu?: number | undefined;
+    readonly low_vram?: boolean | undefined;
+    readonly f16_kv?: boolean | undefined;
+    readonly vocab_only?: boolean | undefined;
+    readonly use_mmap?: boolean | undefined;
+    readonly use_mlock?: boolean | undefined;
+    readonly num_thread?: number | undefined;
+}
+interface RequestCancellationOptions {
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+interface ChatRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly messages: readonly Message[];
+    readonly tools?: readonly ToolDefinition[] | undefined;
+    readonly format?: FormatOption | undefined;
+    readonly options?: ModelOptions | undefined;
+    readonly stream?: boolean | undefined;
+    readonly keep_alive?: string | number | undefined;
+    readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
+}
+interface ChatResponse {
+    readonly model: string;
+    readonly created_at: string;
+    readonly message: Message;
+    readonly done: boolean;
+    readonly done_reason?: string | undefined;
+    readonly total_duration?: number | undefined;
+    readonly load_duration?: number | undefined;
+    readonly prompt_eval_count?: number | undefined;
+    readonly prompt_eval_duration?: number | undefined;
+    readonly eval_count?: number | undefined;
+    readonly eval_duration?: number | undefined;
+}
+interface GenerateRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly prompt: string;
+    readonly suffix?: string | undefined;
+    readonly system?: string | undefined;
+    readonly template?: string | undefined;
+    readonly context?: readonly number[] | undefined;
+    readonly stream?: boolean | undefined;
+    readonly raw?: boolean | undefined;
+    readonly format?: FormatOption | undefined;
+    readonly images?: readonly string[] | undefined;
+    readonly options?: ModelOptions | undefined;
+    readonly keep_alive?: string | number | undefined;
+    readonly think?: boolean | 'low' | 'medium' | 'high' | 'max' | undefined;
+}
+interface GenerateResponse {
+    readonly model: string;
+    readonly created_at: string;
+    readonly response: string;
+    readonly done: boolean;
+    readonly done_reason?: string | undefined;
+    readonly context?: readonly number[] | undefined;
+    readonly total_duration?: number | undefined;
+    readonly load_duration?: number | undefined;
+    readonly prompt_eval_count?: number | undefined;
+    readonly prompt_eval_duration?: number | undefined;
+    readonly eval_count?: number | undefined;
+    readonly eval_duration?: number | undefined;
+    readonly thinking?: string | undefined;
+}
+interface EmbedRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly input: string | readonly string[];
+    readonly truncate?: boolean | undefined;
+    /** Truncates the returned embedding vectors to this many dimensions, if supported by the model. */
+    readonly dimensions?: number | undefined;
+    readonly options?: ModelOptions | undefined;
+    readonly keep_alive?: string | number | undefined;
+}
+interface EmbedResponse {
+    readonly model: string;
+    readonly embeddings: readonly (readonly number[])[];
+    readonly total_duration?: number | undefined;
+    readonly load_duration?: number | undefined;
+    readonly prompt_eval_count?: number | undefined;
+}
+interface EmbeddingsRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly prompt: string;
+    readonly options?: ModelOptions | undefined;
+    readonly keep_alive?: string | number | undefined;
+}
+interface EmbeddingsResponse {
+    readonly embedding: readonly number[];
+}
+interface ModelDetails {
+    readonly parent_model?: string | undefined;
+    readonly format: string;
+    readonly family: string;
+    readonly families?: readonly string[] | undefined;
+    readonly parameter_size: string;
+    readonly quantization_level: string;
+}
+interface ModelResponse {
+    readonly name: string;
+    readonly model: string;
+    readonly modified_at: string;
+    readonly size: number;
+    readonly digest: string;
+    readonly details: ModelDetails;
+    readonly expires_at?: string | undefined;
+    readonly size_vram?: number | undefined;
+}
+interface ListResponse {
+    readonly models: readonly ModelResponse[];
+}
+interface ShowRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly system?: string | undefined;
+    readonly template?: string | undefined;
+    readonly verbose?: boolean | undefined;
+}
+interface ShowResponse {
+    readonly license?: string | undefined;
+    readonly modelfile?: string | undefined;
+    readonly parameters?: string | undefined;
+    readonly template?: string | undefined;
+    readonly system?: string | undefined;
+    readonly details: ModelDetails;
+    readonly messages?: readonly Message[] | undefined;
+    readonly model_info?: Record<string, unknown> | undefined;
+    readonly capabilities?: readonly string[] | undefined;
+    readonly modified_at?: string | undefined;
+}
+interface ProgressResponse {
+    readonly status: string;
+    readonly digest?: string | undefined;
+    readonly total?: number | undefined;
+    readonly completed?: number | undefined;
+}
+interface PullRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly insecure?: boolean | undefined;
+    readonly stream?: boolean | undefined;
+}
+interface PushRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly insecure?: boolean | undefined;
+    readonly stream?: boolean | undefined;
+}
+interface CreateRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+    readonly modelfile?: string | undefined;
+    readonly stream?: boolean | undefined;
+    readonly quantize?: string | undefined;
+    readonly from?: string | undefined;
+    readonly files?: Record<string, string> | undefined;
+    readonly adapters?: Record<string, string> | undefined;
+}
+interface DeleteRequestOptions extends RequestCancellationOptions {
+    readonly model: string;
+}
+interface CopyRequestOptions extends RequestCancellationOptions {
+    readonly source: string;
+    readonly destination: string;
+}
+interface StatusResponse {
+    readonly status: string;
+}
+interface VersionResponse {
+    readonly version: string;
+}
+interface PsResponse {
+    readonly models: readonly ModelResponse[];
+}
+interface WebSearchRequestOptions extends RequestCancellationOptions {
+    readonly query: string;
+    readonly count?: number | undefined;
+}
+interface WebSearchResult {
+    readonly title: string;
+    readonly url: string;
+    readonly snippet: string;
+}
+interface WebSearchResponse {
+    readonly results: readonly WebSearchResult[];
+}
+interface WebFetchRequestOptions extends RequestCancellationOptions {
+    readonly url: string;
+}
+interface WebFetchResponse {
+    readonly content: string;
+}
+
+/**
+ * Tool definition, handler, and execution types.
+ */
+
+interface ToolExecutionContext {
+    readonly signal?: AbortSignal | undefined;
+}
+type ToolHandler<TParams, TResult> = (params: TParams, context: ToolExecutionContext) => Promise<TResult> | TResult;
+interface Tool<TParams = Record<string, unknown>, TResult = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly schema: z.ZodType<TParams>;
+    readonly execute: ToolHandler<TParams, TResult>;
+    readonly definition: ToolDefinition;
+    /**
+     * Per-tool execution timeout in milliseconds, overriding the registry's default.
+     * Pass `0` to explicitly disable timeout enforcement for this tool.
+     */
+    readonly timeoutMs?: number | undefined;
+}
+/**
+ * A `Tool` of *any* parameter shape, for heterogeneous collections — i.e. what
+ * `ToolRegistry` stores and accepts.
+ *
+ * `Tool<TParams>` is **invariant** in `TParams`, because `TParams` appears both
+ * covariantly (`schema: z.ZodType<TParams>`) and contravariantly
+ * (`execute: ToolHandler<TParams, …>`). That makes `Tool<never, unknown>` — the obvious-
+ * looking "bottom" type for a mixed collection — assignable from *nothing*: a perfectly
+ * ordinary `Tool<{ city: string }, string>` from `defineTool` is rejected by it. `any` is
+ * the standard escape hatch for exactly this case, and it is confined to this one alias:
+ * `defineTool` still infers `TParams` from the Zod schema and still type-checks `execute`
+ * against it, so tool authoring keeps full type safety. Only the registry's *storage*
+ * type is widened, and the registry never does anything with a tool's params beyond
+ * handing `schema.safeParse`'s validated output straight back to that same tool's
+ * `execute`.
+ */
+type AnyTool = Tool<any, unknown>;
+interface ToolExecutionSuccess {
+    readonly toolName: string;
+    /** Echoes the originating {@link ToolCall.id}, if the call had one. */
+    readonly toolCallId?: string | undefined;
+    readonly success: true;
+    readonly result: unknown;
+    readonly outputString: string;
+}
+interface ToolExecutionFailure {
+    readonly toolName: string;
+    /** Echoes the originating {@link ToolCall.id}, if the call had one. */
+    readonly toolCallId?: string | undefined;
+    readonly success: false;
+    readonly error: Error;
+    readonly outputString: string;
+}
+type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;
+
+/**
+ * Tool registry for managing definitions and executing model tool calls.
+ */
+
+interface ToolRegistryOptions {
+    readonly tools?: readonly AnyTool[] | undefined;
+    readonly onError?: ((error: Error, toolCall: ToolCall) => string) | undefined;
+    /**
+     * Default per-call execution timeout in milliseconds, applied to any tool that
+     * doesn't declare its own `timeoutMs`. Undefined (the default) means no timeout is
+     * enforced, matching prior behavior. Recommended whenever tool arguments or
+     * implementations are influenced by model output you don't fully control, since an
+     * unbounded tool call can otherwise stall the entire agent loop indefinitely.
+     *
+     * Enforcement is cooperative: it races the tool's promise against a timer and
+     * reports a timeout failure, but cannot forcibly halt synchronous or non-abort-aware
+     * asynchronous work already in flight on the same thread. Tools that perform I/O
+     * should honor `ToolExecutionContext.signal` to stop promptly on timeout.
+     */
+    readonly timeoutMs?: number | undefined;
+    /**
+     * Maximum number of tool calls executed concurrently by `executeToolCalls`.
+     * Undefined (the default) runs all calls in parallel, matching prior behavior.
+     */
+    readonly maxConcurrency?: number | undefined;
+    /**
+     * Maximum length of a tool's `outputString` before it is truncated. Guards against a
+     * single tool call flooding the conversation history / model context (and process
+     * memory) with unbounded output. Undefined (the default) applies no limit.
+     */
+    readonly maxOutputChars?: number | undefined;
+}
+declare class ToolRegistry {
+    private readonly tools;
+    private readonly onError?;
+    private readonly defaultTimeoutMs?;
+    private readonly maxConcurrency?;
+    private readonly maxOutputChars?;
+    constructor(toolsOrOptions?: readonly AnyTool[] | ToolRegistryOptions | undefined);
+    register(tool: AnyTool): this;
+    registerMany(tools: readonly AnyTool[]): this;
+    get(name: string): AnyTool | undefined;
+    definitions(): ToolDefinition[];
+    executeToolCall(toolCall: ToolCall, ctx?: ToolExecutionContext): Promise<ToolExecutionResult>;
+    private executeToolCallUninstrumented;
+    /**
+     * Executes every call in `toolCalls` and returns results in the same order, so results
+     * are always correlatable by array position regardless of `id`. Each result also echoes
+     * its call's `toolCallId` for callers who'd rather match by ID — see the {@link ToolCall}
+     * docs for how that id is produced. Runs fully in parallel (`Promise.all`) unless
+     * `maxConcurrency` was configured, in which case a bounded worker pool is used instead.
+     */
+    executeToolCalls(toolCalls: readonly ToolCall[], ctx?: ToolExecutionContext): Promise<ToolExecutionResult[]>;
+    private runWithTimeout;
+    private truncateOutput;
+    private handleExecutionError;
+}
+
+/**
+ * SKILL.md frontmatter and skill registry types.
+ */
+interface SkillFrontmatter {
+    readonly name: string;
+    readonly description: string;
+    readonly 'allowed-tools'?: readonly string[] | undefined;
+    readonly [key: string]: unknown;
+}
+interface SkillSummary {
+    readonly name: string;
+    readonly description: string;
+    readonly path: string;
+}
+interface Skill extends SkillSummary {
+    readonly frontmatter: SkillFrontmatter;
+    readonly body: string;
+    readonly allowedTools?: readonly string[] | undefined;
+}
+
+/**
+ * Lightweight frontmatter parser for SKILL.md files.
+ */
+
+interface ParsedFrontmatter {
+    readonly frontmatter: SkillFrontmatter;
+    readonly body: string;
+}
+declare function parseFrontmatter(source: string, path?: string): ParsedFrontmatter;
+
+/**
+ * Skill composition and context injection.
+ */
+
+interface ApplySkillOptions {
+    readonly messages: readonly Message[];
+    readonly tools?: ToolRegistry;
+}
+interface AppliedSkillResult {
+    readonly messages: readonly Message[];
+    readonly tools?: ToolRegistry;
+}
+/**
+ * Injects a skill's body into messages as a system prompt and applies allowed tool filters.
+ */
+declare function applySkill(skill: Skill, options: ApplySkillOptions): AppliedSkillResult;
+
+export { parseFrontmatter as $, type AnyTool as A, type Role as B, type ChatResponse as C, type DeleteRequestOptions as D, type EmbedRequestOptions as E, type FormatOption as F, type GenerateResponse as G, type Skill as H, type SkillFrontmatter as I, type SkillSummary as J, type ToolCallFunction as K, type ListResponse as L, type Message as M, type ToolExecutionContext as N, type ToolExecutionFailure as O, type ProgressResponse as P, type ToolExecutionSuccess as Q, type RequestCancellationOptions as R, type ShowRequestOptions as S, type ToolCall as T, type ToolFunctionDefinition as U, type VersionResponse as V, type WebSearchRequestOptions as W, type ToolProperty as X, type ToolRegistryOptions as Y, type WebSearchResult as Z, applySkill as _, type ModelResponse as a, type ShowResponse as b, type PullRequestOptions as c, type PushRequestOptions as d, type CreateRequestOptions as e, type StatusResponse as f, type CopyRequestOptions as g, type PsResponse as h, type ChatRequestOptions as i, type GenerateRequestOptions as j, type EmbedResponse as k, type EmbeddingsRequestOptions as l, type EmbeddingsResponse as m, type WebSearchResponse as n, type WebFetchRequestOptions as o, type WebFetchResponse as p, type ToolHandler as q, type Tool as r, ToolRegistry as s, type ToolExecutionResult as t, type ModelOptions as u, type ToolDefinition as v, type AppliedSkillResult as w, type ApplySkillOptions as x, type ModelDetails as y, type ParsedFrontmatter as z };