Class: Assistant::ToolRouter

Inherits:

Object

Object
Assistant::ToolRouter

show all

Defined in:: app/services/assistant/tool_router.rb

Overview

Automatic tool routing: decides which tool services to activate based on
the user's query and conversation history.

Routing is AI-primary — a fast/cheap LLM call reads the tool catalog and
selects the set of tools needed. Two explicit-intent
mechanisms bypass the AI entirely:

Chip badges — user clicks a tool chip, sent as forced_tools[]
@mentions — user types @Search Console in the query

Conversation history carries forward stateful services (blog editing, etc.)
so follow-up messages don't lose context. If the AI call fails or times
out, content is activated as a safe universal fallback.

Usage:
services = Assistant::ToolRouter.route(
"Show me sales YTD",
conversation: @conversation,
permitted_services: %w[content app_db postgres_versions]
)

=> ["content", "app_db"]

Constant Summary collapse

MENTION_ALIASES = Canonical kebab-case handles for @mentions. The autocomplete inserts these exact handles (e.g. @google-analytics). Additional aliases map common abbreviations and free-typed variants. Format: downcased alias → service key

{
  # Canonical handles (kebab-case, inserted by autocomplete)
  'app-db'               => 'app_db',
  'content-search'       => 'content',
  'image-management'     => 'image_management',
  'faq-management'       => 'faq_management',
  'versions-db'          => 'postgres_versions',
  'google-analytics'     => 'google_analytics',
  'search-console'       => 'search_console',
  'google-ads'           => 'google_ads',
  'ahrefs'               => 'ahrefs',
  'blog-management'      => 'blog_management',
  'email-management'     => 'email_management',
  'product-catalog'      => 'product_catalog',
  'spec-management'      => 'product_spec_management',
  'keywords-people-use'  => 'keywords_people_use',

  'basecamp'             => 'basecamp',

  # Short aliases for manual typing
  'db'       => 'app_db',
  'sql'      => 'app_db',
  'content'  => 'content',
  'images'   => 'image_management',
  'faq'      => 'faq_management',
  'versions' => 'postgres_versions',
  'audit'    => 'postgres_versions',
  'ga4'      => 'google_analytics',
  'ga'       => 'google_analytics',
  'gsc'      => 'search_console',
  'ads'      => 'google_ads',
  'blog'     => 'blog_management',
  'email' => 'email_management',
  'email-template' => 'email_management',
  'campaign'     => 'email_management',
  'campaigns'    => 'email_management',
  'newsletter'   => 'email_management',
  'products' => 'product_catalog',
  'catalog'  => 'product_catalog',
  'sku'      => 'product_catalog',
  'specs'    => 'product_spec_management',
  'spec'     => 'product_spec_management',
  'kpu'      => 'keywords_people_use',
  'bc'       => 'basecamp',
  'todos'    => 'basecamp',

  # Conversation memory
  'conversation-memory' => 'conversation_memory',
  'my-conversations'    => 'conversation_memory',
  'memory'              => 'conversation_memory',

  # Brain management
  'brain-management'    => 'brain_management',
  'brain'               => 'brain_management',

  # Support Cases
  'support-cases'       => 'support_cases',
  'support'             => 'support_cases',
  'tickets'             => 'support_cases',
  'cases'               => 'support_cases',

  # Sales Management
  'sales-management'    => 'sales_management',
  'sales'               => 'sales_management',
  'pipeline'            => 'sales_management',
  'reps'                => 'sales_management',
  'team'                => 'sales_management',
  'workload'            => 'sales_management',
  'schedule'            => 'sales_management',

  # Gamma
  'gamma'               => 'gamma',
  'gamma.app'           => 'gamma',
  'presentation'        => 'gamma',
  'slide-deck'          => 'gamma',
  'slides'              => 'gamma'
}.freeze

MENTION_PATTERN = Regex that matches @mentions in the query. Captures the handle after @ (kebab-case words like google-analytics, or simple single words like ga4).

