Design/context_aware_intent_override_system.md

Context-Aware Intent Override System

Problem Statement

The current recommendation system enforces diversity constraints (max 1-2 tracks per artist) that can conflict with explicit user intent in follow-up queries. When a user first asks for "Music like Mk.gee" and then follows up with "I want more Mk.gee tracks", the system's diversity limits prevent delivering what the user explicitly requested.

Core Issue: Static diversity constraints don't adapt to contextual user intent, leading to suboptimal recommendations when users want to explore a specific artist more deeply.

Value Proposition: Enable the system to intelligently override diversity constraints when user context clearly indicates they want more of the same artist/style, improving user satisfaction and recommendation relevance.

Requirements

Functional Requirements

• FR1: Detect follow-up queries asking for "more" of specific artists from previous recommendations
• FR2: Override diversity constraints when user intent explicitly requests artist deep-dive
• FR3: Maintain session context to track previously recommended artists and user preferences
• FR4: Avoid recommending duplicate tracks while allowing artist expansion
• FR5: Provide up to 8-10 tracks from target artist when explicitly requested
• FR6: Gracefully fall back to standard diversity constraints when context is unclear

Non-Functional Requirements

• NFR1: Context analysis should add <100ms to query processing time
• NFR2: Session context storage should be memory-efficient (max 1MB per session)
• NFR3: System should maintain backward compatibility with existing intent detection
• NFR4: Override logic should be explainable and debuggable

Architecture

High-Level Design

Query → Context Analysis → Intent Detection → Constraint Override → Ranking → Results
         ↑                   ↓                    ↓
    Session Context    Enhanced Intent      Dynamic Constraints

Core Components

1. Enhanced Query Understanding Engine

• Purpose: Detect follow-up queries and extract target entities
• Location: src/agents/planner/query_understanding_engine.py
• New Methods:
  • analyze_followup_context(query, session_context)
  • extract_more_requests(query)
  • validate_target_entity(entity, previous_context)

2. Session Context Manager Enhancement

• Purpose: Track query progression and user interest signals
• Location: src/services/conversation_context_service.py
• New Features:
  • Artist interest tracking
  • Query progression analysis
  • Previous recommendation history

3. Dynamic Constraint System

• Purpose: Override diversity constraints based on context
• Location: src/agents/judge/ranking_logic.py
• New Methods:
  • apply_context_aware_constraints(candidates, intent, context)
  • get_override_constraints(intent_override, target_entity)
  • boost_target_entity_tracks(candidates, target)

4. Intent Override Detection

• Purpose: Identify when to override standard intent classification
• New Intent Types:
  • ARTIST_DEEP_DIVE: "more Mk.gee tracks"
  • STYLE_CONTINUATION: "more like this"
  • PLAYLIST_EXPANSION: "add similar tracks"

Detailed Design

Context Analysis Flow

class ContextAnalyzer:
    def analyze_followup_intent(self, query: str, session_context: Dict) -> Dict:
        """
        Analyze if current query is a follow-up requesting more of something.
        
        Returns:
        {
            'is_followup': bool,
            'intent_override': str,  # artist_deep_dive, style_continuation, etc.
            'target_entity': str,    # artist name, style, etc.
            'confidence': float,     # 0.0-1.0
            'constraint_overrides': Dict
        }
        """

Pattern Recognition

More Request Patterns

MORE_PATTERNS = {
    'artist_deep_dive': [
        r"more (.+?) tracks",
        r"other (.+?) songs", 
        r"different (.+?) tracks",
        r"give me more (.+)",
        r"i want more (.+)"
    ],
    'style_continuation': [
        r"more like (this|that)",
        r"similar to (these|those)",
        r"keep this style"
    ]
}

Context Validation

def validate_target_in_context(target: str, previous_recs: List) -> bool:
    """Check if target artist was in previous recommendations."""
    previous_artists = {rec.artist.lower() for rec in previous_recs}
    return target.lower() in previous_artists

Constraint Override Logic

Dynamic Constraint Matrix

CONTEXT_CONSTRAINT_OVERRIDES = {
    'artist_deep_dive': {
        'max_per_artist': lambda target: {target: 8, 'others': 1},
        'min_genres': 1,  # Relax genre diversity
        'prioritize_target': True,
        'novelty_threshold': 0.2  # Lower threshold for known artist
    },
    'style_continuation': {
        'max_per_artist': 2,  # Keep some diversity
        'min_genres': 2,
        'style_consistency_weight': 0.7
    }
}

