@easbot/ollama-sdk 0.1.0 → 0.1.1

package/README.en.md

@@ -1,17 +1,19 @@
 # @easbot/ollama-sdk
 
-AI SDK v2 compatible Ollama Provider with automatic event stream generation.
+AI SDK v2 compatible Ollama Provider with automatic complete event stream generation.
 
 [中文文档](./README.md) | English
 
 ## Features
 
 - ✅ Full AI SDK v2 compatibility
-- ✅ Automatic generation of missing event stream events
-- ✅ Lightweight wrapper based on `ai-sdk-ollama`
+- ✅ Tool Calling support
+- ✅ Automatic complete event stream generation
+- ✅ Native Ollama implementation with no extra dependencies
 - ✅ TypeScript type support
 - ✅ Streaming and non-streaming generation
 - ✅ Complete error handling
+- ✅ <think> tag reasoning support
 
 ## Installation
 
@@ -24,17 +26,17 @@ pnpm add @easbot/ollama-sdk ai
 ### Basic Usage
 
 ```typescript
-import { createOllama } from '@easbot/ollama-sdk';
+import { NativeOllamaLanguageModel } from '@easbot/ollama-sdk';
 import { streamText } from 'ai';
 
-// Create Ollama provider
-const ollama = createOllama({
+// Create Ollama model
+const model = new NativeOllamaLanguageModel('qwen2.5:0.5b', {
   baseURL: 'http://localhost:11434', // Optional, default value
 });
 
 // Streaming generation
 const result = await streamText({
-  model: ollama('llama2'),
+  model,
   prompt: 'Hello, world!',
 });
 
@@ -43,96 +45,407 @@ for await (const chunk of result.textStream) {
 }
 ```
 
+### Tool Calling
+
+```typescript
+import { NativeOllamaLanguageModel } from '@easbot/ollama-sdk';
+import { generateText } from 'ai';
+
+const model = new NativeOllamaLanguageModel('qwen2.5:0.5b');
+
+// Define tools
+const tools = {
+  read_file: {
+    description: 'Read file content',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'File path',
+        },
+      },
+      required: ['path'],
+    },
+    execute: async ({ path }: { path: string }) => {
+      const fs = await import('fs/promises');
+      return await fs.readFile(path, 'utf-8');
+    },
+  },
+};
+
+// Use tool calling
+const result = await generateText({
+  model,
+  tools,
+  prompt: 'Please read the content of package.json file',
+});
+
+console.log(result.text);
+```
+
 ### Non-Streaming Generation
 
 ```typescript
 import { generateText } from 'ai';
 
+const model = new NativeOllamaLanguageModel('qwen2.5:0.5b');
+
 const result = await generateText({
-  model: ollama('llama2'),
+  model,
   prompt: 'What is the capital of France?',
 });
 
 console.log(result.text);
 ```
 
