ollama-client 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86bef7e3dc6197748e9d75572705cec97bc94a24da8c9e8f7402d9b5db1e1dc8
-  data.tar.gz: 1ae799bfc340896179b3819350b81fe852c8f2b944f6987cf4f8c76b61791153
+  metadata.gz: 908909c57f4d7067168bcdcecce27471ea2587d6452aecb68aca2c25a8547839
+  data.tar.gz: fcbf8ee83cba0f05bcae0892e103ae1201a7db1b045c25848caf0d8a71ca891d
 SHA512:
-  metadata.gz: 1b4a54c4625c0bcb947d74e914bedc0f974e6b0bbaad6f4f46673b8dce5eb6956c5a3bc75745845ccd7f79830149a24ad1e49c54bc03ef165c39ed71d14a92db
-  data.tar.gz: e2ce9114ab3396d65a3075f80c1d273e0d414d2d8be0d4bae4b5e1717fdc62451d2a57590d59e191be86613280fbbd925201ba9d1285a95a2d0cdfabdafc25c3
+  metadata.gz: 67800e85b23a59fd9717ec76a2d27a591538d1813846213cb095d853d41547d6da3bbb10b8096a05b500bec66576a2e0f9268a5ad8738a9c0176b8f2051a99eb
+  data.tar.gz: 1bb186cb330c6fec601ed909af0fa9ef9bee786827edeb9195955ed25e7d0e8ab1d2eb81c302e47806cf304014ad847c207cc05f7b881392f936413419158714

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+- Add tag-triggered GitHub Actions release workflow for RubyGems publishing.
+
+## [0.2.3] - 2026-01-17
+
+- Add per-call `model:` override for `Ollama::Client#generate`.
+- Document `generate` model override usage in README.
+- Add spec to cover per-call `model:` in 404 error path.
+
 ## [0.2.0] - 2026-01-12
 
 - Add `Ollama::Agent::Planner` (stateless `/api/generate`)

data/README.md