Session Context Data Model

Enhanced Session Context

@dataclass
class EnhancedSessionContext:
    session_id: str
    query_history: List[Dict]
    recommendation_history: List[Dict]
    artist_interest_signals: Dict[str, float]  # artist -> interest score
    style_preferences: Dict[str, float]        # style -> preference score
    last_interaction_time: datetime
    context_confidence: float = 0.0
    
    def add_recommendation_feedback(self, track_id: str, feedback: str):
        """Track user feedback to refine interest signals."""
        
    def detect_artist_interest_spike(self, artist: str) -> bool:
        """Detect if user is showing increased interest in specific artist."""

Implementation Plan

Phase 1: Context Analysis Foundation (Week 1)

1. Enhance Query Understanding Engine

   • Add followup pattern detection
   • Implement target entity extraction
   • Add context validation logic

2. Extend Session Context Service

   • Add query progression tracking
   • Implement artist interest signals
   • Create context confidence scoring

Phase 2: Intent Override System (Week 2)

1. Add New Intent Types

   • Implement ARTIST_DEEP_DIVE intent
   • Add STYLE_CONTINUATION intent
   • Create intent confidence scoring

2. Build Dynamic Constraint System

   • Implement constraint override logic
   • Add target entity prioritization
   • Create fallback mechanisms

Phase 3: Integration & Testing (Week 3)

1. Integrate with Existing Pipeline

   • Update ranking logic to use dynamic constraints
   • Ensure backward compatibility
   • Add comprehensive logging

2. Testing & Validation

   • Unit tests for context analysis
   • Integration tests for full pipeline
   • Performance benchmarking

Phase 4: Monitoring & Refinement (Week 4)

1. Add Monitoring

   • Context override success rates
   • User satisfaction metrics
   • Performance impact analysis

2. Fine-tuning

   • Adjust pattern recognition thresholds
   • Optimize constraint override parameters
   • Refine fallback logic

Testing Strategy

Unit Tests

• Context pattern recognition accuracy
• Intent override detection precision
• Constraint override logic validation
• Session context management

Integration Tests

• End-to-end follow-up query processing
• Context-aware recommendation flow
• Constraint override impact on results
• Session continuity across queries

Performance Tests

• Context analysis latency impact
• Memory usage for session storage
• Scalability with multiple sessions
• Database query optimization

User Acceptance Tests

• Scenario 1: "Music like Mk.gee" → "I want more Mk.gee tracks"
• Scenario 2: "Indie rock recommendations" → "More like this style"
• Scenario 3: Complex multi-turn conversations
• Scenario 4: Edge cases and ambiguous requests

Success Metrics

Quantitative Metrics

• Context Detection Accuracy: >90% for clear follow-up patterns
• User Satisfaction: >85% for override scenarios
• Response Time: <150ms total latency increase
• Override Success Rate: >80% when confidence >0.7

Qualitative Metrics

• User Experience: Seamless follow-up conversations
• Recommendation Relevance: Higher satisfaction for artist deep-dives
• System Transparency: Clear explanations for constraint overrides

Risk Assessment

Technical Risks

• High: Context analysis complexity could introduce bugs
• Medium: Performance impact from session context storage
• Low: Integration conflicts with existing intent system

Mitigation Strategies

• Comprehensive unit test coverage
• Gradual rollout with feature flags
• Fallback to standard behavior on errors
• Performance monitoring and alerting

Future Enhancements

Phase 2 Extensions

• Multi-entity Deep Dives: "More tracks like The Strokes and Arctic Monkeys"
• Temporal Context: "Play something different from yesterday"
• Mood Progression: "Keep this energy but change the genre"

Advanced Features

• Learning User Patterns: Predict when users want deep-dives
• Cross-session Context: Remember preferences across sessions
• Social Context: "More like what I shared with friends"

Dependencies

Internal Dependencies

• Enhanced Query Understanding Engine
• Session Context Service upgrades
• Dynamic Constraint System
• Intent classification improvements

External Dependencies

• No new external dependencies required
• Potential database schema updates for session storage

Conclusion

The Context-Aware Intent Override System addresses a critical gap in our recommendation engine by intelligently adapting constraints based on user context. This enhancement will significantly improve user satisfaction for follow-up queries while maintaining the quality and diversity of our recommendations.

The phased implementation approach ensures we can validate each component before full integration, minimizing risk while delivering incremental value.

---

Document Version: 1.0
Created: 2025-05-31
Status: Design Phase
Next Phase: Implementation Planning