boxcars 0.7.6 → 0.8.0

data/lib/boxcars/engine/anthropic.rb

@@ -4,7 +4,9 @@ require 'anthropic'
 # Boxcars is a framework for running a series of tools to get an answer to a question.
 module Boxcars
   # A engine that uses OpenAI's API.
+  # rubocop:disable Metrics/ClassLength
   class Anthropic < Engine
+    include UnifiedObservability
     attr_reader :prompts, :llm_params, :model_kwargs, :batch_size
 
     # The default parameters to use when asking the engine.
@@ -29,7 +31,7 @@ module Boxcars
       @llm_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = 20
-      super(description: description, name: name)
+      super(description:, name:)
     end
 
     def conversation_model?(_model)
@@ -46,33 +48,50 @@ module Boxcars
     #   Defaults to Boxcars.configuration.anthropic_api_key.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
     def client(prompt:, inputs: {}, **kwargs)
-      model_params = llm_params.merge(kwargs)
-      api_key = Boxcars.configuration.anthropic_api_key(**kwargs)
-      aclient = anthropic_client(anthropic_api_key: api_key)
-      prompt = prompt.first if prompt.is_a?(Array)
-      params = convert_to_anthropic(prompt.as_messages(inputs).merge(model_params))
-      if Boxcars.configuration.log_prompts
-        if params[:messages].length < 2 && params[:system].present?
-          Boxcars.debug(">>>>>> Role: system <<<<<<\n#{params[:system]}")
+      start_time = Time.now
+      response_data = { response_obj: nil, parsed_json: nil, success: false, error: nil, status_code: nil }
+      current_params = llm_params.merge(kwargs)
+      current_prompt_object = prompt.is_a?(Array) ? prompt.first : prompt
+      api_request_params = nil
+
+      begin
+        api_key = Boxcars.configuration.anthropic_api_key(**kwargs)
+        aclient = anthropic_client(anthropic_api_key: api_key)
+        api_request_params = convert_to_anthropic(current_prompt_object.as_messages(inputs).merge(current_params))
+
+        if Boxcars.configuration.log_prompts
+          if api_request_params[:messages].length < 2 && api_request_params[:system] && !api_request_params[:system].empty?
+            Boxcars.debug(">>>>>> Role: system <<<<<<\n#{api_request_params[:system]}")
+          end
+          Boxcars.debug(api_request_params[:messages].last(2).map do |p|
+            ">>>>>> Role: #{p[:role]} <<<<<<\n#{p[:content]}"
+          end.join("\n"), :cyan)
         end
-        Boxcars.debug(params[:messages].last(2).map { |p| ">>>>>> Role: #{p[:role]} <<<<<<\n#{p[:content]}" }.join("\n"), :cyan)
+
+        raw_response = aclient.messages(parameters: api_request_params)
+        _process_anthropic_response(raw_response, response_data)
+      rescue StandardError => e
+        _handle_anthropic_error(e, response_data)
+      ensure
+        call_context = {
+          start_time:,
+          prompt_object: current_prompt_object,
+          inputs:,
+          api_request_params:,
+          current_params:
+        }
+        _track_anthropic_observability(call_context, response_data)
       end
-      response = aclient.messages(parameters: params)
-      response['completion'] = response.dig('content', 0, 'text')
-      response.delete('content')
-      response
-    rescue StandardError => e
-      err = e.respond_to?(:response) ? e.response[:body] : e
-      Boxcars.warn("Anthropic Error #{e.class.name}: #{err}", :red)
-      raise
+
+      _anthropic_handle_call_outcome(response_data:)
     end
 
     # get an answer from the engine for a question.
     # @param question [String] The question to ask the engine.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
-    def run(question, **kwargs)
+    def run(question, **)
       prompt = Prompt.new(template: question)
-      response = client(prompt: prompt, **kwargs)
+      response = client(prompt:, **)
 
       raise Error, "Anthropic: No response from API" unless response
       raise Error, "Anthropic: #{response['error']}" if response['error']
@@ -134,7 +153,7 @@ module Boxcars
       # Includes prompt, completion, and total tokens used.
       prompts.each_slice(batch_size) do |sub_prompts|
         sub_prompts.each do |sprompts, inputs|
