ollama-client 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f3a6bc948f8c0f17ccedf3f5f013c8d08d7315f189ef5dec237de4c74fbf257
-  data.tar.gz: 3ce70c7e7af44fcc550860877ca4acb4d1c00af13f70c746b984d855be95aeef
+  metadata.gz: 86bef7e3dc6197748e9d75572705cec97bc94a24da8c9e8f7402d9b5db1e1dc8
+  data.tar.gz: 1ae799bfc340896179b3819350b81fe852c8f2b944f6987cf4f8c76b61791153
 SHA512:
-  metadata.gz: 7148b5b2dbe4dd8c5fb637b79837b1572283c1c2edaaa41df81fd75a347761809cdc7cbd9be8fd16d1cd99a33fbae25f716d436c0f1fde0304a6459338220335
-  data.tar.gz: 78f06aa33cc1d08bc1b915fe9c374c8949c091ea946ac25116ee8d6ec8c9d8080ca74f5c43bdfed91401051ed775b3bc245f808483346d164ecc7033a41d8f92
+  metadata.gz: 1b4a54c4625c0bcb947d74e914bedc0f974e6b0bbaad6f4f46673b8dce5eb6956c5a3bc75745845ccd7f79830149a24ad1e49c54bc03ef165c39ed71d14a92db
+  data.tar.gz: e2ce9114ab3396d65a3075f80c1d273e0d414d2d8be0d4bae4b5e1717fdc62451d2a57590d59e191be86613280fbbd925201ba9d1285a95a2d0cdfabdafc25c3

data/FEATURES_ADDED.md

