CineVault -- AI Movie Discovery Engine

A production-grade movie recommendation system that combines 14 specialized ML engines, a knowledge graph, an LLM-powered conversational agent, and a Netflix-inspired frontend into a single deployable stack. Not a notebook. Not a prototype. A real application.

Every movie recommendation project on GitHub falls into one of two categories:

1. Academic notebooks -- great theory, zero usability. You download a dataset, run cells, read a confusion matrix, and close the tab.
2. Simple web apps -- a search bar, a poster grid, and content-based filtering that recommends "The Dark Knight" if you liked "Batman Begins."

Neither reflects how modern recommendation systems actually work at companies like Netflix, Spotify, or YouTube. Those systems use ensembles of specialized engines (collaborative filtering, neural embeddings, knowledge graphs, mood analysis) orchestrated through a ranking pipeline with reranking and serendipity injection.

CineVault bridges this gap. It implements the full production recommendation stack -- from candidate generation through ranking to explanation -- with a real UI, real API, and real infrastructure. One command to start. No manual dataset downloads.

• Features
• Architecture
• Recommendation Engines
• Frontend Pages
• API Reference
• Quick Start
• Local Development
• Configuration
• Data Pipeline
• Tech Stack
• Testing
• Project Structure
• Operations
• License

• 14 specialized ML engines running in ensemble (content-based, collaborative, neural, graph-based, visual, mood, serendipity)
• Hybrid ranking pipeline that fuses scores from all engines with learned weights
• Cross-encoder reranking using FlashRank (ms-marco-TinyBERT) for final result quality
• Knowledge graph with Louvain community detection for entity-relationship discovery
• Mood-based discovery powered by Gemini LLM -- describe how you feel, get movie recommendations
• Serendipity injection -- deliberately introduces high-quality surprises into ranked lists to prevent filter bubbles
• Session intelligence -- Transformer-based session continuation predicts what you want to watch next based on browsing patterns (not just last-click fallback)
• NEBULA Visual DNA -- extracts cinematographic features (color palettes, shot composition, motion profiles) from movie trailers to build a visual latent space for cinema-aware similarity
• Mood arc playlists -- creates time-evolving movie sequences (e.g., evening: relaxed -> tense -> melancholic -> inspired) for narrative viewing experiences

• Conversational AI agent (LangGraph + GROQ) that can discuss movies, take user preferences, and generate personalized recommendations through natural dialogue
• Agentic discovery via GraphRAG -- an LLM navigates the knowledge graph to answer complex queries ("movies that connect Tarantino to Kurosawa")
• Semantic vector search using Qdrant with sentence-transformers embeddings
• Full-text search with advanced filtering (genre, director, actor, year range, rating range, sort order)
• Visual search using CLIP (ViT-B/32) via FastEmbed -- find movies by poster similarity

• Netflix-inspired UI with cinematic design, smooth animations (Framer Motion), and responsive poster grids
• Taste Fingerprint -- visual radar chart showing a user's preference profile across genres and decades
• Time Machine -- browse cinema history decade by decade with contextual recommendations
• Movie Connections -- interactive graph visualization (react-force-graph-2d) showing how movies relate through shared actors, directors, and genres
• Director filmography pages with deep-linked navigation
• User onboarding flow to cold-start the recommendation engine with initial preferences

• L1/L2 caching -- in-process LRU cache (sub-microsecond) backed by Redis (sub-millisecond)
• Rate limiting via SlowAPI (100 req/15 min per IP)
• Security headers -- CSP, HSTS, X-Frame-Options, Referrer-Policy
• Graceful degradation -- every engine and external service (Qdrant, Redis, Elasticsearch, Gemini) fails gracefully; the API never crashes due to an optional dependency being down
• Health endpoint with SLO tracking (error rate, p95 latency, request counts)
• GZip compression for API responses
• Docker Compose with 5 services, health checks, named volumes, and development watch mode

                                   +-------------------+
                                   |   Next.js 16 UI   |
                                   |   (Turbopack)      |
                                   +--------+----------+
                                            |
                                   HTTP (localhost:3002)
                                            |
                                            v
