ollama-client 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b126aae11a2fd7f0ff26e53e90e12222eb88e23fa6ecf622215c4a9317fe6ce
-  data.tar.gz: 2656544e1ce4bfa852dc687108bdde17084773c3a1e76c53ae9ed59d77604256
+  metadata.gz: 687a8a4fbb73c24bbc408a902cbc94312923dd5c9a42823a2a5e13111977a6b9
+  data.tar.gz: 6c7992774151468a99a855671d2e2e17058a613377de970f5647411c9f627b81
 SHA512:
-  metadata.gz: 5cbd78f768412b8e413e9222b4b0b2ef68e094280546742a0bd8191269072a6281ae4182d591e889ba3829c5b047b0e053c2410fa7734dc4cf1dfe320b527239
-  data.tar.gz: 2f1c2eafa75910646ed2300c8ad5ab312aefe56bb03d6e4797356e219543a57532058c2b2f3fc31b773caf0e7e0d26b3a71a6f9887b1a40955f5b818ffe6e227
+  metadata.gz: c52ad58ee08f15b0014500ac9285c0d7a446447e72ec0df1da17b815ae249103adbf5f3a64ec66e83fc1c821e64d7297b84cd7e19d808c914c862fc3263e52ae
+  data.tar.gz: fad07b8161e7e1442ecfc203b4774e23ceb5075fe660adc1636a1fe81a8ac4a8e27fad80c91bcc20964a9a13e6733a1cb88612cb6d6de2b4c01b5bbbeba6eaf2

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 ## [Unreleased]
 
-- Add tag-triggered GitHub Actions release workflow for RubyGems publishing.
+## [0.2.5] - 2026-01-22
+
+- Add `Ollama::DocumentLoader` for loading files as context in queries
+- Enhance README with context provision methods and examples
+- Improve embeddings error handling and model usage guidance
+- Add comprehensive Ruby guide documentation
+- Update `generate()` method with enhanced functionality and usage examples
+- Improve error handling across client and embeddings modules
 
 ## [0.2.3] - 2026-01-17
 

data/README.md

@@ -74,24 +74,225 @@ gem install ollama-client
 
 ### Primary API: `generate()`
 
-**`generate(prompt:, schema:)`** is the **primary and recommended method** for agent-grade usage:
+**`generate(prompt:, schema: nil)`** is the **primary and recommended method** for agent-grade usage:
 
 - ✅ Stateless, explicit state injection
 - ✅ Uses `/api/generate` endpoint
 - ✅ Ideal for: agent planning, tool routing, one-shot analysis, classification, extraction
 - ✅ No implicit memory or conversation history
+- ✅ Supports both structured JSON (with schema) and plain text/markdown (without schema)
 
 **This is the method you should use for hybrid agents.**
 
+**Usage:**
+- **With schema** (structured JSON): `generate(prompt: "...", schema: {...})`
+- **Without schema** (plain text): `generate(prompt: "...")` - returns plain text/markdown
+
 ### Choosing the Correct API (generate vs chat)
 
 - **Use `/api/generate`** (via `Ollama::Client#generate` or `Ollama::Agent::Planner`) for **stateless planner/router** steps where you want strict, deterministic structured outputs.
 - **Use `/api/chat`** (via `Ollama::Agent::Executor`) for **stateful tool-using** workflows where the model may request tool calls across multiple turns.
 
 **Warnings:**
