ollama-client 0.2.4 → 0.2.6

data/examples/README.md

@@ -1,92 +1,77 @@
 # Examples
 
-This directory contains working examples demonstrating various features of the ollama-client gem.
+This directory contains **minimal examples** demonstrating `ollama-client` usage. These examples focus on **transport and protocol correctness**, not agent behavior.
 
-## Quick Start Examples
+## Minimal Examples
 
-### Basic Tool Calling
-- **[test_tool_calling.rb](test_tool_calling.rb)** - Simple tool calling demo with weather tool
-- **[tool_calling_pattern.rb](tool_calling_pattern.rb)** - Recommended patterns for tool calling
-- **[tool_calling_direct.rb](tool_calling_direct.rb)** - Direct tool calling without Executor
+### Basic Client Usage
 
-### DhanHQ Market Data
-- **[test_dhanhq_tool_calling.rb](test_dhanhq_tool_calling.rb)** - DhanHQ tools with updated intraday & indicators
-- **[dhanhq_tools.rb](dhanhq_tools.rb)** - DhanHQ API wrapper tools
-- **[dhan_console.rb](dhan_console.rb)** - Interactive DhanHQ console with planning
+- **[basic_generate.rb](basic_generate.rb)** - Basic `/generate` usage with schema validation
+  - Demonstrates stateless, deterministic JSON output
+  - Shows schema enforcement
+  - No agent logic
 
-### Multi-Step Agents
-- **[multi_step_agent_e2e.rb](multi_step_agent_e2e.rb)** - End-to-end multi-step agent example
-- **[multi_step_agent_with_external_data.rb](multi_step_agent_with_external_data.rb)** - Agent with external data integration
+- **[basic_chat.rb](basic_chat.rb)** - Basic `/chat` usage
+  - Demonstrates stateful message handling
+  - Shows multi-turn conversation structure
+  - No agent loops
 
-### Structured Data
-- **[structured_outputs_chat.rb](structured_outputs_chat.rb)** - Structured outputs with schemas
-- **[structured_tools.rb](structured_tools.rb)** - Structured tool definitions
-- **[tool_dto_example.rb](tool_dto_example.rb)** - Using DTOs for tool definitions
+- **[tool_calling_parsing.rb](tool_calling_parsing.rb)** - Tool-call parsing (no execution)
+  - Demonstrates tool-call detection and extraction
+  - Shows how to parse tool calls from LLM response
+  - **Does NOT execute tools** - that's agent responsibility
 
-### Advanced Features
-- **[advanced_multi_step_agent.rb](advanced_multi_step_agent.rb)** - Complex multi-step workflows
-- **[advanced_error_handling.rb](advanced_error_handling.rb)** - Error handling patterns
-- **[advanced_edge_cases.rb](advanced_edge_cases.rb)** - Edge case handling
-- **[advanced_complex_schemas.rb](advanced_complex_schemas.rb)** - Complex schema definitions
-- **[advanced_performance_testing.rb](advanced_performance_testing.rb)** - Performance testing
-
-### Interactive Consoles
-- **[chat_console.rb](chat_console.rb)** - Simple chat console with streaming
-- **[dhan_console.rb](dhan_console.rb)** - DhanHQ market data console with formatted tool results
-
-### Complete Workflows
-- **[complete_workflow.rb](complete_workflow.rb)** - Complete agent workflow example
-
-## DhanHQ Examples
-
-The `dhanhq/` subdirectory contains more specialized DhanHQ examples:
-- Technical analysis agents
-- Market scanners (intraday options, swing trading)
-- Pattern recognition and trend analysis
-- Multi-agent orchestration
-
-See [dhanhq/README.md](dhanhq/README.md) for details.
+- **[tool_dto_example.rb](tool_dto_example.rb)** - Tool DTO serialization
+  - Demonstrates Tool class serialization/deserialization
+  - Shows DTO functionality
 
 ## Running Examples
 
-Most examples are standalone and can be run directly:
+All examples are standalone and can be run directly:
 
 ```bash
-# Basic tool calling
-ruby examples/test_tool_calling.rb
+# Basic generate
+ruby examples/basic_generate.rb
+
+# Basic chat
+ruby examples/basic_chat.rb
 
-# DhanHQ with intraday data
-ruby examples/test_dhanhq_tool_calling.rb
+# Tool calling parsing
+ruby examples/tool_calling_parsing.rb
 
-# Interactive console
-ruby examples/chat_console.rb
+# Tool DTO
+ruby examples/tool_dto_example.rb
 ```
 
 ### Requirements
 
