Restructure omni services and add Chatwoot research snapshot

research/chatwoot/enterprise/app/services/captain/tools/base_service.rb

@@ -0,0 +1,53 @@
+class Captain::Tools::BaseService
+  attr_accessor :assistant
+
+  def initialize(assistant, user: nil)
+    @assistant = assistant
+    @user = user
+  end
+
+  def name
+    raise NotImplementedError, "#{self.class} must implement name"
+  end
+
+  def description
+    raise NotImplementedError, "#{self.class} must implement description"
+  end
+
+  def parameters
+    raise NotImplementedError, "#{self.class} must implement parameters"
+  end
+
+  def execute(arguments)
+    raise NotImplementedError, "#{self.class} must implement execute"
+  end
+
+  def to_registry_format
+    {
+      type: 'function',
+      function: {
+        name: name,
+        description: description,
+        parameters: parameters
+      }
+    }
+  end
+
+  def active?
+    true
+  end
+
+  private
+
+  def user_has_permission(permission)
+    return false if @user.blank?
+
+    account_user = AccountUser.find_by(account_id: @assistant.account_id, user_id: @user.id)
+    return false if account_user.blank?
+
+    return account_user.custom_role.permissions.include?(permission) if account_user.custom_role.present?
+
+    # Default permission for agents without custom roles
+    account_user.administrator? || account_user.agent?
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/base_tool.rb

@@ -0,0 +1,28 @@
+class Captain::Tools::BaseTool < RubyLLM::Tool
+  prepend Captain::Tools::Instrumentation
+
+  attr_accessor :assistant
+
+  def initialize(assistant, user: nil)
+    @assistant = assistant
+    @user = user
+    super()
+  end
+
+  def active?
+    true
+  end
+
+  private
+
+  def user_has_permission(permission)
+    return false if @user.blank?
+
+    account_user = AccountUser.find_by(account_id: @assistant.account_id, user_id: @user.id)
+    return false if account_user.blank?
+
+    return account_user.custom_role.permissions.include?(permission) if account_user.custom_role.present?
+
+    account_user.administrator? || account_user.agent?
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/get_article_service.rb

@@ -0,0 +1,18 @@
+class Captain::Tools::Copilot::GetArticleService < Captain::Tools::BaseTool
+  def self.name
+    'get_article'
+  end
+  description 'Get details of an article including its content and metadata'
+  param :article_id, type: :number, desc: 'The ID of the article to retrieve', required: true
+
+  def execute(article_id:)
+    article = Article.find_by(id: article_id, account_id: @assistant.account_id)
+    return 'Article not found' if article.nil?
+
+    article.to_llm_text
+  end
+
+  def active?
+    user_has_permission('knowledge_base_manage')
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/get_contact_service.rb

@@ -0,0 +1,18 @@
+class Captain::Tools::Copilot::GetContactService < Captain::Tools::BaseTool
+  def self.name
+    'get_contact'
+  end
+  description 'Get details of a contact including their profile information'
+  param :contact_id, type: :number, desc: 'The ID of the contact to retrieve', required: true
+
+  def execute(contact_id:)
+    contact = Contact.find_by(id: contact_id, account_id: @assistant.account_id)
+    return 'Contact not found' if contact.nil?
+
+    contact.to_llm_text
+  end
+
+  def active?
+    user_has_permission('contact_manage')
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/get_conversation_service.rb

@@ -0,0 +1,21 @@
+class Captain::Tools::Copilot::GetConversationService < Captain::Tools::BaseTool
+  def self.name
+    'get_conversation'
+  end
+  description 'Get details of a conversation including messages and contact information'
+
+  param :conversation_id, type: :integer, desc: 'ID of the conversation to retrieve', required: true
+
+  def execute(conversation_id:)
+    conversation = Conversation.find_by(display_id: conversation_id, account_id: @assistant.account_id)
+    return 'Conversation not found' if conversation.blank?
+
+    conversation.to_llm_text(include_private_messages: true)
+  end
+
+  def active?
+    user_has_permission('conversation_manage') ||
+      user_has_permission('conversation_unassigned_manage') ||
+      user_has_permission('conversation_participating_manage')
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/search_articles_service.rb