+## System Requirements
+
+### Ollama Version Requirements
+
+- **Tool Calling Feature**: Requires Ollama 0.1.26 or higher
+- **Basic Text Generation**: Supports all Ollama versions
+
+### Supported Models
+
+Tool calling feature requires models that support tool calling. Recommended:
+
+- `qwen2.5:0.5b` - Lightweight, suitable for development and testing
+- `qwen2.5:7b` - Balanced performance and quality
+- `llama3.1:8b` - High-quality tool calling
+- `mistral:7b` - General-purpose model
+
+Check if a model supports tool calling:
+
+```bash
+ollama show <model-name>
+```
+
+Look for the `tools` field in the model information.
+
 ### Multiple Invocation Methods
 
 ```typescript
-// Method 1: Direct provider call
-const model1 = ollama('llama2');
+// Method 1: Direct model instance creation
+const model1 = new NativeOllamaLanguageModel('qwen2.5:0.5b');
+
+// Method 2: Custom baseURL
+const model2 = new NativeOllamaLanguageModel('qwen2.5:0.5b', {
+  baseURL: 'http://192.168.1.100:11434',
+});
+
+// Method 3: Use different models
+const model3 = new NativeOllamaLanguageModel('llama3.1:8b');
+```
+
+## Tool Calling Details
+
+### Tool Definition Format
+
+Tool definitions follow the AI SDK v2 specification, using the `inputSchema` field:
+
+```typescript
+const tools = {
+  tool_name: {
+    description: 'Tool description',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        param1: {
+          type: 'string',
+          description: 'Parameter description',
+        },
+        param2: {
+          type: 'number',
+          description: 'Number parameter',
+        },
+      },
+      required: ['param1'],
+    },
+    execute: async (args) => {
+      // Tool execution logic
+      return result;
+    },
+  },
+};
+```
+
+### Tool Calling Event Stream
+
+Streaming tool calling generates the following event sequence:
+
+```
+response-metadata
+  ↓
+tool-input-start (tool call starts)
+  ↓
+tool-input-delta (parameter accumulation, multiple times)
+  ↓
+tool-input-end (parameter reception complete)
+  ↓
+tool-call (tool call complete)
+  ↓
+finish (finishReason: 'tool-calls')
+```
+
+### Tool Calling Loop
+
+AI SDK automatically handles tool calling loops:
+
+```typescript
+const result = await generateText({
+  model,
+  tools,
+  prompt: 'Please read package.json and analyze its content',
+  maxSteps: 5, // Maximum 5 rounds of tool calling
+});
+
+// AI SDK will automatically:
+// 1. Call tools
+// 2. Return tool results to the model
+// 3. Continue generation until complete or maxSteps reached
+```
+
+### Tool Calling + Reasoning
+
+Models can use both tool calling and reasoning (<think> tags) simultaneously:
+
+```typescript
+const result = await streamText({
+  model,
+  tools,
+  prompt: 'Analyze this problem and use tools to solve it',
+});
+
+for await (const event of result.fullStream) {
+  switch (event.type) {
+    case 'reasoning-delta':
+      console.log('[Reasoning]', event.delta);
+      break;
+    case 'text-delta':
+      console.log('[Text]', event.delta);
+      break;
+    case 'tool-call':
+      console.log('[Tool Call]', event.toolName, event.input);
+      break;
+  }
+}
+```
+
+## Limitations and Considerations
+
+### Tool Calling Limitations
+
+1. **Model Support**: Not all Ollama models support tool calling, please use supported models
+2. **Parameter Format**: Tool parameters must be valid JSON objects
+3. **Concurrent Calls**: A single response can contain multiple tool calls, but they are executed sequentially
+4. **Parameter Size**: Avoid passing overly large parameters (recommended < 10KB)
+
+### Reasoning Tag Limitations
+
+1. **Tag Format**: Must use `<think>...</think>` format
+2. **Nesting**: Nested think tags are not supported
+3. **Mixed Content**: Can be mixed with regular text and tool calling
+
+### Performance Considerations
+
+1. **Streaming First**: For long text generation, prioritize streaming API
+2. **Tool Count**: Recommended number of tools per request < 20
+3. **Parameter Validation**: Validate parameters before tool execution to avoid invalid calls
+
+## FAQ
+
+### Q: How to check Ollama version?
+
+```bash
+ollama --version
+```
+
+If version is lower than 0.1.26, please upgrade:
+
+```bash
+# macOS/Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows
+# Download the latest version from https://ollama.com/download
+```
+
+### Q: What if tool calling doesn't work?
+
+1. Check if Ollama version is >= 0.1.26
+2. Confirm the model supports tool calling (use `ollama show <model>`)
+3. Check if tool definition format is correct (use `inputSchema` instead of `parameters`)
+4. Check log output for error messages
+
+### Q: How to debug tool calling?
+
+Enable debug logging:
+
+```typescript
+import { Log } from '@easbot/ollama-sdk';
 
-// Method 2: Using languageModel method
-const model2 = ollama.languageModel('mistral');
+// Initialize logging system
+await Log.init({
+  print: true,
+  dev: true,
+  level: 'DEBUG', // Enable DEBUG level logging
+});
 
-// Method 3: Using chat method (alias)
-const model3 = ollama.chat('codellama');
+// Now all tool calling details will be output to console
 ```
 