-Some examples require additional setup:
-
-**DhanHQ Examples:**
-- Set `DHANHQ_CLIENT_ID` and `DHANHQ_ACCESS_TOKEN` environment variables
-- Or create `.env` file with credentials
-
-**Ollama:**
 - Ollama server running (default: `http://localhost:11434`)
 - Set `OLLAMA_BASE_URL` if using a different URL
 - Set `OLLAMA_MODEL` if not using default model
 
-## Learning Path
+## Full Agent Examples
+
+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.
+
+## What These Examples Demonstrate
+
+These minimal examples prove:
+
+✅ **Transport layer** - HTTP requests/responses  
+✅ **Protocol correctness** - Request shaping, response parsing  
+✅ **Schema enforcement** - JSON validation  
+✅ **Tool-call parsing** - Detecting and extracting tool calls  
 
-1. **Start here:** `test_tool_calling.rb` - Learn basic tool calling
-2. **Structured data:** `structured_outputs_chat.rb` - Schema-based outputs
-3. **Multi-step:** `multi_step_agent_e2e.rb` - Complex agent workflows
-4. **Market data:** `test_dhanhq_tool_calling.rb` - Real-world API integration
-5. **Interactive:** `dhan_console.rb` - Full-featured console with planning
+These examples do **NOT** demonstrate:
 
-## Contributing
+❌ Agent loops  
+❌ Tool execution  
+❌ Convergence logic  
+❌ Policy decisions  
+❌ Domain-specific logic  
 
-When adding new examples:
-- Include clear comments explaining what the example demonstrates
-- Add `#!/usr/bin/env ruby` shebang at the top
-- Use `frozen_string_literal: true`
-- Update this README with a description
+**Those belong in the separate agent examples repository.**

data/examples/basic_chat.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic /chat usage
+# Demonstrates client transport layer - stateful message handling
+
+require_relative "../lib/ollama_client"
+
+client = Ollama::Client.new
+
+# Simple chat message
+response = client.chat_raw(
+  messages: [{ role: "user", content: "Say hello." }],
+  allow_chat: true
+)
+
+puts "Response: #{response.message.content}"
+puts "Role: #{response.message.role}"
+
+# Multi-turn conversation
+messages = [
+  { role: "user", content: "What is Ruby?" }
+]
+
+response1 = client.chat_raw(messages: messages, allow_chat: true)
+puts "\nFirst response: #{response1.message.content}"
+
+# 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 "\nSecond response: #{response2.message.content}"

data/examples/basic_generate.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Basic /generate usage with schema validation
+# Demonstrates client transport layer - stateless, deterministic JSON output
+
+require_relative "../lib/ollama_client"
+
+client = Ollama::Client.new
+
+# Define schema for structured output
+schema = {
+  "type" => "object",
+  "required" => ["status"],
+  "properties" => {
+    "status" => { "type" => "string" }
+  }
+}
+
+# Generate structured JSON response
+result = client.generate(
+  prompt: "Output a JSON object with a single key 'status' and value 'ok'.",
+  schema: schema
+)
+
+puts "Result: #{result.inspect}"
+puts "Status: #{result['status']}" # => "ok"
+
+# The result is guaranteed to match your schema!

data/examples/tool_calling_parsing.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Tool-call parsing (no execution)
+# Demonstrates client transport layer - tool-call detection and extraction
+# NOTE: This example does NOT execute tools. It only parses tool calls from the LLM response.
+
+require "json"
+require_relative "../lib/ollama_client"
+
+client = Ollama::Client.new
+
+# Define tool using Tool classes
+tool = Ollama::Tool.new(
+  type: "function",
+  function: Ollama::Tool::Function.new(
+    name: "get_weather",
+    description: "Get weather for a location",
+    parameters: Ollama::Tool::Function::Parameters.new(
+      type: "object",
+      properties: {
+        location: Ollama::Tool::Function::Parameters::Property.new(
+          type: "string",
+          description: "The city name"
+        )
+      },
+      required: %w[location]
+    )
+  )
+)
+
+# Request tool call from LLM
+response = client.chat_raw(
+  messages: [{ role: "user", content: "What's the weather in Paris?" }],
+  tools: tool,
+  allow_chat: true
+)
+
+# Parse tool calls (but do NOT execute)
+tool_calls = response.message&.tool_calls
+
+if tool_calls && !tool_calls.empty?
+  puts "Tool calls detected:"
+  tool_calls.each do |call|
+    # Access via method (if available)
+    name = call.respond_to?(:name) ? call.name : call["function"]["name"]
+    args = call.respond_to?(:arguments) ? call.arguments : JSON.parse(call["function"]["arguments"])
+
+    puts "  Tool: #{name}"
+    puts "  Arguments: #{args.inspect}"
+    puts "  (Tool execution would happen here in your agent code)"
+  end
+else
+  puts "No tool calls in response"
+  puts "Response: #{response.message&.content}"
+end
+
+# Alternative: Access via hash
+# tool_calls = response.to_h.dig("message", "tool_calls")