@@ -0,0 +1,35 @@
+class Captain::Tools::Copilot::SearchArticlesService < Captain::Tools::BaseTool
+  def self.name
+    'search_articles'
+  end
+  description 'Search articles based on parameters'
+  param :query, desc: 'Search articles by title or content (partial match)', required: false
+  param :category_id, type: :number, desc: 'Filter articles by category ID', required: false
+  param :status, type: :string, desc: 'Filter articles by status - MUST BE ONE OF: draft, published, archived', required: false
+
+  def execute(query: nil, category_id: nil, status: nil)
+    articles = fetch_articles(query: query, category_id: category_id, status: status)
+    return 'No articles found' unless articles.exists?
+
+    total_count = articles.count
+    articles = articles.limit(100)
+    <<~RESPONSE
+      #{total_count > 100 ? "Found #{total_count} articles (showing first 100)" : "Total number of articles: #{total_count}"}
+      #{articles.map(&:to_llm_text).join("\n---\n")}
+    RESPONSE
+  end
+
+  def active?
+    user_has_permission('knowledge_base_manage')
+  end
+
+  private
+
+  def fetch_articles(query:, category_id:, status:)
+    articles = Article.where(account_id: @assistant.account_id)
+    articles = articles.where('title ILIKE :query OR content ILIKE :query', query: "%#{query}%") if query.present?
+    articles = articles.where(category_id: category_id) if category_id.present?
+    articles = articles.where(status: status) if status.present?
+    articles
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/search_contacts_service.rb

@@ -0,0 +1,29 @@
+class Captain::Tools::Copilot::SearchContactsService < Captain::Tools::BaseTool
+  def self.name
+    'search_contacts'
+  end
+
+  description 'Search contacts based on query parameters'
+  param :email, type: :string, desc: 'Filter contacts by email'
+  param :phone_number, type: :string, desc: 'Filter contacts by phone number'
+  param :name, type: :string, desc: 'Filter contacts by name (partial match)'
+
+  def execute(email: nil, phone_number: nil, name: nil)
+    contacts = Contact.where(account_id: @assistant.account_id)
+    contacts = contacts.where(email: email) if email.present?
+    contacts = contacts.where(phone_number: phone_number) if phone_number.present?
+    contacts = contacts.where('LOWER(name) ILIKE ?', "%#{name.downcase}%") if name.present?
+
+    return 'No contacts found' unless contacts.exists?
+
+    contacts = contacts.limit(100)
+
+    <<~RESPONSE
+      #{contacts.map(&:to_llm_text).join("\n---\n")}
+    RESPONSE
+  end
+
+  def active?
+    user_has_permission('contact_manage')
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/search_conversations_service.rb

@@ -0,0 +1,58 @@
+class Captain::Tools::Copilot::SearchConversationsService < Captain::Tools::BaseTool
+  def self.name
+    'search_conversation'
+  end
+  description 'Search conversations based on parameters'
+
+  param :status, type: :string, desc: 'Status of the conversation (open, resolved, pending, snoozed). Leave empty to search all statuses.'
+  param :contact_id, type: :number, desc: 'Contact id'
+  param :priority, type: :string, desc: 'Priority of conversation (low, medium, high, urgent). Leave empty to search all priorities.'
+  param :labels, type: :string, desc: 'Labels available'
+
+  def execute(status: nil, contact_id: nil, priority: nil, labels: nil)
+    conversations = get_conversations(status, contact_id, priority, labels)
+
+    return 'No conversations found' unless conversations.exists?
+
+    total_count = conversations.count
+    conversations = conversations.limit(100)
+
+    <<~RESPONSE
+      #{total_count > 100 ? "Found #{total_count} conversations (showing first 100)" : "Total number of conversations: #{total_count}"}
+      #{conversations.map { |conversation| conversation.to_llm_text(include_contact_details: true, include_private_messages: true) }.join("\n---\n")}
+    RESPONSE
+  end
+
+  def active?
+    user_has_permission('conversation_manage') ||
+      user_has_permission('conversation_unassigned_manage') ||
+      user_has_permission('conversation_participating_manage')
+  end
+
+  private
+
+  def get_conversations(status, contact_id, priority, labels)
+    conversations = permissible_conversations
+    conversations = conversations.where(contact_id: contact_id) if contact_id.present?
+    conversations = conversations.where(status: status) if valid_status?(status)
+    conversations = conversations.where(priority: priority) if valid_priority?(priority)
+    conversations = conversations.tagged_with(labels, any: true) if labels.present?
+    conversations
+  end
+
+  def valid_status?(status)
+    status.present? && Conversation.statuses.key?(status)
+  end
+
+  def valid_priority?(priority)
+    priority.present? && Conversation.priorities.key?(priority)
+  end
+
+  def permissible_conversations
+    Conversations::PermissionFilterService.new(
+      @assistant.account.conversations,
+      @user,
+      @assistant.account
+    ).perform
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/copilot/search_linear_issues_service.rb

