scout-ai 1.2.5 → 2.0.0

data/lib/scout/llm/backends/default.rb

@@ -1,4 +1,5 @@
 require 'scout'
+require 'securerandom'
 require_relative '../chat'
 
 module LLM
@@ -23,15 +24,19 @@ module LLM
   # methods (like `query` / `format_tool_call`) and Ruby will correctly dispatch
   # to the backend override.
   module Backend
+    class BackendException
+      attr_accessor :chat
+    end
+
     module ClassMethods
       #{{{ CLIENT
 
       def client(options)
         url, key, model, api_version, log_errors, request_timeout = IndiferentHash.process_options options,
           :url, :key, :model, :api_version, :log_errors, :request_timeout,
-          log_errors: true, request_timeout: 1200, api_version: 'v1'
+          log_errors: true, request_timeout: 12000, api_version: 'v1'
 
-        Object::OpenAI::Client.new(api_version: api_version, access_token: key, log_errors: log_errors, uri_base: url, request_timeout: request_timeout)
+        Object::OpenAI::Client.new(api_version: api_version, access_token: key, log_errors: log_errors, uri_base: url, request_timeout: request_timeout.to_i)
       end
 
       def client_options(options)
@@ -43,7 +48,7 @@ module LLM
         key ||= LLM.get_url_config(:key, url, "#{tag}_ask", :ask, tag, env: "#{tag.upcase}_KEY")
         model ||= LLM.get_url_config(:model, url, :openai_ask, :ask, :openai, env: "#{tag.upcase}_MODEL,MODEL", default: default_model)
 
-        { url: url, key: key, model: model, api_version: api_version }.reject { |_k, v| v.nil? }
+        { url: url, key: key, model: model, api_version: api_version, request_timeout: request_timeout }.reject { |_k, v| v.nil? }
       end
 
       def extra_options(options, messages = nil)
@@ -215,6 +220,8 @@ module LLM
           definition = obj if Hash === obj
           definition
 
+          next definition if definition.keys.collect{|k| k.to_s } == ['type']
+
           definition = case definition[:function]
                        when Hash
                          definition.merge(definition.delete :function)
@@ -297,9 +304,14 @@ module LLM
         case tools
         when Array
           tools = tools.inject({}) do |acc, definition|
+            next definition unless Hash === definition
             IndiferentHash.setup definition
             name = definition.dig('name') || definition.dig('function', 'name')
-            acc.merge(name => definition)
+            if name
+              acc.merge(name => definition)
+            else
+              acc.merge(definition[:type] => definition)
+            end
           end
         when nil
           tools = {}
@@ -308,7 +320,7 @@ module LLM
         tools.merge!(LLM.tools messages)
         tools.merge!(LLM.associations messages)
 
-        Log.high "Tools: #{Log.fingerprint tools.keys}" if tools
+        Log.medium "Tools: #{Log.fingerprint tools.keys}" if tools
 
         tools
       end
@@ -383,6 +395,8 @@ module LLM
             next
           when 'function_call', 'mcp_call'
             [tool_call_outputs.shift, tool_call_outputs.shift]
+          when 'image_generation_call'
+            {role: 'image', content: output}
           when 'web_search_call'
             next
           else
@@ -399,63 +413,54 @@ module LLM
 
       def update_meta(response, current_meta = nil)
         current_meta = {} if current_meta.nil?
