ai-sdk-ollama 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- **Auto-Structured Outputs**: Enhanced structured outputs with intelligent auto-detection
+  - 🎯 **Smart Auto-Detection**: Automatically enables structured outputs when JSON schema is provided
+  - 🔧 **Backward Compatibility**: Explicit `structuredOutputs: true/false` settings are still respected
+  - ⚠️ **User-Friendly Warnings**: Clear warnings when auto-enabling structured outputs
+  - 📚 **Enhanced Documentation**: Updated examples and README with auto-detection guidance
+  - 🧪 **Comprehensive Testing**: Added integration tests for auto-detection scenarios
+  - 🛠️ **Improved Developer Experience**: No need to manually set `structuredOutputs: true` for object generation
+
+### Technical Improvements
+
+- Enhanced `shouldEnableStructuredOutputs()` method for intelligent auto-detection
+- Improved schema validation and error handling
+- Updated README with auto-detection examples and best practices
+- Added comprehensive integration tests for edge cases
+- Streamlined configuration for common use cases
+
+## 0.2.0
+
+### Minor Changes
+
+- bf0905a: Fix streaming examples and improve TypeScript type checking
+  - Fix "Stream error: text part not found" by using textStream instead of fullStream for basic streaming
+  - Fix TypeScript errors in all examples (error handling, index access, undefined checks)
+  - Remove rootDir restriction in tsconfig.json to enable type checking for examples
+  - Fix tool call parameter handling and error messages
+  - Remove deprecated model capabilities and suggestions utilities
+  - Improve error handling with proper type checking throughout examples
+  - Update streaming examples to work with AI SDK v5 API changes
+
 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/),
@@ -66,7 +99,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Supported Models
 
-- **Chat Models**: llama3.2, llama3.1, mistral, phi4-mini, qwen2.5, codellama, and all Ollama chat models
+- **Chat Models**: llama3.2, 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
 

package/README.md