-          response = client(prompt: sprompts, inputs: inputs, **params)
+          response = client(prompt: sprompts, inputs:, **params)
           check_response(response)
           choices << response
         end
@@ -146,7 +165,7 @@ module Boxcars
         sub_choices = choices[i * n, (i + 1) * n]
         generations.push(generation_info(sub_choices))
       end
-      EngineResult.new(generations: generations, engine_output: { token_usage: {} })
+      EngineResult.new(generations:, engine_output: { token_usage: {} })
     end
     # rubocop:enable Metrics/AbcSize
 
@@ -191,12 +210,14 @@ module Boxcars
     end
 
     # convert generic parameters to Anthopic specific ones
+    # rubocop:disable Metrics/AbcSize
     def convert_to_anthropic(params)
       params[:stop_sequences] = params.delete(:stop) if params.key?(:stop)
       params[:system] = params[:messages].shift[:content] if params.dig(:messages, 0, :role) == :system
-      params[:messages].pop if params[:messages].last[:content].blank?
+      params[:messages].pop if params[:messages].last[:content].nil? || params[:messages].last[:content].strip.empty?
       combine_assistant(params)
     end
+    # rubocop:enable Metrics/AbcSize
 
     def combine_assistant(params)
       params[:messages] = combine_assistant_entries(params[:messages])
@@ -220,5 +241,82 @@ module Boxcars
     def default_prefixes
       { system: "Human: ", user: "Human: ", assistant: "Assistant: ", history: :history }
     end
+
+    private
+
+    # Process the raw response from Anthropic API
+    # rubocop:disable Metrics/AbcSize
+    def _process_anthropic_response(raw_response, response_data)
+      response_data[:response_obj] = raw_response
+      response_data[:parsed_json] = raw_response # Already parsed by Anthropic gem
+
+      if raw_response && !raw_response["error"]
+        response_data[:success] = true
+        response_data[:status_code] = 200 # Inferred
+        # Transform response to match expected format
+        raw_response['completion'] = raw_response.dig('content', 0, 'text')
+        raw_response.delete('content')
+      else
+        response_data[:success] = false
+        err_details = raw_response["error"] if raw_response
+        msg = err_details ? "#{err_details['type']}: #{err_details['message']}" : "Unknown Anthropic API Error"
+        response_data[:error] ||= StandardError.new(msg)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Handle errors from Anthropic API calls
+    def _handle_anthropic_error(error, response_data)
+      response_data[:error] = error
+      response_data[:success] = false
+      response_data[:status_code] = error.respond_to?(:http_status) ? error.http_status : nil
+    end
+
+    # Track observability using the unified system
+    def _track_anthropic_observability(call_context, response_data)
+      duration_ms = ((Time.now - call_context[:start_time]) * 1000).round
+      request_context = {
+        prompt: call_context[:prompt_object],
+        inputs: call_context[:inputs],
+        conversation_for_api: call_context[:api_request_params]
+      }
+
+      track_ai_generation(
+        duration_ms:,
+        current_params: call_context[:current_params],
+        request_context:,
+        response_data:,
+        provider: :anthropic
+      )
+    end
+
+    # Handle the final outcome of the API call
+    def _anthropic_handle_call_outcome(response_data:)
+      if response_data[:error]
+        _handle_anthropic_error_outcome(response_data[:error])
+      elsif !response_data[:success]
+        _handle_anthropic_response_body_error(response_data[:response_obj])
+      else
+        response_data[:parsed_json] # Return the raw parsed JSON
+      end
+    end
+
+    # Handle error outcomes
+    def _handle_anthropic_error_outcome(error_data)
+      detailed_error_message = error_data.message
+      if error_data.respond_to?(:response) && error_data.response
+        detailed_error_message += " - Details: #{error_data.response[:body]}"
+      end
+      Boxcars.error("Anthropic Error: #{detailed_error_message} (#{error_data.class.name})", :red)
+      raise error_data
+    end
+
+    # Handle response body errors
+    def _handle_anthropic_response_body_error(response_obj)
+      err_details = response_obj&.dig("error")
+      msg = err_details ? "#{err_details['type']}: #{err_details['message']}" : "Unknown error from Anthropic API"
+      raise Error, msg
+    end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/boxcars/engine/cerebras.rb

