ollama-client 1.3.0 → 1.4.0

data/lib/ollama/attachment.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Typed attachment payload for multimodal inputs.
+  #
+  # Each variant normalizes to a single hash accepted by Ollama as the
+  # +:images+ entry on a user message: +{ type: "...", data: "..." }+.
+  #
+  # Example:
+  #
+  #   Ollama::Attachment.file("photo.png")
+  #   # => { type: "file", data: "photo.png" }
+  #
+  #   Ollama::Attachment.base64(b64_string)
+  #   # => { type: "base64", data: b64_string }
+  #
+  #   Ollama::Attachment.url("https://...")
+  #   # => { type: "url", data: "https://..." }
+  class Attachment
+    attr_reader :type, :data
+
+    # @param type [String, Symbol] one of +file+, +base64+, +url+
+    # @param data [String, #read]
+    def initialize(type, data)
+      @type = type.to_s
+      @data = coerce(data)
+    end
+
+    # +type:+ +"file"+, +data:+ +path+ (string or +Pathname+). Reads as base64 when a file path is supplied.
+    # Uses base64-encoded file when a file path is supplied.
+    def self.file(path)
+      path = path.to_s
+      data = if path.include?("\n") || path.include?("+")
+               path
+             else
+               base64_from_file(path)
+             end
+      new("file", data)
+    end
+
+    # +type:+ +"base64"+, +data:+ +base64-encoded string+
+    def self.base64(data)
+      new("base64", data)
+    end
+
+    # +type:+ +"url"+, +data:+ +remote URL+
+    def self.url(url)
+      new("url", url.to_s)
+    end
+
+    def to_h
+      { "type" => type, "data" => data }
+    end
+
+    private
+
+    def coerce(value)
+      return value if value.is_a?(String)
+      return value.read if value.respond_to?(:read)
+
+      value.to_s
+    end
+
+    class << self
+      private
+
+      def base64_from_file(path)
+        File.file?(path) && File.exist?(path) ? [File.binread(path)].pack("m") : path
+      rescue SystemCallError
+        path
+      end
+    end
+  end
+end

data/lib/ollama/capabilities.rb

@@ -26,7 +26,7 @@ module Ollama
       end
 
       TOOLS_FAMILIES = %w[llama qwen2 qwen3 qwen3vl command-r mistral gemma2 gemma4].freeze
-      THINKING_MODELS = [/deepseek-r1/i, /-r1/i, /qwq/i, /qwen3/i, /gemma[_-]?4/i].freeze
+      THINKING_MODELS = [/deepseek-r1/i, /-r1/i, /qwq/i, /\bqwen3(?![.\d])/i, /gemma[_-]?4/i].freeze
       VISION_FAMILIES = %w[llava clip qwen3vl mllama].freeze
       VISION_MODELS = [/vision/i, /vl/i].freeze
       EMBEDDING_FAMILIES = %w[nomic-bert bert mxbai-embed-large].freeze

data/lib/ollama/chat_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Wraps a normalized chat response in a Ruby surface that supports
+  # traditional attribute access and state checks.
+  class ChatResponse
+    attr_reader :content, :thinking, :role, :tool_calls, :images, :done, :model
+
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(
+      content: nil,
+      thinking: nil,
+      role: "assistant",
+      tool_calls: [],
+      images: [],
+      done: true,
+      model: nil
+    )
+      # rubocop:enable Metrics/ParameterLists
+      @content = content
+      @thinking = thinking
+      @role = role
+      @tool_calls = Array(tool_calls)
+      @images = Array(images)
+      @done = done
+      @model = model
+    end
+
+    def done?
+      done
+    end
+  end
+end