data/exe/ollama-client

@@ -1,4 +1,131 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative "../examples/chat_console"
+# Chat console using ChatSession with TTY reader for input only
+# Note: dotenv is automatically loaded by lib/ollama_client.rb
+require_relative "../lib/ollama_client"
+require "tty-reader"
+
+# Build config from environment or defaults
+config = Ollama::Config.new
+config.base_url = ENV["OLLAMA_BASE_URL"] if ENV["OLLAMA_BASE_URL"]
+config.model = ENV["OLLAMA_MODEL"] || config.model
+config.temperature = ENV["OLLAMA_TEMPERATURE"].to_f if ENV["OLLAMA_TEMPERATURE"]
+
+# Enable chat + streaming (required for ChatSession)
+config.allow_chat = true
+config.streaming_enabled = true
+
+client = Ollama::Client.new(config: config)
+
+# Create streaming observer for real-time token display
+observer = Ollama::StreamingObserver.new do |event|
+  case event.type
+  when :token
+    print event.text
+    $stdout.flush
+  when :tool_call_detected
+    puts "\n[Tool call: #{event.name}]"
+  when :final
+    puts "\n"
+  end
+end
+
+# Create chat session with optional system message from env
+system_prompt = ENV.fetch("OLLAMA_SYSTEM", "You are a helpful assistant.")
+chat = Ollama::ChatSession.new(client, system: system_prompt, stream: observer)
+
+# Setup TTY reader for input with history
+def build_reader
+  TTY::Reader.new
+end
+
+def read_input(reader)
+  # Pass prompt directly to read_line - this is how TTY::Reader is designed to work
+  reader.read_line("You: ")
+end
+
+HISTORY_PATH = File.expand_path("~/.ollama_chat_history")
+
+def load_history(reader, path)
+  return unless File.exist?(path)
+
+  File.readlines(path, chomp: true).reverse_each do |line|
+    reader.add_to_history(line) unless line.strip.empty?
+  end
+rescue StandardError
+  # Ignore history loading errors
+end
+
+def save_history(path, text)
+  return if text.strip.empty?
+
+  history = []
+  history = File.readlines(path, chomp: true) if File.exist?(path)
+  history.delete(text)
+  history.unshift(text)
+  history = history.first(200) # Limit history size
+
+  File.write(path, "#{history.join("\n")}\n")
+rescue StandardError
+  # Ignore history saving errors
+end
+
+# Print simple banner
+puts "Ollama Chat Console"
+puts "Model: #{config.model}"
+puts "Base URL: #{config.base_url}"
+puts "Type 'quit' or 'exit' to exit, 'clear' to reset history."
+puts
+
+# Setup reader and load history
+reader = build_reader
+load_history(reader, HISTORY_PATH)
+
+# Main loop
+begin
+  loop do
+    # Use TTY reader with prompt (supports history, arrow keys, editing)
+    input = read_input(reader)
+
+    break if input.nil?
+
+    text = input.strip
+    next if text.empty?
+
+    # Handle commands
+    case text.downcase
+    when "quit", "exit", "/quit", "/exit"
+      puts "\nGoodbye!\n"
+      break
+    when "clear", "/clear"
+      chat.clear
+      puts "Conversation history cleared.\n\n"
+      next
+    end
+
+    # Save to history
+    save_history(HISTORY_PATH, text)
+
+    # Assistant response
+    print "Assistant: "
+
+    begin
+      response = chat.say(text)
+      # Ensure newline after streaming
+      puts "" if response.empty?
+    rescue Ollama::ChatNotAllowedError => e
+      puts "\n❌ Error: #{e.message}"
+      puts "Make sure config.allow_chat = true"
+    rescue Ollama::Error => e
+      puts "\n❌ Error: #{e.message}"
+    end
+
+    puts "" # Blank line between exchanges
+  end
+rescue Interrupt
+  puts "\n\nInterrupted. Goodbye!\n"
+rescue StandardError => e
+  puts "\nUnexpected error: #{e.message}\n"
+  puts "#{e.backtrace.first}\n" if ENV["DEBUG"]
+end