-
-        pattern = {
-          'pt+': [['usage','prompt_tokens']],
-          'ct+': [['usage','completion_tokens']],
-          'tt+': [['usage','total_tokens']],
-        }
-
-        meta = {}
-        pattern.each do |name,key_list|
-          name = name.to_s
-          key_list.each do |keys|
-            value = response.dig *keys
-            next unless value
-
-            if name.end_with?('+')
-              name = name[0..-2]
-              meta[name] = value
-              session_name = name + '_s'
-
-              meta[session_name] ||= Thread.current[session_name] || 0
-              meta[session_name] += value
-
-              Thread.current[session_name] = meta[session_name]
-              meta.delete name if meta[name] == meta[session_name]
-            else
-              value = value.gsub(/\s+/,' ') if String === value
-              meta[name] = value
-            end
-          end
+        IndiferentHash.setup current_meta
+
+        # Extract normalised token fields from the provider usage hash.
+        # Chat.normalize_usage handles all known backend response formats
+        # (OpenAI Chat, Responses API, GLM, Anthropic) and returns a flat
+        # hash keyed by the short names defined in Chat::TOKEN_KEYS.
+        tokens = Chat.normalize_usage(response.dig('usage')).reject { |_name, value| value.nil? }
+
+        # Keep the provider values for this request separate from aggregate
+        # values.  In particular, do not add the running thread/session total
+        # to the chat total: doing that on every request produces the observed
+        # triangular (and, after aggregation, worse) growth.
+        meta = IndiferentHash.setup(tokens.dup)
+        # A lineage digest identifies copied conversational history, not an
+        # actual backend request. Persist a request identity so provenance can
+        # distinguish two genuinely repeated, otherwise identical inferences.
+        meta['inference_id'] = SecureRandom.uuid
+        meta['provider_response_id'] = response['id'] if response['id']
+        tokens.each do |name, value|
+          session_name = name + '_s'
+          Thread.current[session_name] = Thread.current[session_name].to_i + value.to_i
+          meta[session_name] = Thread.current[session_name]
         end
 
-        new = {}
-        meta.each do |name,value|
-          if name.end_with?('_s')
-            chat_name = name.sub(/_s$/,'_c')
-            current_value = current_meta[chat_name] || current_meta[name] || 0
-            new[chat_name] = current_value + value
-          end
+        Chat::TOKEN_KEYS.each do |name|
+          meta["#{name}_c"] = current_meta["#{name}_c"].to_i + tokens[name].to_i
         end
 
-        meta.merge! new
+        Log.medium "Meta: #{Log.fingerprint meta}"
 
         meta
       end
 
       def reasoning(response, current_meta = nil)
-        reasoning_content = response.dig('choices', 0, 'message', 'reasoning_content')
-        reasoning_content = reasoning_content.gsub("\n", ' ') if String === reasoning_content
-        Log.medium "Reasoning:\n" + Log.color(:cyan, reasoning_content) if reasoning_content
-        reasoning_content
+        begin
+          reasoning_content = response.dig('choices', 0, 'message', 'reasoning_content')
+          reasoning_content = reasoning_content.gsub("\n", ' ') if String === reasoning_content
+          Log.medium "Reasoning:\n" + Log.color(:cyan, reasoning_content) if reasoning_content
+          reasoning_content
+        rescue
+        end
       end
 
 
       def upload_messages(server, messages, options)
         id = Misc.digest(messages)
         messages.unshift({role: 'backend', content: self::TAG})
-        TmpFile.with_file [messages, options.except(:client)].to_json do |file|
+        TmpFile.with_file [messages, options].to_json do |file|
           CMD.cmd("scp #{file} #{server}:.scout/var/query/#{ id }.json")
         end
         id
@@ -476,8 +481,8 @@ module LLM
       def ask(question, options = {}, &block)
         original_options = options.dup
 
-        return_messages, log_response, current_meta, relay, process = IndiferentHash.process_options options, 
-          :return_messages, :log_response, :current_meta, :relay, :process,
+        return_messages, log_response, current_meta, relay, process, prompt_strategies = IndiferentHash.process_options options, 
+          :return_messages, :log_response, :current_meta, :relay, :process, :prompt_strategies,
           return_messages: false, log_response: true
 
         messages = self.messages question, options
@@ -486,24 +491,37 @@ module LLM
           id = upload_messages(relay,  messages, options)
           response = gather_response(relay, id)
           IndiferentHash.setup(response)
