ai-sdk-ollama 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 0.8.1
+
+### Patch Changes
+
+- e57ddf2: ## Enhanced Function Renaming & Documentation Improvements
+
+  ### Function Renaming
+  - Renamed `generateTextOllama` to `generateText` (enhanced version from ai-sdk-ollama)
+  - Renamed `streamTextOllama` to `streamText` (enhanced version from ai-sdk-ollama)
+  - Maintains backward compatibility while providing clearer API
+
+  ### Documentation Improvements
+  - **README.md**: Complete restructure with better user flow
+    - Added Quick Start section with immediate installation and basic example
+    - Moved value proposition ("Why Choose") section earlier
+    - Added dedicated "Enhanced Tool Calling" section highlighting main differentiator
+    - Reorganized examples under "More Examples" for better progression
+    - Removed redundant content and improved clarity
+  - **packages/ai-sdk-ollama/README.md**: Applied same improvements
+    - Consistent structure with main README
+    - Better user journey from basic to advanced features
+    - Updated table of contents to match new structure
+
+  ### Key Benefits
+  - **Better Developer Experience**: Clearer function names and improved documentation flow
+  - **Enhanced Tool Calling**: Highlighted the main selling point with dedicated section
+  - **User-Friendly**: Users can now get started in 30 seconds and understand value immediately
+  - **Consistent**: Both READMEs now have the same improved structure and flow
+
+## 0.8.0
+
+### Minor Changes
+
+- 7ce6ed0: Enhanced tool calling with reliable wrapper functions
+
+  ## What's New
+  - **New Enhanced Wrapper Functions**: Added `generateTextOllama()` and `streamTextOllama()` for guaranteed tool calling reliability
+  - **Automatic Response Synthesis**: Enhanced functions automatically complete responses when tools are executed but return empty text
+  - **Configurable Reliability Options**: Control synthesis behavior with `enhancedOptions` parameter
+  - **Improved Documentation**: Comprehensive examples and comparison tables for standard vs enhanced functions
+
+  ## Key Features
+  - **Reliable Tool Calling**: Standard `generateText()` may return empty responses after tool execution. Enhanced wrappers guarantee complete, useful responses every time
+  - **Backward Compatible**: All existing code continues to work unchanged
+  - **Production Ready**: Designed for critical applications that can't handle unpredictable empty responses
+  - **Cross Provider Compatible**: Enhanced functions work with any AI SDK provider
+
+  ## Breaking Changes
+
+  None - this is a purely additive enhancement.
+
+  ## Migration
+
+  No migration required. Existing code works unchanged. To get enhanced reliability:
+
+  ```typescript
+  // Before (may return empty text after tool calls)
+  const { text } = await generateText({
+    model: ollama('llama3.2'),
+    tools,
+    prompt,
+  });
+
+  // After (guaranteed complete responses)
+  const { text } = await generateTextOllama({
+    model: ollama('llama3.2'),
+    tools,
+    prompt,
+  });
+  ```
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -7,29 +7,75 @@
 
 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.
 
