Pattern-057: Grammar-Driven Classification

class IntentCategory(Enum):
    """
    Intent categories grounded in grammatical verb types.

    Each category represents a distinct type of user intention
    mapped to grammatical semantics from the MUX grammar.
    """

    # Action Verbs - User wants something DONE
    EXECUTION = "execution"      # "Create X", "Update Y", "Delete Z"

    # Perception Verbs - User wants to SEE/KNOW
    QUERY = "query"              # "Show me X", "What is Y?"
    STATUS = "status"            # "What am I working on?"
    IDENTITY = "identity"        # "Who are you?"
    TEMPORAL = "temporal"        # "What day is it?"

    # Cognition Verbs - User wants UNDERSTANDING
    ANALYSIS = "analysis"        # "Analyze X", "Why is Y?"
    SYNTHESIS = "synthesis"      # "Summarize X", "Combine Y and Z"
    LEARNING = "learning"        # "Teach me X", "How does Y work?"

    # Planning Verbs - User wants DIRECTION
    PLANNING = "planning"        # "Plan X", "Design Y"
    STRATEGY = "strategy"        # "What's the approach for X?"
    GUIDANCE = "guidance"        # "What should I focus on?"
    PRIORITY = "priority"        # "What's most important?"

    # Social Verbs - User wants CONNECTION
    CONVERSATION = "conversation"  # "Hello", "Thanks", "Goodbye"

    # Review Verbs - User wants VALIDATION
    REVIEW = "review"            # "Review X", "Check Y"

    # Fallback
    UNKNOWN = "unknown"          # Grammatically ambiguous


# Grammatical mapping for classification hints
GRAMMAR_HINTS = {
    # Action verb patterns
    ("create", "make", "build", "add", "write"): IntentCategory.EXECUTION,
    ("update", "change", "modify", "edit"): IntentCategory.EXECUTION,
    ("delete", "remove", "cancel"): IntentCategory.EXECUTION,

    # Perception verb patterns
    ("show", "display", "list", "get"): IntentCategory.QUERY,
    ("what is", "what are", "tell me about"): IntentCategory.QUERY,

    # Cognition verb patterns
    ("analyze", "examine", "investigate"): IntentCategory.ANALYSIS,
    ("summarize", "combine", "synthesize"): IntentCategory.SYNTHESIS,
    ("explain", "teach", "how does"): IntentCategory.LEARNING,

    # Planning verb patterns
    ("plan", "design", "outline"): IntentCategory.PLANNING,
    ("what should", "recommend", "suggest"): IntentCategory.GUIDANCE,
    ("prioritize", "most important", "focus on"): IntentCategory.PRIORITY,

    # Social verb patterns
    ("hello", "hi", "hey", "good morning"): IntentCategory.CONVERSATION,
    ("thanks", "thank you", "bye", "goodbye"): IntentCategory.CONVERSATION,
}

class IntentService:
    """
    Intent handlers organized by grammatical role.

    Each handler group processes a grammatically-related
    set of intent categories.
    """

    # Action handlers - process execution requests
    async def _handle_execution_intent(self, intent: Intent) -> str:
        """Handle action verbs - something needs to be DONE."""
        pass

    # Perception handlers - answer observation questions
    async def _handle_query_canonical(self, intent: Intent) -> str:
        """Handle perception verbs - user wants to SEE."""
        pass

    async def _handle_status_canonical(self, intent: Intent) -> str:
        """Handle status perception - user observes their state."""
        pass

    async def _handle_identity_canonical(self, intent: Intent) -> str:
        """Handle identity perception - user observes Piper."""
        pass

    # Cognition handlers - provide understanding
    async def _handle_analysis_intent(self, intent: Intent) -> str:
        """Handle cognition verbs - user wants UNDERSTANDING."""
        pass

    # Planning handlers - provide direction
    async def _handle_guidance_canonical(self, intent: Intent) -> str:
        """Handle guidance - user wants DIRECTION."""
        pass

    # Social handlers - maintain connection
    async def _handle_conversation_intent(self, intent: Intent) -> str:
        """Handle social verbs - user wants CONNECTION."""
        pass