-          client = prepare_client options, messages
-          formatted_messages = format_messages(messages)
-          tools = tools(formatted_messages, options)
+          formatted_prompt = format_messages(messages)
+          tools = tools(formatted_prompt, options)
         else
 
           client = prepare_client options, messages
-          formatted_messages = format_messages(messages)
-          tools = tools(formatted_messages, options)
+          prompt = Chat.prepare_prompt(messages, prompt_strategies)
+          formatted_prompt = format_messages(prompt)
+          tools = tools(formatted_prompt, options)
 
           response = begin
                        Log.medium "Calling #{self}: #{Log.fingerprint(options.except(:tools))}}"
-                       query(client, formatted_messages, tools, options)
-                     rescue Exception
+                       query(client, formatted_prompt, tools, options)
+                     rescue Exception => e
                        Log.debug 'Asking error. Options: ' + "\n" + JSON.pretty_generate(options.except(:tools))
-                       raise $!
+                       begin
+                         tmpfile = TmpFile.tmp_file 
+                         Open.write tmpfile + ".chat", Chat.print(messages)
+                         Open.write tmpfile + ".options", options.except(:messages, :tools).to_json
+                         Open.write tmpfile + ".meta", current_meta.to_json
+                         Log.warn "Messages and options saved in #{tmpfile}"
+                         e.extend LLM::Backend::BackendException
+                         e.chat tmpfile
+                       rescue
+                       end
+
+                       raise e
                      end
         end
 
+        timestamp = Chat.timestamp
+
         if process
           Scout.var.query.response[process].set_extension(:json).write response.to_json
           return response
@@ -515,16 +533,61 @@ module LLM
 
         reasoning = reasoning response
 
-        output = process_response messages, response, tools, options, &block
+        output = begin
+                   process_response messages, response, tools, options, &block
+                 rescue Exception => e
+
+                   Log.debug 'Processing response error. Options: ' + "\n" + JSON.pretty_generate(options.except(:tools))
+                   begin
+                     tmpfile = TmpFile.tmp_file 
+                     previous_response_id_error = options.delete
+                     if previous_response_id_error
+                       message.unshift IndiferentHash.setup({role: :previous_response_id, content: previous_response_id_error})
+                     end
+                     Open.write tmpfile + ".chat", Chat.print(messages)
+                     Open.write tmpfile + ".options", options.except(:messages, :tools).to_json
+                     Open.write tmpfile + ".meta", current_meta.to_json
+                     Log.warn "Messages and options saved in #{tmpfile}"
+                     e.extend LLM::Backend::BackendException
+                     e.chat tmpfile
+                   rescue
+                   end
+                   raise e
+                 end
 
         if log_response
           meta = self.update_meta response, current_meta
           meta['reas'] = reasoning if reasoning
+          meta['timestamp'] = timestamp
         end
 
         output = chain_tools messages, output, tools, options.merge(client: client, tools: tools, log_response: log_response, current_meta: meta, relay: relay)
 
-        output.unshift({role: :meta, content: Chat.serialize_meta(meta)}) if log_response && meta && meta.any?
+        if log_response && meta && meta.any?
+          # The meta is about to become the first message of a segment that
+          # runs until the next meta (a chained tool-call ask, whose own meta
+          # was already unshifted inside `output` by the recursive call) or
+          # the end of the response.  A reasoning-only request produces no
+          # message at all, so its meta covers zero messages: `output` is
+          # empty, or starts with the nested meta.  Such rounds are real cost
+          # (~7% of prompt tokens in one measured agent log) with nothing to
+          # show for it, so mark them explicitly instead of leaving a bare
+          # meta for the reader to puzzle over.  `Chat.trace_indices` derives
+          # the same fact independently; the marker only makes the persisted
+          # meta self-explanatory and is inert for accounting.
+          #
+          # ScoutCoder: orphan is only meaningful for the meta that opens a
+          # segment. Chained tool calls recurse into `ask`, and their metas
+          # were already unshifted onto `output` before this point, so the
+          # first message of `output` decides: an empty list, or one starting
+          # with the nested meta, means this round covered nothing. Do not
+          # recompute this from `trace_indices` here: that helper sees the
+          # whole chat (parent copies included) and does not exist on this
+          # path.
+          meta['orphan'] = true if output.empty? || output.first[:role].to_s == 'meta'
+
+          output.unshift({role: :meta, content: Chat.serialize_meta(meta)})
+        end
 
         if output.last[:role] != :previous_response_id && options[:previous_response_id]
           output << { role: :previous_response_id, content: options[:previous_response_id] }