-> **Two Ways to Use**: This library enhances the standard AI SDK functions with automatic reliability improvements when you pass tools or schemas. For maximum reliability, use these drop-in replacements written specifically for Ollama:
->
-> - `generateText` → `generateTextOllama`
-> - `generateObject` → `generateObjectOllama`
-> - `streamText` → `streamTextOllama`
-> - `streamObject` → `streamObjectOllama`
+## Quick Start
+
+```bash
+npm install ai-sdk-ollama ai@^5.0.0
+```
+
+```typescript
+import { ollama } from 'ai-sdk-ollama';
+import { generateText } from 'ai';
+
+// Works in both Node.js and browsers
+const { text } = await generateText({
+  model: ollama('llama3.2'),
+  prompt: 'Write a haiku about coding',
+  temperature: 0.8,
+});
+
+console.log(text);
+```
+
+## Why Choose AI SDK Ollama?
+
+- ✅ **Solves tool calling problems** - Response synthesis for reliable tool execution
+- ✅ **Enhanced wrapper functions** - `generateText` and `streamText` guarantees complete responses
+- ✅ **Built-in reliability** - Default reliability features enabled automatically
+- ✅ **Cross-provider compatibility** - Drop-in replacement for OpenAI, Anthropic, etc.
+- ✅ **Type-safe** - Full TypeScript support with strict typing
+- ✅ **Cross-environment** - Works in Node.js and browsers automatically
+- ✅ **Native Ollama power** - Access advanced features like `mirostat`, `repeat_penalty`, `num_ctx`
+- ✅ **Production ready** - Handles the core Ollama limitations other providers struggle with
+
+## Enhanced Tool Calling
+
+> **🚀 The Problem We Solve**: Standard Ollama providers often execute tools but return empty responses. Our enhanced functions guarantee complete, useful responses every time.
+
+```typescript
+import { generateText, streamText } from 'ai-sdk-ollama';
+
+// ✅ Enhanced generateText - guaranteed complete responses
+const { text } = await generateText({
+  model: ollama('llama3.2'),
+  tools: { /* your tools */ },
+  prompt: 'Use the tools and explain the results'
+});
+
+// ✅ Enhanced streaming - tool-aware streaming
+const { textStream } = await streamText({
+  model: ollama('llama3.2'),
+  tools: { /* your tools */ },
+  prompt: 'Stream with tools'
+});
+```
 
 ## Contents
 
 - [AI SDK Ollama Provider](#ai-sdk-ollama-provider)
+  - [Quick Start](#quick-start)
+  - [Why Choose AI SDK Ollama?](#why-choose-ai-sdk-ollama)
+  - [Enhanced Tool Calling](#enhanced-tool-calling)
   - [Contents](#contents)
   - [Prerequisites](#prerequisites)
-  - [Quick Start](#quick-start)
-    - [Installation](#installation)
-    - [Basic Usage](#basic-usage)
   - [Browser Support](#browser-support)
     - [Browser Usage](#browser-usage)
     - [Explicit Browser Import](#explicit-browser-import)
     - [CORS Configuration](#cors-configuration)
-  - [Key Features](#key-features)
+  - [More Examples](#more-examples)
     - [Cross Provider Compatibility](#cross-provider-compatibility)
     - [Native Ollama Power](#native-ollama-power)
-    - [Tool Calling Support](#tool-calling-support)
+    - [Enhanced Tool Calling Wrappers](#enhanced-tool-calling-wrappers)
     - [Simple and Predictable](#simple-and-predictable)
   - [Advanced Features](#advanced-features)
     - [Custom Ollama Instance](#custom-ollama-instance)
@@ -76,16 +122,6 @@ const { text: advancedText } = await generateText({
 - 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
@@ -94,39 +130,6 @@ ollama serve
 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
-```
-
 ## Browser Support
 
 See the [browser example](../../examples/browser/).
@@ -173,7 +176,7 @@ OLLAMA_ORIGINS="http://localhost:3000,https://myapp.com" ollama serve
 
 **Recommended**: Use a development proxy (like Vite proxy) to avoid CORS issues entirely. See the browser example for a complete working setup.
 
-## Key Features
+## More Examples
 
 ### Cross Provider Compatibility
 
@@ -210,35 +213,55 @@ const { text } = await generateText({
 
 > **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
+### Enhanced Tool Calling Wrappers
 
-Ollama supports tool calling with compatible models.
+For maximum tool calling reliability, use our enhanced wrapper functions that guarantee complete responses:
 
 ```typescript
+import { ollama, generateText, streamText } from 'ai-sdk-ollama';
+import { tool } from 'ai';
 import { z } from 'zod';
-import { generateText, tool } from 'ai';
-import { ollama } from 'ai-sdk-ollama';
 
-const { text, toolCalls } = await generateText({
+// Enhanced generateText with automatic response synthesis
+const result = await generateText({
   model: ollama('llama3.2'),
-  prompt: 'What is the weather in San Francisco?',
+  prompt: 'What is 15 + 27? Use the math tool to calculate it.',
   tools: {
-    getWeather: tool({
-      description: 'Get current weather for a location',
+    math: tool({
+      description: 'Perform math calculations',
       inputSchema: z.object({
-        location: z.string().describe('City name'),
-        unit: z.enum(['celsius', 'fahrenheit']).optional(),
+        operation: z.string().describe('Math operation like "15 + 27"'),
       }),
-      execute: async ({ location, unit = 'celsius' }) => {
-        // Your actual weather API call here
-        return { temp: 18, unit, condition: 'sunny' };
+      execute: async ({ operation }) => {
+        return { result: eval(operation), operation };
       },
     }),
   },
+  // Optional: Configure reliability behavior
+  enhancedOptions: {
+    enableSynthesis: true, // Default: true
+    maxSynthesisAttempts: 2, // Default: 2
+    minResponseLength: 10, // Default: 10
+  },
 });
+
+console.log(result.text); // "15 + 27 equals 42. Using the math tool, I calculated..."
 ```
 
-> **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`).
+**When to Use Enhanced Wrappers:**
+
+- **Critical tool calling scenarios** where you need guaranteed text responses
+- **Production applications** that can't handle empty responses after tool execution
+- **Complex multi-step tool interactions** requiring reliable synthesis
+
+**Standard vs Enhanced Comparison:**
+
+| Function                   | Standard `generateText`   | Enhanced `generateText`        |
+| -------------------------- | ------------------------- | ------------------------------------ |
+| **Simple prompts**         | ✅ Perfect                | ✅ Works (slight overhead)           |
+| **Tool calling**           | ⚠️ May return empty text  | ✅ **Guarantees complete responses** |
+| **Complete responses**     | ❌ Manual handling needed | ✅ **Automatic completion**          |
+| **Production reliability** | ⚠️ Unpredictable          | ✅ **Reliable**                      |
 
 ### Simple and Predictable