feat: Migrate ruby llm captain (#12981)

Co-authored-by: aakashb95 <aakash@chatwoot.com>
Co-authored-by: Shivam Mishra <scm.mymail@gmail.com>

enterprise/app/helpers/captain/chat_helper.rb

@@ -1,31 +1,83 @@
 module Captain::ChatHelper
   include Integrations::LlmInstrumentation
-  include Captain::ToolExecutionHelper
+  include Captain::ChatResponseHelper
 
   def request_chat_completion
     log_chat_completion_request
 
+    chat = build_chat
+
+    add_messages_to_chat(chat)
     with_agent_session do
-      response = instrument_llm_call(instrumentation_params) do
-        @client.chat(
-          parameters: chat_parameters
-        )
-      end
-      handle_response(response)
+      response = chat.ask(conversation_messages.last[:content])
+      build_response(response)
     end
   rescue StandardError => e
     Rails.logger.error "#{self.class.name} Assistant: #{@assistant.id}, Error in chat completion: #{e}"
     raise e
   end
 
-  def instrumentation_params
+  private
+
+  def build_chat
+    llm_chat = chat(model: @model, temperature: temperature)
+    llm_chat.with_params(response_format: { type: 'json_object' })
+
+    llm_chat = setup_tools(llm_chat)
+    setup_system_instructions(llm_chat)
+    setup_event_handlers(llm_chat)
+
+    llm_chat
+  end
+
+  def setup_tools(chat)
+    @tools&.each do |tool|
+      chat.with_tool(tool)
+    end
+    chat
+  end
+
+  def setup_system_instructions(chat)
+    system_messages = @messages.select { |m| m[:role] == 'system' || m[:role] == :system }
+    combined_instructions = system_messages.pluck(:content).join("\n\n")
+    chat.with_instructions(combined_instructions)
+  end
+
+  def setup_event_handlers(chat)
+    chat.on_new_message { start_llm_turn_span(instrumentation_params(chat)) }
+    chat.on_end_message { |message| end_llm_turn_span(message) }
+    chat.on_tool_call { |tool_call| handle_tool_call(tool_call) }
+    chat.on_tool_result { |result| handle_tool_result(result) }
+
+    chat
+  end
+
+  def handle_tool_call(tool_call)
+    persist_thinking_message(tool_call)
+    start_tool_span(tool_call)
+    @pending_tool_calls ||= []
+    @pending_tool_calls.push(tool_call)
+  end
+
+  def handle_tool_result(result)
+    end_tool_span(result)
+    persist_tool_completion
+  end
+
+  def add_messages_to_chat(chat)
+    conversation_messages[0...-1].each do |msg|
+      chat.add_message(role: msg[:role].to_sym, content: msg[:content])
+    end
+  end
+
+  def instrumentation_params(chat = nil)
     {
       span_name: "llm.captain.#{feature_name}",
       account_id: resolved_account_id,
       conversation_id: @conversation_id,
       feature_name: feature_name,
       model: @model,
-      messages: @messages,
+      messages: chat ? chat.messages.map { |m| { role: m.role.to_s, content: m.content.to_s } } : @messages,
       temperature: temperature,
       metadata: {
         assistant_id: @assistant&.id
@@ -33,14 +85,8 @@ module Captain::ChatHelper
     }
   end
 
-  def chat_parameters
-    {
-      model: @model,
-      messages: @messages,
-      tools: @tool_registry&.registered_tools || [],
-      response_format: { type: 'json_object' },
-      temperature: temperature
-    }
+  def conversation_messages
+    @messages.reject { |m| m[:role] == 'system' || m[:role] == :system }
   end
 
   def temperature
@@ -51,8 +97,6 @@ module Captain::ChatHelper
     @account&.id || @assistant&.account_id
   end
 
-  private
-
   # Ensures all LLM calls and tool executions within an agentic loop
   # are grouped under a single trace/session in Langfuse.
   #
@@ -78,7 +122,7 @@ module Captain::ChatHelper
   def log_chat_completion_request
     Rails.logger.info(
       "#{self.class.name} Assistant: #{@assistant.id}, Requesting chat completion
-      for messages #{@messages} with #{@tool_registry&.registered_tools&.length || 0} tools
+      for messages #{@messages} with #{@tools&.length || 0} tools
       "
     )
   end

enterprise/app/helpers/captain/chat_response_helper.rb

@@ -0,0 +1,52 @@
+module Captain::ChatResponseHelper
+  private
+
+  def build_response(response)
+    Rails.logger.debug { "#{self.class.name} Assistant: #{@assistant.id}, Received response #{response}" }
+
+    parsed = parse_json_response(response.content)
+
+    persist_message(parsed, 'assistant')
+    parsed
+  end
+
+  def parse_json_response(content)
+    content = content.gsub('```json', '').gsub('```', '')
+    content = content.strip
+    JSON.parse(content)
+  rescue JSON::ParserError => e
+    Rails.logger.error "#{self.class.name} Assistant: #{@assistant.id}, Error parsing JSON response: #{e.message}"
+    { 'content' => content }
+  end
+
+  def persist_thinking_message(tool_call)
+    return if @copilot_thread.blank?
+
+    tool_name = tool_call.name.to_s
+
+    persist_message(
+      {
+        'content' => "Using #{tool_name}",
+        'function_name' => tool_name
+      },
+      'assistant_thinking'
+    )
+  end
+
+  def persist_tool_completion
+    return if @copilot_thread.blank?
+
+    tool_call = @pending_tool_calls&.pop
+    return unless tool_call
+
+    tool_name = tool_call.name.to_s
+
+    persist_message(
+      {
+        'content' => "Completed #{tool_name}",
+        'function_name' => tool_name
+      },
+      'assistant_thinking'
+    )
+  end
+end

enterprise/app/helpers/captain/tool_execution_helper.rb

@@ -1,83 +0,0 @@
-module Captain::ToolExecutionHelper
-  private
-
-  def handle_response(response)
-    Rails.logger.debug { "#{self.class.name} Assistant: #{@assistant.id}, Received response #{response}" }
-    message = response.dig('choices', 0, 'message')
-
-    if message['tool_calls']
-      process_tool_calls(message['tool_calls'])
-    else
-      message = JSON.parse(message['content'].strip)
-      persist_message(message, 'assistant')
-      message
-    end
-  end
-
-  def process_tool_calls(tool_calls)
-    append_tool_calls(tool_calls)
-    tool_calls.each { |tool_call| process_tool_call(tool_call) }
-    request_chat_completion
-  end
-
-  def process_tool_call(tool_call)
-    arguments = JSON.parse(tool_call['function']['arguments'])
-    function_name = tool_call['function']['name']
-    tool_call_id = tool_call['id']
-
-    if @tool_registry.respond_to?(function_name)
-      execute_tool(function_name, arguments, tool_call_id)
-    else
-      process_invalid_tool_call(function_name, tool_call_id)
-    end
-  end
-
-  def execute_tool(function_name, arguments, tool_call_id)
-    persist_tool_status(function_name, 'captain.copilot.using_tool')
-    result = perform_tool_call(function_name, arguments)
-    persist_tool_status(function_name, 'captain.copilot.completed_tool_call')
-    append_tool_response(result, tool_call_id)
-  end
-
-  def perform_tool_call(function_name, arguments)
-    instrument_tool_call(function_name, arguments) do
-      @tool_registry.send(function_name, arguments)
-    end
-  rescue StandardError => e
-    Rails.logger.error "Tool #{function_name} failed: #{e.message}"
-    "Error executing #{function_name}: #{e.message}"
-  end
-
-  def persist_tool_status(function_name, translation_key)
-    persist_message(
-      {
-        content: I18n.t(translation_key, function_name: function_name),
-        function_name: function_name
-      },
-      'assistant_thinking'
-    )
-  end
-
-  def append_tool_calls(tool_calls)
-    @messages << {
-      role: 'assistant',
-      tool_calls: tool_calls
-    }
-  end
-
-  def process_invalid_tool_call(function_name, tool_call_id)
-    persist_message(
-      { content: I18n.t('captain.copilot.invalid_tool_call'), function_name: function_name },
-      'assistant_thinking'
-    )
-    append_tool_response(I18n.t('captain.copilot.tool_not_available'), tool_call_id)
-  end
-
-  def append_tool_response(content, tool_call_id)
-    @messages << {
-      role: 'tool',
-      tool_call_id: tool_call_id,
-      content: content
-    }
-  end
-end