data/lib/ollama/agent/planner.rb

@@ -21,17 +21,22 @@ module Ollama
         ]
       }.freeze
 
-      def initialize(client)
+      def initialize(client, system_prompt: nil)
         @client = client
+        @system_prompt = system_prompt
       end
 
       # @param prompt [String]
       # @param context [Hash, nil]
       # @param schema [Hash, nil]
+      # @param system_prompt [String, nil] Optional system prompt override for this call
       # @return [Object] Parsed JSON (Hash/Array/String/Number/Boolean/Nil)
-      def run(prompt:, context: nil, schema: nil)
+      def run(prompt:, context: nil, schema: nil, system_prompt: nil)
+        effective_system = system_prompt || @system_prompt
         full_prompt = prompt.to_s
 
+        full_prompt = "#{effective_system}\n\n#{full_prompt}" if effective_system && !effective_system.empty?
+
         if context && !context.empty?
           full_prompt = "#{full_prompt}\n\nContext (JSON):\n#{JSON.pretty_generate(context)}"
         end

data/lib/ollama/chat_session.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "streaming_observer"
+require_relative "agent/messages"
+
+module Ollama
+  # Stateful chat session for human-facing interactions.
+  #
+  # Chat sessions maintain conversation history and support streaming
+  # for presentation purposes. They are isolated from agent internals
+  # to preserve deterministic behavior in schema-first workflows.
+  #
+  # Example:
+  #   client = Ollama::Client.new(config: Ollama::Config.new.tap { |c| c.allow_chat = true })
+  #   observer = Ollama::StreamingObserver.new do |event|
+  #     print event.text if event.type == :token
+  #   end
+  #   chat = Ollama::ChatSession.new(client, system: "You are helpful", stream: observer)
+  #   chat.say("Hello")
+  #   chat.say("Explain Ruby blocks")
+  class ChatSession
+    attr_reader :messages
+
+    def initialize(client, system: nil, stream: nil)
+      @client = client
+      @messages = []
+      @stream = stream
+      @messages << Agent::Messages.system(system) if system
+    end
+
+    # Send a user message and get assistant response.
+    #
+    # @param text [String] User message text
+    # @param model [String, nil] Model override (uses client config if nil)
+    # @param format [Hash, nil] Optional JSON schema for formatting (best-effort, not guaranteed)
+    # @param tools [Tool, Array<Tool>, Array<Hash>, nil] Optional tool definitions
+    # @param options [Hash] Additional options (temperature, top_p, etc.)
+    # @return [String] Assistant response content
+    def say(text, model: nil, format: nil, tools: nil, options: {})
+      @messages << Agent::Messages.user(text)
+
+      response = if @stream
+                   stream_response(model: model, format: format, tools: tools, options: options)
+                 else
+                   non_stream_response(model: model, format: format, tools: tools, options: options)
+                 end
+
+      content = response["message"]&.dig("content") || ""
+      tool_calls = response["message"]&.dig("tool_calls")
+
+      @messages << Agent::Messages.assistant(content, tool_calls: tool_calls) if content || tool_calls
+
+      content
+    end
+
+    # Clear conversation history (keeps system message if present).
+    def clear
+      system_msg = @messages.find { |m| m["role"] == "system" }
+      @messages = system_msg ? [system_msg] : []
+    end
+
+    private
+
+    def stream_response(model:, format:, tools:, options:)
+      @client.chat_raw(
+        messages: @messages,
+        model: model,
+        format: format,
+        tools: tools,
+        options: options,
+        allow_chat: true,
+        stream: true
+      ) do |chunk|
+        delta = chunk.dig("message", "content")
+        @stream.emit(:token, text: delta.to_s) if delta && !delta.to_s.empty?
+
+        calls = chunk.dig("message", "tool_calls")
+        if calls.is_a?(Array)
+          calls.each do |call|
+            name = call.dig("function", "name") || call["name"]
+            @stream.emit(:tool_call_detected, name: name, data: call) if name
+          end
+        end
+
+        # Emit final event when stream completes
+        @stream.emit(:final) if chunk["done"] == true
+      end
+    end
+
+    def non_stream_response(model:, format:, tools:, options:)
+      @client.chat_raw(
+        messages: @messages,
+        model: model,
+        format: format,
+        tools: tools,
+        options: options,
+        allow_chat: true
+      )
+    end
+  end
+end

