API Endpoints
Frontend API Routes (Next.js)
/api/ask
Method: POST
Purpose: Proxy for /ask-new backend endpoint
Authentication: JWT token required
Features:
Request Deduplication : Prevents duplicate requests
Error Handling : Graceful fallbacks and user-friendly errors
Streaming Support : Server-Sent Events (SSE) for real-time updates
CORS Handling : Proper cross-origin request management
Token Management : Automatic JWT token handling
Request Flow:
Frontend sends request to `/api/ask`
Next.js API route validates and forwards to backend `/ask-new`
Backend processes with LangGraph workflow
Streaming response sent back through proxy
Frontend receives real-time updates
/api/enhanced-chat
Method: POST
Purpose: Enhanced chat with additional features
Features:
Title Generation : Dynamic conversation titles
Context Management : Advanced conversation context
Response Formatting : Enhanced data presentation
Visualization Support : Chart and graph generation
/api/fun-fact
Method: GET
Purpose: Generate random fun facts about film data
Features:
Error Handling : Graceful degradation
Random Selection : Variety in fun fact content
Backend API Endpoints (FastAPI)
/ask-new - Main Chat Endpoint
Method: POST
Purpose: Primary streaming chat endpoint with LangGraph workflow orchestration
Authentication: JWT Bearer token required
Request Body:
{
"question": "Show me the top performing films by genre?",
"session_id": "user123",
"datamart": "usheru_data_mart"
}Response Format: Server-Sent Events (SSE) stream
{"status": "LLM is generating SQL query...", "type": "status"}Final Response:
{
"status": "FINAL_RESULT",
"type": "result",
"data": {
"query": "SELECT genre, cd.title, SUM(cd.revenue) AS total_revenue\nFROM cogent-tine-87309.nl_filmfonds_data_mart.content_dimension AS cd\nCROSS JOIN UNNEST(cd.genres) AS genre\nWHERE cd.content_type = 'Film'\nGROUP BY genre, cd.title\nORDER BY total_revenue DESC\nLIMIT 3",
"result": [
[
"genre",
"title",
"total_revenue"
],
[
"Action/Adventure",
"Dunkirk",
527000000
],
[
"Drama",
"Dunkirk",
527000000
],
[
"Suspense/Thriller",
"Dunkirk",
527000000
]
],
"insights": "Based on our data, the top-performing film across multiple genres is **Dunkirk**. It stands out in the **Action/Adventure**, **Drama**, and **Suspense/Thriller** categories, with a total performance of **$527 million**. This impressive figure highlights Dunkirk's broad appeal and success across different audiences. Our entertainment data shows that Dunkirk is a significant hit, consistently leading in these genres.",
"token_usage": {
"total_tokens": 13172,
"intent_tokens": 15,
"visualization_detection_tokens": 328,
"query_tokens": 11925,
"answer_tokens": 904,
"latency_secs": 9.234
},
"session_id": "f320d3d3-63b7-4829-9b67-61aa56e26e92",
"conversation_count": 0,
"needs_visualization": true,
"chart_type": "bar",
"chart_data": null,
"visualization_html": null,
"user_role": "user"
}
}
Key Features:
Real-time Streaming : Live updates during processing
LangGraph Workflow : Intelligent agent orchestration
Memory Integration : Context-aware conversations
Error Handling : Graceful degradation with user-friendly messages
Token Tracking : Detailed usage monitoring
SQL Generation : Natural language to BigQuery conversion
Cost Control : Query limits and validation
Processing Workflow:
Authentication : Verify JWT token and extract user context
Memory Retrieval : Load conversation history and context
Intent Detection : Classify user question type
Schema Loading : Fetch relevant BigQuery table schemas
Query Generation : Convert natural language to SQL using GPT-4
Query Validation : Dry run to check syntax and estimate cost
Query Execution : Run against BigQuery with safety limits
Result Processing : Format data and generate insights
Memory Update : Store conversation in thread memory
Response Streaming : Send real-time updates to client
Streaming Events:
`status: "authenticating"` - User authentication in progress
`status: "loading_memory"` - Retrieving conversation context
`status: "generating_query"` - Creating SQL from natural language
`status: "validating_query"` - Checking query syntax and cost
`status: "executing_query"` - Running query against BigQuery
`status: "processing_results"` - Formatting data and generating insights
`status: "completed"` - Final response ready
`status: "error"` - Error occurred with details
Error Handling:
Authentication Errors : Invalid or expired tokens
Query Errors : SQL syntax or BigQuery execution issues
Memory Errors : Thread context retrieval failures
Rate Limiting : Too many requests from user
Cost Limits : Query exceeds 1GB cost limit
Timeout Errors : Query execution exceeds 30 seconds
/health
Method: GET
Purpose: System health check
Response:
{
"status": "healthy",
"database": "connected",
"bigquery": "connected",
"timestamp": "2024-01-01T00:00:00Z"
}/analytics-dashboard
Method: POST
Purpose: Get analytics dashboard data
Features:
Cached responses
Multiple chart types
Real-time data