@@ -287,6 +287,7 @@ schema = {
 # 2. Call the LLM with your schema
 begin
   result = client.generate(
+    model: "llama3.1:8b",
     prompt: "Your prompt here",
     schema: schema
   )
@@ -877,7 +878,12 @@ ruby examples/advanced_multi_step_agent.rb
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+To release a new version, update `lib/ollama/version.rb` and `CHANGELOG.md`, then commit. You can:
+
+- Run `bundle exec rake release` locally to create the tag, push commits/tags, and publish to [rubygems.org](https://rubygems.org).
+- Push a tag `vX.Y.Z` to trigger the GitHub Actions release workflow, which builds and publishes the gem using the `RUBYGEMS_API_KEY` secret.
 
 ## Contributing
 

data/docs/CLOUD.md

@@ -0,0 +1,29 @@
+# Cloud Agent Guide
+
+This repository is a Ruby gem. It has no database and does not require
+application secrets for the default test suite.
+
+## Required Commands
+- `bundle install`
+- `bundle exec rubocop`
+- `bundle exec rspec`
+
+## Agent Prompt Template
+You are operating on a Ruby gem repository.
+Task:
+1. Run `bundle exec rubocop`.
+2. Fix all RuboCop offenses.
+3. Re-run RuboCop until clean.
+4. Run `bundle exec rspec`.
+5. Fix all failing specs.
+6. Re-run RSpec until green.
+
+Rules:
+- Do not skip failures.
+- Do not change public APIs without reporting.
+- Do not bump gem version unless explicitly told.
+- Stop if blocked and explain why.
+
+## Guardrails
+- Keep API surface stable and backward compatible.
+- Update specs when behavior changes.

data/docs/CONSOLE_IMPROVEMENTS.md

@@ -0,0 +1,256 @@
+# Console Improvements
+
+## Overview
+
+Enhanced the interactive console experiences (`chat_console.rb` and `dhan_console.rb`) to provide better user feedback and cleaner output formatting.
+
+## Chat Console (`chat_console.rb`)
+
+### Problem
+
+When the LLM was processing a response, the `llm>` prompt appeared immediately, making it look like it was waiting for user input. This caused confusion where users would start typing, thinking it was a prompt.
+
+### Solution
+
+Added a **thinking indicator** that shows while waiting for the API response:
+
+**Before:**
+```
+you> Hi
+llm> [cursor blinks here - looks like a prompt!]
+[user types something]
+[then response appears]
+```
+
+**After:**
+```
+you> Hi
+... [thinking indicator in cyan]
+llm> Hey! How can I help you?
+you> [clear prompt for next input]
+```
+
+### Implementation
+
+```ruby
+def chat_response(client, messages, config)
+  content = +""
+  prompt_printed = false
+
+  # Show thinking indicator
+  print "#{COLOR_LLM}...#{COLOR_RESET}"
+  $stdout.flush
+
+  client.chat_raw(...) do |chunk|
+    token = chunk.dig("message", "content").to_s
+    next if token.empty?
+
+    # Replace thinking indicator with llm> on first token
+    unless prompt_printed
+      print "\r#{LLM_PROMPT}"
+      prompt_printed = true
+    end
+
+    content << token
+    print token
+    $stdout.flush
+  end
+
+  puts
+  content
+end
+```
+
+**Key Changes:**
+- `\r` (carriage return) replaces `...` with `llm>` when first token arrives
+- `$stdout.flush` ensures immediate visual feedback
+- Clear visual state: thinking → responding → ready for input
+
+## DhanHQ Console (`dhan_console.rb`)
+
+### Problem
+
+Tool results were displayed as raw JSON dumps, making it hard to quickly understand:
+- **Which tool** was called
+- **What data** was retrieved
+- **Key information** from the response
+
+**Before:**
+```
+Tool Results:
+- get_live_ltp
+{
+  "action": "get_live_ltp",
+  "params": {
+    "security_id": "13",
+    "symbol": "NIFTY",
+    "exchange_segment": "IDX_I"
+  },
+  "result": {
+    "security_id": "13",
+    "exchange_segment": "IDX_I",
+    "ltp": 25694.35,
+    "ltp_data": {
+      "last_price": 25694.35
+    },
+    "symbol": "NIFTY"
+  }
+}
+```
+
+### Solution
+
+Implemented **formatted, human-readable tool results** that extract and display key information:
+
+**After:**
+```
+🔧 Tool Called: get_live_ltp
+   → NIFTY (IDX_I)
+   → Last Price: ₹25694.35
+
+llm> The current price of NIFTY is 25694.35.
+```
+
+### Formatted Output by Tool
+
+#### 1. Live LTP (`get_live_ltp`)
+```
+🔧 Tool Called: get_live_ltp
+   → NIFTY (IDX_I)
+   → Last Price: ₹25694.35
+```
+
+#### 2. Market Quote (`get_market_quote`)
+```
+🔧 Tool Called: get_market_quote
+   → RELIANCE
+   → LTP: ₹1457.9
+   → OHLC: O:1458.8 H:1480.0 L:1455.1 C:1457.9
+   → Volume: 17167161
+```
+
+#### 3. Historical Data (`get_historical_data`)
+
+**Regular data:**
+```
+🔧 Tool Called: get_historical_data
+   → Historical data: 30 records
+   → Interval: 5
+```
+
+**With indicators:**
+```
+🔧 Tool Called: get_historical_data
+   → Technical Indicators:
+   →   Current Price: ₹25694.35
+   →   RSI(14): 56.32
+   →   MACD: 12.45
+   →   SMA(20): ₹25680.12
+   →   SMA(50): ₹25550.45
+```
+
+#### 4. Option Chain (`get_option_chain`)
+```
+🔧 Tool Called: get_option_chain
+   → Spot: ₹25694.35
+   → Strikes: 15
+   → (Filtered: ATM/OTM/ITM with both CE & PE)
+```
+
+#### 5. Expiry List (`get_expiry_list`)
+```
+🔧 Tool Called: get_expiry_list
+   → Available expiries: 12
+   → Next expiry: 2026-01-20
+   → Expiries: 2026-01-20, 2026-01-27, 2026-02-03, 2026-02-10, 2026-02-17...
+```
+
+#### 6. Find Instrument (`find_instrument`)
+```
+🔧 Tool Called: find_instrument
+   → Found: NIFTY
+   → Security ID: 13
+   → Exchange: IDX_I
+```
+
+### Implementation
+
+```ruby
+def print_formatted_result(tool_name, content)
+  result = content.dig("result") || content
+
+  case tool_name
+  when "get_live_ltp"
+    print_ltp_result(result)
+  when "get_market_quote"
+    print_quote_result(result)
+  when "get_historical_data"
+    print_historical_result(result, content)
+  # ... other tool formatters
+  end
+end
+```
+
+Each tool has a dedicated formatter that:
+1. Extracts key information from the result
+2. Formats it in a human-readable way
+3. Uses color coding for better readability
+4. Shows relevant details without overwhelming the user
+
+## Benefits
+
+### Chat Console
+✅ **Clear visual feedback** - Users know when the LLM is thinking vs responding
+✅ **No confusion** - Thinking indicator prevents accidental typing
+✅ **Better UX** - Immediate response to user input
+
+### DhanHQ Console
+✅ **Instant comprehension** - See what tool was called at a glance
+✅ **Key data highlighted** - Important values (price, volume) are prominent
+✅ **Less noise** - No JSON clutter, just the facts
+✅ **Consistent formatting** - Each tool type has predictable output
+✅ **Professional appearance** - Clean, organized display with icons
+
+## Configuration
+
+Both consoles support environment variables:
+
+**Chat Console:**
+```bash
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=llama3.1:8b
+OLLAMA_TEMPERATURE=0.7
+OLLAMA_SYSTEM="You are a helpful assistant"
+```
+
+**DhanHQ Console:**
+```bash
+# All chat console vars, plus:
+DHANHQ_CLIENT_ID=your_client_id
+DHANHQ_ACCESS_TOKEN=your_token
+SHOW_PLAN=true              # Show planning step
+ALLOW_NO_TOOL_OUTPUT=false  # Require tool calls
+```
+
+## Testing
+
+```bash
+# Test chat console with thinking indicator
+ruby examples/chat_console.rb
+
+# Test DhanHQ console with formatted results
+ruby examples/dhan_console.rb
+```
+
+Try queries like:
+- "What is NIFTY price?" → See formatted LTP
+- "Get RELIANCE quote" → See formatted quote with OHLC
+- "Show me historical data for NIFTY" → See record count
+- "Get option chain for NIFTY" → See filtered strikes
+
+## Related Files
+
+- `examples/chat_console.rb` - Simple chat with thinking indicator
+- `examples/dhan_console.rb` - Market data with formatted tool results
+- `examples/dhanhq_tools.rb` - Underlying DhanHQ tool implementations
+- `docs/TESTING.md` - Testing guide

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`