ollama-client 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 687a8a4fbb73c24bbc408a902cbc94312923dd5c9a42823a2a5e13111977a6b9
-  data.tar.gz: 6c7992774151468a99a855671d2e2e17058a613377de970f5647411c9f627b81
+  metadata.gz: a1ba22e6a669d0617be340e290bb4009023583418afb1f4952f58b616e22369e
+  data.tar.gz: 33310224720f99ab82cf59b6e30166b682af648240fcecd84ecde9dc5bc88608
 SHA512:
-  metadata.gz: c52ad58ee08f15b0014500ac9285c0d7a446447e72ec0df1da17b815ae249103adbf5f3a64ec66e83fc1c821e64d7297b84cd7e19d808c914c862fc3263e52ae
-  data.tar.gz: fad07b8161e7e1442ecfc203b4774e23ceb5075fe660adc1636a1fe81a8ac4a8e27fad80c91bcc20964a9a13e6733a1cb88612cb6d6de2b4c01b5bbbeba6eaf2
+  metadata.gz: 29ff7766aebd45634c3170e6a2e8bdb09c97728f6d4dc726e17e9cc404d23c53e96c669effda77044c3a2296fcd0642e2a96bb845d84d4549f759b8de20383c0
+  data.tar.gz: d272a70b48a329c09c8b2ddc0baf98b61708a637eb4cbf92693af4291ccfbf42104ecdf3eef0a66b525ad45e57111c4d550baa525662c284482b15feacfcfafa

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.2.6] - 2026-01-26
+
+- Reorganize examples: move agent examples to separate repository, keep minimal client examples
+- Add comprehensive test coverage (increased from 65.66% to 79.59%)
+- Add test suite for `Ollama::DocumentLoader` (file loading, context building)
+- Add test suite for `Ollama::Embeddings` (API calls, error handling)
+- Add test suite for `Ollama::ChatSession` (session management)
+- Add test suite for tool classes (`Tool`, `Function`, `Parameters`, `Property`)
+- Rewrite testing documentation to focus on client-only testing (transport/protocol)
+- Add test checklist with specific test categories (G1-G3, C1-C3, A1-A2, F1-F3)
+- Update README with enhanced "What This Gem IS NOT" section
+- Fix RuboCop offenses and improve code quality
+
 ## [0.2.5] - 2026-01-22
 
 - Add `Ollama::DocumentLoader` for loading files as context in queries

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,19 +78,19 @@ gem install ollama-client
 
 ### Primary API: `generate()`
 
-**`generate(prompt:, schema: nil)`** 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 (without schema)
+- ✅ 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: {...})`
-- **Without schema** (plain text): `generate(prompt: "...")` - returns plain text/markdown
+- **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)
 
@@ -260,13 +264,14 @@ require "ollama_client"
 
 client = Ollama::Client.new
 
-# Get plain text/markdown response (no schema required)
+# Get plain text/markdown response (use allow_plain_text: true to skip schema)
 text_response = client.generate(
-  prompt: "Explain Ruby in simple terms"
+  prompt: "Explain Ruby in simple terms",
+  allow_plain_text: true
 )
 
 puts text_response
-# Output: Plain text or markdown explanation
+# Output: Plain text or markdown explanation (String)
 ```
 
 **Option 2: Using `chat_raw()` (for multi-turn conversations)**
@@ -289,8 +294,8 @@ puts text_response
 ```
 
 **When to use which:**
-- **`generate()` without schema** - Simple one-shot queries, explanations, text generation
-- **`generate()` with schema** - Structured JSON outputs for agents
+- **`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
 
@@ -315,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)
 
@@ -326,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)
@@ -669,6 +708,61 @@ result2 = client.chat(messages: messages, format: decision_schema, allow_chat: t
 # 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
@@ -1204,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