@@ -540,37 +603,14 @@ module LLM
       end
 
       def image(question, options = {}, &block)
-        messages = LLM.chat(question)
-        options = options.merge LLM.options messages
-        tools = LLM.tools messages
-        associations = LLM.associations messages
+        messages = ask(question, options.merge({tools: [{type: 'image_generation'}], return_messages: true}), &block)
 
-        client, url, key, model, log_errors, return_messages, format = IndiferentHash.process_options options,
-          :client, :url, :key, :model, :log_errors, :return_messages, :format,
-          log_errors: true
-
-        if client.nil?
-          url ||= Scout::Config.get(:url, :openai_ask, :ask, :openai, env: 'OPENAI_URL')
-          key ||= LLM.get_url_config(:key, url, :openai_ask, :ask, :openai, env: 'OPENAI_KEY')
-          client = LLM::OpenAI.client url, key, log_errors
-        end
-
-        if model.nil?
-          url ||= Scout::Config.get(:url, :openai_ask, :ask, :openai, env: 'OPENAI_URL')
-          model ||= LLM.get_url_config(:model, url, :openai_ask, :ask, :openai, env: 'OPENAI_MODEL', default: 'gpt-image-1')
-        end
-
-        messages = process_input messages
-        input = []
-        parameters = {}
-        messages.each do |message|
-          input << message
-        end
-        parameters[:prompt] = LLM.print(input)
-
-        response = client.images.generate(parameters: parameters)
-
-        response
+        base64_image = begin
+                         messages.select{|info| info[:role] == 'image' }.first['content']['result']
+                       rescue
+                         Log.warn 'Image error: ' + "\n" + JSON.pretty_generate(messages)
+                         raise $!
+                       end
       end
 
       def embed_query(client, text, parameters = {})

data/lib/scout/llm/backends/glm.rb

@@ -0,0 +1,58 @@
+require_relative 'default'
+require_relative 'openai'
+require 'openai'
+
+module LLM
+  # GLM Chat Completions backend.
+  #
+  # Implemented as a module exposing singleton methods (`LLM::OpenAI.ask`, etc).
+  # We compose the backend by:
+  #   - prepending GLMAIMethods into the singleton class (overrides)
+  #   - including Backend::ClassMethods into the singleton class (shared logic)
+  module GLMAIMethods
+    def format_other(message)
+      role = message[:role]
+
+      case role.to_s
+      when 'image'
+        path = message[:content]
+        path = Chat.find_file path
+        if Open.remote?(path)
+          { role: :user, content: { type: :image_url, image_url: {url: path} } }
+        elsif Open.exists?(path)
+          path = encode_image(path)
+          { role: :user, content: [{ type: :image_url, image_url: {url: path} }] }
+        else
+          raise "Image does not exist in #{path}"
+        end
+      when 'pdf'
+        path = original_path = message[:content]
+        if Open.remote?(path)
+          { role: :user, content: { type: :input_file, file_url: path } }
+        elsif Open.exists?(path)
+          data = encode_pdf(path)
+          { role: :user, content: [{ type: :input_file, file_data: data, filename: File.basename(path) }] }
+        else
+          raise "PDF does not exist in #{path}"
+        end
+      when 'websearch'
+        { role: :tool, content: { type: 'web_search_preview' } }
+      when 'previous_response_id'
+        nil
+      else
+        message
+      end
+    end
+  end
+
+  module GLM
+    TAG = 'glm'
+    DEFAULT_MODEL = 'glm-turbo'
+
+    class << self
+      prepend OpenAIMethods
+      prepend GLMAIMethods
+      include Backend::ClassMethods
+    end
+  end
+end