data/lib/ollama/client/chat/request_preparer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../../multimodal_input"
+require_relative "../../prompt_adapters"
+
+module Ollama
+  class Client
+    module Chat
+      # Prepares Chat Request objects from client configuration and inputs
+      class RequestPreparer
+        def initialize(config:, provider:)
+          @config = config
+          @provider = provider
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def build_request(params, client_instance)
+          target_model = params.model || @config.model
+          active_profile = client_instance.send(:resolve_profile, target_model, params.profile)
+          adapter = PromptAdapters.for(active_profile) if active_profile
+
+          messages = if params.inputs
+                       apply_inputs(params.messages, params.inputs, active_profile)
+                     else
+                       params.messages
+                     end
+
+          adapted_messages = if adapter
+                               adapter.adapt_messages(messages, think: !params.think.nil?, tools: params.tools)
+                             else
+                               messages
+                             end
+
+          effective_think = resolve_think_flag(params.think, adapter)
+          stream_enabled = params.stream.nil? ? hooks_present?(params.hooks) : params.stream
+
+          Request.new(
+            endpoint: :chat,
+            model: target_model,
+            messages: adapted_messages,
+            tools: params.tools,
+            format: params.format,
+            think: effective_think,
+            keep_alive: params.keep_alive,
+            options: client_instance.send(:build_options_with_profile, params.options, active_profile),
+            stream: stream_enabled,
+            metadata: {
+              base_url: @config.base_url,
+              timeout: @config.timeout,
+              hooks: params.hooks,
+              uri: @provider.chat_endpoint
+            },
+            raw_options: {
+              logprobs: params.logprobs,
+              top_logprobs: params.top_logprobs
+            }
+          )
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        private
+
+        def hooks_present?(hooks)
+          [hooks[:on_token], hooks[:on_thought], hooks[:on_error],
+           hooks[:on_complete], hooks[:on_tool_call]].any?
+        end
+
+        def apply_inputs(messages, inputs, active_profile)
+          input_obj = MultimodalInput.build(inputs, profile: active_profile || ModelProfile.for("generic"))
+          messages + [input_obj.to_message]
+        end
+
+        def resolve_think_flag(think, adapter)
+          return nil if think.nil?
+          return nil if adapter&.inject_think_flag? == false && adapter.is_a?(PromptAdapters::Gemma4)
+
+          think
+        end
+      end
+    end
+  end
+end

data/lib/ollama/client/chat.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "chat_stream_processor"
+require_relative "../responses/chat"
+require_relative "../serializers/chat"
+require_relative "../parsers/chat"
+require_relative "chat/request_preparer"
 
 module Ollama
   class Client
@@ -25,97 +29,83 @@ module Ollama
       #   :on_error    ->(error)                — stream or connection error
       #   :on_complete ->                       — stream finished
       # @return [Ollama::Response] Response wrapper with message, tool_calls, timing, etc.
-      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists, Metrics/AbcSize
+      # rubocop:disable Metrics/ParameterLists
       def chat(messages:, model: nil, format: nil, tools: nil, stream: nil,
                think: nil, keep_alive: nil, options: nil, logprobs: nil,
                top_logprobs: nil, hooks: {}, profile: :auto, inputs: nil)
-        raise ArgumentError, "messages is required" if messages.nil? || messages.empty?
-
-        target_model = model || @config.model
-        active_profile = resolve_profile(target_model, profile)
-        adapter = PromptAdapters.for(active_profile) if active_profile
-
-        # Apply multimodal inputs: build typed message and append to history
-        messages = apply_inputs(messages, inputs, active_profile) if inputs
-
-        # Apply prompt adapter (e.g. Gemma 4 prepends the family think tag to the system prompt)
-        adapted_messages = adapter ? adapter.adapt_messages(messages, think: !think.nil?) : messages
-
-        # Resolve think flag: adapter may handle it via prompt tag instead of API flag
-        effective_think = resolve_think_flag(think, adapter)
-
-        chat_uri = URI("#{@config.base_url}/api/chat")
-        req = Net::HTTP::Post.new(chat_uri)
-        req["Content-Type"] = "application/json"
+        # rubocop:enable Metrics/ParameterLists
+        params = Params::Chat.new(
+          messages: messages, model: model, format: format, tools: tools,
+          stream: stream, think: think, keep_alive: keep_alive, options: options,
+          logprobs: logprobs, top_logprobs: top_logprobs, hooks: hooks,
+          profile: profile, inputs: inputs
+        )
+        chat_with_params(params)
+      end
 
-        stream_enabled = stream.nil? ? hooks_present?(hooks) : stream
+      # @param params [Ollama::Params::Chat] Chat parameters
+      # @return [Ollama::Response] Response wrapper with message, tool_calls, timing, etc.
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def chat_with_params(params)
+        raise ArgumentError, "messages is required" if params.messages.nil? || params.messages.empty?
 