data/lib/ollama/client.rb

@@ -206,7 +206,9 @@ module Ollama
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
 
-    def generate(prompt:, schema:, model: nil, strict: false, return_meta: false)
+    def generate(prompt:, schema: nil, model: nil, strict: false, return_meta: false)
+      validate_generate_params!(prompt, schema)
+
       attempts = 0
       @current_schema = schema # Store for prompt enhancement
       started_at = monotonic_time
@@ -227,23 +229,12 @@ module Ollama
           }
         )
 
-        parsed = parse_json_response(raw)
-
-        # CRITICAL: If schema is provided, free-text output is forbidden
-        raise SchemaViolationError, "Empty or nil response when schema is required" if parsed.nil? || parsed.empty?
-
-        SchemaValidator.validate!(parsed, schema)
-        return parsed unless return_meta
-
-        {
-          "data" => parsed,
-          "meta" => {
-            "endpoint" => "/api/generate",
-            "model" => model || @config.model,
-            "attempts" => attempts,
-            "latency_ms" => elapsed_ms(started_at)
-          }
+        meta = {
+          model: model || @config.model,
+          attempts: attempts,
+          started_at: started_at
         }
+        process_generate_response(raw: raw, schema: schema, meta: meta, return_meta: return_meta)
       rescue NotFoundError => e
         # 404 errors are never retried, but we can suggest models
         enhanced_error = enhance_not_found_error(e)
@@ -267,7 +258,7 @@ module Ollama
     end
     # rubocop:enable Metrics/MethodLength
 
-    def generate_strict!(prompt:, schema:, model: nil, return_meta: false)
+    def generate_strict!(prompt:, schema: nil, model: nil, return_meta: false)
       generate(prompt: prompt, schema: schema, model: model, strict: true, return_meta: return_meta)
     end
 
@@ -348,12 +339,43 @@ module Ollama
 
     private
 
+    def validate_generate_params!(prompt, _schema)
+      raise ArgumentError, "prompt is required" if prompt.nil?
+      # schema is optional - nil means plain text/markdown response
+    end
+
+    def process_generate_response(raw:, schema:, meta:, return_meta:)
+      response_data = schema ? parse_and_validate_schema_response(raw, schema) : raw
+      return response_data unless return_meta
+
+      {
+        "data" => response_data,
+        "meta" => {
+          "endpoint" => "/api/generate",
+          "model" => meta[:model],
+          "attempts" => meta[:attempts],
+          "latency_ms" => elapsed_ms(meta[:started_at])
+        }
+      }
+    end
+
+    def parse_and_validate_schema_response(raw, schema)
+      parsed = parse_json_response(raw)
+      raise SchemaViolationError, "Empty or nil response when schema is required" if parsed.nil? || parsed.empty?
+
+      SchemaValidator.validate!(parsed, schema)
+      parsed
+    end
+
     def ensure_chat_allowed!(allow_chat:, strict:, method_name:)
-      return if allow_chat || strict
+      return if allow_chat || strict || @config.allow_chat
 
-      raise Error,
+      raise ChatNotAllowedError,
             "#{method_name}() is intentionally gated because it is easy to misuse inside agents. " \
-            "Prefer generate(). If you really want #{method_name}(), pass allow_chat: true (or strict: true)."
+            "Prefer generate() for deterministic, schema-first workflows. " \
+            "To use #{method_name}(), either: " \
+            "1) Pass allow_chat: true as a parameter, or " \
+            "2) Enable chat in config: config.allow_chat = true"
     end
 
     # Normalize tools to array of hashes for API

data/lib/ollama/config.rb

@@ -15,7 +15,8 @@ module Ollama
   #   client = Ollama::Client.new(config: config)
   #
   class Config
-    attr_accessor :base_url, :model, :timeout, :retries, :temperature, :top_p, :num_ctx, :on_response
+    attr_accessor :base_url, :model, :timeout, :retries, :temperature, :top_p, :num_ctx, :on_response, :allow_chat,
+                  :streaming_enabled
 
     def initialize
       @base_url = "http://localhost:11434"
@@ -26,6 +27,8 @@ module Ollama
       @top_p = 0.9
       @num_ctx = 8192
       @on_response = nil
+      @allow_chat = false
+      @streaming_enabled = false
     end
 
     # Load configuration from JSON file (useful for production deployments)