Intent Routing & Guardrails

The system employs an intelligent Intent Router and a suite of Privacy Guardrails to ensure that user queries are processed efficiently, securely, and contextually. This logic is handled primarily within the LangGraph-powered chat agent.

Intent Routing

The Intent Router acts as the traffic controller for all incoming chat queries. Instead of performing a heavy vector search for every message (e.g., "Hello" or "Who are you?"), the system first classifies the user's intent to determine the optimal execution path.

Classification Categories

| Intent | Description | Action | | :--- | :--- | :--- | | Search / Retrieval | The user is asking a specific question about video content. | Triggers Vector Search across transcripts and visual descriptions. | | General Conversation | Greetings, small talk, or follow-up questions about the AI itself. | Responds directly using the LLM's internal knowledge. | | System Commands | Inquiries about system status or capabilities. | Provides metadata or help information. | | Blocked | Content that violates safety policies or is completely out-of-scope. | Returns a standardized refusal message. |

Real-time Routing Events

When interacting with the /api/v1/chat endpoint, the system emits ChatEvent objects via the application logic. You can monitor the stage field to see the router in action:

{
  "event": "status",
  "data": {
    "stage": "classifying",
    "intent": "search",
    "query": "Show me the elephant scene"
  },
  "timestamp": "2023-10-27T10:00:00Z"
}

Privacy Guardrails (PII Masking)

To maintain data privacy and prevent sensitive information from being sent to LLM providers (especially when using cloud backends like OpenRouter), the system integrates Microsoft Presidio for PII (Personally Identifiable Information) detection and anonymization.

How it Works

1. Detection: Before any query reaches the LLM or the vector database, it is scanned for sensitive entities such as emails, phone numbers, and names.
2. Anonymization: Detected entities are replaced with placeholders (e.g., <EMAIL_ADDRESS>).
3. Reporting: The API provides feedback when PII is detected through the chat event stream.

Configuration

Guardrails are active by default. In the event stream, look for the pii_anonymized stage:

{
  "event": "status",
  "data": {
    "stage": "pii_anonymized",
    "count": 1,
    "reason": "Detected and masked sensitive information for privacy."
  },
  "timestamp": "2023-10-27T10:00:05Z"
}

Usage in API

The routing and guardrail logic is encapsulated within the Chat API. When building a client, you should handle the different stages returned by the agent.

Request Schema

Endpoint: POST /api/v1/chat

interface ChatRequest {
    query: string;         // The raw user input
    video_ids?: string[];  // Optional: Filter search to specific videos
    session_id?: string;   // For maintaining conversation state
}

Handling Guardrail Responses

If a query is flagged by the guardrails or classified as blocked, the response will indicate the final state:

interface ChatEvent {
    event: string;
    data: {
        stage: 'classifying' | 'pii_anonymized' | 'blocked' | 'searching' | 'generating';
        message?: string; // Reason for blocking or error
        count?: number;   // Number of PII entities found
    };
}

Integration Tips

• User Feedback: Use the classifying stage to show a "Thinking..." indicator in your UI.
• Security Transparency: If pii_anonymized is triggered, it is recommended to notify the user that their query was cleaned for privacy.
• Scope Limitation: Use the video_ids parameter to restrict the Intent Router’s search space to a specific set of ingested content, improving retrieval accuracy.