@@ -21,8 +21,8 @@ module Boxcars
     # @param prompts [Array<Prompt>] The prompts to use for the Engine.
     # @param batch_size [Integer] The number of prompts to send to the Engine at a time.
     # @param kwargs [Hash] Additional parameters to pass to the Engine.
-    def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
-      super(provider: :cerebras, description: description, name: name, prompts: prompts, batch_size: batch_size, **kwargs)
+    def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **)
+      super(provider: :cerebras, description:, name:, prompts:, batch_size:, **)
     end
 
     def default_model_params

data/lib/boxcars/engine/cohere.rb

@@ -4,6 +4,7 @@
 module Boxcars
   # A engine that uses Cohere's API.
   class Cohere < Engine
+    include UnifiedObservability
     attr_reader :prompts, :llm_params, :model_kwargs, :batch_size
 
     # The default parameters to use when asking the engine.
@@ -29,7 +30,7 @@ module Boxcars
       @llm_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = 20
-      super(description: description, name: name)
+      super(description:, name:)
     end
 
     def conversation_model?(_model)
@@ -59,20 +60,45 @@ module Boxcars
     #   Defaults to Boxcars.configuration.cohere_api_key.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
     def client(prompt:, inputs: {}, **kwargs)
-      api_key = Boxcars.configuration.cohere_api_key(**kwargs)
-      params = prompt.as_prompt(inputs: inputs, prefixes: default_prefixes, show_roles: true).merge(llm_params.merge(kwargs))
-      params[:message] = params.delete(:prompt)
-      params[:stop_sequences] = params.delete(:stop) if params.key?(:stop)
-      Boxcars.debug("Prompt after formatting:#{params[:message]}", :cyan) if Boxcars.configuration.log_prompts
-      chat(params, api_key)
+      start_time = Time.now
+      response_data = { response_obj: nil, parsed_json: nil, success: false, error: nil, status_code: nil }
+      current_params = llm_params.merge(kwargs)
+      current_prompt_object = prompt.is_a?(Array) ? prompt.first : prompt
+      api_request_params = nil
+
+      begin
+        api_key = Boxcars.configuration.cohere_api_key(**kwargs)
+        api_request_params = current_prompt_object.as_prompt(inputs:, prefixes: default_prefixes,
+                                                             show_roles: true).merge(current_params)
+        api_request_params[:message] = api_request_params.delete(:prompt)
+        api_request_params[:stop_sequences] = api_request_params.delete(:stop) if api_request_params.key?(:stop)
+
+        Boxcars.debug("Prompt after formatting:#{api_request_params[:message]}", :cyan) if Boxcars.configuration.log_prompts
+
+        raw_response = _cohere_api_call(api_request_params, api_key)
+        _process_cohere_response(raw_response, response_data)
+      rescue StandardError => e
+        _handle_cohere_error(e, response_data)
+      ensure
+        call_context = {
+          start_time:,
+          prompt_object: current_prompt_object,
+          inputs:,
+          api_request_params:,
+          current_params:
+        }
+        _track_cohere_observability(call_context, response_data)
+      end
+
+      _cohere_handle_call_outcome(response_data:)
     end
 
     # get an answer from the engine for a question.
     # @param question [String] The question to ask the engine.
     # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
-    def run(question, **kwargs)
+    def run(question, **)
       prompt = Prompt.new(template: question)
-      response = client(prompt: prompt, **kwargs)
+      response = client(prompt:, **)
 
       raise Error, "Cohere: No response from API" unless response
       raise Error, "Cohere: #{response[:error]}" if response[:error]
@@ -131,5 +157,105 @@ module Boxcars
     def default_prefixes
       { system: "SYSTEM: ", user: "USER: ", assistant: "CHATBOT: ", history: :history }
     end