-        body = { model: target_model, messages: adapted_messages, stream: stream_enabled }
-        body[:format]      = format if format
-        body[:tools]       = tools if tools
-        body[:think]       = effective_think unless effective_think.nil?
-        body[:keep_alive]  = keep_alive if keep_alive
-        body[:logprobs]    = logprobs unless logprobs.nil?
-        body[:top_logprobs] = top_logprobs if top_logprobs
-        body[:options] = build_options_with_profile(options, active_profile)
+        preparer = RequestPreparer.new(config: @config, provider: @provider)
+        request = preparer.build_request(params, self)
 
-        req.body = body.to_json
-        @config.apply_auth_to(req)
+        serializer = Serializers::Chat.new
+        transport_req = serializer.call(request)
         response_data = nil
+        stream_enabled = request.stream
+        config_timeout = request.metadata[:timeout]
+        target_model = request.model
+        chat_uri = request.metadata[:uri]
 
         begin
-          Net::HTTP.start(chat_uri.hostname, chat_uri.port,
-                          **@config.http_connection_options(chat_uri)) do |h|
-            h.request(req) do |res|
-              handle_http_error(res, requested_model: target_model) unless res.is_a?(Net::HTTPSuccess)
-
-              response_data = if stream_enabled
-                                ChatStreamProcessor.new(hooks).call(res)
-                              else
-                                JSON.parse(res.body)
-                              end
+          with_rate_limit_key_rotation do |api_key|
+            response_data = nil
+            @config.apply_auth_to(transport_req, api_key: api_key) if transport_req.is_a?(Transport::Request)
+
+            if stream_enabled
+              buffer = +""
+              processor = ChatStreamProcessor.new(params.hooks, provider: @provider)
+              processor.send(:reset_accumulators!)
+
+              @pipeline.stream(transport_req) do |chunk|
+                processor.send(:drain_chunk, buffer, chunk)
+              end
+
+              response_data = processor.send(:build_result)
+            else
+              transport_response = @pipeline.call(transport_req)
+              if transport_response.raw && !transport_response.raw.is_a?(Net::HTTPSuccess)
+                handle_http_error(transport_response.raw,
+                                  requested_model: target_model)
+              end
+
+              parser = Parsers::Chat.new(provider: @provider)
+              parsed_response = parser.call(transport_response)
+              response_data = parsed_response.to_h
             end
           end
         rescue Net::ReadTimeout, Net::OpenTimeout => e
-          hooks[:on_error]&.call(e)
-          raise TimeoutError, "Request timed out after #{@config.timeout}s"
+          params.hooks[:on_error]&.call(e)
+          raise TimeoutError, "Request timed out after #{config_timeout}s"
         rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
-          hooks[:on_error]&.call(e)
+          params.hooks[:on_error]&.call(e)
           raise Error, "Connection failed: #{e.message}"
         rescue Error => e
-          hooks[:on_error]&.call(e)
+          params.hooks[:on_error]&.call(e)
           raise e
         end
 
         emit_response_hook(response_data.is_a?(Hash) ? response_data.to_json : response_data,
-                           endpoint: "/api/chat", model: target_model)
+                           endpoint: chat_uri.path, model: target_model)
 
-        Response.new(response_data)
+        Responses::Chat.new(response_data)
       rescue JSON::ParserError => e
         raise InvalidJSONError, "Failed to parse chat response: #{e.message}"
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/ParameterLists, Metrics/AbcSize
-
-      private
-
-      def hooks_present?(hooks)
-        [hooks[:on_token], hooks[:on_thought], hooks[:on_error],
-         hooks[:on_complete], hooks[:on_tool_call]].any?
-      end
-
-      def apply_inputs(messages, inputs, active_profile)
-        input_obj = MultimodalInput.build(inputs, profile: active_profile || ModelProfile.for("generic"))
-        messages + [input_obj.to_message]
-      end
-
-      # Gemma 4 uses the system-prompt tag — do not send think: true to the API.
-      # Other adapters that inject_think_flag? pass the user's think value through.
-      def resolve_think_flag(think, adapter)
-        return nil if think.nil?
-        return nil if adapter&.inject_think_flag? == false && adapter.is_a?(PromptAdapters::Gemma4)
-
-        think
-      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
     end
   end
 end

