ollama-client 0.2.5 → 0.2.7

data/examples/mcp_executor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Example: Use a local MCP server's tools with Ollama::Agent::Executor.
+#
+# Prerequisites:
+#   - Ollama running (localhost:11434)
+#   - Node.js/npx (for @modelcontextprotocol/server-filesystem)
+#
+# Run:
+#   ruby examples/mcp_executor.rb
+#
+# This connects to the MCP filesystem server, fetches its tools, and runs
+# the Executor so the LLM can call those tools (e.g. list directory, read file).
+
+require_relative "../lib/ollama_client"
+
+ollama = Ollama::Client.new
+
+# Local MCP server via stdio; allow /tmp and the project directory
+project_root = File.expand_path("..", __dir__)
+mcp_client = Ollama::MCP::StdioClient.new(
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp", project_root],
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(stdio_client: mcp_client)
+tools = bridge.tools_for_executor
+
+executor = Ollama::Agent::Executor.new(ollama, tools: tools)
+
+answer = executor.run(
+  system: "You have access to filesystem tools. Use them when the user asks about files or directories.",
+  user: "What files are in  ~/project/ollama-client? List a few."
+)
+
+puts answer
+
+mcp_client.close

data/examples/mcp_http_executor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Example: Use a remote MCP server (HTTP URL) with Ollama::Agent::Executor.
+#
+# Works with GitMCP and any MCP-over-HTTP endpoint:
+#   https://gitmcp.io/owner/repo  → MCP server for that GitHub repo
+#
+# Prerequisites:
+#   - Ollama running (localhost:11434)
+#   - Network access to the MCP URL
+#
+# Run:
+#   ruby examples/mcp_http_executor.rb
+#
+# To add this MCP to Cursor, use ~/.cursor/mcp.json:
+#   {
+#     "mcpServers": {
+#       "agent-runtime Docs": {
+#         "url": "https://gitmcp.io/shubhamtaywade82/agent-runtime"
+#       }
+#     }
+#   }
+
+require "ollama_client"
+
+client = Ollama::Client.new
+
+mcp_client = Ollama::MCP::HttpClient.new(
+  url: "https://gitmcp.io/shubhamtaywade82/agent-runtime",
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(client: mcp_client)
+tools = bridge.tools_for_executor
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+
+answer = executor.run(
+  system: "You have access to the agent-runtime repository docs. Use tools when the user asks about the repo.",
+  user: "What does this repository do? Summarize briefly."
+)
+
+puts answer
+
+mcp_client.close

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

@@ -207,6 +207,8 @@ module Ollama
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists
 
     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,39 +229,12 @@ module Ollama
           }
         )
 
-        # If no schema provided, return plain text/markdown
-        unless schema
-          return raw unless return_meta
-
-          return {
-            "data" => raw,
-            "meta" => {
-              "endpoint" => "/api/generate",
-              "model" => model || @config.model,
-              "attempts" => attempts,
-              "latency_ms" => elapsed_ms(started_at)
-            }
-          }
-        end
-
-        # Schema provided - parse and validate JSON
-        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)
@@ -364,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

@@ -6,16 +6,19 @@ module Ollama
   # Configuration class with safe defaults for agent-grade usage
   #
   # ⚠️ THREAD SAFETY WARNING:
-  # Global configuration via OllamaClient.configure is NOT thread-safe.
-  # For concurrent agents or multi-threaded applications, use per-client
-  # configuration instead:
+  # Global configuration access is mutex-protected, but modifying global config
+  # while clients are active can cause race conditions. For concurrent agents
+  # or multi-threaded applications, use per-client configuration (recommended):
   #
   #   config = Ollama::Config.new
   #   config.model = "llama3.1"
   #   client = Ollama::Client.new(config: config)
   #
+  # Each client instance with its own config is thread-safe.
+  #
   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 +29,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)

data/lib/ollama/document_loader.rb

@@ -150,7 +150,7 @@ module Ollama
         end
       end
 
-      "CSV Data:\n" + text_rows.join("\n")
+      "CSV Data:\n#{text_rows.join("\n")}"
     end
 
     def parse_json(content)

data/lib/ollama/embeddings.rb

@@ -21,7 +21,8 @@ module Ollama
     # @param input [String, Array<String>] Single text or array of texts
     # @return [Array<Float>, Array<Array<Float>>] Embedding vector(s)
     def embed(model:, input:)
-      uri = URI("#{@config.base_url}/api/embeddings")
+      # Use /api/embed (not /api/embeddings) - the working endpoint
+      uri = URI("#{@config.base_url}/api/embed")
       req = Net::HTTP::Post.new(uri)
       req["Content-Type"] = "application/json"
 
@@ -42,35 +43,12 @@ module Ollama
       handle_http_error(res, requested_model: model) unless res.is_a?(Net::HTTPSuccess)
 
       response_body = JSON.parse(res.body)