/@(\w[\w-]*)/i

STATEFUL_SERVICES = Services that represent active multi-step workflows where follow-up messages (corrections, refinements, re-runs) need the same tools as the prior turn even if the follow-up message contains no explicit keywords for that service. Example: "change the C$ symbol" doesn't mention "blog" but still needs blog_management. gamma is intentionally excluded — it is opt-in only (@gamma mention or chip badge).

%w[
  blog_management email_management product_catalog product_spec_management
  image_management faq_management basecamp
  content keywords_people_use seo_audit
  app_db support_cases sales_management
].freeze

SERVICE_BUNDLES = Services that must always be bundled together when the primary service is active. Blog work consistently needs content search (for internal link lookups) and FAQ management (for creating/finding FAQs embedded in posts). These are bundled automatically rather than relying on the AI classifier to remember them every time.

{
  'blog_management' => %w[content faq_management]
}.freeze

SERVICE_DEPENDENCIES = Implicit co-dependencies: when a service is activated, these companion services are also loaded because the workflow inherently uses their tools. Example: blog_management calls find_faqs (content), find_images (content), and image embeds (image_management) during blog editing.

{
  'blog_management' => %w[content image_management faq_management],
  'email_management' => %w[content image_management],
  'faq_management' => %w[content]
}.freeze

ALWAYS_ON_SERVICES = Lightweight services always included when the user's role permits them. brain_management gives permitted users propose_brain_entry to capture corrections reactively. search_brain (read-only retrieval) lives in the content service so ALL users can access brain entries without needing brain_management permission.

%w[brain_management].freeze

CRM_URL_PATTERN = CRM URL pattern — when a query contains a CRM URL, the user is referencing internal data that requires database access. This bypasses the AI classifier to prevent misrouting (e.g. campaign link clicks classified as content search).

%r{crm\.warmlyyours\.com/}i

BASECAMP_URL_PATTERN = Basecamp URL pattern — when a query contains a Basecamp URL, the user wants to interact with that Basecamp resource (todo, message, comment, etc.).

%r{(\d+\.)?basecamp\.com/}i

BLOG_POST_URL_PATTERN = Blog post URL pattern — matches both public-facing and CRM blog URLs: www.warmlyyours.com/en-US/posts/... crm.warmlyyours.com/posts/...

%r{warmlyyours\.com/([\w-]+/)?posts/}i

SUPPORT_CASE_URL_PATTERN = Regex pattern matching support case url.

%r{crm\.warmlyyours\.com/support_cases}i

EMAIL_TEMPLATE_URL_PATTERN = CRM email-template URL — pasting one means the user wants to read/edit that template, so route to email_management (curated tools) rather than raw SQL.

%r{crm\.warmlyyours\.com/email_templates}i

SEO_ACTION_ITEM_PATTERN = SEO action item pattern — matches "Action Item #12345" or "action items" in user queries, signaling that seo_audit + blog_management are needed.

/action\s+items?\b|#\d{4,6}\b.*(?:mark|complet|status|pending)/i

CRM_IDENTIFIER_PATTERN = CRM identifier patterns — when a query references ON12345 (opportunity) or CN12345 (party), load sales_management so get_opportunity_brief / get_customer_brief are available. Without this, the AI classifier routes these queries to app_db only, the brief tools aren't loaded, and Sunny falls back to hand-rolled SQL — which is exactly the workflow the briefs were built to replace.

/\b(?:ON|CN|SQ)\d{5,}\b/i

Class Method Summary collapse

.build_tool_menu(permitted_services) ⇒ Object
Build a compact menu of available tools for the AI prompt.
.extract_mentioned_services(query) ⇒ Array<String>
Public: extract @mentions from a query and return resolved service keys.
.resolve_handles(handles) ⇒ Array<String>
Public: resolve an array of tool handles (from form params) to service keys.
.route(query, conversation: nil, permitted_services: [], forced_services: [], classifier_result: nil) ⇒ Array<String>
Route a user query to the appropriate tool services.
.strip_mentions(query) ⇒ String
Strip @mentions from the query so the LLM sees clean text.