data/lib/ollama/client/chat_stream_processor.rb

@@ -5,10 +5,24 @@ module Ollama
     # Consumes an NDJSON /api/chat stream, aggregates message fields, and dispatches hooks.
     # Line buffering matches Ollama::GenerateStreamHandler so both NDJSON parsers stay parallel.
     class ChatStreamProcessor
-      def initialize(hooks)
+      # Convenience class method to process a stream.
+      # @param res [Net::HTTPResponse]
+      # @param hooks [Hash]
+      # @param provider [Ollama::Providers::Base]
+      # @return [Hash] the aggregated result
+      def self.call(res, hooks, provider: nil)
+        new(hooks, provider: provider).call(res)
+      end
+
+      # @param hooks [Hash]
+      # @param provider [Ollama::Providers::Base]
+      def initialize(hooks, provider: nil)
         @hooks = hooks
+        @provider = provider
       end
 
+      # @param res [Net::HTTPResponse]
+      # @return [Hash] the aggregated result
       def call(res)
         reset_accumulators!
 
@@ -41,9 +55,13 @@ module Ollama
       end
 
       def handle_line(line)
-        handle_event(JSON.parse(line))
-      rescue JSON::ParserError
-        nil
+        # OpenAI SSE uses "data: " prefix and ends with "data: [DONE]"
+        return if line == "data: [DONE]"
+
+        json_text = line.start_with?("data: ") ? line.sub(/^data: /, "") : line
+        handle_event(JSON.parse(json_text))
+      rescue JSON::ParserError => e
+        @hooks[:on_error]&.call(MalformedStreamError.new("Failed to parse JSON line: #{e.message}"))
       end
 
       def build_result
@@ -57,39 +75,81 @@ module Ollama
       end
 
       def handle_event(obj)
-        if obj["error"]
-          error = StreamError.new(obj["error"])
-          @hooks[:on_error]&.call(error)
-          raise error
-        end
+        # Normalize event if it's from OpenAI
+        obj = normalize_openai_delta(obj) if @provider.is_a?(Providers::OpenAI)
 
-        if obj["message"]
-          content = obj["message"]["content"]
-          thinking = obj["message"]["thinking"]
+        handle_error_event(obj) if obj["error"]
+        process_message_field(obj) if obj["message"]
+        finalize_stream_if_done(obj) if obj["done"]
+      end
 
-          if thinking && !thinking.empty?
-            start_thought_block unless @thinking_started
-            @full_thinking << thinking
-            @hooks[:on_thought]&.call(StreamEvent.new(type: :thought_delta, data: thinking))
-          end
+      def handle_error_event(obj)
+        error = StreamError.new(obj["error"])
+        @hooks[:on_error]&.call(error)
+        raise error
+      end
 
-          if content && !content.empty?
-            end_thought_block_if_needed
-            @full_content << content
-            emit_token(content, obj["logprobs"])
-          end
+      def process_message_field(obj)
+        msg = obj["message"]
+        content = msg["content"]
+        thinking = msg["thinking"]
 
-          @full_logprobs.concat(obj["logprobs"]) if obj["logprobs"]
-        end
+        process_thinking(thinking) if thinking && !thinking.empty?
+        process_content(content, obj["logprobs"]) if content && !content.empty?
+
+        @full_logprobs.concat(obj["logprobs"]) if obj["logprobs"]
+      end
 
-        return unless obj["done"]
+      def process_thinking(thinking)
+        start_thought_block unless @thinking_started
+        @full_thinking << thinking
+        @hooks[:on_thought]&.call(StreamEvent.new(type: :thought_delta, data: thinking))
+      end
+
+      def process_content(content, logprobs)
+        end_thought_block_if_needed
+        @full_content << content
+        emit_token(content, logprobs)
+      end
 
+      def finalize_stream_if_done(obj)
         Array(obj.dig("message", "tool_calls")).each { |tc| @hooks[:on_tool_call]&.call(tc) }
 
         @hooks[:on_complete]&.call
         @last_data = obj
       end
 