+------------------+            +------------------------+            +----------------+
|   SurrealDB      |<---------->|    FastAPI Backend     |<---------->|    Qdrant       |
|   (Graph DB)     |            |    (Python 3.12)       |            |  (Vector DB)    |
+------------------+            +-----+------+-----------+            +----------------+
                                      |      |
                          +-----------+      +-----------+
                          |                              |
                          v                              v
                   +-------------+              +---------------+
                   |   SQLite    |              |    Redis      |
                   |  (7,880     |              |  (L2 Cache    |
                   |   movies)   |              |   + Sessions) |
                   +-------------+              +---------------+

1. Frontend server-renders pages via Next.js App Router, calling the backend API server-side
2. API receives request, checks L1 cache (in-process) -> L2 cache (Redis) -> computes if miss
3. Recommendation Pipeline: candidate generation (multiple engines) -> score fusion -> reranking -> serendipity injection -> response
4. Caching: result stored in both L1 and L2 with configurable TTL and Cache-Control headers

CineVault runs 10 specialized engines in parallel, each excelling at a different aspect of recommendation:

User Request
     |
     v
+----+----+----+----+----+----+
| Content | Collab | NCF | KG |  ... (all 10 engines)
+----+----+----+----+----+----+
     |         |       |    |
     +----+----+----+--+----+
          |
   Score Fusion (weighted ensemble)
          |
          v
   FlashRank Cross-Encoder Reranking
          |
          v
   Serendipity Injection
          |
          v
   Final Ranked Results + Explanations

The ranking pipeline (ranking_pipeline.py) fuses scores from all engines using configurable weights. The reranker (reranker.py) applies a cross-encoder model (ms-marco-TinyBERT-L-2-v2) to re-score the top candidates for maximum relevance. Finally, the serendipity engine injects novel picks that score high on quality but low on predictability.

curl -s "http://localhost:8001/movies/search?q=inception&per_page=1" | python3 -m json.tool

