Search Fast Paths & Intent Classification
Relevant source files
The following files were used as context for generating this wiki page:
The Search Fast Paths and Intent Classification system serves as the primary intelligence layer for the mdeAI platform. Its purpose is to analyze user natural language input, identify specific search intents (such as rentals, events, or restaurants), and determine the most efficient execution path—either a "Fast Path" deterministic search or a complex agentic reasoning flow.
This system ensures that high-confidence queries are executed immediately using structured filters, reducing latency and LLM costs, while maintaining the ability to handle ambiguous requests through clarifying questions or full agent interaction.
Sources: src/mastra/agents/router.ts:1-10, src/lib/intent-slots.ts:1-10
Architecture and Intent Routing
The system utilizes a multi-step routing logic managed primarily by the Router Agent and the Concierge Routing Workflow. The routing process categorizes user messages into specific intents and assigns a confidence score that dictates the subsequent action.
Intent Categories
The system recognizes the following primary intents:
- Rental Search: Finding apartments or long-term stays.
- Event Discovery: Locating tickets for concerts, festivals, or nightlife.
- Restaurant Search: Identifying sit-down meals and dining venues.
- Cafe Search: Specifically targeting coffee shops and remote-work friendly spots.
- Chitchat: General greetings or vague assistance.
- Unknown: Queries that do not match specific verticals.
Sources: src/mastra/agents/router.ts:11-16, src/lib/intent-slots.ts:15-22
Execution Logic Flow
The data flow follows a tiered confidence model:
- Fast-Path (Confidence ≥ 0.85): Deterministic search triggers immediately using extracted slots.
- Clarify (Confidence 0.50–0.84): The system asks a focused follow-up question.
- Agent (Confidence < 0.50): The request is handed over to a full agent for complex reasoning.
This diagram illustrates how user queries are routed based on confidence thresholds.
Sources: src/lib/intent-slots.ts:50-54, src/mastra/workflows/concierge-routing-workflow.ts:153-160
Deterministic Classification (Regex-Based)
To optimize performance, the concierge-routing-workflow implements a deterministic classification step using regular expressions and keyword matching. This allows for immediate identification of neighborhoods and key filters without invoking an LLM.
Keyword Signals
| Vertical | Key Signal Patterns |
|---|---|
| Rentals | rental, apartment, stay, long-term, bedroom, wifi, studio |
| Events | concert, salsa, nightlife, ticket, festival, tonight, weekend |
| Restaurants | restaurant, dinner, lunch, food, cuisine, eat |
| Attractions | tour, museum, viewpoint, park, day trip, hike, sightseeing |
Sources: src/mastra/workflows/concierge-routing-workflow.ts:77-105
Neighborhood Extraction
The system identifies specific Medellín neighborhoods to bias search results. Recognized areas include Laureles, El Poblado, Envigado, Belén, Estadio, Centro, and Guatapé.
Sources: src/mastra/workflows/concierge-routing-workflow.ts:40-60
Slot Extraction and Schema
When an intent is identified, the system extracts "slots"—specific parameters used to filter database queries. These are defined in the sharedSlotsSchema.
Common Slots
- Neighborhood: The specific area of interest.
- Bedrooms: Number of rooms (for rentals).
- Budget: Includes amount, currency, and type (
nightly,monthly, ortotal_trip). - Date Range: Start and end dates or labels like "this weekend".
- Vibes/Needs: Array of strings (e.g., "remote-work", "rooftop", "quiet").
Sources: src/lib/intent-slots.ts:35-47
Fast-Path Eligibility Rules
A query is only eligible for a "Search Now" action if specific mandatory slots are present:
- Rentals: Must have (Budget + Location) OR (Budget + Bedrooms + Location).
- Restaurants/Cafes: Must have
queryTextORneighborhood. - Events: Must have
neighborhood,dateRange, orvibes.
Sources: src/lib/intent-slots.ts:56-80
Workflow Dispatching
Once classified, the Router Agent dispatches the request to the appropriate vertical workflow.
The sequence shows the transition from raw text to structured database query and result rendering.
Sources: src/mastra/agents/router.ts:25-40, src/mastra/workflows/concierge-routing-workflow.ts:168-180
Search Recovery & Clarification
If a search is triggered but returns no results, or if the intent is clear but slots are missing, the system enters a recovery or clarification state.
Rental Clarification Gate
The Concierge Agent enforces a "pre-search clarification gate" for rentals. If the confidence is below 0.6 and no previous query exists in memory, it sends a single grouped clarification message:
- Format: "What dates, budget, and setup are you looking for? Example: 1BR remote-work apartment under $80/night for June."
Sources: src/mastra/agents/concierge.ts:123-145
Empty State Recovery
For rental searches with zero results:
- The system states the reason (e.g., "No 1BR in Laureles under $35/night").
- It automatically relaxes exactly one filter (price, bedrooms, or neighborhood).
- It re-runs the search and suggests alternative neighborhoods.
Sources: src/mastra/agents/concierge.ts:186-193
Summary
The Search Fast Paths and Intent Classification system provides a robust framework for handling discovery in Medellín. By combining deterministic keyword matching with flexible LLM-based intent extraction, the system achieves a balance between performance and conversational depth. The tiered confidence architecture ensures that simple queries are processed with high speed, while complex or ambiguous user needs are managed through structured clarification gates and intelligent state recovery.
Sources: src/lib/intent-slots.ts:1-10, src/mastra/agents/concierge.ts:1-20