ollama-client 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b1ed7c3f2d09174f4127c92b0b22eef90fc3deb895dc86183d296a6a70cc3b4
-  data.tar.gz: f2d0737f5cbb77557fa736fb45f7a5c7c94fd939d1005c53d68e82d229844283
+  metadata.gz: 908909c57f4d7067168bcdcecce27471ea2587d6452aecb68aca2c25a8547839
+  data.tar.gz: fcbf8ee83cba0f05bcae0892e103ae1201a7db1b045c25848caf0d8a71ca891d
 SHA512:
-  metadata.gz: 04dcc1b56d68d715727f5f51bd9511d1c4b633369435e4f95008b2bb826d988d00df6fa307dc900fb0c8365b6f4bc0e111e17b4c74deb9c25360bfa36f6148cd
-  data.tar.gz: 8ea4bef981e5601dddd258a1f0dab481e76601f765bddc9783098bedc144cd1d0ceeb9e30b185541fa688ea8519fc796356a9ffe6abbc437a7dae6d93b757852
+  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

@@ -36,15 +36,15 @@ This keeps it **clean and future-proof**.
 
 ## 🔒 Guarantees
 
-| Guarantee                              | Yes |
-| -------------------------------------- | --- |
-| Client requests are explicit           | ✅   |
-| Planner is stateless (no hidden memory)| ✅   |
-| Executor is stateful (explicit messages)| ✅  |
-| Retry bounded                          | ✅   |
-| Schema validated (when schema provided)| ✅   |
-| Tools run in Ruby (not in the LLM)     | ✅   |
-| Streaming is display-only (Executor)   | ✅   |
+| Guarantee                                | Yes |
+| ---------------------------------------- | --- |
+| Client requests are explicit             | ✅   |
+| Planner is stateless (no hidden memory)  | ✅   |
+| Executor is stateful (explicit messages) | ✅   |
+| Retry bounded                            | ✅   |
+| Schema validated (when schema provided)  | ✅   |
+| Tools run in Ruby (not in the LLM)       | ✅   |
+| Streaming is display-only (Executor)     | ✅   |
 
 **Non-negotiable safety rule:** the **LLM never executes side effects**. It may request a tool call; **your Ruby code** executes the tool.
 
@@ -97,8 +97,8 @@ gem install ollama-client
 
 This gem intentionally focuses on **agent building blocks**:
 
-- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`
-- **Not guaranteed**: full endpoint parity with every Ollama release (embeddings, advanced model mgmt, etc.)
+- **Supported**: `/api/generate`, `/api/chat`, `/api/tags`, `/api/ping`, `/api/embeddings`
+- **Not guaranteed**: full endpoint parity with every Ollama release (advanced model mgmt, etc.)
 
 ### Agent endpoint mapping (unambiguous)
 
@@ -130,6 +130,8 @@ puts plan
 
 ### Executor Agent (tool loop, /api/chat)
 
+**Simple approach (auto-inferred schemas):**
+
 ```ruby
 require "ollama_client"
 require "json"