+
+    private
+
+    # Make the actual API call to Cohere
+    def _cohere_api_call(params, api_key)
+      raise Boxcars::Error, 'Cohere API key not set' if api_key.blank?
+
+      # Define the API endpoint and parameters
+      api_endpoint = 'https://api.cohere.ai/v1/chat'
+
+      connection = Faraday.new(api_endpoint) do |faraday|
+        faraday.request :url_encoded
+        faraday.headers['Authorization'] = "Bearer #{api_key}"
+        faraday.headers['Content-Type'] = 'application/json'
+      end
+
+      # Make the API call
+      connection.post { |req| req.body = params.to_json }
+    end
+
+    # Process the raw response from Cohere API
+    def _process_cohere_response(raw_response, response_data)
+      response_data[:response_obj] = raw_response
+      response_data[:status_code] = raw_response.status
+
+      if raw_response.status == 200
+        parsed_json = JSON.parse(raw_response.body, symbolize_names: true)
+        response_data[:parsed_json] = parsed_json
+
+        if parsed_json[:error]
+          response_data[:success] = false
+          response_data[:error] = Boxcars::Error.new("Cohere API Error: #{parsed_json[:error]}")
+        else
+          response_data[:success] = true
+        end
+      else
+        response_data[:success] = false
+        response_data[:error] = Boxcars::Error.new("HTTP #{raw_response.status}: #{raw_response.reason_phrase}")
+      end
+    end
+
+    # Handle errors from Cohere API calls
+    def _handle_cohere_error(error, response_data)
+      response_data[:error] = error
+      response_data[:success] = false
+      response_data[:status_code] = error.respond_to?(:response) && error.response ? error.response[:status] : nil
+    end
+
+    # Track observability using the unified system
+    def _track_cohere_observability(call_context, response_data)
+      duration_ms = ((Time.now - call_context[:start_time]) * 1000).round
+      request_context = {
+        prompt: call_context[:prompt_object],
+        inputs: call_context[:inputs],
+        conversation_for_api: call_context[:api_request_params]
+      }
+
+      track_ai_generation(
+        duration_ms:,
+        current_params: call_context[:current_params],
+        request_context:,
+        response_data:,
+        provider: :cohere
+      )
+    end
+
+    # Handle the final outcome of the API call
+    def _cohere_handle_call_outcome(response_data:)
+      if response_data[:error]
+        _handle_cohere_error_outcome(response_data[:error])
+      elsif !response_data[:success]
+        _handle_cohere_response_body_error(response_data[:response_obj])
+      else
+        response_data[:parsed_json] # Return the raw parsed JSON
+      end
+    end
+
+    # Handle error outcomes
+    def _handle_cohere_error_outcome(error_data)
+      detailed_error_message = error_data.message
+      if error_data.respond_to?(:response) && error_data.response
+        detailed_error_message += " - Details: #{error_data.response[:body]}"
+      end
+      Boxcars.error("Cohere Error: #{detailed_error_message} (#{error_data.class.name})", :red)
+      raise error_data
+    end
+
+    # Handle response body errors
+    def _handle_cohere_response_body_error(response_obj)
+      msg = "Unknown error from Cohere API"
+      if response_obj.respond_to?(:body)
+        begin
+          parsed_body = JSON.parse(response_obj.body)
+          msg = parsed_body["message"] || parsed_body["error"] || msg
+        rescue JSON::ParserError
+          msg = "HTTP #{response_obj.status}: #{response_obj.reason_phrase}"
+        end
+      end
+      raise Error, msg
+    end
   end
 end

data/lib/boxcars/engine/gemini_ai.rb

@@ -1,118 +1,193 @@
 # frozen_string_literal: true
 
-# Boxcars is a framework for running a series of tools to get an answer to a question.
+require 'openai' # Gemini uses the OpenAI gem with a custom URI base
+require 'json'
+
 module Boxcars
-  # A engine that uses GeminiAI's API.
+  # A engine that uses GeminiAI's API via an OpenAI-compatible interface.
   class GeminiAi < Engine
-    attr_reader :prompts, :llm_parmas, :model_kwargs, :batch_size
+    include UnifiedObservability
+    attr_reader :prompts, :llm_params, :model_kwargs, :batch_size # Corrected typo llm_parmas to llm_params
 