@@ -0,0 +1,57 @@
+class Captain::Tools::Copilot::SearchLinearIssuesService < Captain::Tools::BaseTool
+  def self.name
+    'search_linear_issues'
+  end
+
+  description 'Search Linear issues based on a search term'
+  param :term, type: :string, desc: 'The search term to find Linear issues', required: true
+
+  def execute(term:)
+    return 'Linear integration is not enabled' unless active?
+
+    linear_service = Integrations::Linear::ProcessorService.new(account: @assistant.account)
+    result = linear_service.search_issue(term)
+
+    return result[:error] if result[:error]
+
+    issues = result[:data]
+    return 'No issues found, I should try another similar search term' if issues.blank?
+
+    total_count = issues.length
+
+    <<~RESPONSE
+      Total number of issues: #{total_count}
+      #{issues.map { |issue| format_issue(issue) }.join("\n---\n")}
+    RESPONSE
+  end
+
+  def active?
+    @user.present? && @assistant.account.hooks.exists?(app_id: 'linear')
+  end
+
+  private
+
+  def format_issue(issue)
+    <<~ISSUE
+      Title: #{issue['title']}
+      ID: #{issue['id']}
+      State: #{issue['state']['name']}
+      Priority: #{format_priority(issue['priority'])}
+      #{issue['assignee'] ? "Assignee: #{issue['assignee']['name']}" : 'Assignee: Unassigned'}
+      #{issue['description'].present? ? "\nDescription: #{issue['description']}" : ''}
+    ISSUE
+  end
+
+  def format_priority(priority)
+    return 'No priority' if priority.nil?
+
+    case priority
+    when 0 then 'No priority'
+    when 1 then 'Urgent'
+    when 2 then 'High'
+    when 3 then 'Medium'
+    when 4 then 'Low'
+    else 'Unknown'
+    end
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/firecrawl_service.rb

@@ -0,0 +1,40 @@
+class Captain::Tools::FirecrawlService
+  def initialize
+    @api_key = InstallationConfig.find_by!(name: 'CAPTAIN_FIRECRAWL_API_KEY').value
+    raise 'Missing API key' if @api_key.empty?
+  end
+
+  def perform(url, webhook_url, crawl_limit = 10)
+    HTTParty.post(
+      'https://api.firecrawl.dev/v1/crawl',
+      body: crawl_payload(url, webhook_url, crawl_limit),
+      headers: headers
+    )
+  rescue StandardError => e
+    raise "Failed to crawl URL: #{e.message}"
+  end
+
+  private
+
+  def crawl_payload(url, webhook_url, crawl_limit)
+    {
+      url: url,
+      maxDepth: 50,
+      ignoreSitemap: false,
+      limit: crawl_limit,
+      webhook: webhook_url,
+      scrapeOptions: {
+        onlyMainContent: false,
+        formats: ['markdown'],
+        excludeTags: ['iframe']
+      }
+    }.to_json
+  end
+
+  def headers
+    {
+      'Authorization' => "Bearer #{@api_key}",
+      'Content-Type' => 'application/json'
+    }
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/instrumentation.rb

@@ -0,0 +1,10 @@
+module Captain::Tools::Instrumentation
+  extend ActiveSupport::Concern
+  include Integrations::LlmInstrumentation
+
+  def execute(**args)
+    instrument_tool_call(name, args) do
+      super
+    end
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/search_documentation_service.rb