@@ -19,12 +19,14 @@ A Vercel AI SDK v5+ provider for Ollama built on the official `ollama` package.
     - [Cross Provider Compatibility](#cross-provider-compatibility)
     - [Native Ollama Power](#native-ollama-power)
     - [Tool Calling Support](#tool-calling-support)
-    - [Smart Model Intelligence](#smart-model-intelligence)
+    - [Simple and Predictable](#simple-and-predictable)
   - [Advanced Features](#advanced-features)
     - [Custom Ollama Instance](#custom-ollama-instance)
     - [Structured Output](#structured-output)
+    - [Auto-Detection of Structured Outputs](#auto-detection-of-structured-outputs)
   - [Common Issues](#common-issues)
   - [Supported Models](#supported-models)
+  - [Testing](#testing)
   - [Learn More](#learn-more)
   - [License](#license)
 
@@ -151,7 +153,7 @@ const { text } = await generateText({
 
 ### Tool Calling Support
 
-Ollama supports tool calling with compatible models:
+Ollama supports tool calling with compatible models.
 
 ```typescript
 import { z } from 'zod';
@@ -162,7 +164,7 @@ const { text, toolCalls } = await generateText({
   tools: {
     getWeather: {
       description: 'Get current weather for a location',
-      parameters: z.object({
+      inputSchema: z.object({
         location: z.string().describe('City name'),
         unit: z.enum(['celsius', 'fahrenheit']).optional(),
       }),
@@ -175,28 +177,26 @@ const { text, toolCalls } = await generateText({
 });
 ```
 
-### Smart Model Intelligence
+> **Note on Tool Parameters**: Due to Zod version compatibility issues, tool schemas may not always convert properly. When this happens, Ollama may use different parameter names than defined in your schema. It's recommended to handle parameter variations in your tool's execute function (e.g., checking for both `location` and `city`).
 
-The provider automatically detects model capabilities and provides helpful suggestions:
+### Simple and Predictable
+
+The provider works the same way with any model - just try the features you need:
 
 ```typescript
-// The provider will automatically warn you if a model doesn't support tools
+// No capability checking required - just use any model
 const { text } = await generateText({
-  model: ollama('llama3'), // Older model without tool support
+  model: ollama('any-model'),
   prompt: 'What is the weather?',
   tools: {
     /* ... */
-  }, // This will throw a helpful error with suggestions
+  }, // If the model doesn't support tools, you'll get a clear error
 });
 
-// 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...' }]
+// The provider is simple and predictable
+// - Try any feature with any model
+// - Get clear error messages if something doesn't work
+// - No hidden complexity or capability detection
 ```
 
 ## Advanced Features
@@ -225,8 +225,9 @@ const { text } = await generateText({
 import { generateObject } from 'ai';
 import { z } from 'zod';
 
+// Auto-detection: structuredOutputs is automatically enabled for object generation
 const { object } = await generateObject({
-  model: ollama('llama3.2', { structuredOutputs: true }),
+  model: ollama('llama3.2'), // No need to set structuredOutputs: true
   schema: z.object({
     name: z.string(),
     age: z.number(),
@@ -237,6 +238,40 @@ const { object } = await generateObject({
 
 console.log(object);
 // { name: "Alice", age: 28, interests: ["reading", "hiking"] }
+
+// Explicit setting still works
+const { object: explicitObject } = await generateObject({
+  model: ollama('llama3.2', { structuredOutputs: true }), // Explicit
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+  }),
+  prompt: 'Generate a person',
+});
+```
+
+### Auto-Detection of Structured Outputs
+
+The provider automatically detects when structured outputs are needed:
+
+- **Object Generation**: `generateObject` and `streamObject` automatically enable `structuredOutputs: true`
+- **Text Generation**: `generateText` and `streamText` require explicit `structuredOutputs: true` for JSON output
+- **Backward Compatibility**: Explicit settings are respected, with warnings when overridden
+- **No Breaking Changes**: Existing code continues to work as expected
+
+```typescript
+// This works without explicit structuredOutputs: true
+const { object } = await generateObject({
+  model: ollama('llama3.2'),
+  schema: z.object({ name: z.string() }),
+  prompt: 'Generate a name',
+});
+
+// This still requires explicit setting for JSON output
+const { text } = await generateText({
+  model: ollama('llama3.2', { structuredOutputs: true }),
+  prompt: 'Generate JSON with a message field',
+});
 ```
 
 ## Common Issues
@@ -252,10 +287,29 @@ console.log(object);
 
 Works with any model in your Ollama installation:
 
-- **Chat**: `llama3.2`, `llama3.1`, `mistral`, `phi4-mini`, `qwen2.5`, `codellama`
+- **Chat**: `llama3.2`, `mistral`, `phi4-mini`, `qwen2.5`, `codellama`
 - **Vision**: `llava`, `bakllava`, `llama3.2-vision`, `minicpm-v`
 - **Embeddings**: `nomic-embed-text`, `all-minilm`, `mxbai-embed-large`
 
+## Testing
+
+The project includes unit and integration tests:
+
+```bash
+# Run unit tests only (fast, no external dependencies)
+npm test
+
+# Run all tests (unit + integration)
+npm run test:all
+
+# Run integration tests only (requires Ollama running)
+npm run test:integration
+```
+
+> **Note**: Integration tests may occasionally fail due to the non-deterministic nature of AI model outputs. This is expected behavior - the tests use loose assertions to account for LLM output variability. Some tests may also skip if required models aren't available locally.
+
+For detailed testing information, see [Integration Tests Documentation](./src/integration-tests/README.md).
+
 ## Learn More
 
 📚 **[Examples Directory](./examples/)** - Comprehensive usage patterns with real working code

package/dist/compatibility.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=compatibility.test.d.ts.map

package/dist/compatibility.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.test.d.ts","sourceRoot":"","sources":["../src/compatibility.test.ts"],"names":[],"mappings":""}

package/dist/compatibility.test.js

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import { ollama } from './index';
+describe('OpenAI API Compatibility', () => {
+    describe('Provider Interface Compatibility', () => {
+        it('should implement standard provider pattern like OpenAI provider', () => {
+            // Test that our provider follows the same pattern as Vercel's OpenAI provider
+            expect(typeof ollama).toBe('function');
+            expect(typeof ollama.chat).toBe('function');
+            expect(typeof ollama.languageModel).toBe('function');
+            expect(typeof ollama.embedding).toBe('function');
+            expect(typeof ollama.textEmbedding).toBe('function');
+            expect(typeof ollama.textEmbeddingModel).toBe('function');
+        });
+        it('should create LanguageModelV2 compatible models', () => {
+            const model = ollama('llama3.2');
+            // Test LanguageModelV2 interface compliance
+            expect(model.specificationVersion).toBe('v2');
+            expect(typeof model.modelId).toBe('string');
+            expect(typeof model.provider).toBe('string');
+            expect(typeof model.doGenerate).toBe('function');
+            expect(typeof model.doStream).toBe('function');
+            // Test that model has expected properties (interface may have changed)
+            expect(typeof model.supportedUrls).toBe('object');
+        });
+        it('should create EmbeddingModelV2 compatible models', () => {
+            const model = ollama.embedding('nomic-embed-text');
+            // Test EmbeddingModelV2 interface compliance
+            expect(model.specificationVersion).toBe('v2');
+            expect(typeof model.modelId).toBe('string');
+            expect(typeof model.provider).toBe('string');
+            expect(typeof model.doEmbed).toBe('function');
+            // Test standard properties
+            expect(typeof model.maxEmbeddingsPerCall).toBe('number');
+            expect(typeof model.supportsParallelCalls).toBe('boolean');
+        });
+    });
+    describe('AI SDK Integration Compatibility', () => {
+        it('should work with generateText like OpenAI provider', () => {
+            const model = ollama('llama3.2');
+            // Test that model can be used with AI SDK functions
+            expect(typeof model.doGenerate).toBe('function');
+            expect(model.doGenerate.length).toBe(1); // Takes one parameter (options)
+        });
+        it('should work with streamText like OpenAI provider', () => {
+            const model = ollama('llama3.2');
+            expect(typeof model.doStream).toBe('function');
+            expect(model.doStream.length).toBe(1); // Takes one parameter (options)
+        });
+        it('should work with embed like OpenAI provider', () => {
+            const model = ollama.embedding('nomic-embed-text');
+            expect(() => {
+                // Test embedding interface compatibility
+                expect(typeof model.doEmbed).toBe('function');
+                expect(model.doEmbed.length).toBe(1); // Takes one parameter (options)
+            }).not.toThrow();
+        });
+    });
+    describe('Response Format Compatibility', () => {
+        it('should support JSON response format like OpenAI', () => {
+            const model = ollama('llama3.2');
+            // Test that our model exists and can be configured
+            expect(model.provider).toBe('ollama');
+            expect(model.modelId).toBe('llama3.2');
+        });
+        it('should support standard parameters like OpenAI', () => {
+            const model = ollama('llama3.2');
+            // Test basic model properties
+            expect(typeof model.doGenerate).toBe('function');
+            expect(typeof model.doStream).toBe('function');
+        });
+    });
+    describe('Error Handling Compatibility', () => {
+        it('should handle errors consistently with OpenAI provider', () => {
+            const model = ollama('llama3.2');
+            // Test that our error handling follows standard patterns
+            expect(model.provider).toBe('ollama');
+            expect(model.modelId).toBe('llama3.2');
+            // Models should have consistent error behavior
+            expect(() => {
+                // Test model creation with invalid parameters
+                ollama(''); // Empty model name
+            }).not.toThrow(); // Should create model, errors happen at runtime
+        });
+    });
+    describe('Provider Settings Compatibility', () => {
+        it('should support provider-specific settings like OpenAI', () => {
+            // Test custom settings similar to how OpenAI provider works
+            const modelWithSettings = ollama('llama3.2', {
+                options: {
+                    temperature: 0.8,
+                    num_ctx: 4096,
+                    top_k: 50,
+                },
+            });
+            expect(modelWithSettings.modelId).toBe('llama3.2');
+            expect(modelWithSettings.provider).toBe('ollama');
+        });
+        it('should support structured outputs setting', () => {
+            const modelWithStructuredOutputs = ollama('llama3.2', {
+                structuredOutputs: true,
+            });
+            expect(modelWithStructuredOutputs.provider).toBe('ollama');
+        });
+    });
+    describe('Embedding Model Compatibility', () => {
+        it('should handle embeddings consistently with OpenAI', () => {
+            const embeddingModel = ollama.embedding('nomic-embed-text');
+            expect(embeddingModel.modelId).toBe('nomic-embed-text');
+            expect(embeddingModel.provider).toBe('ollama');
+            expect(embeddingModel.specificationVersion).toBe('v2');
+            expect(typeof embeddingModel.maxEmbeddingsPerCall).toBe('number');
+            expect(embeddingModel.maxEmbeddingsPerCall).toBeGreaterThan(0);
+        });
+        it('should support embedding settings', () => {
+            const embeddingModel = ollama.embedding('nomic-embed-text', {
+                options: {
+                    num_thread: 8,
+                },
+            });
+            expect(embeddingModel.provider).toBe('ollama');
+        });
+    });
+});