-- Don’t use `generate()` for tool-calling loops (you’ll end up re-implementing message/tool lifecycles).
-- Don’t use `chat()` for deterministic planners unless you’re intentionally managing conversation state.
-- Don’t let streaming output drive decisions (streaming is presentation-only).
+- Don't use `generate()` for tool-calling loops (you'll end up re-implementing message/tool lifecycles).
+- Don't use `chat()` for deterministic planners unless you're intentionally managing conversation state.
+- Don't let streaming output drive decisions (streaming is presentation-only).
+
+### Providing Context to Queries
+
+You can provide context to your queries in several ways:
+
+**Option 1: Include context directly in the prompt (generate)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Build prompt with context
+context = "User's previous actions: search, calculate, validate"
+user_query = "What should I do next?"
+
+full_prompt = "Given this context: #{context}\n\nUser asks: #{user_query}"
+
+result = client.generate(
+  prompt: full_prompt,
+  schema: {
+    "type" => "object",
+    "required" => ["action"],
+    "properties" => {
+      "action" => { "type" => "string" }
+    }
+  }
+)
+```
+
+**Option 2: Use system messages (chat/chat_raw)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Provide context via system message
+context = "You are analyzing market data. Current market status: Bullish. Key indicators: RSI 65, MACD positive."
+
+response = client.chat_raw(
+  messages: [
+    { role: "system", content: context },
+    { role: "user", content: "What's the next trading action?" }
+  ],
+  allow_chat: true
+)
+
+puts response.message.content
+```
+
+**Option 3: Use Planner with context parameter**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+planner = Ollama::Agent::Planner.new(client)
+
+context = {
+  previous_actions: ["search", "calculate"],
+  user_preferences: "prefers conservative strategies"
+}
+
+plan = planner.run(
+  prompt: "Decide the next action",
+  context: context
+)
+```
+
+**Option 4: Load documents from directory (DocumentLoader)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Load all documents from a directory (supports .txt, .md, .csv, .json)
+loader = Ollama::DocumentLoader.new("docs/")
+loader.load_all  # Loads all supported files
+
+# Get all documents as context
+context = loader.to_context
+
+# Use in your query
+result = client.generate(
+  prompt: "Context from documents:\n#{context}\n\nQuestion: What is Ruby?",
+  schema: {
+    "type" => "object",
+    "required" => ["answer"],
+    "properties" => {
+      "answer" => { "type" => "string" }
+    }
+  }
+)
+
+# Or load specific files
+loader.load_file("ruby_guide.md")
+ruby_context = loader["ruby_guide.md"]
+
+result = client.generate(
+  prompt: "Based on this documentation:\n#{ruby_context}\n\nExplain Ruby's key features."
+)
+```
+
+**Option 5: RAG-style context injection (using embeddings + DocumentLoader)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# 1. Load documents
+loader = Ollama::DocumentLoader.new("docs/")
+loader.load_all
+
+# 2. When querying, find relevant context using embeddings
+query = "What is Ruby?"
+# (In real RAG, you'd compute embeddings and find similar docs)
+
+# 3. Inject relevant context into prompt
+relevant_context = loader["ruby_guide.md"]  # Or find via similarity search
+
+result = client.generate(
+  prompt: "Context: #{relevant_context}\n\nQuestion: #{query}\n\nAnswer based on the context:"
+)
+```
+
+**Option 5: Multi-turn conversation with accumulated context**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+messages = [
+  { role: "system", content: "You are a helpful assistant with access to context." },
+  { role: "user", content: "What is Ruby?" }
+]
+
+# First response
+response1 = client.chat_raw(messages: messages, allow_chat: true)
+puts response1.message.content
+
+# Add context and continue conversation
+messages << { role: "assistant", content: response1.message.content }
+messages << { role: "user", content: "Tell me more about its use cases" }
+
+response2 = client.chat_raw(messages: messages, allow_chat: true)
+puts response2.message.content
+```
+
+### Plain Text / Markdown Responses (No JSON Schema)
+
+For simple text or markdown responses without JSON validation, you can use either `generate()` or `chat_raw()`:
+
+**Option 1: Using `generate()` (recommended for simple queries)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Get plain text/markdown response (no schema required)
+text_response = client.generate(
+  prompt: "Explain Ruby in simple terms"
+)
+
+puts text_response
+# Output: Plain text or markdown explanation
+```
+
+**Option 2: Using `chat_raw()` (for multi-turn conversations)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Get plain text/markdown response (no format required)
+response = client.chat_raw(
+  messages: [{ role: "user", content: "Explain Ruby in simple terms" }],
+  allow_chat: true
+)
+
+# Access the plain text content
+text_response = response.message.content
+puts text_response
+# Output: Plain text or markdown explanation
+```
+
+**When to use which:**
+- **`generate()` without schema** - Simple one-shot queries, explanations, text generation
+- **`generate()` with schema** - Structured JSON outputs for agents
+- **`chat_raw()` without format** - Multi-turn conversations with plain text
+- **`chat_raw()` with format** - Multi-turn conversations with structured outputs
 
 ### Scope / endpoint coverage
 
