ai-sdk-ollama 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-08-06
+
+### Added
+
+- 🎉 Initial release of AI SDK Ollama Provider
+- ✅ Full support for Vercel AI SDK v5 (`LanguageModelV2` and `EmbeddingModelV2`)
+- 🤖 **Chat Language Model** with streaming support
+  - Text generation with **dual parameter support** (AI SDK standard + native Ollama)
+  - **Cross provider compatibility** via AI SDK parameters (temperature, maxOutputTokens, etc.)
+  - **Advanced Ollama features** via native options (mirostat, num_ctx, etc.)
+  - **Parameter precedence system** - Ollama options override AI SDK parameters
+  - Structured output support (JSON objects)
+  - Tool calling capabilities
+  - Image input support (with compatible models)
+- 🔍 **Embedding Model** for text embeddings
+  - Batch embedding support (up to 2048 texts)
+  - Support for all Ollama embedding models
+- 🧠 **Model Intelligence System**
+  - Comprehensive model capability database
+  - Smart model suggestions based on requirements
+  - Automatic feature detection and validation
+  - Helpful error messages with actionable recommendations
+- 🛠️ **Provider Features**
+  - Official `ollama` package integration with **direct option pass-through**
+  - **Future proof**: All current and future Ollama parameters supported automatically
+  - Custom base URL configuration
+  - Custom headers support
+  - Custom fetch implementation
+  - Comprehensive error handling with custom OllamaError class
+- 📦 **Modern Package**
+  - TypeScript with full type safety
+  - ES modules with CommonJS compatibility
+  - Node.js 22+ support
+  - Clean, organized codebase structure
+- 🧪 **Quality Assurance**
+  - Tests (unit + integration)
+  - Full TypeScript coverage
+  - Linting with ESLint + Prettier
+  - Automated testing with Vitest
+- 📚 **Examples & Documentation**
+  - 8 comprehensive examples covering all features
+  - Basic chat, streaming, tool calling, embeddings
+  - Dual parameter demonstrations
+  - Model capabilities and validation examples
+  - Comprehensive README with AI SDK v5+ compatibility
+- 🖼️ **Image Processing Support**: Complete implementation of AI SDK v5 image handling with Ollama
+  - Support for image URLs, base64 encoded images, and multiple images
+  - Full integration with vision models like LLaVA and bakllava
+  - Streaming support with images
+  - Mixed content types (text + image + text)
+
+### Technical Details
+
+- Built with AI SDK v5 (`@ai-sdk/provider: ^2.0.0`)
+- Uses official Ollama client (`ollama: ^0.5.16`)
+- Requires Node.js >=22
+- Fully typed with TypeScript 5.9+
+- ES module first with CJS fallback
+
+### Supported Models
+
+- **Chat Models**: llama3.2, llama3.1, mistral, phi4-mini, qwen2.5, codellama, and all Ollama chat models
+- **Vision Models**: llava, bakllava, llama3.2-vision, minicpm-v
+- **Embedding Models**: nomic-embed-text, all-minilm, mxbai-embed-large, and all Ollama embedding models
+
+[0.1.0]: https://github.com/jagreehal/ai-sdk-ollama/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Jag Reehal 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# AI SDK Ollama Provider
+
+[![npm version](https://badge.fury.io/js/ai-sdk-ollama.svg)](https://badge.fury.io/js/ai-sdk-ollama)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Vercel AI SDK v5+ provider for Ollama built on the official `ollama` package. Type safe, future proof, with cross provider compatibility and native Ollama features.
+
+## Contents
+
+- [AI SDK Ollama Provider](#ai-sdk-ollama-provider)
+  - [Contents](#contents)
+  - [Prerequisites](#prerequisites)
+  - [Quick Start](#quick-start)
+    - [Installation](#installation)
+    - [Basic Usage](#basic-usage)
+  - [Key Features](#key-features)
+    - [Cross Provider Compatibility](#cross-provider-compatibility)
+    - [Native Ollama Power](#native-ollama-power)
+    - [Tool Calling Support](#tool-calling-support)
+    - [Smart Model Intelligence](#smart-model-intelligence)
+  - [Advanced Features](#advanced-features)
+    - [Custom Ollama Instance](#custom-ollama-instance)
+    - [Structured Output](#structured-output)
+  - [Common Issues](#common-issues)
+  - [Supported Models](#supported-models)
+  - [Learn More](#learn-more)
+  - [License](#license)
+
+```typescript
+import { ollama } from 'ai-sdk-ollama';
+import { generateText } from 'ai';
+
+// Standard AI SDK parameters work everywhere
+const { text } = await generateText({
+  model: ollama('llama3.2'),
+  prompt: 'Write a haiku about coding',
+  temperature: 0.8,
+  maxOutputTokens: 100,
+});
+
+// Plus access to Ollama's advanced features
+const { text: advancedText } = await generateText({
+  model: ollama('llama3.2', {
+    options: {
+      mirostat: 2, // Advanced sampling algorithm
+      repeat_penalty: 1.1, // Fine-tune repetition
+      num_ctx: 8192, // Larger context window
+    },
+  }),
+  prompt: 'Write a haiku about coding',
+  temperature: 0.8, // Standard parameters still work
+});
+```
+
+## Prerequisites
+
+- Node.js 22+
+- [Ollama](https://ollama.com) installed locally or running on a remote server
+- AI SDK v5+ (`ai` package)
+- TypeScript 5.9+ (for TypeScript users)
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install ai-sdk-ollama ai@^5.0.0
+```
+
+Ensure you have Ollama running locally:
+
+```bash
+# Install Ollama from ollama.com
+ollama serve
+
+# Pull a model
+ollama pull llama3.2
+```
+
+### Basic Usage
+
+```typescript
+import { ollama } from 'ai-sdk-ollama';
+import { generateText, streamText, embed } from 'ai';
+
+// Simple text generation
+const { text } = await generateText({
+  model: ollama('llama3.2'),
+  prompt: 'What is the capital of France?',
+});
+
+console.log(text); // "The capital of France is Paris."
+
+// Streaming responses
+const { textStream } = await streamText({
+  model: ollama('llama3.2'),
+  prompt: 'Tell me a story about a robot',
+});
+
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
+}
+
+// Embeddings
+const { embedding } = await embed({
+  model: ollama.embedding('nomic-embed-text'),
+  value: 'Hello world',
+});
+
+console.log(embedding.length); // 768 dimensions
+```
+
+## Key Features
+
+### Cross Provider Compatibility
+
+Write code that works with any AI SDK provider:
+
+```typescript
+// This exact code works with OpenAI, Anthropic, or Ollama
+const { text } = await generateText({
+  model: ollama('llama3.2'), // or openai('gpt-4') or anthropic('claude-3')
+  prompt: 'Write a haiku',
+  temperature: 0.8,
+  maxOutputTokens: 100,
+  topP: 0.9,
+});
+```
+
+### Native Ollama Power
+
+Access Ollama's advanced features without losing portability:
+
+```typescript
+const { text } = await generateText({
+  model: ollama('llama3.2', {
+    options: {
+      mirostat: 2, // Advanced sampling algorithm
+      repeat_penalty: 1.1, // Repetition control
+      num_ctx: 8192, // Context window size
+    },
+  }),
+  prompt: 'Write a haiku',
+  temperature: 0.8, // Standard parameters still work
+});
+```
+
+> **Parameter Precedence**: When both AI SDK parameters and Ollama options are specified, **Ollama options take precedence**. For example, if you set `temperature: 0.5` in Ollama options and `temperature: 0.8` in the `generateText` call, the final value will be `0.5`. This allows you to use standard AI SDK parameters for portability while having fine-grained control with Ollama-specific options when needed.
+
+### Tool Calling Support
+
+Ollama supports tool calling with compatible models:
+
+```typescript
+import { z } from 'zod';
+
+const { text, toolCalls } = await generateText({
+  model: ollama('llama3.2'),
+  prompt: 'What is the weather in San Francisco?',
+  tools: {
+    getWeather: {
+      description: 'Get current weather for a location',
+      parameters: z.object({
+        location: z.string().describe('City name'),
+        unit: z.enum(['celsius', 'fahrenheit']).optional(),
+      }),
+      execute: async ({ location, unit = 'celsius' }) => {
+        // Your actual weather API call here
+        return { temp: 18, unit, condition: 'sunny' };
+      },
+    },
+  },
+});
+```
+
+### Smart Model Intelligence
+
+The provider automatically detects model capabilities and provides helpful suggestions:
+
+```typescript
+// The provider will automatically warn you if a model doesn't support tools
+const { text } = await generateText({
+  model: ollama('llama3'), // Older model without tool support
+  prompt: 'What is the weather?',
+  tools: {
+    /* ... */
+  }, // This will throw a helpful error with suggestions
+});
+
+// Get model recommendations for specific features
+import { suggestModelsForFeatures } from 'ai-sdk-ollama';
+
+const suggestions = suggestModelsForFeatures({
+  toolCalling: true,
+  performance: 'fast',
+});
+// Returns: [{ modelId: 'llama3.2', reason: 'Excellent tool calling...' }]
+```
+
+## Advanced Features
+
+### Custom Ollama Instance
+
+```typescript
+import { createOllama } from 'ai-sdk-ollama';
+
+const ollama = createOllama({
+  baseURL: 'http://my-ollama-server:11434',
+  headers: {
+    'Custom-Header': 'value',
+  },
+});
+
+const { text } = await generateText({
+  model: ollama('llama3.2'),
+  prompt: 'Hello!',
+});
+```
+
+### Structured Output
+
+```typescript
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const { object } = await generateObject({
+  model: ollama('llama3.2', { structuredOutputs: true }),
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+    interests: z.array(z.string()),
+  }),
+  prompt: 'Generate a random person profile',
+});
+
+console.log(object);
+// { name: "Alice", age: 28, interests: ["reading", "hiking"] }
+```
+
+## Common Issues
+
+- **Make sure Ollama is running** - Run `ollama serve` before using the provider
+- **Pull models first** - Use `ollama pull model-name` before generating text
+- **Model compatibility errors** - The provider will throw errors if you try to use unsupported features (e.g., tools with non-compatible models)
+- **Network issues** - Verify Ollama is accessible at the configured URL
+- **TypeScript support** - Full type safety with TypeScript 5.9+
+- **AI SDK v5+ compatibility** - Built for the latest AI SDK specification
+
+## Supported Models
+
+Works with any model in your Ollama installation:
+
+- **Chat**: `llama3.2`, `llama3.1`, `mistral`, `phi4-mini`, `qwen2.5`, `codellama`
+- **Vision**: `llava`, `bakllava`, `llama3.2-vision`, `minicpm-v`
+- **Embeddings**: `nomic-embed-text`, `all-minilm`, `mxbai-embed-large`
+
+## Learn More
+
+📚 **[Examples Directory](./examples/)** - Comprehensive usage patterns with real working code
+
+🚀 **[Quick Start Guide](./examples/basic-chat.ts)** - Get running in 2 minutes
+
+⚙️ **[Dual Parameters Demo](./examples/dual-parameter-example.ts)** - See the key feature in action
+
+🔧 **[Tool Calling Guide](./examples/tool-calling-example.ts)** - Function calling with Ollama
+
+🖼️ **[Image Processing Guide](./examples/image-handling-example.ts)** - Vision models with LLaVA
+
+📡 **[Streaming Examples](./examples/streaming-simple-test.ts)** - Real-time responses
+
+## License
+
+MIT © [Jag Reehal](https://jagreehal.com)
+
+See [LICENSE](./LICENSE) for details.