ollama-client 0.2.5 → 0.2.7

data/lib/ollama/mcp/http_client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Ollama
+  module MCP
+    # Connects to a remote MCP server via HTTP(S).
+    # Sends JSON-RPC via POST; supports session ID from initialize response.
+    # Use for URLs like https://gitmcp.io/owner/repo.
+    class HttpClient
+      PROTOCOL_VERSION = "2025-11-25"
+
+      def initialize(url:, timeout_seconds: 30, headers: {})
+        @uri = URI(url)
+        @uri.path = "/" if @uri.path.nil? || @uri.path.empty?
+        @timeout = timeout_seconds
+        @extra_headers = headers.transform_keys(&:to_s)
+        @request_id = 0
+        @session_id = nil
+        @initialized = false
+      end
+
+      def start
+        return if @initialized
+
+        run_initialize
+        @initialized = true
+      end
+
+      def tools
+        start
+        response = request("tools/list", {})
+        list = response.dig("result", "tools")
+        return [] unless list.is_a?(Array)
+
+        list.map do |t|
+          {
+            name: (t["name"] || t[:name]).to_s,
+            description: (t["description"] || t[:description]).to_s,
+            input_schema: t["inputSchema"] || t[:input_schema] || { "type" => "object" }
+          }
+        end
+      end
+
+      def call_tool(name:, arguments: {})
+        start
+        response = request("tools/call", "name" => name.to_s, "arguments" => stringify_keys(arguments))
+        result = response["result"]
+        raise Ollama::Error, "tools/call failed: #{response["error"]}" if response["error"]
+        raise Ollama::Error, "tools/call returned no result" unless result
+
+        content_to_string(result["content"])
+      end
+
+      def close
+        @session_id = nil
+        @initialized = false
+      end
+
+      private
+
+      def run_initialize
+        init_params = {
+          "protocolVersion" => PROTOCOL_VERSION,
+          "capabilities" => {},
+          "clientInfo" => {
+            "name" => "ollama-client",
+            "version" => Ollama::VERSION
+          }
+        }
+        response = request("initialize", init_params)
+        raise Ollama::Error, "initialize failed: #{response["error"]}" if response["error"]
+
+        send_notification("notifications/initialized", {})
+      end
+
+      def next_id
+        @request_id += 1
+      end
+
+      def request(method, params)
+        id = next_id
+        msg = { "jsonrpc" => "2.0", "id" => id, "method" => method, "params" => params }
+        post_request(msg, method: method)
+      end
+
+      def send_notification(method, params)
+        body = { "jsonrpc" => "2.0", "method" => method, "params" => params }
+        post_request(body, method: method)
+      end
+
+      def post_request(body, method: nil)
+        req = Net::HTTP::Post.new(@uri)
+        req["Content-Type"] = "application/json"
+        req["Accept"] = "application/json, text/event-stream"
+        req["MCP-Protocol-Version"] = PROTOCOL_VERSION
+        req["MCP-Session-Id"] = @session_id if @session_id
+        @extra_headers.each { |k, v| req[k] = v }
+        req.body = body.is_a?(Hash) ? JSON.generate(body) : body.to_s
+
+        res = http_request(req)
+
+        if method == "initialize" && res["MCP-Session-Id"]
+          @session_id = res["MCP-Session-Id"].to_s.strip
+          @session_id = nil if @session_id.empty?
+        end
+
+        return {} if res.code == "202"
+
+        raise Ollama::Error, "MCP HTTP error: #{res.code} #{res.message}" unless res.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(res.body)
+      end
+
+      def http_request(req)
+        Net::HTTP.start(
+          @uri.hostname,
+          @uri.port,
+          use_ssl: @uri.scheme == "https",
+          read_timeout: @timeout,
+          open_timeout: @timeout
+        ) { |http| http.request(req) }
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        raise Ollama::TimeoutError, "MCP server did not respond within #{@timeout}s"
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+        raise Ollama::Error, "MCP connection failed: #{e.message}"
+      end
+
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.transform_keys(&:to_s)
+      end
+
+      def content_to_string(content)
+        return "" unless content.is_a?(Array)
+
+        content.filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          text = item["text"] || item[:text]
+          text&.to_s
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/ollama/mcp/stdio_client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ollama
+  module MCP
+    # Connects to a local MCP server via stdio (spawns subprocess).
+    # Handles JSON-RPC lifecycle: initialize, tools/list, tools/call.
+    class StdioClient
+      PROTOCOL_VERSION = "2025-11-25"
+
+      def initialize(command:, args: [], env: {}, timeout_seconds: 30)
+        @command = command
+        @args = Array(args)
+        @env = env
+        @timeout = timeout_seconds
+        @request_id = 0
+        @reader = nil
+        @writer = nil
+        @initialized = false
+      end
+
+      def start
+        return if @initialized
+
+        env_merged = ENV.to_h.merge(@env.transform_keys(&:to_s))
+        stdin, stdout = Open3.popen2(env_merged, @command, *@args)
+        @writer = stdin
+        @reader = stdout
+        run_initialize
+        @initialized = true
+      end
+
+      def tools
+        start
+        response = request("tools/list", {})
+        list = response.dig("result", "tools")
+        return [] unless list.is_a?(Array)
+
+        list.map do |t|
+          {
+            name: (t["name"] || t[:name]).to_s,
+            description: (t["description"] || t[:description]).to_s,
+            input_schema: t["inputSchema"] || t[:input_schema] || { "type" => "object" }
+          }
+        end
+      end
+
+      def call_tool(name:, arguments: {})
+        start
+        response = request("tools/call", "name" => name.to_s, "arguments" => stringify_keys(arguments))
+        result = response["result"]
+        raise Ollama::Error, "tools/call failed: #{response["error"]}" if response["error"]
+        raise Ollama::Error, "tools/call returned no result" unless result
+
+        content_to_string(result["content"])
+      end
+
+      def close
+        return unless @writer
+
+        @writer.close
+        @writer = nil
+        @reader = nil
+        @initialized = false
+      end
+
+      private
+
+      def run_initialize
+        init_params = {
+          "protocolVersion" => PROTOCOL_VERSION,
+          "capabilities" => {},
+          "clientInfo" => {
+            "name" => "ollama-client",
+            "version" => Ollama::VERSION
+          }
+        }
+        response = request("initialize", init_params)
+        raise Ollama::Error, "initialize failed: #{response["error"]}" if response["error"]
+
+        send_notification("notifications/initialized", {})
+      end
+
+      def next_id
+        @request_id += 1
+      end
+
+      def request(method, params)
+        id = next_id
+        msg = { "jsonrpc" => "2.0", "id" => id, "method" => method, "params" => params }
+        send_message(msg)
+        wait_for_response(id)
+      end
+
+      def send_notification(method, params)
+        send_message("jsonrpc" => "2.0", "method" => method, "params" => params)
+      end
+
+      def send_message(msg)
+        line = "#{JSON.generate(msg)}\n"
+        @writer.write(line)
+        @writer.flush
+      end
+
+      def wait_for_response(expected_id)
+        loop do
+          line = read_line_with_timeout
+          next if line.nil? || line.strip.empty?
+          next unless line.strip.start_with?("{")
+
+          parsed = JSON.parse(line)
+          next if parsed["method"] # notification from server
+
+          return parsed if parsed["id"] == expected_id
+        end
+      end
+
+      def read_line_with_timeout
+        unless @reader.wait_readable(@timeout)
+          raise Ollama::TimeoutError, "MCP server did not respond within #{@timeout}s"
+        end
+
+        @reader.gets
+      end
+
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.transform_keys(&:to_s)
+      end
+
+      def content_to_string(content)
+        return "" unless content.is_a?(Array)
+
+        content.filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          text = item["text"] || item[:text]
+          text&.to_s
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/ollama/mcp/tools_bridge.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+
+module Ollama
+  module MCP
+    # Bridges an MCP server's tools to Ollama::Agent::Executor.
+    # Fetches tools via tools/list, converts them to Ollama tool format,
+    # and provides a callable per tool that invokes tools/call.
+    # Accepts either client: (StdioClient or HttpClient) or stdio_client: for backward compatibility.
+    class ToolsBridge
+      def initialize(stdio_client: nil, client: nil)
+        @client = client || stdio_client
+        raise ArgumentError, "Provide client: or stdio_client:" unless @client
+
+        @tools_cache = nil
+      end
+
+      # Returns a hash suitable for Executor: name => { tool: Ollama::Tool, callable: proc }.
+      # Callable receives keyword args and returns a string (tool result for the LLM).
+      def tools_for_executor
+        fetch_tools unless @tools_cache
+
+        @tools_cache.transform_values do |entry|
+          {
+            tool: entry[:tool],
+            callable: build_callable(entry[:name])
+          }
+        end
+      end
+
+      # Returns raw MCP tool list (name, description, input_schema).
+      def list_tools
+        @client.tools
+      end
+
+      private
+
+      def fetch_tools
+        list = @client.tools
+        @tools_cache = list.each_with_object({}) do |mcp_tool, hash|
+          name = mcp_tool[:name]
+          next if name.nil? || name.to_s.empty?
+
+          hash[name.to_s] = {
+            name: name.to_s,
+            tool: mcp_tool_to_ollama(mcp_tool)
+          }
+        end
+      end
+
+      def mcp_tool_to_ollama(mcp_tool)
+        schema = mcp_tool[:input_schema] || { "type" => "object" }
+        function_hash = {
+          "name" => mcp_tool[:name].to_s,
+          "description" => (mcp_tool[:description] || "MCP tool: #{mcp_tool[:name]}").to_s,
+          "parameters" => schema
+        }
+        Ollama::Tool.from_hash("type" => "function", "function" => function_hash)
+      end
+
+      def build_callable(name)
+        client = @client
+        ->(**kwargs) { client.call_tool(name: name, arguments: stringify_keys(kwargs)) }
+      end
+
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/ollama/mcp.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# MCP (Model Context Protocol) support for local servers.
+#
+# Connect to MCP servers running via stdio (e.g. npx @modelcontextprotocol/server-filesystem)
+# and use their tools with Ollama::Agent::Executor.
+#
+# Example (remote URL, e.g. GitMCP):
+#   mcp_client = Ollama::MCP::HttpClient.new(url: "https://gitmcp.io/owner/repo")
+#   bridge = Ollama::MCP::ToolsBridge.new(client: mcp_client)
+#   tools = bridge.tools_for_executor
+#   executor = Ollama::Agent::Executor.new(ollama_client, tools: tools)
+#   executor.run(system: "...", user: "What does this repo do?")
+#
+# Example (local stdio):
+#   mcp_client = Ollama::MCP::StdioClient.new(
+#     command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+#   )
+#   bridge = Ollama::MCP::ToolsBridge.new(stdio_client: mcp_client)
+#   tools = bridge.tools_for_executor
+#   executor.run(system: "...", user: "List files in /tmp")
+#
+module Ollama
+  # Model Context Protocol client and tools bridge for Executor.
+  module MCP
+  end
+end
+
+require_relative "mcp/stdio_client"
+require_relative "mcp/http_client"
+require_relative "mcp/tools_bridge"