@@ -0,0 +1,38 @@
+class Captain::Tools::SearchDocumentationService < Captain::Tools::BaseTool
+  def self.name
+    'search_documentation'
+  end
+  description 'Search and retrieve documentation from knowledge base'
+
+  param :query, desc: 'Search Query', required: true
+
+  def execute(query:)
+    Rails.logger.info { "#{self.class.name}: #{query}" }
+
+    translated_query = Captain::Llm::TranslateQueryService
+                       .new(account: assistant.account)
+                       .translate(query, target_language: assistant.account.locale_english_name)
+
+    responses = assistant.responses.approved.search(translated_query)
+
+    return 'No FAQs found for the given query' if responses.empty?
+
+    responses.map { |response| format_response(response) }.join
+  end
+
+  private
+
+  def format_response(response)
+    formatted_response = "
+        Question: #{response.question}
+        Answer: #{response.answer}
+        "
+    if response.documentable.present? && response.documentable.try(:external_link)
+      formatted_response += "
+          Source: #{response.documentable.external_link}
+          "
+    end
+
+    formatted_response
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/search_reply_documentation_service.rb

@@ -0,0 +1,46 @@
+class Captain::Tools::SearchReplyDocumentationService < RubyLLM::Tool
+  prepend Captain::Tools::Instrumentation
+
+  description 'Search and retrieve documentation/FAQs from knowledge base'
+
+  param :query, desc: 'Search Query', required: true
+
+  def initialize(account:, assistant: nil)
+    @account = account
+    @assistant = assistant
+    super()
+  end
+
+  def name
+    'search_documentation'
+  end
+
+  def execute(query:)
+    Rails.logger.info { "#{self.class.name}: #{query}" }
+
+    translated_query = Captain::Llm::TranslateQueryService
+                       .new(account: @account)
+                       .translate(query, target_language: @account.locale_english_name)
+
+    responses = search_responses(translated_query)
+    return 'No FAQs found for the given query' if responses.empty?
+
+    responses.map { |response| format_response(response) }.join
+  end
+
+  private
+
+  def search_responses(query)
+    if @assistant.present?
+      @assistant.responses.approved.search(query, account_id: @account.id)
+    else
+      @account.captain_assistant_responses.approved.search(query, account_id: @account.id)
+    end
+  end
+
+  def format_response(response)
+    result = "\nQuestion: #{response.question}\nAnswer: #{response.answer}\n"
+    result += "Source: #{response.documentable.external_link}\n" if response.documentable.present? && response.documentable.try(:external_link)
+    result
+  end
+end

research/chatwoot/enterprise/app/services/captain/tools/simple_page_crawl_service.rb

@@ -0,0 +1,60 @@
+class Captain::Tools::SimplePageCrawlService
+  attr_reader :external_link
+
+  def initialize(external_link)
+    @external_link = external_link
+    @doc = Nokogiri::HTML(HTTParty.get(external_link).body)
+  end
+
+  def page_links
+    sitemap? ? extract_links_from_sitemap : extract_links_from_html
+  end
+
+  def page_title
+    title_element = @doc.at_xpath('//title')
+    title_element&.text&.strip
+  end
+
+  def body_text_content
+    ReverseMarkdown.convert @doc.at_xpath('//body'), unknown_tags: :bypass, github_flavored: true
+  end
+
+  def meta_description
+    meta_desc = @doc.at_css('meta[name="description"]')
+    return nil unless meta_desc && meta_desc['content']
+
+    meta_desc['content'].strip
+  end
+
+  def favicon_url
+    favicon_link = @doc.at_css('link[rel*="icon"]')
+    return nil unless favicon_link && favicon_link['href']
+
+    resolve_url(favicon_link['href'])
+  end
+
+  private
+
+  def sitemap?
+    @external_link.end_with?('.xml')
+  end
+
+  def extract_links_from_sitemap
+    @doc.xpath('//loc').to_set(&:text)
+  end
+
+  def extract_links_from_html
+    @doc.xpath('//a/@href').to_set do |link|
+      absolute_url = URI.join(@external_link, link.value).to_s
+      absolute_url
+    end
+  end
+
+  def resolve_url(url)
+    return url if url.start_with?('http')
+
+    URI.join(@external_link, url).to_s
+  rescue StandardError
+    url
+  end
+end