+      def normalize_openai_delta(obj)
+        return obj unless obj.key?("choices")
+
+        choice = obj["choices"][0]
+        delta = choice["delta"] || {}
+
+        {
+          "model" => obj["model"],
+          "message" => {
+            "role" => delta["role"],
+            "content" => delta["content"],
+            "tool_calls" => translate_openai_tool_calls(delta["tool_calls"])
+          },
+          "done" => !choice["finish_reason"].nil?,
+          "done_reason" => choice["finish_reason"]
+        }
+      end
+
+      def translate_openai_tool_calls(openai_tool_calls)
+        return nil unless openai_tool_calls
+
+        openai_tool_calls.map do |tc|
+          {
+            "function" => {
+              "name" => tc.dig("function", "name"),
+              "arguments" => tc.dig("function", "arguments")
+            }
+          }
+        end
+      end
+
       def start_thought_block
         @hooks[:on_thought]&.call(StreamEvent.new(type: :thought_start, data: nil))
         @thinking_started = true

data/lib/ollama/client/generate/request_preparer.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../../request"
+
+module Ollama
+  class Client
+    module Generate
+      # Prepares Generate Request objects from client configuration and inputs
+      class RequestPreparer
+        def initialize(config:, provider:, schema_cache: {})
+          @config = config
+          @provider = provider
+          @schema_cache = schema_cache
+        end
+
+        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        def build_request(prompt:, context:, schema:, model:, hooks:, system: nil, images: nil,
+                          think: nil, keep_alive: nil, suffix: nil, raw: nil, options: nil, client_instance: nil)
+          config_model = @config.model
+          config_timeout = @config.timeout
+          base_url = @config.base_url
+
+          stream_enabled = streaming_requested?(hooks)
+
+          request_params = {
+            model: model || config_model,
+            prompt: prompt,
+            stream: stream_enabled,
+            options: client_instance.send(:build_options, options)
+          }
+
+          request_params[:context] = context if context
+          request_params[:system] = system if system
+          request_params[:images] = images if images
+          request_params[:think] = think unless think.nil?
+          request_params[:keep_alive] = keep_alive if keep_alive
+          request_params[:suffix] = suffix if suffix
+          request_params[:raw] = raw unless raw.nil?
+
+          if schema
+            request_params[:format] = schema
+            request_params[:prompt] = enhance_prompt_for_json(prompt, schema)
+          end
+
+          Request.new(
+            endpoint: :generate,
+            model: model || config_model,
+            prompt: request_params[:prompt],
+            schema: schema,
+            options: request_params[:options],
+            stream: stream_enabled,
+            keep_alive: keep_alive,
+            think: think,
+            format: request_params[:format],
+            images: images,
+            metadata: {
+              base_url: base_url,
+              timeout: config_timeout,
+              hooks: hooks,
+              uri: @provider.generate_endpoint
+            },
+            raw_options: {
+              system: system,
+              suffix: suffix,
+              raw: raw,
+              context: context
+            }
+          )
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
+
+        private
+
+        def streaming_requested?(hooks)
+          !(hooks[:on_token] || hooks[:on_error] || hooks[:on_complete]).nil?
+        end
+
+        def enhance_prompt_for_json(prompt, schema)
+          return prompt if prompt.match?(/json|JSON/i)
+
+          schema_summary = summarize_schema(schema)
+          json_instruction = "CRITICAL: Respond with ONLY valid JSON (no markdown code blocks, no explanations). " \
+                             "The JSON must include these exact required fields: #{schema_summary}"
+          "#{prompt}\n\n#{json_instruction}"
+        end
+
+        def summarize_schema(schema)
+          return "object" unless schema.is_a?(Hash)
+
+          cache_key = schema.hash
+          return @schema_cache[cache_key] if @schema_cache.key?(cache_key)
+
+          required = schema["required"] || []
+          properties = schema["properties"] || {}
+          return "object" if required.empty? && properties.empty?
+
+          example = {}
+          required.each do |key|
+            prop = properties[key] || {}
+            example[key] = case prop["type"]
+                           when "string" then "string_value"
+                           when "number" then 0
+                           when "boolean" then true
+                           when "array" then []
+                           else {}
+                           end
+          end
+
+          required_list = required.map { |k| "\"#{k}\"" }.join(", ")
+          example_json = JSON.pretty_generate(example)
+          result = "Required fields: [#{required_list}]. Example structure:\n#{example_json}"
+          @schema_cache[cache_key] = result
+          result
+        end
+      end
+    end
+  end
+end