@petrgrishin/ai-sdk-ollama 3.0.2

package/dist/index.browser.d.ts

@@ -0,0 +1,726 @@
+import { RerankingModelV3, RerankingModelV3CallOptions, JSONSchema7, ProviderV3, LanguageModelV3, EmbeddingModelV3 } from '@ai-sdk/provider';
+import { Ollama, Config, ChatRequest, Options as Options$1, EmbedRequest } from 'ollama';
+import { FetchFunction } from '@ai-sdk/provider-utils';
+import * as ai from 'ai';
+import { generateText as generateText$1, streamText as streamText$1 } from 'ai';
+
+/**
+ * Configuration for the Ollama reranking model
+ */
+interface OllamaRerankingConfig {
+    provider: string;
+    baseURL: string;
+    headers: () => Record<string, string | undefined>;
+    fetch?: FetchFunction;
+}
+/**
+ * Settings for configuring Ollama reranking models
+ */
+interface OllamaRerankingSettings {
+    /**
+     * Custom instruction for the reranker model.
+     * Defaults to the model's built-in instruction (usually "Please judge relevance").
+     */
+    instruction?: string;
+}
+/**
+ * Ollama provider options for reranking calls
+ */
+interface OllamaRerankingProviderOptions {
+    /**
+     * Custom instruction for this specific reranking call.
+     * Overrides the instruction set in model settings.
+     */
+    instruction?: string;
+}
+/**
+ * Native Ollama Reranking Model
+ *
+ * **WAITING FOR OFFICIAL SUPPORT**
+ *
+ * This implementation uses Ollama's /api/rerank endpoint from PR #11389.
+ * As of December 2024, this PR has NOT been merged into Ollama.
+ *
+ * **For a working solution, use `OllamaEmbeddingRerankingModel` instead:**
+ * ```ts
+ * import { ollama } from 'ai-sdk-ollama';
+ * import { rerank } from 'ai';
+ *
+ * const result = await rerank({
+ *   model: ollama.embeddingReranking('bge-m3'),
+ *   query: 'What is machine learning?',
+ *   documents: [...],
+ * });
+ * ```
+ *
+ * This native implementation will work once Ollama adds reranking support:
+ * @see https://github.com/ollama/ollama/pull/11389
+ *
+ * @example
+ * ```ts
+ * // NOT YET WORKING - requires Ollama reranking API
+ * import { ollama } from 'ai-sdk-ollama';
+ * import { rerank } from 'ai';
+ *
+ * const { rerankedDocuments } = await rerank({
+ *   model: ollama.rerankingModel('bge-reranker-v2-m3'),
+ *   query: 'What is machine learning?',
+ *   documents: [
+ *     'Machine learning is a subset of AI...',
+ *     'The weather today is sunny...',
+ *     'Deep learning uses neural networks...',
+ *   ],
+ *   topN: 2,
+ * });
+ * ```
+ */
+declare class OllamaRerankingModel implements RerankingModelV3 {
+    readonly specificationVersion: "v3";
+    readonly modelId: string;
+    private readonly config;
+    private readonly settings;
+    constructor(modelId: string, settings: OllamaRerankingSettings, config: OllamaRerankingConfig);
+    get provider(): string;
+    doRerank({ documents, headers, query, topN, abortSignal, providerOptions, }: RerankingModelV3CallOptions): Promise<Awaited<ReturnType<RerankingModelV3['doRerank']>>>;
+}
+
+/**
+ * Settings for configuring Ollama embedding-based reranking
+ */
+interface OllamaEmbeddingRerankingSettings {
+    /**
+     * Embedding model to use for computing document similarity.
+     * If not specified, uses the modelId passed to the constructor.
+     * Recommended models: 'bge-m3', 'nomic-embed-text', 'mxbai-embed-large'
+     */
+    embeddingModel?: string;
+    /**
+     * Maximum number of texts to embed per request. Smaller batches reduce
+     * memory/latency spikes for large document sets while still avoiding one
+     * request per document. Defaults to 16.
+     */
+    maxBatchSize?: number;
+}
+
+type OllamaWithWebSearch = Ollama;
+/**
+ * Configuration options for the web search tool
+ */
+interface WebSearchToolOptions {
+    /**
+     * Timeout for search requests in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Ollama client instance to use for web search
+     * If not provided, will need to be injected at runtime
+     */
+    client?: OllamaWithWebSearch;
+}
+/**
+ * Output schema for web search results
+ */
+type WebSearchOutput = {
+    results: Array<{
+        title: string;
+        url: string;
+        snippet: string;
+        publishedDate?: string;
+    }>;
+    searchQuery: string;
+    totalResults: number;
+};
+declare function webSearch(options?: WebSearchToolOptions): ai.Tool<{
+    query: string;
+    maxResults?: number | undefined;
+}, WebSearchOutput>;
+
+type OllamaWithWebFetch = Ollama;
+/**
+ * Configuration options for the web fetch tool
+ */
+interface WebFetchToolOptions {
+    /**
+     * Timeout for fetch requests in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Maximum content length to return in characters
+     * @default 10000
+     */
+    maxContentLength?: number;
+    /**
+     * Ollama client instance to use for web fetch
+     * If not provided, will need to be injected at runtime
+     */
+    client?: OllamaWithWebFetch;
+}
+/**
+ * Output schema for web fetch results
+ */
+type WebFetchOutput = {
+    content: string;
+    title?: string;
+    url: string;
+    contentLength: number;
+    error?: string;
+};
+/**
+ * Creates a web fetch tool that allows AI models to retrieve content from specific URLs.
+ *
+ * This tool uses Ollama's web fetch capabilities to retrieve and parse web page content,
+ * making it accessible to AI models for analysis, summarization, or answering questions
+ * about specific web pages.
+ *
+ * @param options - Configuration options for the web fetch tool
+ * @returns A tool that can be used in AI SDK generateText/streamText calls
+ *
+ * @example
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { ollama } from 'ai-sdk-ollama';
+ *
+ * const result = await generateText({
+ *   model: ollama('llama3.2'),
+ *   prompt: 'Summarize the main points from this article: https://example.com/article',
+ *   tools: {
+ *     webFetch: ollama.tools.webFetch()
+ *   }
+ * });
+ * ```
+ */
+declare function webFetch(options?: WebFetchToolOptions): ai.Tool<{
+    url: string;
+}, WebFetchOutput>;
+
+/**
+ * Ollama-specific tools that leverage the provider's web search capabilities.
+ * Follows the same pattern as Google and OpenAI providers.
+ */
+declare const ollamaTools: {
+    /**
+     * Creates a web search tool that allows models to search the internet for current information.
+     *
+     * @param options - Configuration options for the web search tool
+     * @returns A tool that can search the web and return relevant results
+     *
+     * @example
+     * ```typescript
+     * import { ollama } from 'ai-sdk-ollama';
+     * import { generateText } from 'ai';
+     *
+     * const result = await generateText({
+     *   model: ollama('llama3.2'),
+     *   prompt: 'What are the latest AI developments?',
+     *   tools: {
+     *     webSearch: ollama.tools.webSearch({ maxResults: 5 })
+     *   }
+     * });
+     * ```
+     */
+    readonly webSearch: typeof webSearch;
+    /**
+     * Creates a web fetch tool that allows models to retrieve content from specific URLs.
+     *
+     * @param options - Configuration options for the web fetch tool
+     * @returns A tool that can fetch web page content
+     *
+     * @example
+     * ```typescript
+     * import { ollama } from 'ai-sdk-ollama';
+     * import { generateText } from 'ai';
+     *
+     * const result = await generateText({
+     *   model: ollama('llama3.2'),
+     *   prompt: 'Summarize the content from https://example.com',
+     *   tools: {
+     *     webFetch: ollama.tools.webFetch()
+     *   }
+     * });
+     * ```
+     */
+    readonly webFetch: typeof webFetch;
+};
+
+/**
+ * Object Generation Reliability Utilities for Ollama
+ *
+ * This module provides utilities to make Ollama object generation more reliable
+ * and deterministic. It addresses common issues like:
+ * - Schema validation failures
+ * - Inconsistent results across multiple attempts
+ * - Timeout and fetch errors
+ * - Malformed JSON responses
+ * - Type mismatches (strings vs numbers)
+ */
+
+/**
+ * A function that attempts to repair the raw output of the model
+ * to enable JSON parsing and validation.
+ *
+ * Similar to AI SDK's RepairTextFunction but tailored for Ollama's output patterns.
+ */
+type RepairTextFunction = (options: {
+    text: string;
+    error: Error;
+    schema?: JSONSchema7 | unknown;
+}) => Promise<string | null>;
+interface ObjectGenerationOptions {
+    /**
+     * Maximum number of retry attempts for object generation
+     */
+    maxRetries?: number;
+    /**
+     * Whether to attempt schema recovery when validation fails
+     */
+    attemptRecovery?: boolean;
+    /**
+     * Whether to use fallback values for failed generations
+     */
+    useFallbacks?: boolean;
+    /**
+     * Custom fallback values for specific fields
+     */
+    fallbackValues?: Record<string, unknown>;
+    /**
+     * Timeout for object generation in milliseconds
+     */
+    generationTimeout?: number;
+    /**
+     * Whether to validate and fix type mismatches
+     */
+    fixTypeMismatches?: boolean;
+    /**
+     * Custom repair function for malformed JSON or validation errors
+     * If provided, this will be used instead of the default jsonrepair
+     */
+    repairText?: RepairTextFunction;
+    /**
+     * Whether to enable automatic JSON repair for malformed LLM outputs
+     * Default: true (enabled by default for better reliability)
+     * Handles 14+ types of JSON issues including Python constants, JSONP, comments,
+     * escaped quotes, URLs in strings, trailing commas, unquoted keys, etc.
+     * Set to false to disable all automatic repair
+     */
+    enableTextRepair?: boolean;
+}
+
+interface Options extends Options$1 {
+    /**
+     * Minimum probability threshold for token selection
+     * This parameter is supported by Ollama API but missing from ollama-js TypeScript definitions
+     */
+    min_p?: number;
+}
+
+/**
+ * Settings for configuring the Ollama provider.
+ * Extends from Ollama's Config type for consistency with the underlying client.
+ */
+interface OllamaProviderSettings extends Pick<Config, 'headers' | 'fetch'> {
+    /**
+     * Base URL for the Ollama API (defaults to http://127.0.0.1:11434)
+     * Maps to Config.host in the Ollama client
+     */
+    baseURL?: string;
+    /**
+     * Ollama API key for authentication with cloud services.
+     * The API key will be set as Authorization: Bearer {apiKey} header.
+     */
+    apiKey?: string;
+    /**
+     * Existing Ollama client instance to use instead of creating a new one.
+     * When provided, baseURL, headers, and fetch are ignored.
+     */
+    client?: Ollama;
+}
+interface OllamaProvider extends ProviderV3 {
+    /**
+     * Create a language model instance
+     */
+    (modelId: string, settings?: OllamaChatSettings): LanguageModelV3;
+    /**
+     * Create a language model instance with the `chat` method
+     */
+    chat(modelId: string, settings?: OllamaChatSettings): LanguageModelV3;
+    /**
+     * Create a language model instance with the `languageModel` method
+     */
+    languageModel(modelId: string, settings?: OllamaChatSettings): LanguageModelV3;
+    /**
+     * Create an embedding model instance
+     */
+    embedding(modelId: string, settings?: OllamaEmbeddingSettings): EmbeddingModelV3;
+    /**
+     * Create an embedding model instance with the `textEmbedding` method
+     */
+    textEmbedding(modelId: string, settings?: OllamaEmbeddingSettings): EmbeddingModelV3;
+    /**
+     * Create an embedding model instance with the `textEmbeddingModel` method
+     */
+    textEmbeddingModel(modelId: string, settings?: OllamaEmbeddingSettings): EmbeddingModelV3;
+    /**
+     * Create a reranking model instance
+     */
+    reranking(modelId: string, settings?: OllamaRerankingSettings): RerankingModelV3;
+    /**
+     * Create a reranking model instance with the `rerankingModel` method
+     *
+     * NOTE: This uses Ollama's native /api/rerank endpoint which is NOT YET AVAILABLE.
+     * Use `embeddingReranking()` for a working solution.
+     * @see https://github.com/ollama/ollama/pull/11389
+     */
+    rerankingModel(modelId: string, settings?: OllamaRerankingSettings): RerankingModelV3;
+    /**
+     * Create an embedding-based reranking model (RECOMMENDED - working now)
+     *
+     * This is a workaround that uses embedding similarity for reranking
+     * since Ollama doesn't have native reranking support yet.
+     *
+     * @param modelId - The embedding model to use (e.g., 'bge-m3', 'nomic-embed-text')
+     * @param settings - Optional settings for the reranking model
+     *
+     * @example
+     * ```ts
+     * const result = await rerank({
+     *   model: ollama.embeddingReranking('bge-m3'),
+     *   query: 'What is machine learning?',
+     *   documents: [...],
+     *   topN: 3,
+     * });
+     * ```
+     */
+    embeddingReranking(modelId: string, settings?: OllamaEmbeddingRerankingSettings): RerankingModelV3;
+    /**
+     * Ollama-specific tools that leverage web search capabilities
+     */
+    tools: {
+        webSearch: (options?: WebSearchToolOptions) => ReturnType<typeof ollamaTools.webSearch>;
+        webFetch: (options?: WebFetchToolOptions) => ReturnType<typeof ollamaTools.webFetch>;
+    };
+}
+interface OllamaChatSettings extends Pick<ChatRequest, 'keep_alive' | 'format' | 'tools' | 'think'> {
+    /**
+     * Additional model parameters - uses extended Options type that includes min_p
+     * This automatically includes ALL Ollama parameters including new ones like 'dimensions'
+     */
+    options?: Partial<Options>;
+    /**
+     * Enable structured output mode
+     */
+    structuredOutputs?: boolean;
+    /**
+     * Enable reliable tool calling with retry and completion mechanisms.
+     * Defaults to true whenever function tools are provided; set to false to opt out.
+     */
+    reliableToolCalling?: boolean;
+    /**
+     * Tool calling reliability options. These override the sensible defaults used by the
+     * built-in reliability layer (maxRetries=2, forceCompletion=true,
+     * normalizeParameters=true, validateResults=true).
+     */
+    toolCallingOptions?: {
+        /**
+         * Maximum number of retry attempts for tool calls
+         */
+        maxRetries?: number;
+        /**
+         * Whether to force completion when tool calls succeed but no final text is generated
+         */
+        forceCompletion?: boolean;
+        /**
+         * Whether to normalize parameter names to handle inconsistencies
+         */
+        normalizeParameters?: boolean;
+        /**
+         * Whether to validate tool results and attempt recovery
+         */
+        validateResults?: boolean;
+        /**
+         * Custom parameter normalization mappings
+         */
+        parameterMappings?: Record<string, string[]>;
+        /**
+         * Timeout for tool execution in milliseconds
+         */
+        toolTimeout?: number;
+    };
+    /**
+     * Enable reliable object generation with retry and repair mechanisms.
+     * Defaults to true whenever JSON schemas are used; set to false to opt out.
+     */
+    reliableObjectGeneration?: boolean;
+    /**
+     * Object generation reliability options. These override the sensible defaults used by the
+     * built-in reliability layer (maxRetries=3, attemptRecovery=true, useFallbacks=true,
+     * fixTypeMismatches=true, enableTextRepair=true).
+     */
+    objectGenerationOptions?: ObjectGenerationOptions;
+}
+/**
+ * Settings for configuring Ollama embedding models.
+ * Uses Pick from EmbedRequest for type consistency with the Ollama API.
+ */
+interface OllamaEmbeddingSettings extends Pick<EmbedRequest, 'dimensions'> {
+    /**
+     * Additional embedding parameters (temperature, num_ctx, etc.)
+     */
+    options?: Partial<Options>;
+}
+/**
+ * Options for configuring Ollama provider calls
+ */
+interface OllamaProviderOptions {
+    /**
+     * Additional headers to include in requests
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Options for configuring Ollama chat model calls
+ */
+interface OllamaChatProviderOptions extends OllamaProviderOptions {
+    /**
+     * Enable structured output mode for object generation
+     */
+    structuredOutputs?: boolean;
+}
+/**
+ * Options for configuring Ollama embedding model calls
+ */
+interface OllamaEmbeddingProviderOptions extends OllamaProviderOptions {
+    /**
+     * Maximum number of embeddings to process in a single call
+     */
+    maxEmbeddingsPerCall?: number;
+}
+
+/**
+ * Create an Ollama provider instance for browser environments
+ */
+declare function createOllama(options?: OllamaProviderSettings): OllamaProvider;
+/**
+ * Default Ollama provider instance for browser environments
+ */
+declare const ollama: OllamaProvider;
+
+interface OllamaErrorData {
+    message: string;
+    code?: string;
+    details?: unknown;
+}
+declare class OllamaError extends Error {
+    readonly cause?: unknown;
+    readonly data?: OllamaErrorData;
+    constructor({ message, cause, data, }: {
+        message: string;
+        cause?: unknown;
+        data?: OllamaErrorData;
+    });
+    static isOllamaError(error: unknown): error is OllamaError;
+}
+
+/**
+ * Calculate cosine similarity between two vectors.
+ *
+ * Cosine similarity measures the angle between two vectors in multi-dimensional space,
+ * returning a value between -1 and 1 where:
+ * - 1 means identical direction (most similar)
+ * - 0 means orthogonal (unrelated)
+ * - -1 means opposite direction (least similar)
+ *
+ * For normalized embedding vectors, this is equivalent to the dot product.
+ *
+ * @param a First vector
+ * @param b Second vector
+ * @returns Cosine similarity score between -1 and 1
+ * @throws Error if vectors have different dimensions
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+
+/**
+ * Tool Calling Reliability Utilities for Ollama
+ *
+ * This module provides utilities to make Ollama tool calling more reliable
+ * and deterministic. It addresses common issues like:
+ * - Empty final text responses after tool execution
+ * - Inconsistent parameter names
+ * - Incomplete agent loops
+ * - Tool result validation and recovery
+ */
+
+interface ToolCallingOptions {
+    /**
+     * Maximum number of retry attempts for tool calls
+     */
+    maxRetries?: number;
+    /**
+     * Whether to force completion when tool calls succeed but no final text is generated
+     */
+    forceCompletion?: boolean;
+    /**
+     * Whether to normalize parameter names to handle inconsistencies
+     */
+    normalizeParameters?: boolean;
+    /**
+     * Whether to validate tool results and attempt recovery
+     */
+    validateResults?: boolean;
+    /**
+     * Custom parameter normalization mappings
+     */
+    parameterMappings?: Record<string, string[]>;
+    /**
+     * Timeout for tool execution in milliseconds
+     */
+    toolTimeout?: number;
+}
+interface ResolvedToolCallingOptions extends Omit<ToolCallingOptions, 'maxRetries' | 'forceCompletion' | 'normalizeParameters' | 'validateResults'> {
+    maxRetries: number;
+    forceCompletion: boolean;
+    normalizeParameters: boolean;
+    validateResults: boolean;
+}
+interface ToolCallResult {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+    normalizedInput?: Record<string, unknown>;
+}
+interface ReliableToolCallResult {
+    text: string;
+    toolCalls: Array<{
+        toolName: string;
+        input: Record<string, unknown>;
+    }>;
+    toolResults?: Array<{
+        toolName: string;
+        input: Record<string, unknown>;
+        normalizedInput?: Record<string, unknown>;
+        result: unknown;
+        success: boolean;
+        error?: string;
+    }>;
+    completionMethod: 'natural' | 'forced' | 'incomplete';
+    retryCount: number;
+    errors?: string[];
+}
+interface ToolDefinition {
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+/**
+ * generateText - Enhanced generateText with Ollama-specific reliability
+ *
+ * This wrapper provides response synthesis and enhanced tool calling reliability
+ * that addresses the core Ollama limitation: tools execute but no final text is generated.
+ */
+
+/**
+ * Enhanced options for Ollama-specific reliability features
+ */
+interface EnhancedOptions {
+    /**
+     * Enable response synthesis when tools are called but no text is generated
+     * @default true
+     */
+    enableSynthesis?: boolean;
+    /**
+     * Custom synthesis prompt template
+     */
+    synthesisPrompt?: string;
+    /**
+     * Maximum attempts for synthesis
+     * @default 2
+     */
+    maxSynthesisAttempts?: number;
+    /**
+     * Minimum response length to consider valid
+     * @default 10
+     */
+    minResponseLength?: number;
+    /**
+     * EXPERIMENTAL: Enable tool calling with structured output (experimental_output)
+     *
+     * The official AI SDK doesn't support combining toolChoice: 'required' with experimental_output.
+     * When enabled, this uses a two-phase approach:
+     * 1. Execute tools first (without experimental_output)
+     * 2. Generate structured output with tool results injected as context
+     *
+     * This is NOT standard AI SDK behavior - only enable if you need both features together.
+     *
+     * @default false
+     */
+    enableToolsWithStructuredOutput?: boolean;
+}
+/**
+ * Enhanced generateText options that extend the official AI SDK options
+ */
+type GenerateTextOptions = Parameters<typeof generateText$1>[0] & {
+    /**
+     * Enhanced options for Ollama-specific reliability features
+     */
+    enhancedOptions?: EnhancedOptions;
+};
+/**
+ * Enhanced generateText function with Ollama-specific reliability improvements
+ *
+ * This function applies synthesis by default when tools execute but return empty responses.
+ * The enhancement preserves the original response prototype and all methods/getters.
+ *
+ * Type parameters are inferred from the options, preserving AI SDK's type inference.
+ */
+declare function generateText(options: GenerateTextOptions): Promise<Awaited<ReturnType<typeof generateText$1>>>;
+
+/**
+ * streamText - Enhanced streamText with Ollama-specific reliability
+ *
+ * This wrapper provides streaming tool calling reliability by detecting
+ * when tools execute but no text is streamed, then providing synthesis.
+ *
+ * Enhances both `textStream` and `fullStream` with synthesis support.
+ */
+
+type AIStreamTextOptions = Parameters<typeof streamText$1>[0];
+/**
+ * Enhanced streamText options that extend the official AI SDK options
+ * This ensures 100% compatibility - all AI SDK properties are supported
+ */
+type StreamTextOptions = AIStreamTextOptions & {
+    /**
+     * Enhanced options for Ollama-specific reliability features
+     */
+    enhancedOptions?: {
+        /**
+         * Enable enhanced tool calling logging
+         * @default true
+         */
+        enableToolLogging?: boolean;
+        /**
+         * Enable streaming synthesis when tools execute but no text streams
+         * @default true
+         */
+        enableStreamingSynthesis?: boolean;
+        /**
+         * Minimum streamed characters before considering it successful
+         * @default 10
+         */
+        minStreamLength?: number;
+        /**
+         * Timeout in ms to wait for streaming before applying synthesis
+         * @default 3000
+         */
+        synthesisTimeout?: number;
+    };
+};
+/**
+ * Enhanced streamText function with Ollama-specific reliability improvements
+ * Enhances both textStream and fullStream with synthesis support
+ */
+declare function streamText(options: StreamTextOptions): Promise<Awaited<ReturnType<typeof streamText$1>>>;
+
+export { type GenerateTextOptions, type ObjectGenerationOptions, type OllamaChatProviderOptions, type OllamaChatSettings, type OllamaEmbeddingProviderOptions, type OllamaEmbeddingSettings, OllamaError, type OllamaErrorData, type OllamaProvider, type OllamaProviderOptions, type OllamaProviderSettings, OllamaRerankingModel, type OllamaRerankingProviderOptions, type OllamaRerankingSettings, type ReliableToolCallResult, type ResolvedToolCallingOptions, type StreamTextOptions, type ToolCallResult, type ToolCallingOptions, type ToolDefinition, cosineSimilarity, createOllama, generateText, ollama, streamText };