ollama-client 0.2.1 → 0.2.3

data/docs/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/docs/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/docs/README.md

@@ -0,0 +1,37 @@
+# Internal Documentation
+
+This directory contains internal development documentation for the ollama-client gem.
+
+## Contents
+
+### Design Documentation
+- **[HANDLERS_ANALYSIS.md](HANDLERS_ANALYSIS.md)** - Analysis of handler architecture decisions (why we didn't adopt ollama-ruby's handler pattern)
+- **[FEATURES_ADDED.md](FEATURES_ADDED.md)** - Features integrated from ollama-ruby that align with our agent-first philosophy
+- **[PRODUCTION_FIXES.md](PRODUCTION_FIXES.md)** - Production-ready fixes for hybrid agents (JSON parsing, retry policy, etc.)
+- **[SCHEMA_FIXES.md](SCHEMA_FIXES.md)** - Schema validation fixes and best practices for numeric constraints
+- **[CONSOLE_IMPROVEMENTS.md](CONSOLE_IMPROVEMENTS.md)** - Interactive console UX improvements (thinking indicators, formatted tool results)
+
+### Testing Documentation
+- **[TESTING.md](TESTING.md)** - Testing guide and examples
+- **[TEST_UPDATES.md](TEST_UPDATES.md)** - Recent test updates for DhanHQ tool calling enhancements
+
+### CI/Automation
+- **[CLOUD.md](CLOUD.md)** - Cloud agent guide for automated testing and fixes
+
+## For Users
+
+If you're looking for user-facing documentation, see:
+- [Main README](../README.md) - Getting started, API reference, examples
+- [CHANGELOG](../CHANGELOG.md) - Version history and changes
+- [CONTRIBUTING](../CONTRIBUTING.md) - How to contribute
+- [Examples](../examples/) - Working code examples
+
+## For Contributors
+
+These internal docs help maintainers understand:
+- **Why** certain design decisions were made
+- **What** features have been added and why
+- **How** to test and maintain the codebase
+- **Where** production fixes were applied
+
+They are not intended for end users and can be safely ignored when using the gem.

data/docs/SCHEMA_FIXES.md

@@ -0,0 +1,147 @@
+# Schema Validation Fixes
+
+## Problem
+
+LLMs were returning confidence values as percentages (e.g., 95, 100) instead of decimals (e.g., 0.95, 1.0), causing schema validation errors:
+
+```
+The property '#/confidence' did not have a maximum value of 1, inclusively
+```
+
+## Root Cause
+
+JSON schemas defined numeric constraints (0-1) but lacked explicit descriptions explaining the expected format. LLMs naturally interpret "confidence" as percentages without guidance.
+
+## Solution
+
+Added explicit descriptions to all numeric fields with constrained ranges, clarifying the expected format.
+
+### Fixed Fields
+
+#### Confidence Fields (0.0 to 1.0)
+Updated in 8 locations across the codebase:
+
+- `examples/complete_workflow.rb` (2 instances)
+  - TaskPlanner schema
+  - DataAnalyzer schema
+- `examples/dhanhq_agent.rb` (2 instances)
+- `examples/dhanhq/schemas/agent_schemas.rb` (2 instances)
+- `examples/dhanhq/agents/technical_analysis_agent.rb` (1 instance)
+- `examples/advanced_multi_step_agent.rb` (1 instance)
+
+**Before:**
+```ruby
+"confidence" => {
+  "type" => "number",
+  "minimum" => 0,
+  "maximum" => 1
+}
+```
+
+**After:**
+```ruby
+"confidence" => {
+  "type" => "number",
+  "minimum" => 0,
+  "maximum" => 1,
+  "description" => "Confidence in this decision (0.0 to 1.0, where 1.0 is 100% confident)"
+}
+```
+
+#### Other Constrained Fields
+
+- `reproducibility_score` in `advanced_complex_schemas.rb`
+  - Added: "Reproducibility score (0.0 to 1.0, where 1.0 means fully reproducible)"
+
+- `profit_margin` in `advanced_complex_schemas.rb`
+  - Added: "Profit margin as percentage (0 to 100)"
+
+- `overall_score` in `advanced_complex_schemas.rb`
+  - Added: "Overall quality score (0 to 100)"
+
+## Best Practices
+
+### When Defining Schemas
+
+1. **Always include descriptions** for numeric fields with constraints
+2. **Be explicit about format**: decimal (0.0-1.0) vs percentage (0-100)
+3. **Provide examples** in descriptions when helpful
+4. **Use clear units**: "as percentage", "as decimal", "where 1.0 is 100%"
+
+### When Writing Prompts
+
+**Schema descriptions alone may not be enough!** Always reinforce numeric formats in the prompt itself:
+
+```ruby
+# ❌ BAD: Relies only on schema description
+result = @client.generate(
+  prompt: "Analyze this data: #{data}",
+  schema: @schema
+)
+
+# ✅ GOOD: Explicit examples in prompt
+result = @client.generate(
+  prompt: "Analyze this data: #{data}\n\nIMPORTANT: Express confidence as a decimal between 0.0 and 1.0 (e.g., 0.85 for 85% confidence, not 85).",
+  schema: @schema
+)
+```
+
+**Why this matters:**
+- LLMs may not always read schema descriptions carefully
+- Concrete examples in prompts are more effective
+- Prevents "100" vs "1.0" confusion
+
+### Example Patterns
+
+**Decimal confidence (0-1):**
+```ruby
+"confidence" => {
+  "type" => "number",
+  "minimum" => 0,
+  "maximum" => 1,
+  "description" => "Confidence level (0.0 to 1.0, where 1.0 is 100% confident)"
+}
+```
+
+**Percentage score (0-100):**
+```ruby
+"score" => {
+  "type" => "number",
+  "minimum" => 0,
+  "maximum" => 100,
+  "description" => "Quality score as percentage (0 to 100)"
+}
+```
+
+**Probability (0-1):**
+```ruby
+"probability" => {
+  "type" => "number",
+  "minimum" => 0,
+  "maximum" => 1,
+  "description" => "Probability value (0.0 to 1.0)"
+}
+```
+
+## Testing
+
+All modified files passed syntax validation:
+```bash
+ruby -c examples/complete_workflow.rb         # Syntax OK
+ruby -c examples/dhanhq_agent.rb              # Syntax OK
+ruby -c examples/advanced_multi_step_agent.rb # Syntax OK
+ruby -c examples/advanced_complex_schemas.rb  # Syntax OK
+```
+
+## Impact
+
+- **Examples now run without schema validation errors**
+- **LLMs receive clear guidance** on numeric formats
+- **Consistent patterns** across all example schemas
+- **Better developer experience** with self-documenting schemas
+
+## Related Files
+
+See also:
+- [Testing Guide](TESTING.md) - How to test structured outputs
+- [Features Added](FEATURES_ADDED.md) - Schema validation features