Class Method Details

.build_tool_menu(permitted_services) ⇒ `Object`

Build a compact menu of available tools for the AI prompt.
Public so QueryClassifier can reuse it without duplicating catalog logic.

# File 'app/services/assistant/tool_router.rb', line 364

def self.build_tool_menu(permitted_services)
  catalog = ChatToolBuilder.chat_services
  permitted_services.filter_map do |key|
    meta = catalog[key]
    next unless meta

    "- #{key}: #{meta[:description]}"
  end
end

.extract_mentioned_services(query) ⇒ `Array<String>`

Public: extract @mentions from a query and return resolved service keys.
Used by the controller to identify which tools were explicitly forced.

Parameters:

query (String)

Returns:

(Array<String>) —
unique resolved service keys



285
286
287

# File 'app/services/assistant/tool_router.rb', line 285

def self.extract_mentioned_services(query)
  extract_mentions(query).uniq
end

.resolve_handles(handles) ⇒ `Array<String>`

Public: resolve an array of tool handles (from form params) to service keys.
Handles are kebab-case strings sent by the chip badges (e.g. "google-analytics").

Parameters:

handles (Array<String>) —
tool handles from the client

Returns:

(Array<String>) —
unique resolved service keys (invalid handles silently ignored)

# File 'app/services/assistant/tool_router.rb', line 294

def self.resolve_handles(handles)
  return [] if handles.blank?

  handles.filter_map do |h|
    raw = h.to_s.strip.downcase
    ChatToolBuilder.service_key_for_handle(raw) || MENTION_ALIASES[raw]
  end.uniq
end

.route(query, conversation: nil, permitted_services: [], forced_services: [], classifier_result: nil) ⇒ `Array<String>`

Route a user query to the appropriate tool services.

Parameters:

query (String) —
the user's message
conversation (AssistantConversation, nil) (defaults to: nil) —
current conversation (for history)
permitted_services (Array<String>) (defaults to: []) —
services the user's role allows
forced_services (Array<String>) (defaults to: []) —
service keys explicitly forced by chip badges
classifier_result (Assistant::QueryClassifier::Result, nil) (defaults to: nil) —
pre-computed classification
to avoid a duplicate AI call when the caller has already run QueryClassifier

Returns:

(Array<String>) —
service keys to activate

# File 'app/services/assistant/tool_router.rb', line 194