@@ -200,16 +401,36 @@ Use structured tools when you need:
 All Tool classes support serialization and deserialization:
 
 ```ruby
+# Create a tool
+tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "fetch_weather",
+    description: "Get weather for a city",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        city: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The city name"
+        )
+      },
+      required: %w[city]
+    )
+  )
+)
+
 # Serialize to JSON
 json = tool.to_json
 
 # Deserialize from hash
-tool = Ollama::Tool.from_hash(JSON.parse(json))
+tool2 = Ollama::Tool.from_hash(JSON.parse(json))
 
 # Equality comparison
-tool1 == tool2  # Compares hash representations
+tool == tool2  # Compares hash representations (returns true)
 
 # Empty check
+params = Ollama::Tool::Function::Parameters.new(type: "object", properties: {})
 params.empty?  # True if no properties/required fields
 ```
 
@@ -267,7 +488,23 @@ end
 
 ### Quick Start Pattern
 
-The basic pattern for using structured outputs:
+**Option 1: Plain text/markdown (no schema)**
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Simple text response - no schema needed
+response = client.generate(
+  prompt: "Explain Ruby programming in one sentence"
+)
+
+puts response
+# Output: Plain text explanation
+```
+
+**Option 2: Structured JSON (with schema)**
 
 ```ruby
 require "ollama_client"
@@ -288,7 +525,7 @@ schema = {
 begin
   result = client.generate(
     model: "llama3.1:8b",
-    prompt: "Your prompt here",
+    prompt: "Return a JSON object with field1 as a string and field2 as a number. Example: field1 could be 'example' and field2 could be 42.",
     schema: schema
   )
 
@@ -400,7 +637,18 @@ end
 **For agents, prefer `generate()` with explicit state injection:**
 
 ```ruby
+# Define decision schema
+decision_schema = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => { "type" => "string" },
+    "reasoning" => { "type" => "string" }
+  }
+}
+
 # ✅ GOOD: Explicit state in prompt
+actions = ["search", "calculate", "validate"]
 context = "Previous actions: #{actions.join(', ')}"
 result = client.generate(
   prompt: "Given context: #{context}. Decide next action.",
@@ -408,8 +656,17 @@ result = client.generate(
 )
 
 # ❌ AVOID: Implicit conversation history
-messages = [{ role: "user", content: "..." }]
-result = client.chat(messages: messages, format: schema, allow_chat: true)  # History grows silently
+messages = [{ role: "user", content: "Decide the next action based on previous actions: search, calculate, validate" }]
+result = client.chat(messages: messages, format: decision_schema, allow_chat: true)
+
+# Problem: History grows silently - you must manually manage it
+messages << { role: "assistant", content: result.to_json }
+messages << { role: "user", content: "Now do the next step" }
+result2 = client.chat(messages: messages, format: decision_schema, allow_chat: true)
+# messages.size is now 3, and will keep growing with each turn
+# You must manually track what's in the history
+# Schema validation can become weaker with accumulated context
+# Harder to reason about state in agent systems
 ```
 
 ### Example: Chat API (Advanced Use Case)
@@ -567,7 +824,7 @@ data = "Sales increased 25% this quarter, customer satisfaction is at 4.8/5"
 
 begin
   result = client.generate(
-    prompt: "Analyze this data: #{data}",
+    prompt: "Analyze this data: #{data}. Return confidence as a decimal between 0 and 1 (e.g., 0.85 for 85% confidence).",
     schema: analysis_schema
   )
 
@@ -589,7 +846,8 @@ begin
 
 rescue Ollama::SchemaViolationError => e
   puts "Analysis failed validation: #{e.message}"
-  # Could retry or use fallback logic
+  puts "The LLM response didn't match the schema constraints."
+  # Could retry with a clearer prompt or use fallback logic
 rescue Ollama::TimeoutError => e
   puts "Request timed out: #{e.message}"
 rescue Ollama::Error => e
@@ -631,6 +889,63 @@ models = client.list_models
 puts "Available models: #{models.join(', ')}"
 ```
 
+### Loading Documents from Directory (DocumentLoader)
+
+Load files from a directory and use them as context for your queries. Supports `.txt`, `.md`, `.csv`, and `.json` files:
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Load all documents from a directory
+loader = Ollama::DocumentLoader.new("docs/")
+loader.load_all  # Loads all .txt, .md, .csv, .json files
+
+# Get all documents as a single context string
+context = loader.to_context
+
+# Use in your query
+result = client.generate(
+  prompt: "Context from documents:\n#{context}\n\nQuestion: What is Ruby?",
+  schema: {
+    "type" => "object",
+    "required" => ["answer"],
+    "properties" => {
+      "answer" => { "type" => "string" }
+    }
+  }
+)
+
+# Load specific file
+ruby_guide = loader.load_file("ruby_guide.md")
+
+# Access loaded documents
+all_files = loader.files  # ["ruby_guide.md", "python_intro.txt", ...]
+specific_doc = loader["ruby_guide.md"]
+
+# Load recursively from subdirectories
+loader.load_all(recursive: true)
+
+# Select documents by pattern
+ruby_docs = loader.select(/ruby/)
+```
+
+**Supported file types:**
+- **`.txt`** - Plain text files
+- **`.md`, `.markdown`** - Markdown files
+- **`.csv`** - CSV files (converted to readable text format)
+- **`.json`** - JSON files (pretty-printed)
+
+**Example directory structure:**
+```
+docs/
+  ├── ruby_guide.md
+  ├── python_intro.txt
+  ├── data.csv
+  └── config.json
+```
+
 ### Embeddings for RAG/Semantic Search
 
 Use embeddings for building knowledge bases and semantic search in agents:
@@ -640,21 +955,55 @@ 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)
+# Note: You need an embedding model installed in Ollama
+# Common models: nomic-embed-text, all-minilm, mxbai-embed-large
+# Check available models: client.list_models
 