-    # The default parameters to use when asking the engine.
     DEFAULT_PARAMS = {
-      model: "gemini-1.5-flash-latest",
+      model: "gemini-1.5-flash-latest", # Default model for Gemini
       temperature: 0.1
+      # max_tokens is often part of the request, not a fixed default here
     }.freeze
-
-    # the default name of the engine
     DEFAULT_NAME = "GeminiAI engine"
-    # the default description of the engine
-    DEFAULT_DESCRIPTION = "useful for when you need to use AI to answer questions. " \
+    DEFAULT_DESCRIPTION = "useful for when you need to use Gemini AI to answer questions. " \
                           "You should ask targeted questions"
 
-    # A engine is a container for a single tool to run.
-    # @param name [String] The name of the engine. Defaults to "GeminiAI engine".
-    # @param description [String] A description of the engine. Defaults to:
-    #        useful for when you need to use AI to answer questions. You should ask targeted questions".
-    # @param prompts [Array<String>] The prompts to use when asking the engine. Defaults to [].
-    # @param batch_size [Integer] The number of prompts to send to the engine at once. Defaults to 20.
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
-      @llm_parmas = DEFAULT_PARAMS.merge(kwargs)
+      @llm_params = DEFAULT_PARAMS.merge(kwargs) # Corrected typo here
       @prompts = prompts
       @batch_size = batch_size
-      super(description: description, name: name)
+      super(description:, name:)
     end
 
-    # Get the OpenAI API client
-    # @param gemini_api_key [String] The access token to use when asking the engine.
-    #   Defaults to Boxcars.configuration.gemini_api_key
-    # @return [OpenAI::Client] The OpenAI API gem client.
-    def self.open_ai_client(gemini_api_key: nil)
-      access_token = Boxcars.configuration.gemini_api_key(gemini_api_key: gemini_api_key)
-      ::OpenAI::Client.new(access_token: access_token, uri_base: "https://generativelanguage.googleapis.com/v1beta/openai/")
+    # Renamed from open_ai_client to gemini_client for clarity
+    def self.gemini_client(gemini_api_key: nil)
+      access_token = Boxcars.configuration.gemini_api_key(gemini_api_key:)
+      # NOTE: The OpenAI gem might not support `log_errors: true` for custom uri_base.
+      # It's a param for OpenAI::Client specific to their setup.
+      ::OpenAI::Client.new(access_token:, uri_base: "https://generativelanguage.googleapis.com/v1beta/")
+      # Removed /openai from uri_base as it's usually for OpenAI-specific paths on custom domains.
+      # The Gemini endpoint might be directly at /v1beta/models/gemini...:generateContent
+      # This might need adjustment based on how the OpenAI gem forms the full URL.
+      # For direct generateContent, a different client or HTTP call might be needed if OpenAI gem is too restrictive.
+      # Assuming for now it's an OpenAI-compatible chat endpoint.
     end
 
-    def conversation_model?(_model)
+    # Gemini models are typically conversational.
+    def conversation_model?(_model_name)
       true
     end
 
-    # Get an answer from the engine.
-    # @param prompt [String] The prompt to use when asking the engine.
-    # @param gemini_api_key [String] The access token to use when asking the engine.
-    #   Defaults to Boxcars.configuration.gemini_api_key.
-    # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
     def client(prompt:, inputs: {}, gemini_api_key: nil, **kwargs)