data/lib/ollama/options.rb

@@ -8,7 +8,9 @@ module Ollama
   #
   # Example:
   #   options = Ollama::Options.new(temperature: 0.7, top_p: 0.95)
-  #   client.generate(prompt: "...", schema: {...}, options: options.to_h)
+  #   client.chat(messages: [...], format: {...}, options: options.to_h, allow_chat: true)
+  #
+  # Note: generate() doesn't accept options parameter - set options in config instead
   class Options
     VALID_KEYS = %i[temperature top_p top_k num_ctx repeat_penalty seed].freeze
 

data/lib/ollama/personas.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Persona system for explicit, contextual personalization.
+  #
+  # Personas are NOT baked into models or server config. They are injected
+  # explicitly at the system/prompt layer, allowing you to:
+  #
+  # - Use compressed versions for schema-based agent work (deterministic)
+  # - Use minimal chat-safe versions for chat/streaming UI work (human-facing)
+  # - Switch personas per task without model changes
+  # - Maintain multiple personas for different contexts
+  #
+  # This is architecturally superior to ChatGPT's implicit global personalization.
+  #
+  # ## Persona Variants
+  #
+  # Each persona has two variants:
+  #
+  # ### Agent Variants (`:agent`)
+  # - Designed for `/api/generate` with JSON schemas
+  # - Minimal, directive, non-chatty
+  # - Preserves determinism in structured outputs
+  # - No markdown, no explanations, no extra fields
+  # - Use with Planner, structured extraction, decision engines
+  #
+  # ### Chat Variants (`:chat`)
+  # - Designed for `/api/chat` with ChatSession
+  # - Minimal, chat-safe, allows explanations
+  # - Explicitly disclaims authority and side effects
+  # - Allows streaming and markdown for presentation
+  # - Use ONLY for human-facing chat interfaces
+  # - Must NEVER be used for schema-based agent work
+  #
+  # ## Critical Separation
+  #
+  # - Agent personas: `/api/generate` + schemas = deterministic reasoning
+  # - Chat personas: `/api/chat` + humans = explanatory conversation
+  #
+  # Mixing them breaks determinism and safety boundaries.
+  # rubocop:disable Metrics/ModuleLength
+  module Personas
+    # Minimal agent-safe persona for schema-based planning and structured outputs.
+    #
+    # This version is:
+    # - Minimal and direct (no verbosity)
+    # - Focused on correctness and invariants
+    # - No chatty behavior or markdown drift
+    # - Preserves determinism in structured outputs
+    # - Designed for /api/generate, schema-validated, deterministic workflows
+    #
+    # This prompt turns the LLM into a deterministic reasoning subroutine,
+    # not a conversational partner. Use for planners, routers, decision engines.
+    ARCHITECT_AGENT = <<~PROMPT
+      You are acting as a senior software architect and system designer.
+
+      Operating rules:
+      - Optimize for correctness and robustness first.
+      - Make explicit decisions; do not hedge.
+      - Do not invent data, APIs, or system behavior.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume side effects; propose intent only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer simple, explicit solutions over clever ones.
+
+      Focus areas:
+      - System boundaries and invariants
+      - Failure modes and edge cases
+      - Production-grade architecture decisions
+    PROMPT
+
+    # Minimal chat-safe persona for human-facing chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    ARCHITECT_CHAT = <<~PROMPT
+      You are a senior software architect and systems engineer.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain reasoning when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent APIs, data, or system behavior.
+      - If information is missing, say so explicitly.
+      - Prefer concrete examples over abstract theory.
+
+      Boundaries:
+      - You do not execute actions or side effects.
+      - You provide explanations, guidance, and reasoning only.
+      - Decisions that affect systems must be validated externally.
+
+      Tone:
+      - Professional, calm, and no-nonsense.
+      - Assume the user has strong technical background.
+    PROMPT
+
+    # Minimal agent-safe persona for trading/analysis work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for market analysis, risk assessment, and trading decisions.
+    TRADING_AGENT = <<~PROMPT
+      You are acting as a quantitative trading system analyst.
+
+      Operating rules:
+      - Optimize for data accuracy and risk assessment first.
+      - Make explicit decisions based on provided data only.
+      - Do not invent market data, prices, or indicators.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume market behavior; base analysis on data only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit risk statements over predictions.
+
+      Focus areas:
+      - Risk management and edge cases
+      - Data-driven analysis without emotional bias
+      - Objective assessment of market conditions
+    PROMPT
+
+    # Minimal chat-safe persona for trading chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    TRADING_CHAT = <<~PROMPT
+      You are a quantitative trading system analyst.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and data-focused.
+      - Explain analysis when it helps understanding.
+      - Avoid predictions, guarantees, or emotional language.
+      - Do not invent market data, prices, or indicators.
+      - If information is missing, say so explicitly.
+      - Prefer concrete data examples over abstract theory.
+
+      Boundaries:
+      - You do not execute trades or market actions.
+      - You provide analysis, guidance, and reasoning only.
+      - Trading decisions must be validated externally.
+
+      Tone:
+      - Professional, objective, and risk-aware.
+      - Assume the user understands market fundamentals.
+    PROMPT
+
+    # Minimal agent-safe persona for code review work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for code quality assessment and refactoring decisions.
+    REVIEWER_AGENT = <<~PROMPT
+      You are acting as a code review assistant focused on maintainability and correctness.
+
+      Operating rules:
+      - Optimize for code clarity and maintainability first.
+      - Make explicit decisions about code quality issues.
+      - Do not invent code patterns or assume implementation details.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume intent; identify issues from code structure only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit refactoring suggestions over general advice.
+
+      Focus areas:
+      - Unclear names, long methods, hidden responsibilities
+      - Single responsibility and testability
+      - Unnecessary complexity and code smells
+    PROMPT
+
+    # Minimal chat-safe persona for code review chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    REVIEWER_CHAT = <<~PROMPT
+      You are a code review assistant focused on maintainability and correctness.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain code quality issues when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent code patterns or assume implementation details.
+      - If information is missing, say so explicitly.
+      - Prefer concrete refactoring examples over abstract principles.
+
+      Boundaries:
+      - You do not modify code or execute refactorings.
+      - You provide review, guidance, and suggestions only.
+      - Code changes must be validated externally.
+
+      Tone:
+      - Professional, constructive, and no-nonsense.
+      - Assume the user values code quality and maintainability.
+    PROMPT
+
+    # Registry of all available personas.
+    #
+    # Each persona has two variants:
+    # - `:agent` - Minimal version for schema-based agent work (/api/generate)
+    # - `:chat` - Minimal chat-safe version for human-facing interfaces (/api/chat)
+    #
+    # IMPORTANT: Chat personas must NEVER be used for schema-based agent work.
+    # They are designed for ChatSession and streaming only.
+    REGISTRY = {
+      architect: {
+        agent: ARCHITECT_AGENT,
+        chat: ARCHITECT_CHAT
+      },
+      trading: {
+        agent: TRADING_AGENT,
+        chat: TRADING_CHAT
+      },
+      reviewer: {
+        agent: REVIEWER_AGENT,
+        chat: REVIEWER_CHAT
+      }
+    }.freeze
+
+    # Get a persona by name and variant.
+    #
+    # @param name [Symbol] Persona name (:architect, :trading, :reviewer)
+    # @param variant [Symbol] Variant (:agent or :chat)
+    # @return [String, nil] Persona prompt text, or nil if not found
+    #
+    # @example
+    #   Personas.get(:architect, :agent)  # => Compressed agent version
+    #   Personas.get(:architect, :chat)    # => Full chat version
+    def self.get(name, variant: :agent)
+      REGISTRY.dig(name.to_sym, variant.to_sym)
+    end
+
+    # List all available persona names.
+    #
+    # @return [Array<Symbol>] List of persona names
+    def self.available
+      REGISTRY.keys
+    end
+
+    # Check if a persona exists.
+    #
+    # @param name [Symbol, String] Persona name
+    # @return [Boolean] True if persona exists
+    def self.exists?(name)
+      REGISTRY.key?(name.to_sym)
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end