Smart Shopping Assistant
Relevant source files
The following files were used as context for generating this wiki page:
The Smart Shopping Assistant is a core artificial intelligence component of the MarketSage platform designed to provide intelligent, natural language-based shopping guidance. It leverages Natural Language Processing (NLP) to interpret user queries, perform multi-platform product searches, and provide automated safety and pricing analysis. The assistant integrates deeply with the platform's security and pricing engines to ensure users make informed decisions when navigating Chinese marketplaces.
The system's scope includes intent extraction, entity recognition (such as price ranges, brands, and urgency), and the generation of structured recommendations. It serves as the primary conversational interface between the user and the complex data processing layers of the application, including the Security Analyzer and the Unified Browser Manager.
Core Architecture and Intent Processing
The assistant is implemented as a singleton service that manages conversation contexts and processes natural language via pattern matching. It uses a session-based approach to maintain context across multiple interactions within a 30-minute window.
Conversation Pipeline
The processing of a user query follows a structured pipeline:
- Context Retrieval: Fetches or initializes a
ConversationContextbased on theuserId. - Intent Extraction: Uses RegEx patterns to identify the user's goal (e.g., searching, comparing, or checking safety).
- Entity Recognition: Extracts specific parameters like product names, max prices, colors, and brands.
- Response Generation: Executes logic specific to the intent, often involving external service calls to the
PricePredictionEngineorAdvancedThreatDetection.
Intent Patterns
The assistant recognizes six primary intents to categorize user requests:
| Intent Name | Patterns / Keywords | Primary Function |
|---|---|---|
find_product | find, search, buy, purchase | Initiates product discovery across platforms. |
compare_products | compare, vs, better, difference | Triggers side-by-side product analysis. |
price_inquiry | price, cost, budget, cheap | Requests market price and prediction data. |
safety_check | safe, scam, fake, legitimate | Runs a security analysis on a product/seller. |
recommendation | recommend, suggest, advice | Generates personalized picks based on history. |
shipping_inquiry | shipping, delivery, fast, how long | Checks logistics and arrival estimates. |
Sources: src/core/ai/SmartShoppingAssistant.ts:91-115
Product Discovery and Browsing
The SmartShoppingAssistant interacts with the UnifiedBrowserManager to aggregate results from various marketplaces such as AliExpress, Temu, and DHGate. This process includes normalizing data and applying scam detection filters before the assistant presents the final recommendation.
Multi-Platform Aggregation
The assistant builds a search query from extracted entities and dispatches it to the browser manager. The results are then analyzed for safety and value ranking.
Security and Risk Analysis
A critical function of the assistant is the safety_check intent, which utilizes the SecurityAnalyzer and ScamDetectionModel. This system evaluates products based on multiple risk vectors including seller history, price anomalies, and listing quality.
Risk Evaluation Logic
The SecurityAnalyzer calculates an overall risk score using weighted factors:
- Seller History (40%): Evaluates seller ratings and account age via
Storage.getSellerRating. - Price Anomaly (30%): Uses Z-scores to determine if a price is suspiciously low compared to historical averages.
- Listing Quality (30%): Checks for scam keywords (e.g., "urgent", "guarantee", "win") and the presence of descriptions and images.
Sources: src/background/services/protect/securityAnalyzer.ts:16-55
User-Specific Actions
Depending on the risk level determined by the assistant, different actions are taken based on the user's riskTolerance settings:
| Risk Level | Action (Conservative) | Action (Aggressive) |
|---|---|---|
| CRITICAL | Hide product | Display warning |
| HIGH | Warn/Highlight | Notify |
| MEDIUM | Notify | None |
Sources: src/common/models/unifiedClient/UnifiedBrowserManager.ts:133-155, src/core/ai/SmartShoppingAssistant.ts:40-50
Enhanced Product Scouting
The assistant's capabilities are surfaced in the UI through the EnhancedScoutSection, which provides a specialized interface for browsing AI-discovered products, active deals, and a personal watchlist.
Scout Features
- Auto-Discovery: Analyzes the current active browser tab to suggest products related to the page content.
- Tiered Intelligence: Product discovery depth varies by user level (basic, enhanced, or premium). Premium users receive higher
maxResultsand a "similarity score" for each match. - Watchlist Management: Allows users to track specific products, triggering security re-evaluations and price alerts via the
SocialShoppingHub.
Technical Data Models
Assistant Response Structure
The assistant communicates through a structured AssistantResponse interface to ensure the UI can render appropriate action buttons and reasoning.
export interface AssistantResponse {
type: 'answer' | 'product_recommendation' | 'comparison' | 'warning' | 'clarification';
message: string;
products?: Product[];
alternatives?: Product[];
reasoning?: string[];
confidence: number;
followUpSuggestions?: string[];
actionButtons?: ActionButton[];
}
Sources: src/core/ai/SmartShoppingAssistant.ts:52-61
Conclusion
The Smart Shopping Assistant acts as the central intelligence hub of MarketSage, transforming complex marketplace data into actionable conversational insights. By combining NLP-based intent recognition with robust security analysis and multi-platform product discovery, it provides a safe and efficient shopping experience tailored to individual user preferences and risk tolerances.