Merge branch 'feature/cw-7495-api' into feature/cw-7496-frontend

spec/enterprise/jobs/captain/llm/conversation_faq_job_spec.rb

@@ -0,0 +1,57 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Llm::ConversationFaqJob, type: :job do
+  let(:account) { create(:account) }
+  let(:inbox) { create(:inbox, account: account) }
+  let(:assistant) { create(:captain_assistant, account: account, config: { feature_faq: true }) }
+  let(:conversation) { create(:conversation, account: account, inbox: inbox, first_reply_created_at: Time.zone.now) }
+  let(:faq_service) { instance_double(Captain::Llm::ConversationFaqService, generate_suggestions: []) }
+  let(:lock_manager) { instance_double(Redis::LockManager, lock: true, unlock: true) }
+  let(:lock_key) { "CAPTAIN_CONVERSATION_FAQ_LOCK::#{assistant.id}::en" }
+
+  before do
+    create(:captain_inbox, inbox: inbox, captain_assistant: assistant)
+    conversation.update!(status: :resolved)
+    allow(Redis::LockManager).to receive(:new).and_return(lock_manager)
+    allow(Captain::Llm::ConversationFaqService).to receive(:new).and_return(faq_service)
+  end
+
+  describe '#perform' do
+    it 'uses the assistant captured when the job was enqueued' do
+      replacement_assistant = create(:captain_assistant, account: account, config: { feature_faq: true })
+      inbox.captain_inbox.update!(captain_assistant: replacement_assistant)
+
+      expect(inbox.reload.captain_assistant).to eq(replacement_assistant)
+      expect(Captain::Llm::ConversationFaqService).to receive(:new)
+        .with(assistant, conversation)
+        .and_return(faq_service)
+      expect(faq_service).to receive(:generate_suggestions)
+
+      described_class.perform_now(conversation, assistant)
+    end
+
+    it 'locks FAQ grouping for the assistant and normalized language' do
+      conversation.update!(additional_attributes: { conversation_language: 'pt-BR' })
+      expected_key = "CAPTAIN_CONVERSATION_FAQ_LOCK::#{assistant.id}::pt"
+
+      expect(lock_manager).to receive(:lock).with(expected_key, described_class::LOCK_TIMEOUT).and_return(true)
+      expect(lock_manager).to receive(:unlock).with(expected_key)
+
+      described_class.perform_now(conversation, assistant)
+    end
+
+    context 'when another job holds the grouping lock' do
+      before do
+        allow(lock_manager).to receive(:lock).with(lock_key, described_class::LOCK_TIMEOUT).and_return(false)
+      end
+
+      it 'does not generate suggestions concurrently' do
+        expect(Captain::Llm::ConversationFaqService).not_to receive(:new)
+
+        expect do
+          described_class.new.perform(conversation, assistant)
+        end.to raise_error(MutexApplicationJob::LockAcquisitionError)
+      end
+    end
+  end
+end

spec/enterprise/listeners/captain_listener_spec.rb

@@ -43,7 +43,7 @@ describe CaptainListener do
       end
 
       it 'enqueues FAQ suggestion generation' do
-        expect(Captain::Llm::ConversationFaqJob).to receive(:perform_later).with(conversation)
+        expect(Captain::Llm::ConversationFaqJob).to receive(:perform_later).with(conversation, assistant)
         expect(Captain::Llm::ContactNotesService).not_to receive(:new)
 
         listener.conversation_resolved(event)

spec/enterprise/services/captain/llm/conversation_faq_prompts_service_spec.rb

@@ -0,0 +1,13 @@
+require 'rails_helper'
+
+RSpec.describe Captain::Llm::ConversationFaqPromptsService do
+  describe '.generator' do
+    it 'allows a complete FAQ answer to use several related agent messages' do
+      prompt = described_class.generator
+
+      expect(prompt).to include('message or messages that together provide a complete public answer')
+      expect(prompt).to include('Combine facts only across related agent messages')
+      expect(prompt).not_to include('no single human agent message')
+    end
+  end
+end

spec/enterprise/services/captain/llm/conversation_faq_service_spec.rb

@@ -193,6 +193,117 @@ RSpec.describe Captain::Llm::ConversationFaqService do
         end.to change(Captain::FaqObservation.discarded, :count).by(2)
         expect(captain_assistant.faq_suggestions.count).to be_zero
       end