-      clnt = GeminiAi.open_ai_client(gemini_api_key: gemini_api_key)
-      params = llm_parmas.merge(kwargs)
-      prompt = prompt.first if prompt.is_a?(Array)
-      params = prompt.as_messages(inputs).merge(params)
-      if Boxcars.configuration.log_prompts
-        Boxcars.debug(params[:messages].last(2).map { |p| ">>>>>> Role: #{p[:role]} <<<<<<\n#{p[:content]}" }.join("\n"), :cyan)
+      start_time = Time.now
+      response_data = { response_obj: nil, parsed_json: nil, success: false, error: nil, status_code: nil }
+      current_params = @llm_params.merge(kwargs) # Use instance var @llm_params
+      api_request_params = nil
+      current_prompt_object = prompt.is_a?(Array) ? prompt.first : prompt
+
+      begin
+        clnt = GeminiAi.gemini_client(gemini_api_key:)
+        api_request_params = _prepare_gemini_request_params(current_prompt_object, inputs, current_params)
+
+        log_messages_debug(api_request_params[:messages]) if Boxcars.configuration.log_prompts && api_request_params[:messages]
+        _execute_and_process_gemini_call(clnt, api_request_params, response_data)
+      rescue ::OpenAI::Error => e # Catch OpenAI gem errors if they apply
+        response_data[:error] = e
+        response_data[:success] = false
+        response_data[:status_code] = e.http_status if e.respond_to?(:http_status)
+      rescue StandardError => e # Catch other errors
+        response_data[:error] = e
+        response_data[:success] = false
+      ensure
+        duration_ms = ((Time.now - start_time) * 1000).round
+        request_context = {
+          prompt: current_prompt_object,
+          inputs:,
+          conversation_for_api: api_request_params&.dig(:messages) || []
+        }
+        track_ai_generation(
+          duration_ms:,
+          current_params:,
+          request_context:,
+          response_data:,
+          provider: :gemini
+        )
       end
-      clnt.chat(parameters: params)
-    rescue => e
-      Boxcars.error(e, :red)
-      raise
+
+      _gemini_handle_call_outcome(response_data:)
     end
 
-    # get an answer from the engine for a question.
-    # @param question [String] The question to ask the engine.
-    # @param kwargs [Hash] Additional parameters to pass to the engine if wanted.
-    def run(question, **kwargs)
+    def run(question, **)
       prompt = Prompt.new(template: question)
-      response = client(prompt: prompt, **kwargs)
-      raise Error, "GeminiAI: No response from API" unless response
-
-      check_response(response)
-      response["choices"].map { |c| c.dig("message", "content") || c["text"] }.join("\n").strip
+      answer = client(prompt:, inputs: {}, **)
+      Boxcars.debug("Answer: #{answer}", :cyan)
+      answer
     end
 
-    # Get the default parameters for the engine.
     def default_params
-      llm_params
+      @llm_params # Use instance variable
     end
 
-    # make sure we got a valid response
-    # @param response [Hash] The response to check.
-    # @param must_haves [Array<String>] The keys that must be in the response. Defaults to %w[choices].
-    # @raise [KeyError] if there is an issue with the access token.
-    # @raise [ValueError] if the response is not valid.
-    def check_response(response, must_haves: %w[choices])
-      if response['error'].is_a?(Hash)
-        code = response.dig('error', 'code')
-        msg = response.dig('error', 'message') || 'unknown error'
-        raise KeyError, "GEMINI_API_TOKEN not valid" if code == 'invalid_api_key'
-
-        raise ValueError, "GeminiAI error: #{msg}"
+    private
+
+    def _execute_and_process_gemini_call(gemini_client_obj, prepared_api_params, current_response_data)
+      # The OpenAI gem's `chat` method might not work directly if Gemini's endpoint
+      # isn't perfectly OpenAI-compatible for chat completions.
+      # It might require calling a different method or using a more direct HTTP client.
+      # For this refactor, we'll assume `gemini_client_obj.chat` is the intended path.
+      raw_response = gemini_client_obj.chat(parameters: prepared_api_params)
+
+      current_response_data[:response_obj] = raw_response
+      current_response_data[:parsed_json] = raw_response # OpenAI gem returns Hash
+
+      if raw_response && !raw_response["error"] &&
+         (raw_response["choices"] || raw_response["candidates"]) # Combined check for OpenAI or Gemini success
+        current_response_data[:success] = true
+        current_response_data[:status_code] = 200 # Inferred
+      else
+        current_response_data[:success] = false
+        err_details = raw_response["error"] if raw_response
+        msg = if err_details
+                (err_details.is_a?(Hash) ? err_details['message'] : err_details).to_s
+              else
+                "Unknown Gemini API Error"
+              end
+        current_response_data[:error] = StandardError.new(msg)
       end