-# Multiple texts
-embeddings = client.embeddings.embed(
-  model: "all-minilm",
-  input: ["What is Ruby?", "What is Python?", "What is JavaScript?"]
-)
-# Returns: [[...], [...], [...]] (array of embedding arrays)
+begin
+  # Single text embedding
+  # Note: Use the full model name with tag if needed (e.g., "nomic-embed-text:latest")
+  embedding = client.embeddings.embed(
+    model: "nomic-embed-text:latest",  # Use an available embedding model
+    input: "What is Ruby programming?"
+  )
+  # Returns: [0.123, -0.456, ...] (array of floats)
+  if embedding.empty?
+    puts "Warning: Empty embedding returned. Check model compatibility."
+  else
+    puts "Embedding dimension: #{embedding.length}"
+    puts "First few values: #{embedding.first(5).map { |v| v.round(4) }}"
+  end
+
+  # Multiple texts
+  embeddings = client.embeddings.embed(
+    model: "nomic-embed-text:latest",
+    input: ["What is Ruby?", "What is Python?", "What is JavaScript?"]
+  )
+  # Returns: [[...], [...], [...]] (array of embedding arrays)
+  if embeddings.is_a?(Array) && embeddings.first.is_a?(Array)
+    puts "Number of embeddings: #{embeddings.length}"
+    puts "Each embedding dimension: #{embeddings.first.length}"
+  else
+    puts "Unexpected response format: #{embeddings.class}"
+  end
+
+rescue Ollama::NotFoundError => e
+  puts "Model not found. Install an embedding model first:"
+  puts "  ollama pull nomic-embed-text"
+  puts "Or check available models: client.list_models"
+  puts "Note: Use the full model name with tag (e.g., 'nomic-embed-text:latest')"
+rescue Ollama::Error => e
+  puts "Error: #{e.message}"
+end
 
 # Use for semantic similarity in agents
