ollama-client 0.2.4 → 0.2.6

data/README.md

@@ -26,11 +26,15 @@ Domain tools and application logic live **outside** this gem. For convenience, i
 
 ## 🚫 What This Gem IS NOT
 
-* ❌ Domain tool implementations
-* ❌ Domain logic
-* ❌ Memory store
-* ❌ Chat UI
-* ❌ A promise of full Ollama API coverage (it focuses on agent workflows)
+This gem is **NOT**:
+* ❌ A chatbot UI framework
+* ❌ A domain-specific agent implementation
+* ❌ A tool execution engine
+* ❌ A memory store
+* ❌ A promise of full Ollama API coverage (focuses on agent workflows)
+* ❌ An agent runtime (it provides transport + protocol, not agent logic)
+
+**Domain tools and application logic live outside this gem.**
 
 This keeps it **clean and future-proof**.
 
@@ -74,24 +78,226 @@ gem install ollama-client
 
 ### Primary API: `generate()`
 
-**`generate(prompt:, schema:)`** is the **primary and recommended method** for agent-grade usage:
+**`generate(prompt:, schema: nil, allow_plain_text: false)`** 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 (with `allow_plain_text: true`)
 
 **This is the method you should use for hybrid agents.**
 
+**Usage:**
+- **With schema** (structured JSON): `generate(prompt: "...", schema: {...})` - returns Hash
+- **Without schema** (plain text): `generate(prompt: "...", allow_plain_text: true)` - returns String
+
 ### 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 (use allow_plain_text: true to skip schema)
+text_response = client.generate(
+  prompt: "Explain Ruby in simple terms",
+  allow_plain_text: true
+)
+
+puts text_response
+# Output: Plain text or markdown explanation (String)
+```
+
+**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()` with `allow_plain_text: true`** - Simple one-shot queries, explanations, text generation
+- **`generate()` with schema** - Structured JSON outputs for agents (default, recommended)
+- **`chat_raw()` without format** - Multi-turn conversations with plain text
+- **`chat_raw()` with format** - Multi-turn conversations with structured outputs
 
 ### Scope / endpoint coverage
 
@@ -114,6 +320,40 @@ Within `Ollama::Agent`:
 ```ruby
 require "ollama_client"
 
+client = Ollama::Client.new
+
+# Option 1: With schema (recommended for structured outputs)
+DECISION_SCHEMA = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => {
+      "type" => "string",
+      "enum" => ["search", "calculate", "store", "retrieve", "finish"]
+    },
+    "reasoning" => {
+      "type" => "string"
+    }
+  }
+}
+
+planner = Ollama::Agent::Planner.new(client)
+
+plan = planner.run(
+  prompt: "Given the user request, decide the next action.",
+  schema: DECISION_SCHEMA,
+  context: { user_request: "Plan a weekend trip to Rome" }
+)
+
+puts plan["action"]      # => "search" (or one of the enum values)
+puts plan["reasoning"]    # => Explanation string
+```
+
+**Option 2: Without schema (returns any JSON)**
+
+```ruby
+require "ollama_client"
+
 client = Ollama::Client.new
 planner = Ollama::Agent::Planner.new(client)
 
@@ -125,7 +365,7 @@ plan = planner.run(
   context: { user_request: "Plan a weekend trip to Rome" }
 )
 
-puts plan
+puts plan  # => Any valid JSON structure
 ```
 
 ### Executor Agent (tool loop, /api/chat)
@@ -200,16 +440,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 +527,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 +564,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 +676,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,10 +695,74 @@ 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
+```
+
+### Decision Table: `generate()` vs `chat()` vs `ChatSession`
+
+> **Use `generate()` for systems. Use `chat()` or `ChatSession` for humans.**
+
+| Use Case | Method | Schema Guarantees | Streaming | Memory | When to Use |
+|----------|--------|-------------------|-----------|--------|-------------|
+| **Agent planning/routing** | `generate()` | ✅ Strong | ❌ No | ❌ Stateless | Default for agents |
+| **Structured extraction** | `generate()` | ✅ Strong | ❌ No | ❌ Stateless | Data extraction, classification |
+| **Tool-calling loops** | `chat_raw()` | ⚠️ Weaker | ✅ Yes | ✅ Stateful | Executor agent internals |
+| **UI chat interface** | `ChatSession` | ⚠️ Best-effort | ✅ Yes | ✅ Stateful | Human-facing assistants |
+| **Multi-turn conversations** | `ChatSession` | ⚠️ Best-effort | ✅ Yes | ✅ Stateful | Interactive chat |
+
+**Core Rule:** Chat must be a feature flag, not default behavior.
+
+### Using `ChatSession` for Human-Facing Chat
+
+For UI assistants and interactive chat, use `ChatSession` to manage conversation state:
+
+```ruby
+require "ollama_client"
+
+# Enable chat in config
+config = Ollama::Config.new
+config.allow_chat = true
+config.streaming_enabled = true
+
+client = Ollama::Client.new(config: config)
+
+# Create streaming observer for presentation
+observer = Ollama::StreamingObserver.new do |event|
+  case event.type
+  when :token
+    print event.text
+  when :final
+    puts "\n--- DONE ---"
+  end
+end
+
+# Create chat session with system message
+chat = Ollama::ChatSession.new(
+  client,
+  system: "You are a helpful assistant",
+  stream: observer
+)
+
+# Send messages (history is managed automatically)
+chat.say("Hello")
+chat.say("Explain Ruby blocks")
+
+# Clear history if needed (keeps system message)
+chat.clear
 ```
 
+**Important:** Schema validation in chat is **best-effort** for formatting, not correctness. Never use chat+schema for agent control flow.
+
 ### Example: Chat API (Advanced Use Case)
 
 ```ruby