data/lib/scout/llm/backends/huggingface.rb

@@ -1,3 +1,11 @@
+# query() calls ScoutPython.dict2hash, which is defined by the scout/python
+# support (scout-rig), not by this repo: require it up-front so the tool loop
+# path does not hit NameError.
+# ScoutCoder: 'scout/python' alone loads the module but PyCall::List (needed by
+# ScoutPython.py2ruby_a inside dict2hash) is only defined by pycall/list, so
+# require that too, otherwise the offline tool-loop path raises NameError.
+require 'scout/python'
+require 'pycall/list'
 require_relative 'default'
 
 module LLM
@@ -58,7 +66,11 @@ module LLM
       parameters[:chat_template] ||= IndiferentHash.pull_keys parameters, :chat_template
       parameters = parameters.keys_to_sym 
       response = client.chat(messages, formatted_tools, parameters)
-      response = ScoutPython.dict2hash(response)
+      # ScoutCoder: ScoutPython.dict2hash only works on real PyCall dicts; fake
+      # clients in tests replay plain Ruby Hashes (which have no #get), so only
+      # convert when the object actually is a python wrapper.
+      response = ScoutPython.dict2hash(response) if defined?(PyCall) && PyCall === response
+      response = response.to_h if defined?(PyCall) && (PyCall::Dict === response rescue false)
       IndiferentHash.setup({message: response})
     rescue
       Log.debug 'Input parameters: ' + "\n" + JSON.pretty_generate(parameters.except(:tools))

data/lib/scout/llm/backends/ollama.rb

@@ -114,6 +114,19 @@ module LLM
       info['role'] = 'tool'
       info
     end
+
+    # ScoutCoder: Backend::ClassMethods#ask assigns into the meta hash
+    # (meta['timestamp'] = ...) right after update_meta, so a backend override
+    # MUST return a Hash; returning nil crashes the request when log_response
+    # is on (the default). Ollama does not report OpenAI-style usage here, so an
+    # empty hash keeps the request working.
+    def update_meta(response, current_meta = nil)
+      {}
+    end
+
+    def reasoning(response, current_meta = nil)
+    end
+
   end
 
   module OLlama

data/lib/scout/llm/backends/openwebui.rb

@@ -17,20 +17,22 @@ module LLM
     include OpenAIMethods
 
     def client(options, messages = nil)
-      url, key, model = IndiferentHash.process_options options,
-        :url, :key, :model
+      url, key, model, request_timeout = IndiferentHash.process_options options,
+        :url, :key, :model, :request_timeout, 
+        request_timeout: 12000
 
       {
         base_url: url,
         key: key,
         model: model,
         method: :post,
+        request_timeout: request_timeout,
         action: 'chat/completions'
       }
     end
 
     def query(client, messages, tools = [], parameters = {})
-      base_url, key, model, method, action = IndiferentHash.process_options client.dup, :base_url, :key, :model, :method, :action
+      base_url, key, model, method, action, timeout = IndiferentHash.process_options client.dup, :base_url, :key, :model, :method, :action, :request_timeout
       url = File.join(base_url, action.to_s)
 
       parameters = parameters.dup
@@ -38,6 +40,9 @@ module LLM
       parameters[:tools] = format_tool_definitions(tools) if tools && tools.any?
       parameters[:messages] = messages
       parameters[:verify_ssl] = false
+      parameters[:timeout] = timeout.to_i if timeout
+      parameters[:read_timeout] = timeout.to_i if timeout
+      parameters[:open_timeout] = timeout.to_i if timeout
 
       headers = IndiferentHash.setup({ 'Authorization' => "Bearer #{key}", 'Content-Type' => 'application/json' })
       Misc.insist do