How karthikesh-ui/ai-movie-recommendation-system works
MovieAI serves Indian-movie search, title-based recommendations, natural-language recommendations, and separate discovery/enrichment capabilities. The main recommendation path validates user intent, filters and ranks the local catalog, then optionally enriches selected results; Gemini does not choose recommendations. Hybrid retrieval and Watchmode discovery add provider-backed results and verified availability separately. Edges reflect README-described flows and sampled imports/calls; unsampled frontend-to-API wiring is not asserted.
Main entry points: app.py HTTP API · app.js Movie web UI · nl_pipeline.py NL recommendation flow · hybrid_retrieval.py Hybrid retrieval
Components 24
User experience
- Movie web UI
frontend/app.js - Search and autocomplete
frontend/movie-search.js - Movie details
frontend/movie-details.js - Recommendation results
frontend/recommendation.js
API orchestration
- HTTP API
backend/app.py
Local recommendations
- Indian movie catalog
data/processed/indian_movies_clean.csv - Title similarity
backend/app.py - Gemini intent parsing
backend/app.py - Intent validation
backend/nl_intent.py - Filtered retrieval
backend/nl_recommender.py - Deterministic ranking
backend/nl_ranking.py - NL recommendation flow
backend/nl_pipeline.py - Grounded explanations
backend/app.py - Hybrid retrieval
backend/hybrid_retrieval.py - Normalized candidates
backend/movie_candidate.py
External providers
- OMDb enrichment
backend/app.py - Watchmode client
backend/watchmode_client.py - Live release discovery
backend/discovery_provider.py - TMDB discovery client
backend/tmdb_client.py - Gemini service
- OMDb service
- Watchmode service
- TMDB service
Other components
- Movie seeker
Connections 25
- Movie seeker → Movie web UI: uses
README.md - Movie web UI → Search and autocomplete: includes
- Movie web UI → Movie details: includes
- Movie web UI → Recommendation results: includes
- Movie seeker → HTTP API: requests
README.md - HTTP API → Indian movie catalog: reads
README.md - HTTP API → Title similarity: routes recommendations
README.md - HTTP API → Gemini intent parsing: parses request
README.md - Gemini intent parsing → Gemini service: requests intent
README.md - HTTP API → Intent validation: validates intent
backend/app.py - HTTP API → NL recommendation flow: runs recommendations
backend/app.py - NL recommendation flow → Filtered retrieval: retrieves candidates
backend/nl_pipeline.py - NL recommendation flow → Deterministic ranking: ranks candidates
backend/nl_pipeline.py - Filtered retrieval → Indian movie catalog: filters
README.md - HTTP API → Grounded explanations: assembles explanations
README.md - HTTP API → OMDb enrichment: enriches results
backend/app.py - OMDb enrichment → OMDb service: requests metadata
backend/app.py - HTTP API → Hybrid retrieval: routes hybrid requests
backend/app.py - Hybrid retrieval → Normalized candidates: normalizes results
backend/hybrid_retrieval.py - Hybrid retrieval → Watchmode client: checks availability
backend/hybrid_retrieval.py - Watchmode client → Watchmode service: calls API
backend/watchmode_client.py - HTTP API → Live release discovery: routes discovery
backend/app.py - Live release discovery → Watchmode client: fetches releases
backend/discovery_provider.py - HTTP API → TMDB discovery client: uses discovery client
backend/app.py - TMDB discovery client → TMDB service: calls API
backend/tmdb_client.py