SmartMovieSearch — Technical White Paper

01 The Problem

Ask a movie database "Show me good bank heist movies" and it returns nothing — heist is a theme, not a genre tag. Ask it "Is Project Hail Mary Ryan Gosling's best work?" and it has no way to answer. These questions require reasoning, not filtering.

Movie databases like TMDB are exhaustive but rigid. They expose genre filters, release years, and ratings — but they cannot interpret themes, compare filmographies, or synthesise critical perspective. A single LLM call lacks live data. A single API lacks semantic understanding. The only viable solution is decomposition: multiple specialised agents working in parallel, coordinated by an orchestrator.

02 System Architecture

User (browser)
    │  HTTPS — Cloudflare CDN + SSL termination
    │
Nginx  (reverse proxy, OVH VPS)
    ├── /         → React frontend  (static, port 5174)
    └── /api/*    → FastAPI backend (uvicorn,  port 8001)
                      │
                      │  Server-Sent Events stream
                      │
              LangGraph StateGraph
                      │
          ┌───────────┴────────────┐
          │    supervisor_route    │  ← decides which agents to invoke
          └──┬──────────┬──────┬───┘
             │          │      │     (parallel fan-out)
       tmdb_agent   rag_agent   search_agent
       TMDB API      Milvus      Tavily Web
       (httpx)       :19530      API
             │          │      │
          └──┴──────────┴──────┴───┘
                      │
               synthesise          ← merges results, streams answer
                      │
             SSE → browser (token by token)

Each layer has a single, clear responsibility. The supervisor decides routing. Agents specialise. The synthesiser integrates. The SSE stream makes the entire process visible to the user in real time.

03 Core Technologies

LangGraph — Multi-Agent Orchestration

LangGraph models the AI pipeline as a directed graph. Each node is an async Python function (an agent); each edge is conditional routing logic. A shared StateGraph object carries conversation state between nodes, and MemorySaver checkpoints that state to disk so multi-turn conversation context persists across queries on the same thread.

Why not a single LLM call? A prompt cannot simultaneously call a live API, query a vector database, and do a web search. Agents decompose the problem so each specialist uses the right tool — and they run in parallel, not sequentially.

Milvus — Hybrid Vector Search

Milvus stores the movie knowledge corpus (critical essays, directorial analyses, genre guides). The RAG agent retrieves relevant passages using hybrid search: a fusion of two complementary retrieval methods ranked by Reciprocal Rank Fusion (RRF).

Dense

Embedding search

OpenAI text-embedding-3-small converts text to 1536-dim vectors. Finds semantically similar content even when exact words differ.

Sparse

BM25 keyword search

Exact keyword matching — critical for proper nouns, film titles, and director names that embeddings can miss.

Fusion

RRF ranking

Reciprocal Rank Fusion merges both ranked lists into one. Gets the precision of BM25 and the recall of embeddings simultaneously.

Groq — Fast LLM Inference

Groq runs llama-3.3-70b-versatile on custom LPU (Language Processing Unit) hardware, delivering roughly 10× the token throughput of comparable GPU cloud providers at a fraction of the cost. In a streaming UI where users watch tokens appear in real time, inference latency is the user experience — this choice is why the first tokens arrive within ~1 second.

FastAPI + Server-Sent Events

The backend exposes a single streaming endpoint. It runs the LangGraph pipeline with astream_events() and translates internal events — agent lifecycle, LLM tokens, retrieved chunks, TMDB results — into a typed SSE stream consumed by the browser.

Why SSE over WebSockets? SSE is unidirectional (server → client), matching this use case exactly. It works through Cloudflare without configuration, and EventSource in the browser auto-reconnects on drop. WebSockets add bidirectional protocol overhead that is unnecessary here.

React + TypeScript Frontend

The frontend is a Vite SPA that maintains a live EventSource connection per query. It renders the pipeline in real time across four tabs: an animated pipeline graph (node status), a Gantt timeline (agent latency), a typed event log, and a context panel (retrieved chunks and TMDB cards). The AI process is visible, not a black box.

04 A Query, Step by Step

Tracing "Show me good bank heist movies" through the full stack:

Supervisor receives the question, calls Groq to classify intent → routes to all three agents in parallel: tmdb + rag + search

TMDB agent calls Groq to extract intent (discover, genre: Crime/Thriller) → queries TMDB API → calls Groq to write a grounded answer citing specific films with ratings

RAG agent embeds the query with OpenAI → runs hybrid BM25+dense search in Milvus → retrieves heist film corpus chunks → calls Groq to synthesise a knowledge-based answer

Search agent sends the query to Tavily → retrieves current web results → calls Groq to ground the answer in recent criticism and best-of lists

Synthesiser receives all three outputs, calls Groq to merge them into a single coherent answer — deduplicating overlapping film mentions and attributing sources

SSE stream delivers typed events to the browser as they occur: pipeline_start → routing_decision → agent_start → token (×N) → tmdb_results → chunks_retrieved → agent_end → done

Total latency: typically 3–6 seconds. First tokens appear within ~1 second of submitting. The parallel agent fan-out means all three agents run concurrently — if they ran sequentially it would take 3× as long.

05 Technical Highlights

🔀

Hybrid retrieval (BM25 + dense, RRF fusion) Outperforms either method alone. BM25 catches exact name matches; embeddings catch semantic similarity. RRF merges both ranked lists without needing a learned combiner.

⚡

Parallel agent execution TMDB, RAG, and web search run concurrently via asyncio.gather. Each agent also parallelises its own internal fetches — movie details and actor filmography are fetched simultaneously.

🧠

Multi-turn conversation memory LangGraph's MemorySaver + thread_id gives the supervisor history across turns. "What about his other films?" works correctly without re-stating context.

🔭

Observable pipeline Every internal event — agent start/end, LLM call, retrieved chunks, routing decision — streams to the UI. The AI reasoning process is transparent, not a black box with a spinner.

🎬

Filmography comparison intent A movie_and_person intent type fetches movie detail and actor filmography in parallel, sorts by rating, and hands the ranked list to the synthesis LLM — turning "is this their best film?" from a non-answer into a precise ranked response.

🚀

Production deployment Full Docker Compose stack on OVH VPS: Milvus + etcd + MinIO + FastAPI + React. Nginx reverse proxy. Cloudflare for SSL, CDN, and DDoS protection. Live at smartmoviesearch.com.

06 Full Stack Summary

Layer	Technology	Role
Orchestration	LangGraph 1.1	Multi-agent state machine with conditional routing and conversation memory
LLM inference	Groq (llama-3.3-70b)	All reasoning: routing decisions, intent extraction, answer generation
Vector DB	Milvus 2.5	Hybrid BM25 + dense search over the movie knowledge corpus
Embeddings	OpenAI text-embedding-3-small	1536-dim dense vectors for semantic retrieval
Movie data	TMDB API	Real-time film/TV metadata, cast, ratings, trending, person filmography
Web search	Tavily API	Current web results as a third retrieval source
Backend	FastAPI + uvicorn	Async SSE streaming, typed event protocol
Frontend	React + TypeScript + Vite	Real-time pipeline visualisation, conversation UI, dark/light theme
Infrastructure	Docker Compose + Nginx + Cloudflare	Containerised deployment, reverse proxy, SSL termination, CDN

How SmartMovieSearch works