+
+      it 'uses the conversation FAQ matching feature model' do
+        expect(RubyLLM).to receive(:chat).with(
+          model: Llm::Models.default_model_for('conversation_faq_matching')
+        ).at_least(:once).and_return(mock_chat)
+
+        service.generate_suggestions
+      end
+
+      it 'uses the account model override for conversation FAQ matching' do
+        conversation.account.update!(captain_models: { 'conversation_faq_matching' => 'gpt-5-mini' })
+
+        expect(RubyLLM).to receive(:chat).with(model: 'gpt-5-mini').at_least(:once).and_return(mock_chat)
+
+        service.generate_suggestions
+      end
+
+      it 'resolves the matching feature model from the conversation account' do
+        allow(Llm::FeatureRouter).to receive(:resolve).and_call_original
+        expect(Llm::FeatureRouter).to receive(:resolve).with(
+          feature: 'conversation_faq_matching',
+          account: conversation.account
+        ).and_call_original
+
+        service.generate_suggestions
+      end
+    end
+
+    context 'when FAQ comparison cannot be completed' do
+      let(:existing_response) do
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'Similar question', answer: 'Similar answer', embedding: embedding_one)
+      end
+      let(:comparison_response) { instance_double(RubyLLM::Message, content: comparison_response_content) }
+      let(:comparison_response_content) { 'invalid json' }
+
+      before do
+        existing_response
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? comparison_response : mock_response
+        end
+        allow(Rails.logger).to receive(:error)
+      end
+
+      it 'raises when the comparison response is malformed' do
+        expect do
+          service.generate_suggestions
+        end.to raise_error(JSON::ParserError)
+        expect(captain_assistant.faq_suggestions.count).to be_zero
+      end
+
+      context 'when the response omits the comparison result' do
+        let(:comparison_response_content) { {}.to_json }
+
+        it 'raises instead of treating the response as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(KeyError)
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+
+      context 'when the comparison result is not a boolean' do
+        let(:comparison_response_content) { { same_faq: 'false' }.to_json }
+
+        it 'raises instead of treating the response as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(TypeError, 'same_faq must be a boolean')
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+
+      context 'when the comparison provider fails' do
+        before do
+          allow(mock_chat).to receive(:ask) do |input|
+            raise RubyLLM::Error.new(nil, 'API Error') if input.start_with?('{')
+
+            mock_response
+          end
+        end
+
+        it 'raises instead of treating the failure as a non-match' do
+          expect do
+            service.generate_suggestions
+          end.to raise_error(RubyLLM::Error)
+          expect(captain_assistant.faq_suggestions.count).to be_zero
+        end
+      end
+    end
+
+    context 'when the classifier confirms a non-match' do
+      let(:sample_faqs) { [{ 'question' => 'How can I use the feature?', 'answer' => 'Enable it in settings.' }] }
+      let(:match_response) { instance_double(RubyLLM::Message, content: { same_faq: false }.to_json) }
+
+      before do
+        create(:captain_assistant_response, assistant: captain_assistant, account: captain_assistant.account,
+                                            question: 'How do I enable the feature?', answer: 'Turn it on in settings.',
+                                            embedding: embedding_one)
+        allow(embedding_service).to receive(:get_embedding).and_return(embedding_one)
+        allow(mock_chat).to receive(:ask) do |input|
+          input.start_with?('{') ? match_response : mock_response
+        end
+      end
+
+      it 'creates a new suggestion' do
+        expect do
+          service.generate_suggestions
+        end.to change(captain_assistant.faq_suggestions, :count).by(1)
+      end
     end
 
     context 'when an open suggestion is the same FAQ' do

spec/lib/llm/models_spec.rb

@@ -26,9 +26,10 @@ RSpec.describe Llm::Models do
       end
     end
 
-    it 'routes document and conversation FAQ generation independently' do
+    it 'routes each FAQ operation independently' do
       expect(described_class.default_model_for('document_faq_generation')).to eq('gpt-4.1-mini')
       expect(described_class.default_model_for('conversation_faq_generation')).to eq('gpt-5.2')
+      expect(described_class.default_model_for('conversation_faq_matching')).to eq('gpt-4.1-mini')
     end
   end