data/docs/TEST_UPDATES.md

@@ -0,0 +1,107 @@
+# Test File Updates
+
+## Summary
+
+Updated test examples to reflect recent enhancements to DhanHQ tool calling, particularly around historical data and technical indicators.
+
+## Files Updated
+
+### 1. `examples/test_dhanhq_tool_calling.rb`
+
+#### Changes Made:
+
+1. **Updated `historical_data_tool` definition** (lines 66-101):
+   - Changed `interval` enum from `["daily", "weekly", "monthly"]` to `["1", "5", "15", "25", "60"]`
+   - Added proper description: "Minute interval for intraday data. Omit for daily data."
+   - Added `calculate_indicators` boolean parameter
+   - Updated description to mention technical indicators (RSI, MACD, SMA, EMA, Bollinger Bands, ATR)
+   - Added `required` fields: `from_date` and `to_date`
+
+2. **Added Test 5: Historical Data with Technical Indicators**
+   - Tests the new `calculate_indicators` parameter
+   - Verifies LLM includes all required parameters including interval
+   - Shows how to request intraday data with indicators
+
+3. **Added Test 6: Intraday Data with 5-minute intervals**
+   - Tests intraday data specifically
+   - Uses current date dynamically
+   - Validates interval parameter is one of the valid values (1, 5, 15, 25, 60)
+   - Shows date range handling
+
+4. **Enhanced Summary Section**
+   - Added notes about historical data enhancements
+   - Documents interval usage for intraday vs daily data
+   - Explains `calculate_indicators` feature and its benefits
+
+## Key Features Tested
+
+### Intraday Data
+- ✅ Interval parameter with values: "1", "5", "15", "25", "60"
+- ✅ Date handling (from_date, to_date)
+- ✅ 5-minute intervals (most commonly used for intraday analysis)
+
+### Technical Indicators
+- ✅ `calculate_indicators` parameter
+- ✅ Returns RSI, MACD, SMA, EMA, Bollinger Bands, ATR
+- ✅ Reduces response size vs raw OHLCV data
+
+### Tool Calling
+- ✅ chat_raw() method for accessing tool_calls
+- ✅ Structured Tool classes
+- ✅ Parameter validation
+
+## Example Usage
+
+```ruby
+# Get intraday data with indicators
+historical_data_tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_historical_data",
+    description: "Get historical price data (OHLCV) or technical indicators...",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        interval: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "Minute interval for intraday data",
+          enum: %w[1 5 15 25 60]  # Updated from ["daily", "weekly", "monthly"]
+        ),
+        calculate_indicators: Ollama::Tool::Function::Parameters::Property.new(
+          type: "boolean",
+          description: "If true, returns technical indicators instead of raw data"
+        ),
+        # ... other properties
+      }
+    )
+  )
+)
+
+# Request with intraday and indicators
+response = client.chat_raw(
+  messages: [Ollama::Agent::Messages.user(
+    "Get NIFTY intraday data with 5-minute intervals and technical indicators"
+  )],
+  tools: historical_data_tool
+)
+```
+
+## Testing
+
+Run the updated tests:
+
+```bash
+# Tool calling examples
+ruby examples/test_dhanhq_tool_calling.rb
+ruby examples/test_tool_calling.rb
+
+# DhanHQ specific tests
+ruby examples/dhanhq/test_tool_calling.rb
+```
+
+## Notes
+
+- The `interval` parameter is now correctly defined for intraday minute intervals
+- The old values ("daily", "weekly", "monthly") were incorrect for the DhanHQ API
+- The new `calculate_indicators` parameter provides technical analysis without large response sizes
+- Tests now include date handling examples using `Date.today`