@@ -151,6 +153,68 @@ answer = executor.run(
 puts answer
 ```
 
+**Structured approach (explicit schemas with Tool classes):**
+
+```ruby
+require "ollama_client"
+
+# Define explicit tool schema
+location_prop = Ollama::Tool::Function::Parameters::Property.new(
+  type: "string",
+  description: "The city name"
+)
+
+params = Ollama::Tool::Function::Parameters.new(
+  type: "object",
+  properties: { city: location_prop },
+  required: %w[city]
+)
+
+function = Ollama::Tool::Function.new(
+  name: "fetch_weather",
+  description: "Get weather for a city",
+  parameters: params
+)
+
+tool = Ollama::Tool.new(type: "function", function: function)
+
+# Associate tool schema with callable
+tools = {
+  "fetch_weather" => {
+    tool: tool,
+    callable: ->(city:) { { city: city, forecast: "sunny" } }
+  }
+}
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+```
+
+Use structured tools when you need:
+- Explicit control over parameter types and descriptions
+- Enum constraints on parameters
+- Better documentation for complex tools
+- Serialization/deserialization (JSON storage, API responses)
+
+**DTO (Data Transfer Object) functionality:**
+
+All Tool classes support serialization and deserialization:
+
+```ruby
+# Serialize to JSON
+json = tool.to_json
+
+# Deserialize from hash
+tool = Ollama::Tool.from_hash(JSON.parse(json))
+
+# Equality comparison
+tool1 == tool2  # Compares hash representations
+
+# Empty check
+params.empty?  # True if no properties/required fields
+```
+
+See `examples/tool_dto_example.rb` for complete DTO usage examples.
+
 ### Streaming (Executor only; presentation-only)
 
 Streaming is treated as **presentation**, not control. The agent buffers the full assistant message and only
@@ -223,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
   )
@@ -407,6 +472,67 @@ rescue Ollama::Error => e
 end
 ```
 
+### Example: Tool Calling (Direct API Usage)
+
+For tool calling, use `chat_raw()` to access `tool_calls` from the response:
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# Define tool using Tool classes
+tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_current_weather",
+    description: "Get the current weather for a location",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        location: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The location to get the weather for, e.g. San Francisco, CA"
+        ),
+        temperature_unit: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The unit to return the temperature in",
+          enum: %w[celsius fahrenheit]
+        )
+      },
+      required: %w[location temperature_unit]
+    )
+  )
+)
+
+# Create message
+message = Ollama::Agent::Messages.user("What is the weather today in Paris?")
+
+# Use chat_raw() to get full response with tool_calls
+response = client.chat_raw(
+  model: "llama3.1:8b",
+  messages: [message],
+  tools: tool,  # Pass Tool object directly (or array of Tool objects)
+  allow_chat: true
+)
+
+# Access tool_calls from response
+tool_calls = response.dig("message", "tool_calls")
+if tool_calls && !tool_calls.empty?
+  tool_calls.each do |call|
+    name = call.dig("function", "name")
+    args = call.dig("function", "arguments")
+    puts "Tool: #{name}, Args: #{args}"
+  end
+end
+```
+
+**Note:**
+- `chat()` returns only the content (for simple use cases)
+- `chat_raw()` returns the full response with `message.tool_calls` (for tool calling)
+- Both methods accept `tools:` parameter (Tool object, array of Tool objects, or array of hashes)
+- For agent tool loops, use `Ollama::Agent::Executor` instead (handles tool execution automatically)
+
 ### Example: Data Analysis with Validation
 
 ```ruby
@@ -505,6 +631,83 @@ models = client.list_models
 puts "Available models: #{models.join(', ')}"
 ```
 
+### Embeddings for RAG/Semantic Search
+
+Use embeddings for building knowledge bases and semantic search in agents:
+
+```ruby
+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)
+
+# Multiple texts
+embeddings = client.embeddings.embed(
+  model: "all-minilm",
+  input: ["What is Ruby?", "What is Python?", "What is JavaScript?"]
+)
+# Returns: [[...], [...], [...]] (array of embedding arrays)
+
+# Use for semantic similarity in agents
+def find_similar(query_embedding, document_embeddings, threshold: 0.7)
+  document_embeddings.select do |doc_emb|
+    cosine_similarity(query_embedding, doc_emb) > threshold
+  end
+end
+```
+
+### Configuration from JSON
+
+Load configuration from JSON files for production deployments:
+
+```ruby
+require "ollama_client"
+
+# config.json:
+# {
+#   "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)
+```
+
+### Type-Safe Model Options
+
+Use the `Options` class for type-checked model parameters:
+
+```ruby
+require "ollama_client"
+
+# Options with validation
+options = Ollama::Options.new(
+  temperature: 0.7,
+  top_p: 0.95,
+  top_k: 40,
+  num_ctx: 4096,
+  seed: 42
+)
+
+# 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
+)
+```
+
 ### Error Handling
 
 ```ruby
@@ -675,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