def self.route(query, conversation: nil, permitted_services: [], forced_services: [], classifier_result: nil)
  services = Set.new

  # 1. Explicitly forced tools (chip badges) — highest priority, always honoured.
  services.merge(forced_services) if forced_services.present?

  # 2. @mentions in text — always honoured.
  mentioned = extract_mentions(query)
  services.merge(mentioned)

  # 2b. URL detection — unambiguous signals that bypass AI classification.
  # Support-case URLs are handled by curated tools; avoid pulling raw SQL (app_db) unless the query is broader CRM.
  services << 'app_db' if query.match?(CRM_URL_PATTERN) && !query.match?(SUPPORT_CASE_URL_PATTERN) && !query.match?(EMAIL_TEMPLATE_URL_PATTERN)
  services << 'basecamp' if query.match?(BASECAMP_URL_PATTERN)
  services << 'blog_management' if query.match?(BLOG_POST_URL_PATTERN)
  services << 'support_cases' if query.match?(SUPPORT_CASE_URL_PATTERN)
  services << 'email_management' if query.match?(EMAIL_TEMPLATE_URL_PATTERN)

  # 2c. SEO action item references — "Action Item #22824", "SEO action items", etc.
  if query.match?(SEO_ACTION_ITEM_PATTERN)
    services << 'seo_audit'
    services << 'blog_management'
  end

  # 2d. CRM identifier references (ON12345 / CN12345 / SQ12345) — load
  # sales_management so the bundled brief tools (get_opportunity_brief,
  # get_customer_brief) are available. The AI classifier alone routes
  # these to app_db only, which forces Sunny to hand-roll SQL and
  # negates the whole point of the bundled tools. app_db comes along
  # for follow-up queries that need columns the brief doesn't return.
  if query.match?(CRM_IDENTIFIER_PATTERN)
    services << 'sales_management'
    services << 'app_db'
  end

  # 3. AI classification — the primary routing mechanism.
  # When the caller has already run QueryClassifier (e.g. the controller),
  # reuse its tools to avoid a duplicate LLM round-trip.
  ai_services = if classifier_result
                  classifier_result.tools
                else
                  ai_classify(query, permitted_services)
                end
  services.merge(ai_services)

  # 4. Conversation continuity
  if conversation
    history_services = ChatToolBuilder.services_from_history(conversation)

    # 4a. Inherit parent conversation's tool services for forked conversations.
    # When a user forks ("continue in new conversation"), the new conversation
    # has no tool-call history yet, so services_from_history returns [].
    # Carry forward the parent's persisted tool_services so the user doesn't
    # have to re-enable badges for the same workflow.
    if history_services.empty? && conversation.parent_conversation_id.present?
      parent = AssistantConversation.find_by(id: conversation.parent_conversation_id)
      history_services = (parent&.tool_services || []).compact_blank if parent
    end

    # Capture current-turn signals before merging history so the
    # vague follow-up check isn't short-circuited by carried-forward services.
    auto_detected = services - forced_services.to_set - mentioned.to_set

    stateful_from_history = history_services & STATEFUL_SERVICES
    services.merge(stateful_from_history)

    # For vague follow-ups where AI found nothing new, carry forward
    # ALL prior services (e.g. "try again", "do the prior week").
    services.merge(history_services) if auto_detected.empty?
  end

  # 5. Fallback: if nothing matched, activate content as a universal default.
  services << 'content' if services.empty?

  # Expand implicit co-dependencies (blog_management needs content, etc.)
  expand_dependencies!(services)

  # 6. Always-on services for permitted users only.
  #    brain_management → propose_brain_entry (captures corrections).
  #    search_brain is in the content service (available to everyone).
  ALWAYS_ON_SERVICES.each { |s| services << s if permitted_services.include?(s) }

  # Intersect with what the user is permitted to access
  services.to_a & permitted_services
end

.strip_mentions(query) ⇒ `String`

Strip @mentions from the query so the LLM sees clean text.
Public because the controller needs it to clean the message before
passing it to the worker.

Parameters:

query (String)

Returns:

(String) —
query with @mentions removed

# File 'app/services/assistant/tool_router.rb', line 336

def self.strip_mentions(query)
  return query unless query.include?('@')

  cleaned = query.gsub(MENTION_PATTERN) do |full|
    raw = Regexp.last_match(1).strip.downcase
    resolve_mention(raw) ? '' : full
  end
  cleaned.gsub(/\s{2,}/, ' ').strip
end

Class: Assistant::ToolRouter

Overview

=> ["content", "app_db"]

Constant Summary collapse

Class Method Summary collapse

Class Method Details

.build_tool_menu(permitted_services) ⇒ Object

.extract_mentioned_services(query) ⇒ Array<String>

.resolve_handles(handles) ⇒ Array<String>

.route(query, conversation: nil, permitted_services: [], forced_services: [], classifier_result: nil) ⇒ Array<String>

.strip_mentions(query) ⇒ String

.build_tool_menu(permitted_services) ⇒ `Object`

.extract_mentioned_services(query) ⇒ `Array<String>`

.resolve_handles(handles) ⇒ `Array<String>`

.route(query, conversation: nil, permitted_services: [], forced_services: [], classifier_result: nil) ⇒ `Array<String>`

.strip_mentions(query) ⇒ `String`