{
  "items": [
    {
      "title": "Inception",
      "genres": "Action Thriller Science Fiction Mystery Adventure",
      "director": "Christopher Nolan",
      "cast": "Leonardo DiCaprio Joseph Gordon-Levitt Ellen Page Tom Hardy",
      "vote_average": 8.1,
      "vote_count": 13752,
      "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious...",
      "poster_path": "/xlaY2zyzMfkhk0HSC5VUwzoZPU1.jpg"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 1,
  "total_pages": 1
}

curl -s "http://localhost:8001/recommendations/similar/27205?limit=3" | python3 -m json.tool

{
  "movie": "Inception",
  "recommendations": [
    { "title": "Interstellar", "content_score": 42.3 },
    { "title": "The Prestige", "content_score": 38.1 },
    { "title": "Shutter Island", "content_score": 35.7 }
  ]
}

• Docker (v20+) and Docker Compose v2

make docker

This runs the start.sh script which:

1. Creates .env from .env.example if missing
2. Builds and starts all 5 services (API, Frontend, SurrealDB, Redis, Qdrant)
3. Waits for the API to report ready=true (database initialized, engine trained)
4. Waits for the frontend to be reachable
5. Prints access URLs

Once ready:

For development with live code syncing:

make watch

File changes in backend/ and frontend/ sync into the running containers automatically.

For running without Docker (useful for debugging):

• uv (Python package manager)
• bun (JavaScript runtime)
• Python 3.12+

# Copy environment config
cp .env.example .env

# Start backend + frontend with auto-seeding
make dev

This installs Python/JS dependencies, seeds the SQLite database with ~7,880 movies and sample users/ratings, and starts both servers:

• Backend: http://localhost:8001 (uvicorn with hot reload)
• Frontend: http://localhost:3002 (Next.js Turbopack)

make run            # Backend only
make frontend-dev   # Frontend only

All configuration is managed through environment variables (.env file), validated by Pydantic Settings.

The repository ships with data/movies.csv containing 7,880 movies from TMDB. On first startup with AUTO_INIT_DB=true, the API:

1. Creates the database schema (movies, users, ratings, watch_history, favorites)
2. Imports all movies from CSV
3. Generates 100 sample users with realistic rating distributions
4. Trains all recommendation engines in the background (~30 seconds)

For production-scale testing with the full IMDb dataset:

make deploy-1m

This runs the IMDb ingestion pipeline which:

• Fetches movie metadata from TMDB API (rate-limited at 40 req/sec)
• Imports poster images and metadata
• Builds vector embeddings for semantic search
• Requires a valid TMDB_API_KEY in .env

uv run python -m pytest                    # Run all tests
uv run python -m pytest -m unit            # Unit tests only
uv run python -m pytest -m integration     # Integration tests only
uv run ruff check                          # Linting
uv run ruff format --check                 # Format check

cd frontend
bun run lint       # ESLint
bun run build      # Type check + build

.
├── backend/
│   ├── app/
│   │   ├── main.py                          # FastAPI app with lifespan, middleware, security
│   │   ├── routers/                         # Modular API routes
│   │   │   ├── health.py                    # Health + SLO metrics
│   │   │   ├── movies.py                    # Movie CRUD + browsing
│   │   │   ├── search.py                    # Full-text + semantic search
│   │   │   ├── recommendations.py           # Hybrid recommendations
│   │   │   ├── graph.py                     # Knowledge graph queries
│   │   │   ├── agent.py                     # AI chat + agentic discovery
│   │   │   └── users.py                     # Auth + user management
│   │   ├── schemas.py                       # Pydantic v2 models
│   │   └── dependencies.py                  # FastAPI dependency injection
│   ├── services/
│   │   └── recommendation_engine_service/
│   │       ├── engines/
│   │       │   ├── recommendation.py        # Main engine (content + collab + hybrid)
│   │       │   ├── ncf.py                   # Neural Collaborative Filtering
│   │       │   ├── two_tower.py             # Two-Tower candidate generation
│   │       │   ├── lightgcn.py              # LightGCN graph collaborative filtering
│   │       │   ├── knowledge_graph.py       # NetworkX knowledge graph
│   │       │   ├── vector_engine.py         # Qdrant semantic search
│   │       │   ├── visual_engine.py         # CLIP visual search
│   │       │   ├── mood_engine.py           # Gemini-powered mood analysis
│   │       │   ├── serendipity.py           # Novelty injection
│   │       │   ├── ranking_pipeline.py      # Score fusion orchestrator
│   │       │   ├── reranker.py              # FlashRank cross-encoder
│   │       │   ├── explainability.py        # Recommendation explanations
│   │       │   ├── session_engine.py        # Transformer-based session continuation
│   │       │   └── nebula/                  # NEBULA Visual DNA pipeline (color, composition, motion)
│   │       └── agents/
│   │           ├── concierge.py             # LangGraph conversational agent
│   │           └── memory.py                # Conversation memory
│   ├── cache.py                             # L1 (in-process) + L2 (Redis) cache
│   ├── config.py                            # Pydantic Settings configuration
│   └── database.py                          # SQLModel engine, schema, seeding
├── frontend/
│   ├── app/                                 # Next.js App Router pages
│   │   ├── page.tsx                         # Home (trending + genre carousels)
│   │   ├── search/page.tsx                  # Advanced search
│   │   ├── movie/[id]/page.tsx              # Movie detail
│   │   ├── agentic/page.tsx                 # AI concierge chat
│   │   ├── mood/page.tsx                    # Mood-based discovery
│   │   ├── connections/page.tsx             # Knowledge graph visualization
│   │   ├── time-machine/page.tsx            # Decade browsing
│   │   ├── taste/page.tsx                   # Taste fingerprint radar chart
│   │   ├── director/[name]/page.tsx         # Director filmography
│   │   ├── onboarding/page.tsx              # New user preference setup
│   │   └── my-list/page.tsx                 # Personal watchlist
│   ├── components/                          # Shared React components
│   ├── server-api.ts                        # Server-side API client
│   └── api.ts                               # Client-side API client
├── data/
│   ├── movies.csv                           # 7,880 movie dataset (ships with repo)
│   └── movies_recommender.db                # SQLite database (auto-created)
├── docker-compose.yml                       # 5-service stack definition
├── Makefile                                 # Build commands
├── start.sh                                 # Startup orchestration script
└── pyproject.toml                           # Python dependencies (uv)

The /health endpoint returns real-time SLO metrics:

{
  "status": "healthy",
  "ready": true,
  "movies_loaded": 7880,
  "engine_trained": true,
  "slo": {
    "total_requests": 1523,
    "total_errors": 2,
    "error_rate": 0.001,
    "avg_latency_ms": 45.2,
    "p95_latency_ms": 180.3
  }
}

uv run python -m alembic -c alembic.ini upgrade head

This project is for educational and portfolio purposes.