@@ -567,7 +918,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 +940,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 +983,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 +1049,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 +1111,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
+}
 
-config = Ollama::Config.load_from_json("config.json")
-client = Ollama::Client.new(config: config)
+# Write config file
+File.write("config.json", JSON.pretty_generate(config_data))
+
+# 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 +1142,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 +1165,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 +1185,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
@@ -812,67 +1298,35 @@ end
 
 This keeps the `ollama-client` gem **domain-agnostic** and **reusable** across any project.
 
-**See `examples/tool_calling_pattern.rb` for a working implementation of this pattern.**
-
-## Advanced Examples
-
-The `examples/` directory contains advanced examples demonstrating production-grade patterns:
-
-### `tool_calling_pattern.rb`
-**Working implementation of the ToolRouter pattern from the Architecture section:**
-- Tool registry and routing
-- LLM outputs intent, agent executes tools
-- Demonstrates the correct separation of concerns
-- Matches the pattern shown in README.md lines 430-500
-
-### `dhanhq_trading_agent.rb`
-**Real-world integration: Ollama (reasoning) + DhanHQ (execution):**
-- Ollama analyzes market data and makes trading decisions
-- DhanHQ executes trades (place orders, check positions, etc.)
-- Demonstrates proper separation: LLM = reasoning, DhanHQ = execution
-- Shows risk management with super orders (SL/TP)
-- Perfect example of agent-grade tool calling pattern
-
-### `advanced_multi_step_agent.rb`
-Multi-step agent workflow with:
-- Complex nested schemas
-- State management across steps
-- Confidence thresholds
-- Risk assessment
-- Error recovery
-
-### `advanced_error_handling.rb`
-Comprehensive error handling patterns:
-- All error types (NotFoundError, HTTPError, TimeoutError, etc.)
-- Retry strategies with exponential backoff
-- Fallback mechanisms
-- Error statistics and observability
-
-### `advanced_complex_schemas.rb`
-Real-world complex schemas:
-- Financial analysis (nested metrics, recommendations, risk factors)
-- Code review (issues, suggestions, effort estimation)
-- Research paper analysis (findings, methodology, citations)
-
-### `advanced_performance_testing.rb`
-Performance and observability:
-- Latency measurement (min, max, avg, p95, p99)
-- Throughput testing
-- Error rate tracking
-- Metrics export
-
-### `advanced_edge_cases.rb`
-Boundary and edge case testing:
-- Empty/long prompts
-- Special characters and unicode
-- Minimal/strict schemas
-- Deeply nested structures
-- Enum constraints
-
-Run any example:
-```bash
-ruby examples/advanced_multi_step_agent.rb
-```
+**See the [ollama-agent-examples](https://github.com/shubhamtaywade82/ollama-agent-examples) repository for working implementations of this pattern.**
+
+## 📚 Examples
+
+### Minimal Examples (In This Repo)
+
+The `examples/` directory contains minimal examples demonstrating **client usage only**:
+
+- **`basic_generate.rb`** - Basic `/generate` usage with schema validation
+- **`basic_chat.rb`** - Basic `/chat` usage
+- **`tool_calling_parsing.rb`** - Tool-call parsing (no execution)
+- **`tool_dto_example.rb`** - Tool DTO serialization
+
+These examples focus on **transport and protocol correctness**, not agent behavior.
+
+### Full Agent Examples (Separate Repository)
+
+For complete agent examples (trading agents, coding agents, RAG agents, multi-step workflows, tool execution patterns, etc.), see:
+
+**[ollama-agent-examples](https://github.com/shubhamtaywade82/ollama-agent-examples)**
+
+This separation keeps `ollama-client` focused on the transport layer while providing comprehensive examples for agent developers.
+
+**Why this separation?**
+- Examples rot faster than APIs
+- Agent examples pull in domain-specific dependencies
+- Tool examples imply opinions about tool design
+- The client stays clean and maintainable
+- Users don't confuse client vs agent responsibilities
 
 ## Development