+    end
+
+    def _prepare_gemini_request_params(current_prompt, current_inputs, current_engine_params)
+      # Gemini typically uses a chat-like interface.
+      # Prepare messages for the API
+      # current_prompt.as_messages(current_inputs) returns a hash like { messages: [...] }
+      # We need to extract the array part for the OpenAI client's :messages parameter.
+      message_hash = current_prompt.as_messages(current_inputs)
+      # Ensure roles are 'user' and 'model' for Gemini if needed, or transform them.
+      # OpenAI gem expects 'system', 'user', 'assistant'. Adapter logic might be needed.
+      # For now, assume as_messages produces compatible roles or Gemini endpoint handles them.
+
+      # Gemini might not use 'model' in the same way in request body if using generateContent directly.
+      # If using OpenAI gem's chat method, it expects 'model' for routing.
+      # Let's assume api_request_params are for OpenAI gem's chat method.
+      { messages: message_hash[:messages] }.merge(current_engine_params)
+    end
+
+    def log_messages_debug(messages)
+      return unless messages.is_a?(Array)
+
+      Boxcars.debug(messages.last(2).map { |p| ">>>>>> Role: #{p[:role]} <<<<<<\n#{p[:content]}" }.join("\n"), :cyan)
+    end
 
-      must_haves.each do |key|
-        raise ValueError, "Expecting key #{key} in response" unless response.key?(key)
+    def _gemini_handle_call_outcome(response_data:)
+      if response_data[:error]
+        Boxcars.error("GeminiAI Error: #{response_data[:error].message} (#{response_data[:error].class.name})", :red)
+        raise response_data[:error]
+      elsif !response_data[:success]
+        err_details = response_data.dig(:response_obj, "error")
+        msg = if err_details
+                err_details.is_a?(Hash) ? "#{err_details['type']}: #{err_details['message']}" : err_details.to_s
+              else
+                "Unknown error from GeminiAI API"
+              end
+        raise Error, msg
+      else
+        _extract_content_from_gemini_response(response_data[:parsed_json])
       end
     end
 
-    # the engine type
-    def engine_type
-      "gemini_ai"
+    def _extract_content_from_gemini_response(parsed_json)
+      # Handle Gemini's specific response structure (candidates)
+      # or OpenAI-compatible structure if the endpoint behaves that way.
+      if parsed_json&.key?("candidates") # Native Gemini generateContent response
+        parsed_json["candidates"].map { |c| c.dig("content", "parts", 0, "text") }.join("\n").strip
+      elsif parsed_json&.key?("choices") # OpenAI-compatible response
+        parsed_json["choices"].map { |c| c.dig("message", "content") || c["text"] }.join("\n").strip
+      else
+        raise Error, "GeminiAI: Could not extract answer from response"
+      end
     end
 
-    # Calculate the maximum number of tokens possible to generate for a prompt.
-    # @param prompt_text [String] The prompt text to use.
-    # @return [Integer] the number of tokens possible to generate.
-    def max_tokens_for_prompt(prompt_text)
-      num_tokens = get_num_tokens(prompt_text)
+    # check_response method might be partially covered by _gemini_handle_call_outcome
+    # Retaining it if run method still uses it explicitly.
+    def check_response(response, must_haves: %w[choices candidates])
+      if response['error'].is_a?(Hash)
+        code = response.dig('error', 'code')
+        msg = response.dig('error', 'message') || 'unknown error'
+        # GEMINI_API_TOKEN is not standard, usually it's an API key.
+        # This check might need to align with actual error codes from Gemini.
+        raise KeyError, "Gemini API Key not valid or permission issue" if ['invalid_api_key', 'permission_denied'].include?(code)
+
+        raise ValueError, "GeminiAI error: #{msg}"
+      end
 
-      # get max context size for model by name
-      max_size = 8096
-      max_size - num_tokens
+      # Check for either 'choices' (OpenAI style) or 'candidates' (Gemini native style)
+      has_valid_content = must_haves.any? { |key| response.key?(key) && !response[key].empty? }
+      raise ValueError, "Expecting key like 'choices' or 'candidates' in response" unless has_valid_content
     end
   end
 end