-      embedding = response_body["embedding"]
+      # /api/embed returns "embeddings" (plural) as array of arrays
+      embeddings = response_body["embeddings"] || response_body["embedding"]
 
-      if embedding.nil?
-        raise Error,
-              "Embedding not found in response. Response keys: #{response_body.keys.join(", ")}. Full response: #{response_body.inspect[0..200]}"
-      end
-
-      if embedding.is_a?(Array) && embedding.empty?
-        error_msg = "Empty embedding returned. This usually means:\n"
-        error_msg += "  1. The model may not be properly loaded - try: ollama pull #{model}\n"
-        error_msg += "  2. The model may not support embeddings - verify it's an embedding model\n"
-        error_msg += "  3. Check if the model is working: curl http://localhost:11434/api/embeddings -d '{\"model\":\"#{model}\",\"input\":\"test\"}'\n"
-        error_msg += "Response: #{response_body.inspect[0..300]}"
-        raise Error, error_msg
-      end
+      validate_embedding_response!(embeddings, response_body, model)
 
-      # Return single array for single input, or array of arrays for multiple inputs
-      if input.is_a?(Array)
-        # Ollama returns single embedding array even for multiple inputs
-        # We need to check the response structure
-        if embedding.is_a?(Array) && embedding.first.is_a?(Array)
-          embedding
-        else
-          # Single embedding returned, wrap it
-          [embedding]
-        end
-      else
-        embedding
-      end
+      format_embedding_result(embeddings, input)
     rescue JSON::ParserError => e
       raise InvalidJSONError, "Failed to parse embeddings response: #{e.message}"
     rescue Net::ReadTimeout, Net::OpenTimeout
@@ -81,6 +59,61 @@ module Ollama
 
     private
 
+    def validate_embedding_response!(embeddings, response_body, model)
+      if embeddings.nil?
+        keys = response_body.keys.join(", ")
+        response_preview = response_body.inspect[0..200]
+        raise Error, "Embeddings not found in response. Response keys: #{keys}. " \
+                     "Full response: #{response_preview}"
+      end
+
+      # Handle both formats: array of arrays [[...]] or single array [...]
+      # Check if it's empty or contains empty arrays
+      if embeddings.is_a?(Array) && (embeddings.empty? || (embeddings.first.is_a?(Array) && embeddings.first.empty?))
+        error_msg = build_empty_embedding_error_message(model, response_body)
+        raise Error, error_msg
+      end
+
+      nil
+    end
+
+    def build_empty_embedding_error_message(model, response_body)
+      curl_command = "curl -X POST http://localhost:11434/api/embed " \
+                     "-d '{\"model\":\"#{model}\",\"input\":\"test\"}'"
+      response_preview = response_body.inspect[0..300]
+
+      # Check for error messages in response
+      error_hint = ""
+      if response_body.is_a?(Hash)
+        if response_body.key?("error")
+          error_hint = "\n  Error from Ollama: #{response_body["error"]}"
+        elsif response_body.key?("message")
+          error_hint = "\n  Message from Ollama: #{response_body["message"]}"
+        end
+      end
+
+      "Empty embedding returned. This usually means:\n  " \
+        "1. The model may not be properly loaded - try: ollama pull #{model}\n  " \
+        "2. The model file may be corrupted - try: ollama rm #{model} && ollama pull #{model}\n  " \
+        "3. The model may not support embeddings - verify it's an embedding model\n  " \
+        "4. Check if the model is working: #{curl_command}#{error_hint}\n" \
+        "Response: #{response_preview}"
+    end
+
+    def format_embedding_result(embeddings, input)
+      # /api/embed returns "embeddings" as array of arrays [[...]]
+      # For single input, it's [[...]], for multiple inputs it's [[...], [...], ...]
+      if embeddings.is_a?(Array) && embeddings.first.is_a?(Array)
+        # Already in correct format (array of arrays)
+        # For single input, return first embedding array
+        # For multiple inputs, return all embedding arrays
+        input.is_a?(Array) ? embeddings : embeddings.first
+      else
+        # Fallback: single array format (shouldn't happen with /api/embed)
+        input.is_a?(Array) ? [embeddings] : embeddings
+      end
+    end
+
     def handle_http_error(res, requested_model: nil)
       status_code = res.code.to_i
       raise NotFoundError.new(res.message, requested_model: requested_model) if status_code == 404

data/lib/ollama/errors.rb

@@ -6,6 +6,7 @@ module Ollama
   class InvalidJSONError < Error; end
   class SchemaViolationError < Error; end
   class RetryExhaustedError < Error; end
+  class ChatNotAllowedError < Error; end
 
   # HTTP error with retry logic
   class HTTPError < Error