+def cosine_similarity(vec1, vec2)
+  dot_product = vec1.zip(vec2).sum { |a, b| a * b }
+  magnitude1 = Math.sqrt(vec1.sum { |x| x * x })
+  magnitude2 = Math.sqrt(vec2.sum { |x| x * x })
+  dot_product / (magnitude1 * magnitude2)
+end
+
 def find_similar(query_embedding, document_embeddings, threshold: 0.7)
   document_embeddings.select do |doc_emb|
     cosine_similarity(query_embedding, doc_emb) > threshold
@@ -668,18 +1017,28 @@ Load configuration from JSON files for production deployments:
 
 ```ruby
 require "ollama_client"
+require "json"
 
-# config.json:
-# {
-#   "base_url": "http://localhost:11434",
-#   "model": "llama3.1:8b",
-#   "timeout": 30,
-#   "retries": 3,
-#   "temperature": 0.2
-# }
+# Create config.json file (or use an existing one)
+config_data = {
+  "base_url" => "http://localhost:11434",
+  "model" => "llama3.1:8b",
+  "timeout" => 30,
+  "retries" => 3,
+  "temperature" => 0.2
+}
+
+# Write config file
+File.write("config.json", JSON.pretty_generate(config_data))
 
-config = Ollama::Config.load_from_json("config.json")
-client = Ollama::Client.new(config: config)
+# Load configuration from file
+begin
+  config = Ollama::Config.load_from_json("config.json")
+  client = Ollama::Client.new(config: config)
+  puts "Client configured from config.json"
+rescue Ollama::Error => e
+  puts "Error loading config: #{e.message}"
+end
 ```
 
 ### Type-Safe Model Options
@@ -689,6 +1048,17 @@ Use the `Options` class for type-checked model parameters:
 ```ruby
 require "ollama_client"
 
+client = Ollama::Client.new
+
+# Define schema
+analysis_schema = {
+  "type" => "object",
+  "required" => ["summary"],
+  "properties" => {
+    "summary" => { "type" => "string" }
+  }
+}
+
 # Options with validation
 options = Ollama::Options.new(
   temperature: 0.7,
@@ -701,11 +1071,19 @@ options = Ollama::Options.new(
 # 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
+# Use with chat() - chat() accepts options parameter
+client.chat(
+  messages: [{ role: "user", content: "Analyze this data" }],
+  format: analysis_schema,
+  options: options.to_h,
+  allow_chat: true
 )
+
+# Note: generate() doesn't accept options parameter
+# For generate(), set options in config instead:
+# config = Ollama::Config.new
+# config.temperature = 0.7
+# client = Ollama::Client.new(config: config)
 ```
 
 ### Error Handling
@@ -713,8 +1091,22 @@ client.generate(
 ```ruby
 require "ollama_client"
 
+client = Ollama::Client.new
+schema = {
+  "type" => "object",
+  "required" => ["result"],
+  "properties" => {
+    "result" => { "type" => "string" }
+  }
+}
+
 begin
-  result = client.generate(prompt: prompt, schema: schema)
+  result = client.generate(
+    prompt: "Return a simple result",
+    schema: schema
+  )
+  # Success - use the result
+  puts "Result: #{result['result']}"
 rescue Ollama::NotFoundError => e
   # 404 Not Found - model or endpoint doesn't exist
   # The error message automatically suggests similar model names if available

data/docs/README.md

@@ -4,8 +4,7 @@ This directory contains internal development documentation for the ollama-client
 
 ## Quick Links
 
-- 🚀 **[Quick Release Reference](QUICK_RELEASE.md)** - Fast release checklist
-- 📘 **[Complete Release Guide](GEM_RELEASE_GUIDE.md)** - Full automation setup (794 lines)
+- 🚀 **[Release Guide](RELEASE_GUIDE.md)** - Complete guide for automated gem releases with MFA
 
 ## Contents
 
@@ -22,7 +21,7 @@ This directory contains internal development documentation for the ollama-client
 
 ### CI/Automation
 - **[CLOUD.md](CLOUD.md)** - Cloud agent guide for automated testing and fixes
-- **[GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md)** - Complete guide for automated gem releases via GitHub Actions and git tags
+- **[RELEASE_GUIDE.md](RELEASE_GUIDE.md)** - Complete guide for automated gem releases via GitHub Actions with OTP/MFA
 
 ## For Users