+### Q: What tool parameter types are supported?
+
+All JSON Schema types are supported:
+
+- `string` - String
+- `number` - Number
+- `boolean` - Boolean
+- `object` - Object
+- `array` - Array
+- `null` - Null
+
+### Q: How to handle tool calling errors?
+
+```typescript
+const tools = {
+  risky_operation: {
+    description: 'Operation that may fail',
+    inputSchema: { /* ... */ },
+    execute: async (args) => {
+      try {
+        // Execute operation
+        return result;
+      } catch (error) {
+        // Return error message to model
+        throw new Error(`Operation failed: ${error.message}`);
+      }
+    },
+  },
+};
+```
+
+### Q: What about backward compatibility?
+
+Fully backward compatible:
+
+- When `tools` parameter is not provided, behavior is exactly the same as before
+- Existing text generation and reasoning features are not affected
+- API signature remains unchanged
+
+## Example Code
+
+For complete usage examples, please refer to:
+
+- [Basic Tool Calling Example](./.easbot/test-ollama-tool-calling.ts)
+- [Multiple Tool Calling Example](./.easbot/test-ollama-tool-calling.ts#example2)
+- [Tool Calling + Reasoning Example](./.easbot/test-ollama-tool-calling.ts#example3)
+- [Error Handling Example](./.easbot/test-ollama-tool-calling.ts#example4)
+- [Tool Calling Loop Example](./.easbot/test-ollama-tool-calling.ts#example5)
+
 ## API Reference
 
-### `createOllama(config?)`
+### `NativeOllamaLanguageModel`
 
-Create an Ollama provider instance.
+Native Ollama language model implementation, fully compatible with AI SDK v2.
+
+**Constructor:**
+
+```typescript
+new NativeOllamaLanguageModel(modelId: string, config?: {
+  baseURL?: string;
+})
+```
 
 **Parameters:**
 
-- `config` (optional): Provider configuration
+- `modelId` (string): Ollama model ID (e.g., 'qwen2.5:0.5b', 'llama3.1:8b')
+- `config` (optional): Model configuration
   - `baseURL` (string): Ollama API base URL, defaults to `'http://localhost:11434'`
-  - `headers` (Record<string, string>): Custom request headers
-  - `fetch` (typeof fetch): Custom fetch implementation
 
-**Returns:**
+**Methods:**
 
-`OllamaProvider` - Callable provider object
+- `doStream(options)`: Streaming generation, returns ReadableStream
+- `doGenerate(options)`: Non-streaming generation, returns complete result
 
 **Example:**
 
 ```typescript
-const ollama = createOllama({
+const model = new NativeOllamaLanguageModel('qwen2.5:0.5b', {
   baseURL: 'http://localhost:11434',
-  headers: {
-    'X-Custom-Header': 'value',
-  },
+});
+
+// Streaming generation
+const streamResult = await model.doStream({
+  prompt: [
+    { role: 'user', content: [{ type: 'text', text: 'Hello' }] }
+  ],
+  tools: [/* ... */],
+});
+
+// Non-streaming generation
+const generateResult = await model.doGenerate({
+  prompt: [
+    { role: 'user', content: [{ type: 'text', text: 'Hello' }] }
+  ],
+  tools: [/* ... */],
 });
 ```
 
-### `OllamaProvider`
+## Event Stream
 
-Provider object that provides three ways to create language models:
+This SDK generates a complete AI SDK v2 event stream, including:
 
-```typescript
-// Direct call
-const model = ollama('llama2');
+### Basic Events
+
+1. **response-metadata** - First event, contains model ID and timestamp
+2. **text-start** - Emitted before the first text-delta
+3. **text-delta** - Text content delta (multiple times)
+4. **text-end** - Emitted after all text-deltas
+5. **finish** - Last event, contains finishReason and usage
+
+### Tool Calling Events
+
+6. **tool-input-start** - Tool call starts, contains toolName
+7. **tool-input-delta** - Tool parameter delta (multiple times)
+8. **tool-input-end** - Tool parameter reception complete
+9. **tool-call** - Tool call complete, contains complete parameters
+
+### Reasoning Events
+
+10. **reasoning-start** - Reasoning starts (<think> tag)
+11. **reasoning-delta** - Reasoning content delta (multiple times)
+12. **reasoning-end** - Reasoning ends (</think> tag)
+
+### Event Stream Order Examples
 
-// Using languageModel method
-const model = ollama.languageModel('llama2');
+**Pure Text Generation:**
 
-// Using chat method
-const model = ollama.chat('llama2');
+```
+response-metadata → text-start → text-delta (multiple) → text-end → finish
 ```
 
-## Event Stream Enhancement
+**Tool Calling:**
 
-This SDK automatically enhances the `ai-sdk-ollama` event stream by adding the following missing events:
+```
+response-metadata → tool-input-start → tool-input-delta (multiple) → 
+tool-input-end → tool-call → finish (finishReason: 'tool-calls')
+```
 
-1. **response-metadata** - First event, contains model ID and timestamp
-2. **text-start** - Emitted before the first text-delta
-3. **text-end** - Emitted after all text-deltas
-4. **finish** - Automatically added if ai-sdk-ollama doesn't emit it
+**Reasoning + Text:**
 
-### Event Stream Order
+```
+response-metadata → reasoning-start → reasoning-delta (multiple) → 
+reasoning-end → text-start → text-delta (multiple) → text-end → finish
+```
+
+**Tool Calling + Reasoning:**
 
 ```
-response-metadata
-  ↓
-text-start (if text generation occurs)
-  ↓
-text-delta (multiple)
-  ↓
-text-end (if text generation occurs)
-  ↓
-finish
+response-metadata → reasoning-start → reasoning-delta (multiple) → 
+reasoning-end → tool-input-start → tool-input-delta (multiple) → 
+tool-input-end → tool-call → finish
 ```
 
 ## Error Handling
@@ -141,64 +454,96 @@ The SDK provides complete error types:
 
 ```typescript
 import {
-  OllamaError,
-  ConnectionError,
-  ModelNotFoundError,
-  ValidationError,
-  TimeoutError,
+  InvalidToolDefinitionError,
 } from '@easbot/ollama-sdk';
 
 try {
+  const model = new NativeOllamaLanguageModel('qwen2.5:0.5b');
   const result = await generateText({
-    model: ollama('llama2'),
+    model,
+    tools: {
+      invalid_tool: {
+        // Missing inputSchema field
+        description: 'Invalid tool',
+      } as any,
+    },
     prompt: 'Hello',
   });
 } catch (error) {
-  if (error instanceof ConnectionError) {
-    console.error('Cannot connect to Ollama service:', error.url);
-  } else if (error instanceof ModelNotFoundError) {
-    console.error('Model not found:', error.modelId);
-  } else if (error instanceof ValidationError) {
-    console.error('Validation failed:', error.field, error.value);
-  } else if (error instanceof TimeoutError) {
-    console.error('Request timeout:', error.timeoutMs);
+  if (error instanceof InvalidToolDefinitionError) {
+    console.error('Invalid tool definition:', error.toolName, error.missingField);
+  } else {
+    console.error('Other error:', error);
+  }
+}
+```
+
+### Error Events
+
+In streaming processing, errors are emitted as events:
+
+```typescript
+const result = await model.doStream({
+  prompt: [{ role: 'user', content: [{ type: 'text', text: 'Hello' }] }],
+});
+
+for await (const event of result.stream) {
+  if (event.type === 'error') {
+    console.error('Streaming error:', event.error);
+  } else if (event.type === 'finish') {
+    if (event.finishReason === 'error') {
+      console.error('Error occurred during generation');
+    }
   }
 }
 ```
 
 ## Architecture
 
-This SDK is a lightweight wrapper layer that relies on `ai-sdk-ollama` for actual LLM requests:
+This SDK is a fully native Ollama implementation that directly calls the Ollama HTTP API:
 
 ```
 User Code
   ↓
-@easbot/ollama-sdk (Wrapper Layer)
-  ├── createOllama() - Provider factory
-  ├── OllamaLanguageModel - Language model wrapper
-  │   ├── doGenerate() - Delegates to ai-sdk-ollama
-  │   └── doStream() - Delegates + event stream enhancement
-  └── enhanceStream() - Event stream enhancer
-  ↓
-ai-sdk-ollama (Underlying LLM requests)
+@easbot/ollama-sdk
+  ├── NativeOllamaLanguageModel - Language model implementation
+  │   ├── doGenerate() - Non-streaming generation
+  │   └── doStream() - Streaming generation + event stream generation
+  ├── NativeOllamaClient - HTTP client
+  │   ├── chat() - Non-streaming request
+  │   └── streamChat() - Streaming request
+  ├── prepareTools() - Tool definition conversion
+  ├── convertToOllamaMessages() - Message format conversion
+  └── Log - Structured logging system
   ↓
 Ollama HTTP API
 ```
 
-## Comparison with Other Providers
+### Features
+
+- **Zero Dependencies**: No dependency on `ai-sdk-ollama` or other third-party libraries
+- **Complete Implementation**: Fully compliant with AI SDK v2 specification
+- **High Performance**: Batch event queue, timely state cleanup
+- **Debuggable**: Structured logging, trace ID tracking
+
+## Comparison with Other Implementations
 
 ### vs `ai-sdk-ollama`
 
-- ✅ Complete AI SDK v2 event stream (automatically adds missing events)
+- ✅ Complete tool calling support (ai-sdk-ollama doesn't support)
+- ✅ Complete AI SDK v2 event stream
 - ✅ Better TypeScript type support
 - ✅ Complete error handling system
-- ✅ Maintains same performance as `ai-sdk-ollama`
+- ✅ Structured logging and debugging support
+- ✅ Zero extra dependencies
 
 ### vs `ollama-ai-provider`
 
-- ✅ Based on official `ai-sdk-ollama`, more stable
-- ✅ Automatic event stream enhancement
+- ✅ Native implementation, more stable
+- ✅ Tool calling support
+- ✅ Automatic event stream generation
 - ✅ Cleaner API
+- ✅ Complete documentation and examples
 
 ## Development
 
@@ -225,10 +570,4 @@ MIT
 
 ## Contributing
 
-Issues and Pull Requests are welcome!
-
-## Links
-
-- npm package: https://www.npmjs.com/package/@easbot/ollama-sdk
-- GitHub repository: https://github.com/houjallen/easbot
-- Issue tracker: https://github.com/houjallen/easbot/issues
+Issues and Pull Requests are welcome!