@@ -0,0 +1,145 @@
+# New Features Added from ollama-ruby
+
+This document describes the features we've integrated from `ollama-ruby` that align with our **agent-first philosophy**.
+
+## ✅ Features Added
+
+### 1. Embeddings API (`client.embeddings`)
+
+**Purpose**: Enable RAG (Retrieval-Augmented Generation) and semantic search in agents.
+
+**Why it fits**: Agents often need to search knowledge bases, compare documents, and build context from embeddings.
+
+**Usage**:
+```ruby
+embedding = client.embeddings.embed(model: "all-minilm", input: "What is Ruby?")
+```
+
+**Files Added**:
+- `lib/ollama/embeddings.rb` - Embeddings API wrapper
+- Updated `lib/ollama/client.rb` - Added `embeddings` accessor
+
+### 2. Config Loading from JSON (`Config.load_from_json`)
+
+**Purpose**: Load configuration from JSON files for production deployments.
+
+**Why it fits**: Production agents need configuration management without hardcoding values.
+
+**Usage**:
+```ruby
+config = Ollama::Config.load_from_json("config.json")
+client = Ollama::Client.new(config: config)
+```
+
+**Files Modified**:
+- `lib/ollama/config.rb` - Added `load_from_json` class method
+
+### 3. Options Class (`Ollama::Options`)
+
+**Purpose**: Type-safe model parameter configuration with validation.
+
+**Why it fits**: Agents need to adjust model behavior dynamically with safety guarantees.
+
+**Usage**:
+```ruby
+options = Ollama::Options.new(temperature: 0.7, top_p: 0.95)
+client.generate(prompt: "...", schema: {...}, options: options.to_h)
+```
+
+**Files Added**:
+- `lib/ollama/options.rb` - Options class with type checking
+
+### 4. Structured Tool Classes (`Ollama::Tool`, `Tool::Function`, etc.)
+
+**Purpose**: Type-safe, explicit tool schema definitions for agent tools.
+
+**Why it fits**: Production agents need explicit control over tool schemas beyond auto-inference. Enables enum constraints, detailed descriptions, and better documentation.
+
+**Usage**:
+```ruby
+# Define explicit schema
+property = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "City name",
+  enum: %w[paris london tokyo]  # Optional enum constraint
+)
+
+params = Ollama::Tool::Function::Parameters.new(
+  type: "object",
+  properties: { city: property },
+  required: %w[city]
+)
+
+function = Ollama::Tool::Function.new(
+  name: "get_weather",
+  description: "Get weather for a city",
+  parameters: params
+)
+
+tool = Ollama::Tool.new(type: "function", function: function)
+
+# Use with Executor (explicit schema + callable)
+tools = {
+  "get_weather" => {
+    tool: tool,
+    callable: ->(city:) { { city: city, temp: "22C" } }
+  }
+}
+```
+
+**Files Added**:
+- `lib/ollama/dto.rb` - Simplified DTO module (no external dependencies)
+- `lib/ollama/tool.rb` - Tool class with DTO support
+- `lib/ollama/tool/function.rb` - Function definition with DTO support
+- `lib/ollama/tool/function/parameters.rb` - Parameters specification with DTO support
+- `lib/ollama/tool/function/parameters/property.rb` - Property definition with DTO support
+- Updated `lib/ollama/agent/executor.rb` - Support for explicit Tool objects
+- `examples/tool_dto_example.rb` - DTO serialization/deserialization examples
+
+**DTO Features:**
+- `to_json` - JSON serialization
+- `from_hash` - Deserialization from hash/JSON
+- `==` - Equality comparison based on hash representation
+- `empty?` - Check if object has no meaningful attributes
+
+All Tool classes include the DTO module, enabling serialization for storage, API responses, and testing.
+
+## 🎯 Design Decisions
+
+### What We Added
+- ✅ Features that directly support agent workflows
+- ✅ Type safety and validation (Options class)
+- ✅ Production deployment needs (JSON config)
+- ✅ RAG capabilities (embeddings)
+
+### What We Didn't Add
+- ❌ Handler-based architecture (doesn't fit our schema-first approach)
+  - See `HANDLERS_ANALYSIS.md` for detailed comparison
+  - We use `StreamingObserver` instead for presentation-only streaming
+- ❌ Interactive console (not needed for agents)
+- ❌ CLI executables (outside our scope)
+- ❌ Full API coverage (we focus on agent building blocks)
+
+## 📝 Examples
+
+See `examples/structured_tools.rb` and `examples/tool_dto_example.rb` for complete examples demonstrating:
+- Structured tool definitions
+- RAG agent with embeddings
+- Options usage for fine-tuning
+
+## 🔄 Migration Notes
+
+All new features are **additive** and **backward compatible**:
+- Existing code continues to work unchanged
+- New features are opt-in
+- No breaking changes to existing APIs
+
+## 🚀 Next Steps
+
+These features enable:
+1. **RAG Agents**: Build knowledge bases with semantic search
+2. **Production Deployments**: JSON-based configuration
+3. **Fine-Tuning**: Type-safe model parameter adjustment
+4. **Structured Tools**: Explicit tool schemas with enum constraints and validation
+
+All while maintaining our **agent-first philosophy** and **safety guarantees**.

data/HANDLERS_ANALYSIS.md

@@ -0,0 +1,190 @@
+# Handlers Analysis: ollama-ruby vs ollama-client
+
+## Handlers in ollama-ruby
+
+The `ollama-ruby` gem uses a **handler-based architecture** where handlers respond to `to_proc` and return lambda expressions to process responses:
+
+| Handler | Purpose | Use Case |
+|---------|---------|----------|
+| **Collector** | Collects all responses in an array | Streaming responses |
+| **Single** | Returns single response directly | Non-streaming responses |
+| **Progress** | Progress bar for create/pull/push | Model management operations |
+| **DumpJSON** | Dumps responses as JSON | Debugging/inspection |
+| **DumpYAML** | Dumps responses as YAML | Debugging/inspection |
+| **Print** | Prints to display | Interactive use |
+| **Markdown** | Prints as ANSI markdown | Interactive use |
+| **Say** | Text-to-speech output | Accessibility |
+| **NOP** | Does nothing | Silent operations |
+
+## Why We Didn't Add Handlers
+
+### 1. **Philosophical Mismatch**
+
+**ollama-ruby approach:**
+```ruby
+# Handler-based, flexible, general-purpose
+ollama.chat(model: 'llama3.1', stream: true, messages: msgs, &Print)
+ollama.generate(model: 'llama3.1', prompt: '...', &Markdown)
+```
+
+**ollama-client approach:**
+```ruby
+# Schema-first, contract-based, agent-focused
+result = client.generate(prompt: '...', schema: schema)
+# Returns validated, structured data directly
+```
+
+### 2. **Different Return Semantics**
+
+- **ollama-ruby**: Handlers control what gets returned (could be array, single value, nothing)
+- **ollama-client**: Always returns validated, structured data matching the schema
+
+### 3. **State Management**
+
+- **ollama-ruby**: Handlers are stateless processors
+- **ollama-client**: We have explicit state (Planner stateless, Executor stateful via messages)
+
+### 4. **Streaming Philosophy**
+
+- **ollama-ruby**: Handlers process streaming chunks (could affect control flow)
+- **ollama-client**: Streaming is **presentation-only** via `StreamingObserver` (never affects control flow)
+
+## What We Have Instead
+
+### StreamingObserver (Agent-Focused)
+
+```ruby
+observer = Ollama::StreamingObserver.new do |event|
+  case event.type
+  when :token
+    print event.text
+  when :tool_call_detected
+    puts "\n[Tool: #{event.name}]"
+  when :state
+    puts "State: #{event.state}"
+  when :final
+    puts "\n--- DONE ---"
+  end
+end
+
+executor = Ollama::Agent::Executor.new(client, tools: tools, stream: observer)
+```
+
+**Key differences:**
+- ✅ Explicit event types (`:token`, `:tool_call_detected`, `:state`, `:final`)
+- ✅ Never affects control flow (presentation-only)
+- ✅ Agent-aware (knows about tool calls, state transitions)
+- ✅ Structured events (not raw response chunks)
+
+### Direct Return Values
+
+```ruby
+# Always returns validated, structured data
+result = client.generate(prompt: '...', schema: schema)
+# result is a Hash matching the schema exactly
+```
+
+**vs ollama-ruby:**
+```ruby
+# Handler determines return value
+result = ollama.generate(model: '...', prompt: '...', &Collector)
+# result could be array, single value, or nil depending on handler
+```
+
+## Potential Handler-Like Utilities for Agents
+
+While we don't want the full handler architecture, there might be value in **debugging/development utilities**:
+
+### 1. **Response Debugger** (Useful for Agents)
+
+```ruby
+# Could add as a utility, not a handler
+module Ollama
+  module Debug
+    def self.dump_json(response, output: $stdout)
+      output.puts JSON.pretty_generate(response)
+    end
+
+    def self.dump_yaml(response, output: $stdout)
+      require 'yaml'
+      output.puts response.to_yaml
+    end
+  end
+end
+
+# Usage:
+result = client.generate(prompt: '...', schema: schema)
+Ollama::Debug.dump_json(result) if ENV['DEBUG']
+```
+
+### 2. **Progress Indicator** (For Long-Running Agent Operations)
+
+```ruby
+# Could add for agent workflows that take time
+module Ollama
+  module Agent
+    class ProgressIndicator
+      def initialize(total_steps:)
+        @total = total_steps
+        @current = 0
+      end
+
+      def step(message = nil)
+        @current += 1
+        print "\r[#{@current}/#{@total}] #{message || 'Processing...'}"
+        $stdout.flush
+      end
+
+      def finish
+        puts "\n✓ Complete"
+      end
+    end
+  end
+end
+```
+
+### 3. **Response Formatter** (For Agent Output)
+
+```ruby
+# Could add for pretty-printing agent responses
+module Ollama
+  module Format
+    def self.markdown(text, output: $stdout)
+      # Use a markdown library to format
+      output.puts text
+    end
+
+    def self.structured(data, output: $stdout)
+      output.puts JSON.pretty_generate(data)
+    end
+  end
+end
+```
+
+## Recommendation
+
+**Don't add handlers** because:
+1. ❌ They conflict with our schema-first, contract-based approach
+2. ❌ They introduce ambiguity about return values
+3. ❌ They don't fit our explicit state management
+4. ❌ Our `StreamingObserver` already handles presentation needs
+
+**Do consider** adding **utility modules** for:
+1. ✅ Debugging helpers (`Ollama::Debug.dump_json`)
+2. ✅ Progress indicators for long agent workflows
+3. ✅ Response formatters (if needed for agent output)
+
+These would be **explicit utilities** rather than **handler callbacks**, maintaining our philosophy while providing useful development tools.
+
+## Summary
+
+| Aspect | ollama-ruby Handlers | ollama-client Approach |
+|--------|---------------------|------------------------|
+| **Architecture** | Handler-based callbacks | Direct return values + StreamingObserver |
+| **Return Values** | Handler-dependent | Always validated, structured data |
+| **Streaming** | Handler processes chunks | Observer emits events (presentation-only) |
+| **State** | Stateless processors | Explicit state (Planner/Executor) |
+| **Use Case** | General-purpose, flexible | Agent-focused, contract-based |
+| **Debugging** | DumpJSON/DumpYAML handlers | Could add utility modules |
+
+**Conclusion**: Handlers don't fit our agent-first philosophy, but we could add explicit utility modules for debugging/development needs.

data/README.md

@@ -36,15 +36,15 @@ This keeps it **clean and future-proof**.
 
 ## 🔒 Guarantees
 
-| Guarantee                              | Yes |
-| -------------------------------------- | --- |
-| Client requests are explicit           | ✅   |
-| Planner is stateless (no hidden memory)| ✅   |
-| Executor is stateful (explicit messages)| ✅  |
-| Retry bounded                          | ✅   |
-| Schema validated (when schema provided)| ✅   |
-| Tools run in Ruby (not in the LLM)     | ✅   |
-| Streaming is display-only (Executor)   | ✅   |
+| Guarantee                                | Yes |
+| ---------------------------------------- | --- |
+| Client requests are explicit             | ✅   |
+| Planner is stateless (no hidden memory)  | ✅   |
+| Executor is stateful (explicit messages) | ✅   |
+| Retry bounded                            | ✅   |
+| Schema validated (when schema provided)  | ✅   |
+| Tools run in Ruby (not in the LLM)       | ✅   |
+| Streaming is display-only (Executor)     | ✅   |
 
 **Non-negotiable safety rule:** the **LLM never executes side effects**. It may request a tool call; **your Ruby code** executes the tool.
 
@@ -97,8 +97,8 @@ gem install ollama-client
 
 This gem intentionally focuses on **agent building blocks**:
 
-- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`
-- **Not guaranteed**: full endpoint parity with every Ollama release (embeddings, advanced model mgmt, etc.)
+- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`, `/api/embeddings`
+- **Not guaranteed**: full endpoint parity with every Ollama release (advanced model mgmt, etc.)
 
 ### Agent endpoint mapping (unambiguous)
 
@@ -130,6 +130,8 @@ puts plan
 
 ### Executor Agent (tool loop, /api/chat)
 
+**Simple approach (auto-inferred schemas):**
+
 ```ruby
 require "ollama_client"
 require "json"
@@ -151,6 +153,68 @@ answer = executor.run(
 puts answer
 ```
 
+**Structured approach (explicit schemas with Tool classes):**
+
+```ruby
+require "ollama_client"
+
+# Define explicit tool schema
+location_prop = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "The city name"
+)
+
+params = Ollama::Tool::Function::Parameters.new(
+  type: "object",
+  properties: { city: location_prop },
+  required: %w[city]
+)
+
+function = Ollama::Tool::Function.new(
+  name: "fetch_weather",
+  description: "Get weather for a city",
+  parameters: params
+)
+
+tool = Ollama::Tool.new(type: "function", function: function)
+
+# Associate tool schema with callable
+tools = {
+  "fetch_weather" => {
+    tool: tool,
+    callable: ->(city:) { { city: city, forecast: "sunny" } }
+  }
+}
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+```
+
+Use structured tools when you need:
+- Explicit control over parameter types and descriptions
+- Enum constraints on parameters
+- Better documentation for complex tools
+- Serialization/deserialization (JSON storage, API responses)
+
+**DTO (Data Transfer Object) functionality:**
+
+All Tool classes support serialization and deserialization:
+
+```ruby
+# Serialize to JSON
+json = tool.to_json
+
+# Deserialize from hash
+tool = Ollama::Tool.from_hash(JSON.parse(json))
+
+# Equality comparison
+tool1 == tool2  # Compares hash representations
+
+# Empty check
+params.empty?  # True if no properties/required fields
+```
+
+See `examples/tool_dto_example.rb` for complete DTO usage examples.
+
 ### Streaming (Executor only; presentation-only)
 
 Streaming is treated as **presentation**, not control. The agent buffers the full assistant message and only
@@ -407,6 +471,67 @@ rescue Ollama::Error => e
 end
 ```
 
+### Example: Tool Calling (Direct API Usage)
+
+For tool calling, use `chat_raw()` to access `tool_calls` from the response:
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Define tool using Tool classes
+tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_current_weather",
+    description: "Get the current weather for a location",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        location: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The location to get the weather for, e.g. San Francisco, CA"
+        ),
+        temperature_unit: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The unit to return the temperature in",
+          enum: %w[celsius fahrenheit]
+        )
+      },
+      required: %w[location temperature_unit]
+    )
+  )
+)
+
+# Create message
+message = Ollama::Agent::Messages.user("What is the weather today in Paris?")
+
+# Use chat_raw() to get full response with tool_calls
+response = client.chat_raw(
+  model: "llama3.1:8b",
+  messages: [message],
+  tools: tool,  # Pass Tool object directly (or array of Tool objects)
+  allow_chat: true
+)
+
+# Access tool_calls from response
+tool_calls = response.dig("message", "tool_calls")
+if tool_calls && !tool_calls.empty?
+  tool_calls.each do |call|
+    name = call.dig("function", "name")
+    args = call.dig("function", "arguments")
+    puts "Tool: #{name}, Args: #{args}"
+  end
+end
+```
+
+**Note:**
+- `chat()` returns only the content (for simple use cases)
+- `chat_raw()` returns the full response with `message.tool_calls` (for tool calling)
+- Both methods accept `tools:` parameter (Tool object, array of Tool objects, or array of hashes)
+- For agent tool loops, use `Ollama::Agent::Executor` instead (handles tool execution automatically)
+
 ### Example: Data Analysis with Validation
 
 ```ruby
@@ -505,6 +630,83 @@ models = client.list_models
 puts "Available models: #{models.join(', ')}"
 ```
 
+### Embeddings for RAG/Semantic Search
+
+Use embeddings for building knowledge bases and semantic search in agents:
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Single text embedding
+embedding = client.embeddings.embed(
+  model: "all-minilm",
+  input: "What is Ruby programming?"
+)
+# Returns: [0.123, -0.456, ...] (array of floats)
+
+# Multiple texts
+embeddings = client.embeddings.embed(
+  model: "all-minilm",
+  input: ["What is Ruby?", "What is Python?", "What is JavaScript?"]
+)
+# Returns: [[...], [...], [...]] (array of embedding arrays)
+
+# Use for semantic similarity in agents
+def find_similar(query_embedding, document_embeddings, threshold: 0.7)
+  document_embeddings.select do |doc_emb|
+    cosine_similarity(query_embedding, doc_emb) > threshold
+  end
+end
+```
+
+### Configuration from JSON
+
+Load configuration from JSON files for production deployments:
+
+```ruby
+require "ollama_client"
+
+# config.json:
+# {
+#   "base_url": "http://localhost:11434",
+#   "model": "llama3.1:8b",
+#   "timeout": 30,
+#   "retries": 3,
+#   "temperature": 0.2
+# }
+
+config = Ollama::Config.load_from_json("config.json")
+client = Ollama::Client.new(config: config)
+```
+
+### Type-Safe Model Options
+
+Use the `Options` class for type-checked model parameters:
+
+```ruby
+require "ollama_client"
+
+# Options with validation
+options = Ollama::Options.new(
+  temperature: 0.7,
+  top_p: 0.95,
+  top_k: 40,
+  num_ctx: 4096,
+  seed: 42
+)
+
+# Will raise ArgumentError if values are out of range
+# options.temperature = 3.0  # Error: temperature must be between 0.0 and 2.0
+
+client.generate(
+  prompt: "Analyze this data",
+  schema: analysis_schema,
+  options: options.to_h
+)
+```
+
 ### Error Handling
 
 ```ruby