prepare for hugging face spaces deployment

.dockerignore

@@ -0,0 +1,15 @@
+__pycache__
+.pixi
+.git
+.gitignore
+tests/
+*.pyc
+.pytest_cache
+.coverage
+htmlcov/
+*.txt
+*.backup
+pixi.*
+pyrightconfig.json
+ruff.toml
+.gitattributes

.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

.gitignore

@@ -0,0 +1,3 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml

Dockerfile

@@ -0,0 +1,45 @@
+FROM ghcr.io/prefix-dev/pixi:0.39.2 AS build
+
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy pixi configuration
+COPY pixi.toml pixi.lock ./
+
+# Install dependencies matching the lock file
+RUN pixi install --frozen
+
+# Copy source code
+COPY . .
+
+# Expose port
+EXPOSE 8000
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+# Create non-root user
+RUN groupadd --gid 1000 appgroup && \
+    useradd --uid 1000 --gid appgroup --shell /bin/bash --create-home appuser
+
+# Create bandit_models directory for persistent bandit data
+RUN mkdir -p bandit_models && chown -R appuser:appgroup bandit_models
+
+# Add health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1
+
+# Set ownership of app directory
+RUN chown -R appuser:appgroup /app
+
+# Switch to non-root user
+USER appuser
+
+# Run the application
+# We use `pixi run` to ensure we use the environment we just installed
+CMD ["pixi", "run", "start"]

Dockerfile.hf

@@ -0,0 +1,22 @@
+FROM python:3.10-slim
+
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user (HF Spaces security best practice)
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user:user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+COPY --chown=user:user . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,27 @@
+---
+title: Nostalgic Recommendation API
+emoji: 🎬
+colorFrom: purple
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# Nostalgic Recommendation API
+
+FastAPI backend for movie and song recommendations using machine learning.
+
+## Features
+
+- Movie Recommendations using LightFM collaborative filtering
+- Song Recommendations using content-based filtering with vector similarity
+- Stress and Emotion Detection
+- Contextual Bandit for personalized recommendations
+
+## Endpoints
+
+- `GET /health` - Health check and model status
+- `GET /docs` - Interactive API documentation
+- `POST /movies/recommend` - Get movie recommendations
+- `POST /songs/recommend` - Get song recommendations

core/__init__.py

@@ -0,0 +1,19 @@
+"""Core package - Utilities, database, and shared components."""
+
+from core.db import get_db_connection
+from core.schemas import (
+    HealthCheckResponse,
+    MovieRecommendRequest,
+    MovieRecommendResponse,
+    SongRecommendRequest,
+    SongRecommendResponse,
+)
+
+__all__ = [
+    "get_db_connection",
+    "HealthCheckResponse",
+    "MovieRecommendRequest",
+    "MovieRecommendResponse",
+    "SongRecommendRequest",
+    "SongRecommendResponse",
+]

core/db.py

@@ -0,0 +1,66 @@
+import os
+import psycopg2
+from typing import Dict, Any
+from dotenv import load_dotenv
+from pathlib import Path
+
+# Load env (Path: core/ -> fastapi-backend/ -> project_root/)
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+ENV_FILE = PROJECT_ROOT / ".env"
+load_dotenv(ENV_FILE)
+
+DATABASE_URL = os.getenv(
+    "DATABASE_URL", "postgresql://postgres:postgres@localhost:5432/myapp"
+)
+
+
+def get_db_connection():
+    return psycopg2.connect(DATABASE_URL)
+
+
+def fetch_latest_context(user_id: str) -> Dict[str, Any]:
+    """
+    Fetch the latest stress and emotion context for a user from daily_habit_logs.
+
+    Args:
+        user_id: The user's ID
+
+    Returns:
+        Dict with 'stress_score' (float) and 'emotion' (str)
+        Defaults to neutral if no log found.
+    """
+    conn = get_db_connection()
+    cursor = conn.cursor()
+
+    try:
+        # Get the most recent log entry for this user
+        # We order by date descending to get the latest one
+        cursor.execute(
+            """
+            SELECT stress_level, emotion 
+            FROM daily_habit_logs 
+            WHERE user_id = %s 
+            ORDER BY date DESC, created_at DESC 
+            LIMIT 1;
+        """,
+            (user_id,),
+        )
+
+        row = cursor.fetchone()
+
+        if row:
+            stress = row[0]
+            emotion = row[1]
+            return {
+                "stress_score": float(stress) if stress is not None else 0.5,
+                "emotion": emotion if emotion else "neutral",
+            }
+
+    except Exception as e:
+        print(f"Error fetching latest context: {e}")
+    finally:
+        cursor.close()
+        conn.close()
+
+    # Default fallback
+    return {"stress_score": 0.5, "emotion": "neutral"}

core/dependencies.py

@@ -0,0 +1,58 @@
+"""
+Dependency injection for FastAPI routes.
+
+This module provides dependencies for accessing the loaded recommenders
+via FastAPI's dependency injection system.
+"""
+
+from typing import TypedDict
+
+from fastapi import Request
+
+from services.movie_recommender import MovieRecommender
+from services.song_recommender import SongRecommender
+
+
+class Recommenders(TypedDict):
+    """Type definition for the recommenders state."""
+
+    movie: MovieRecommender | None
+    song: SongRecommender | None
+
+
+def get_movie_recommender(request: Request) -> MovieRecommender:
+    """
+    Dependency to get the movie recommender from app state.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        MovieRecommender instance
+
+    Raises:
+        RuntimeError: If movie recommender is not loaded
+    """
+    recommenders: Recommenders = request.app.state.recommenders
+    if recommenders["movie"] is None:
+        raise RuntimeError("Movie recommender not loaded. Check server startup logs.")
+    return recommenders["movie"]
+
+
+def get_song_recommender(request: Request) -> SongRecommender:
+    """
+    Dependency to get the song recommender from app state.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        SongRecommender instance
+
+    Raises:
+        RuntimeError: If song recommender is not loaded
+    """
+    recommenders: Recommenders = request.app.state.recommenders
+    if recommenders["song"] is None:
+        raise RuntimeError("Song recommender not loaded. Check server startup logs.")
+    return recommenders["song"]

core/schemas.py

@@ -0,0 +1,410 @@
+"""
+Pydantic schemas for request and response validation.
+
+This module defines all the data models used for API request/response
+validation and serialization.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, ConfigDict
+from pydantic.alias_generators import to_camel
+
+
+# =============================================================================
+# Movie Schemas
+# =============================================================================
+
+
+class MovieBase(BaseModel):
+    """Base movie schema with common fields."""
+
+    movie_id: int = Field(..., description="MovieLens movieId")
+    title: str = Field(..., description="Movie title")
+    genres: str = Field(
+        ..., description="Pipe-separated genres (e.g., 'Action|Comedy')"
+    )
+
+
+class MovieInfo(MovieBase):
+    """Full movie information response."""
+
+    decade: Optional[str] = Field(
+        None, description="Decade the movie was released (e.g., '1990s')"
+    )
+
+
+class MovieRecommendation(MovieInfo):
+    """Movie recommendation with score."""
+
+    score: float = Field(..., description="Recommendation score (higher is better)")
+
+
+class MovieRecommendRequest(BaseModel):
+    """Request model for movie recommendations."""
+
+    liked_movie_ids: list[int] = Field(
+        ...,
+        min_length=1,
+        max_length=50,
+        description="List of MovieLens movieIds the user has liked",
+    )
+    n_recommendations: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Number of recommendations to return",
+    )
+    exclude_liked: bool = Field(
+        default=True,
+        description="Whether to exclude liked movies from recommendations",
+    )
+
+
+class MovieRecommendResponse(BaseModel):
+    """Response model for movie recommendations."""
+
+    recommendations: list[MovieRecommendation]
+    liked_movies: list[MovieInfo]
+
+
+class MovieSearchRequest(BaseModel):
+    """Request model for movie search."""
+
+    query: str = Field(..., min_length=1, max_length=200, description="Search query")
+    limit: int = Field(
+        default=10, ge=1, le=100, description="Maximum number of results"
+    )
+
+
+class MovieSearchResponse(BaseModel):
+    """Response model for movie search."""
+
+    results: list[MovieInfo]
+    query: str
+
+
+# =============================================================================
+# Song Schemas
+# =============================================================================
+
+
+class SongBase(BaseModel):
+    """Base song schema with common fields."""
+
+    spotify_id: str = Field(..., description="Spotify track ID")
+    name: str = Field(..., description="Song name")
+    artists: str = Field(..., description="Artist name(s)")
+
+
+class SongInfo(SongBase):
+    """Full song information response."""
+
+    genre: Optional[str] = Field(None, description="Genre of the song")
+    year: Optional[int] = Field(None, description="Release year")
+
+
+class SongDetails(SongInfo):
+    """Extended song information with audio features."""
+
+    danceability: Optional[float] = Field(
+        None, ge=0, le=1, description="Danceability score"
+    )
+    energy: Optional[float] = Field(None, ge=0, le=1, description="Energy score")
+    key: Optional[int] = Field(None, ge=0, le=11, description="Musical key (0-11)")
+    loudness: Optional[float] = Field(None, description="Loudness in dB")
+    mode: Optional[int] = Field(None, ge=0, le=1, description="Mode (0=minor, 1=major)")
+    speechiness: Optional[float] = Field(
+        None, ge=0, le=1, description="Speechiness score"
+    )
+    acousticness: Optional[float] = Field(
+        None, ge=0, le=1, description="Acousticness score"
+    )
+    instrumentalness: Optional[float] = Field(
+        None, ge=0, le=1, description="Instrumentalness score"
+    )
+    liveness: Optional[float] = Field(None, ge=0, le=1, description="Liveness score")
+    valence: Optional[float] = Field(
+        None, ge=0, le=1, description="Valence (happiness) score"
+    )
+    tempo: Optional[float] = Field(None, ge=0, description="Tempo in BPM")
+    niche_genres: Optional[str] = Field(None, description="Niche genre tags")
+
+
+class SongRecommendation(SongInfo):
+    """Song recommendation with similarity score."""
+
+    similarity: float = Field(
+        ..., ge=0, le=1, description="Cosine similarity score (0-1)"
+    )
+
+
+class SongRecommendRequest(BaseModel):
+    """Request model for song recommendations based on liked songs."""
+
+    liked_song_ids: list[str] = Field(
+        ...,
+        min_length=1,
+        max_length=50,
+        description="List of Spotify track IDs the user likes",
+    )
+    n_recommendations: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Number of recommendations to return",
+    )
+    exclude_liked: bool = Field(
+        default=True,
+        description="Whether to exclude liked songs from recommendations",
+    )
+
+
+class SongRecommendByIdRequest(BaseModel):
+    """Request model for song recommendations based on a single song."""
+
+    spotify_id: str = Field(..., description="Spotify track ID")
+    n_recommendations: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Number of recommendations to return",
+    )
+
+
+class SongRecommendResponse(BaseModel):
+    """Response model for song recommendations."""
+
+    recommendations: list[SongRecommendation]
+    query_songs: list[SongInfo]
+
+
+class SongSearchRequest(BaseModel):
+    """Request model for song search."""
+
+    query: str = Field(
+        ...,
+        min_length=1,
+        max_length=200,
+        description="Search query for song name or artist",
+    )
+    limit: int = Field(
+        default=10, ge=1, le=100, description="Maximum number of results"
+    )
+
+
+class SongSearchResponse(BaseModel):
+    """Response model for song search."""
+
+    results: list[SongInfo]
+    query: str
+
+
+# =============================================================================
+# Text Analysis Schemas (Stress + Emotion Detection)
+# =============================================================================
+
+
+class TextAnalysisRequest(BaseModel):
+    """Request model for text analysis (stress and emotion detection)."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        max_length=5000,
+        description="Text to analyze for stress and emotion",
+    )
+
+
+class EmotionResult(BaseModel):
+    """Emotion detection result."""
+
+    emotion: str = Field(
+        ...,
+        description="Predicted emotion (anger, fear, joy, love, neutral, sadness, surprise)",
+    )
+    confidence: float = Field(
+        ...,
+        ge=0,
+        le=1,
+        description="Confidence score for the prediction",
+    )
+    probabilities: dict[str, float] = Field(
+        ...,
+        description="Probability distribution across all emotions",
+    )
+
+
+class TextAnalysisResponse(BaseModel):
+    """Response model for text analysis."""
+
+    text: str = Field(..., description="The analyzed text")
+    stress_score: float = Field(
+        ...,
+        ge=0,
+        le=1,
+        description="Stress level (0=no stress, 1=high stress)",
+    )
+    emotion: EmotionResult = Field(..., description="Detected emotion")
+
+
+class AnalyzeRequest(BaseModel):
+    """Request model for text analysis."""
+
+    text: str = Field(..., min_length=1, max_length=5000, description="Text to analyze")
+
+
+class AnalyzeResponse(BaseModel):
+    """Response model for text analysis."""
+
+    stress_score: float = Field(..., ge=0, description="Stress level")
+    emotion: EmotionResult = Field(..., description="Detected emotion")
+
+
+# Legacy schemas for backwards compatibility
+class StressDetectionRequest(BaseModel):
+    """Request model for stress detection (legacy)."""
+
+    text: str = Field(
+        ...,
+        min_length=1,
+        max_length=5000,
+        description="Text to analyze for stress",
+    )
+
+
+class StressDetectionResponse(BaseModel):
+    """Response model for stress detection (legacy)."""
+
+    stress_score: float = Field(
+        ...,
+        ge=0,
+        le=1,
+        description="Stress level (0=no stress, 1=high stress)",
+    )
+    text: str = Field(..., description="The analyzed text")
+
+
+# =============================================================================
+# Health Check Schema
+# =============================================================================
+
+
+class HealthCheckResponse(BaseModel):
+    """Health check response."""
+
+    status: str = Field(..., description="API status")
+    movie_model_loaded: bool = Field(..., description="Whether movie model is loaded")
+    song_model_loaded: bool = Field(..., description="Whether song model is loaded")
+    stress_model_loaded: bool = Field(..., description="Whether stress model is loaded")
+    emotion_model_loaded: bool = Field(
+        ..., description="Whether emotion model is loaded"
+    )
+    bandit_loaded: bool = Field(..., description="Whether bandit model is loaded")
+    version: str = Field(..., description="API version")
+
+
+# =============================================================================
+# Unified Recommendation Schemas
+# =============================================================================
+
+
+class RecommendRequest(BaseModel):
+    """Request model for unified recommendation endpoint."""
+
+    user_id: str = Field(..., description="User ID")
+    journal_text: str = Field(
+        default="",
+        max_length=5000,
+        description="Journal text to analyze for stress and emotion",
+    )
+
+
+class RecommendedContent(BaseModel):
+    """Recommended content (either song or movie)."""
+
+    type: str = Field(..., description="Content type: 'song' or 'movie'")
+    id: str = Field(
+        ..., description="Content ID (spotify_id for songs, movieId for movies)"
+    )
+
+    # Movie fields
+    title: Optional[str] = Field(None, description="Movie title")
+    genres: Optional[list[str]] = Field(None, description="Movie genres")
+
+    # Song fields
+    name: Optional[str] = Field(None, description="Song name")
+    artists: Optional[list[str]] = Field(None, description="Song artists")
+    genre: Optional[str] = Field(None, description="Song genre")
+
+    # Common fields
+    year: Optional[int] = Field(None, description="Release year")
+
+
+class RecommendResponse(BaseModel):
+    """Response model for unified recommendation endpoint."""
+
+    content: RecommendedContent = Field(..., description="Recommended content")
+    stress_score: float = Field(..., ge=0, le=1, description="Detected stress level")
+    emotion: EmotionResult = Field(..., description="Detected emotion")
+    bandit_score: float = Field(..., ge=0, description="Bandit confidence score")
+
+
+class RecommendFeedbackRequest(BaseModel):
+    """Request model for recommendation feedback."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    user_id: str = Field(..., description="User ID")
+    content_type: str = Field(..., description="Content type: 'song' or 'movie'")
+    content_id: str = Field(..., description="Content ID")
+
+    # Interaction fields
+    interaction_type: str = Field(
+        default="feedback",
+        description="Type of interaction (feedback, view, click, skip, next, replay)",
+    )
+    duration_seconds: Optional[int] = Field(
+        None, description="Duration of interaction in seconds"
+    )
+    feedback_submitted: bool = Field(
+        default=False,
+        description="Whether explicit feedback has already been submitted for this session",
+    )
+
+    # Primary feedback signal (optional now, as implicit interactions might not have it)
+    brings_back_memories: Optional[bool] = Field(
+        None, description="Primary feedback signal"
+    )
+
+    # Content metadata for bandit update
+    content_year: Optional[int] = Field(None, description="Content year")
+    content_genre: Optional[str] = Field(None, description="Content genre")
+
+    # Context snapshot (state at time of recommendation)
+    context_stress: Optional[float] = Field(
+        None, description="Stress score when recommendation was made"
+    )
+    context_emotion: Optional[str] = Field(
+        None, description="Emotion when recommendation was made"
+    )
+
+
+class RecommendFeedbackResponse(BaseModel):
+    """Response model for recommendation feedback."""
+
+    success: bool = Field(..., description="Whether feedback was recorded")
+    reward: float = Field(..., ge=0, le=1, description="Calculated reward value")
+    message: str = Field(..., description="Status message")
+
+
+# =============================================================================
+# Error Schemas
+# =============================================================================
+
+
+class ErrorResponse(BaseModel):
+    """Error response model."""
+
+    detail: str = Field(..., description="Error message")
+    error_type: str = Field(default="error", description="Type of error")

explain_approach3.txt

@@ -0,0 +1 @@
+planning time: 5msexecution time: 292msdistribution: localvectorized: trueplan type: customrows decoded from KV: 1,525 (720 KiB, 2 gRPC calls)cumulative time spent in KV: 207msmaximum memory usage: 1.3 MiBDistSQL network usage: 0 B (0 messages)sql cpu time: 62msisolation level: serializablepriority: normalquality of service: regular• top-k│ sql nodes: n1│ actual row count: 10│ execution time: 87µs│ estimated max memory allocated: 10 KiB│ sql cpu time: 87µs│ estimated row count: 1│ order: -similarity│ k: 10│└── • render    │    └── • filter        │ sql nodes: n1        │ actual row count: 159        │ execution time: 3ms        │ sql cpu time: 3ms        │ estimated row count: 1        │ filter: row_number = 1        │        └── • window            │ sql nodes: n1            │ actual row count: 165            │ execution time: 480µs            │ estimated max memory allocated: 89 KiB            │ sql cpu time: 478µs            │ estimated row count: 500            │            └── • render                │                └── • lookup join                    │ sql nodes: n1                    │ kv nodes: n1                    │ actual row count: 165                    │ KV time: 106ms                    │ KV rows decoded: 500                    │ KV bytes read: 135 KiB                    │ KV gRPC calls: 1                    │ execution time: 111ms                    │ estimated max memory allocated: 200 KiB                    │ sql cpu time: 4ms                    │ estimated row count: 500                    │ table: songs@songs_pkey                    │ equality: (spotify_id) = (id)                    │ equality cols are key                    │ pred: year <= 2016                    │                    └── • top-k                        │ sql nodes: n1                        │ actual row count: 500                        │ execution time: 4ms                        │ estimated max memory allocated: 50 KiB                        │ sql cpu time: 4ms                        │ estimated row count: 500                        │ order: +distance                        │ k: 500                        │                        └── • render                            │                            └── • lookup join                                │ sql nodes: n1                                │ kv nodes: n1                                │ actual row count: 1,025                                │ KV time: 101ms                                │ KV rows decoded: 1,025                                │ KV bytes read: 584 KiB                                │ KV gRPC calls: 1                                │ execution time: 110ms                                │ estimated max memory allocated: 280 KiB                                │ sql cpu time: 9ms                                │ table: song_vectors@song_vectors_pkey                                │ equality: (id) = (id)                                │ equality cols are key                                │                                └── • vector search                                      sql nodes: n1                                      actual row count: 1,025                                      execution time: 55ms                                      sql cpu time: 38ms                                      table: song_vectors@song_vectors_embedding_idx                                      target count: 500

explain_new.txt

@@ -0,0 +1 @@
+planning time: 2msexecution time: 8.3sdistribution: localvectorized: trueplan type: customrows decoded from KV: 1,101,238 (464 MiB, 47 gRPC calls)cumulative time spent in KV: 2.7smaximum memory usage: 120 MiBDistSQL network usage: 0 B (0 messages)max sql temp disk usage: 80 MiBsql cpu time: 5.9sisolation level: serializablepriority: normalquality of service: regular• top-k│ sql nodes: n1│ actual row count: 10│ execution time: 32µs│ estimated max memory allocated: 10 KiB│ sql cpu time: 32µs│ estimated row count: 1│ order: -similarity│ k: 10│└── • render    │    └── • filter        │ sql nodes: n1        │ actual row count: 475        │ execution time: 6µs        │ sql cpu time: 7µs        │ estimated row count: 1        │ filter: row_number = 1        │        └── • top-k            │ sql nodes: n1            │ actual row count: 500            │ execution time: 8ms            │ estimated max memory allocated: 170 KiB            │ sql cpu time: 8ms            │ estimated row count: 500            │ order: +column38            │ k: 500            │            └── • render                │                └── • window                    │ sql nodes: n1                    │ actual row count: 400,927                    │ execution time: 2.1s                    │ estimated max memory allocated: 55 MiB                    │ sql cpu time: 1.8s                    │ estimated row count: 368,267                    │                    └── • render                        │                        └── • hash join                            │ sql nodes: n1                            │ actual row count: 400,927                            │ execution time: 2.7s                            │ estimated max memory allocated: 77 MiB                            │ sql cpu time: 2.3s                            │ estimated row count: 368,267                            │ equality: (spotify_id) = (id)                            │ left cols are key                            │ right cols are key                            │                            ├── • scan                            │     sql nodes: n1                            │     kv nodes: n1                            │     actual row count: 550,619                            │     KV time: 1.8s                            │     KV rows decoded: 550,619                            │     KV bytes read: 317 MiB                            │     KV gRPC calls: 32                            │     estimated max memory allocated: 11 MiB                            │     sql cpu time: 720ms                            │     estimated row count: 574,254 (100% of the table; stats collected 1 hour ago; using stats forecast for 1 hour ago)                            │     table: song_vectors@song_vectors_pkey                            │     spans: FULL SCAN                            │                            └── • filter                                │ sql nodes: n1                                │ actual row count: 400,927                                │ execution time: 3ms                                │ sql cpu time: 3ms                                │ estimated row count: 368,267                                │ filter: year <= 2016                                │                                └── • scan                                      sql nodes: n1                                      kv nodes: n1                                      actual row count: 550,619                                      KV time: 927ms                                      KV rows decoded: 550,619                                      KV bytes read: 147 MiB                                      KV gRPC calls: 15                                      estimated max memory allocated: 10 MiB                                      sql cpu time: 218ms                                      estimated row count: 505,005 (100% of the table; stats collected 2 hours ago)                                      table: songs@songs_pkey                                      spans: FULL SCAN

explain_optimized.txt

@@ -0,0 +1 @@
+planning time: 2msexecution time: 7.2sdistribution: localvectorized: trueplan type: customrows decoded from KV: 1,101,238 (464 MiB, 47 gRPC calls)cumulative time spent in KV: 2.1smaximum memory usage: 121 MiBDistSQL network usage: 0 B (0 messages)max sql temp disk usage: 80 MiBsql cpu time: 5.4sisolation level: serializablepriority: normalquality of service: regular• top-k│ sql nodes: n1│ actual row count: 10│ execution time: 23µs│ estimated max memory allocated: 10 KiB│ sql cpu time: 23µs│ estimated row count: 1│ order: -similarity│ k: 10│└── • render    │    └── • filter        │ sql nodes: n1        │ actual row count: 475        │ execution time: 5µs        │ sql cpu time: 5µs        │ estimated row count: 1        │ filter: row_number = 1        │        └── • top-k            │ sql nodes: n1            │ actual row count: 500            │ execution time: 9ms            │ estimated max memory allocated: 170 KiB            │ sql cpu time: 9ms            │ estimated row count: 500            │ order: +column38            │ k: 500            │            └── • render                │                └── • window                    │ sql nodes: n1                    │ actual row count: 400,927                    │ execution time: 2.1s                    │ estimated max memory allocated: 55 MiB                    │ sql cpu time: 1.8s                    │ estimated row count: 368,267                    │                    └── • render                        │                        └── • hash join                            │ sql nodes: n1                            │ actual row count: 400,927                            │ execution time: 2.3s                            │ estimated max memory allocated: 77 MiB                            │ sql cpu time: 1.9s                            │ estimated row count: 368,267                            │ equality: (spotify_id) = (id)                            │ left cols are key                            │ right cols are key                            │                            ├── • scan                            │     sql nodes: n1                            │     kv nodes: n1                            │     actual row count: 550,619                            │     KV time: 1.3s                            │     KV rows decoded: 550,619                            │     KV bytes read: 317 MiB                            │     KV gRPC calls: 32                            │     estimated max memory allocated: 11 MiB                            │     sql cpu time: 630ms                            │     estimated row count: 574,254 (100% of the table; stats collected 1 hour ago; using stats forecast for 1 hour ago)                            │     table: song_vectors@song_vectors_pkey                            │     spans: FULL SCAN                            │                            └── • filter                                │ sql nodes: n1                                │ actual row count: 400,927                                │ execution time: 3ms                                │ sql cpu time: 3ms                                │ estimated row count: 368,267                                │ filter: year <= 2016                                │                                └── • scan                                      sql nodes: n1                                      kv nodes: n1                                      actual row count: 550,619                                      KV time: 777ms                                      KV rows decoded: 550,619                                      KV bytes read: 147 MiB                                      KV gRPC calls: 15                                      estimated max memory allocated: 10 MiB                                      sql cpu time: 237ms                                      estimated row count: 505,005 (100% of the table; stats collected 2 hours ago)                                      table: songs@songs_pkey                                      spans: FULL SCAN

explain_output.txt

@@ -0,0 +1 @@
+planning time: 194µsexecution time: 4.4sdistribution: localvectorized: trueplan type: generic, reusedrows decoded from KV: 1,101,238 (464 MiB, 47 gRPC calls)cumulative time spent in KV: 1.5smaximum memory usage: 122 MiBDistSQL network usage: 0 B (0 messages)max sql temp disk usage: 74 MiBsql cpu time: 3.2sisolation level: serializablepriority: normalquality of service: regular• render│└── • limit    │ count: 5    │    └── • filter        │ sql nodes: n1        │ actual row count: 5        │ execution time: 10µs        │ sql cpu time: 10µs        │ estimated row count: 1        │ filter: row_number = 1        │        └── • window            │ sql nodes: n1            │ actual row count: 1,024            │ execution time: 359ms            │ estimated max memory allocated: 71 MiB            │ sql cpu time: 301ms            │ estimated row count: 368,267            │            └── • render                │                └── • hash join                    │ sql nodes: n1                    │ actual row count: 400,927                    │ execution time: 1.9s                    │ estimated max memory allocated: 77 MiB                    │ sql cpu time: 1.6s                    │ estimated row count: 368,267                    │ equality: (spotify_id) = (id)                    │ left cols are key                    │ right cols are key                    │                    ├── • scan                    │     sql nodes: n1                    │     kv nodes: n1                    │     actual row count: 550,619                    │     KV time: 1s                    │     KV rows decoded: 550,619                    │     KV bytes read: 317 MiB                    │     KV gRPC calls: 32                    │     estimated max memory allocated: 11 MiB                    │     sql cpu time: 583ms                    │     estimated row count: 574,254 (100% of the table; stats collected 1 hour ago; using stats forecast for 59 minutes ago)                    │     table: song_vectors@song_vectors_pkey                    │     spans: FULL SCAN                    │                    └── • filter                        │ sql nodes: n1                        │ actual row count: 400,927                        │ execution time: 2ms                        │ sql cpu time: 2ms                        │ estimated row count: 368,267                        │ filter: year <= 2016                        │                        └── • scan                              sql nodes: n1                              kv nodes: n1                              actual row count: 550,619                              KV time: 491ms                              KV rows decoded: 550,619                              KV bytes read: 147 MiB                              KV gRPC calls: 15                              estimated max memory allocated: 10 MiB                              sql cpu time: 204ms                              estimated row count: 505,005 (100% of the table; stats collected 2 hours ago)                              table: songs@songs_pkey                              spans: FULL SCAN

main.py

@@ -0,0 +1,318 @@
+"""FastAPI Recommendation Server
+
+This server provides endpoints for movie and song recommendations.
+Models are loaded on startup using FastAPI's lifespan events.
+
+Run with: uvicorn main:app --reload
+"""
+
+import os
+import traceback
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import AsyncGenerator
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+ENV_FILE = Path(__file__).parent.parent / ".env"
+load_dotenv(ENV_FILE)
+
+from routes.movies import router as movies_router  # noqa: E402
+from routes.songs import router as songs_router  # noqa: E402
+from routes.stress import router as analyze_router  # noqa: E402
+from routes.recommend import router as recommend_router  # noqa: E402
+from core.schemas import HealthCheckResponse  # noqa: E402
+from services.movie_recommender import MovieRecommender  # noqa: E402
+from services.song_recommender import SongRecommender  # noqa: E402
+from services.stress_detector import StressDetector  # noqa: E402
+from services.emotion_detector import EmotionDetector  # noqa: E402
+from services.contextual_bandit import HierarchicalBandit  # noqa: E402
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+API_VERSION = "1.0.0"
+API_TITLE = "Nostalgic Recommendation API"
+API_DESCRIPTION = """
+A recommendation API for movies and songs using machine learning models.
+
+## Features
+
+- 🎬 **Movie Recommendations**: Using LightFM collaborative filtering with cold-start support
+- 🎵 **Song Recommendations**: Using content-based filtering with pgvector similarity search
+- 🔍 **Search**: Search movies by title, songs by name or artist
+- ✨ **Validation**: Full request/response validation with Pydantic
+
+## Models
+
+- **Movie Recommender**: LightFM model trained on MovieLens 32M dataset
+- **Song Recommender**: Content-based filtering using audio features, stored in pgvector
+"""
+
+# CORS configuration
+CORS_ORIGINS = os.getenv("CORS_ORIGINS", "*").split(",")
+
+
+# =============================================================================
+# Model State
+# =============================================================================
+
+
+class AppState:
+    """Application state container for recommenders."""
+
+    movie_recommender: MovieRecommender | None = None
+    song_recommender: SongRecommender | None = None
+    movie_model_loaded: bool = False
+    song_model_loaded: bool = False
+
+
+# =============================================================================
+# Lifespan Events
+# =============================================================================
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """
+    Manage application lifespan.
+
+    On startup: Load movie and song recommendation models.
+    On shutdown: Clean up resources.
+    """
+    print("=" * 60)
+    print(f"🚀 Starting {API_TITLE} v{API_VERSION}")
+    print("=" * 60)
+
+    # Initialize state
+    app.state.recommenders = {
+        "movie": None,
+        "song": None,
+        "stress": None,
+        "emotion": None,
+        "bandit": None,
+    }
+    app.state.model_status = {
+        "movie_loaded": False,
+        "song_loaded": False,
+        "stress_loaded": False,
+        "emotion_loaded": False,
+        "bandit_loaded": False,
+    }
+
+    # Load movie recommender
+    print("\n📽️  Loading Movie Recommender...")
+    try:
+        movie_recommender = MovieRecommender()
+        app.state.recommenders["movie"] = movie_recommender  # type: ignore[assignment]
+        app.state.model_status["movie_loaded"] = True  # type: ignore[assignment]
+        print("✅ Movie Recommender loaded successfully!")
+    except FileNotFoundError as e:
+        print(f"⚠️  Movie model files not found: {e}")
+        print("   Movie recommendations will be unavailable.")
+    except Exception as e:
+        print(f"❌ Error loading Movie Recommender: {e}")
+        traceback.print_exc()
+
+    # Load song recommender
+    print("\n🎵 Loading Song Recommender...")
+    try:
+        song_recommender = SongRecommender()
+        app.state.recommenders["song"] = song_recommender  # type: ignore[assignment]
+        app.state.model_status["song_loaded"] = True  # type: ignore[assignment]
+        print("✅ Song Recommender loaded successfully!")
+    except FileNotFoundError as e:
+        print(f"⚠️  Song model files not found: {e}")
+        print("   Song recommendations will be unavailable.")
+    except Exception as e:
+        print(f"❌ Error loading Song Recommender: {e}")
+        print("   This may be due to database connection issues.")
+        traceback.print_exc()
+
+    # Load stress detector
+    print("\n🧠  Loading Stress Detector...")
+    try:
+        stress_detector = StressDetector()
+        app.state.recommenders["stress"] = stress_detector  # type: ignore[assignment]
+        app.state.model_status["stress_loaded"] = True  # type: ignore[assignment]
+        print("✅ Stress Detector loaded successfully!")
+    except FileNotFoundError as e:
+        print(f"⚠️  Stress model files not found: {e}")
+        print("   Stress detection will be unavailable.")
+    except Exception as e:
+        print(f"❌ Error loading Stress Detector: {e}")
+        traceback.print_exc()
+
+    # Load emotion detector
+    print("\n💭 Loading Emotion Detector...")
+    try:
+        emotion_detector = EmotionDetector(use_mock=False)
+        app.state.recommenders["emotion"] = emotion_detector  # type: ignore[assignment]
+        app.state.model_status["emotion_loaded"] = True  # type: ignore[assignment]
+        print("✅ Emotion Detector loaded successfully!")
+    except Exception as e:
+        print(f"⚠️  Error loading real Emotion Detector: {e}")
+        print("   Falling back to MOCK Emotion Detector.")
+        try:
+            emotion_detector = EmotionDetector(use_mock=True)
+            app.state.recommenders["emotion"] = emotion_detector  # type: ignore[assignment]
+            app.state.model_status["emotion_loaded"] = True  # type: ignore[assignment]
+            print("✅ Mock Emotion Detector loaded.")
+        except Exception as e2:
+            print(f"❌ Error loading Mock Emotion Detector: {e2}")
+            traceback.print_exc()
+
+    # Load contextual bandit
+    print("\n🎰 Loading Contextual Bandit...")
+    try:
+        bandit = HierarchicalBandit()
+        app.state.recommenders["bandit"] = bandit  # type: ignore[assignment]
+        app.state.model_status["bandit_loaded"] = True  # type: ignore[assignment]
+        print("✅ Contextual Bandit loaded successfully!")
+    except Exception as e:
+        print(f"❌ Error loading Contextual Bandit: {e}")
+        traceback.print_exc()
+
+    print("\n" + "=" * 60)
+    print("🌐 Server is ready to accept requests")
+    print("=" * 60 + "\n")
+
+    # Yield control to the application
+    yield
+
+    # Cleanup on shutdown
+    print("\n🛑 Shutting down server...")
+
+    # Close database connections
+    if app.state.recommenders["movie"]:
+        app.state.recommenders["movie"].close()
+        print("   Closed movie recommender database connection.")
+
+    if app.state.recommenders["song"]:
+        app.state.recommenders["song"].close()
+        print("   Closed song recommender database connection.")
+
+    if app.state.recommenders["stress"]:
+        app.state.recommenders["stress"].close()
+        print("   Closed stress detector.")
+
+    if app.state.recommenders["emotion"]:
+        app.state.recommenders["emotion"].close()
+        print("   Closed emotion detector.")
+
+    if app.state.recommenders["bandit"]:
+        app.state.recommenders["bandit"].close()
+        print("   Closed contextual bandit.")
+
+    # Clear references
+    app.state.recommenders["movie"] = None
+    app.state.recommenders["song"] = None
+    app.state.recommenders["stress"] = None
+    app.state.recommenders["emotion"] = None
+    app.state.recommenders["bandit"] = None
+
+    print("👋 Server shutdown complete.\n")
+
+
+# =============================================================================
+# FastAPI Application
+# =============================================================================
+
+app = FastAPI(
+    title=API_TITLE,
+    description=API_DESCRIPTION,
+    version=API_VERSION,
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+)
+
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# =============================================================================
+# Health Check Endpoint
+# =============================================================================
+
+
+@app.get(
+    "/health",
+    response_model=HealthCheckResponse,
+    tags=["Health"],
+    summary="Health check",
+    description="Check the API status and model availability.",
+)
+async def health_check() -> HealthCheckResponse:
+    """Return the API health status and model loading status."""
+    return HealthCheckResponse(
+        status="healthy",
+        movie_model_loaded=app.state.model_status.get("movie_loaded", False),
+        song_model_loaded=app.state.model_status.get("song_loaded", False),
+        stress_model_loaded=app.state.model_status.get("stress_loaded", False),
+        emotion_model_loaded=app.state.model_status.get("emotion_loaded", False),
+        bandit_loaded=app.state.model_status.get("bandit_loaded", False),
+        version=API_VERSION,
+    )
+
+
+@app.get("/", tags=["Root"])
+async def root() -> dict[str, str]:
+    """Root endpoint with welcome message."""
+    return {
+        "message": f"Welcome to {API_TITLE}",
+        "version": API_VERSION,
+        "docs": "/docs",
+        "health": "/health",
+    }
+
+
+# =============================================================================
+# Register Routers
+# =============================================================================
+
+app.include_router(movies_router)
+app.include_router(songs_router)
+app.include_router(analyze_router)
+app.include_router(recommend_router)
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+
+if __name__ == "__main__":
+    import signal
+    import sys
+    import uvicorn
+
+    def shutdown_handler(signum, frame):
+        print(f"\n🛑 Received signal {signum}, initiating graceful shutdown...")
+        sys.exit(0)
+
+    signal.signal(signal.SIGTERM, shutdown_handler)
+    signal.signal(signal.SIGINT, shutdown_handler)
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    reload = os.getenv("RELOAD", "true").lower() == "true"
+
+    print(f"\n🔧 Starting server on http://{host}:{port}")
+    uvicorn.run(
+        "main:app",
+        host=host,
+        port=port,
+        reload=reload,
+    )

pixi.toml

@@ -0,0 +1,33 @@
+[workspace]
+authors = ["Victor-Iroko <irokovictor7@gmail.com>"]
+channels = ["conda-forge"]
+name = "fastapi-backend"
+platforms = ["win-64", "linux-64"]
+version = "0.1.0"
+
+[tasks]
+start = "uvicorn main:app --host 0.0.0.0 --port 8000"
+dev = "uvicorn main:app --reload"
+lint = "ruff check ."
+format = "ruff format ."
+fix = "ruff check . --fix"
+typecheck = "pyright ."
+check = "ruff format . --check && ruff check . && pyright ."
+
+[dependencies]
+numpy = ">=1.26.4,<2"
+pandas = ">=2.3.3,<3"
+fastapi = ">=0.128.0,<0.129"
+lightfm = ">=1.17,<2"
+uvicorn = ">=0.40.0,<0.41"
+scikit-learn = ">=1.8.0,<2"
+transformers = ">=4.57.3,<5"
+pytorch = ">=2.9.1,<3"
+psycopg2 = ">=2.9.11,<3"
+huggingface_hub = ">=0.26.0"
+
+[pypi-dependencies]
+mab2rec = ">=1.3.1, <2"
+ruff = ">=0.8.0,<1"
+pyright = ">=1.1.0,<2"
+pandas-stubs = ">=2.3.0,<3"

pyrightconfig.json

@@ -0,0 +1,11 @@
+{
+  "typeCheckingMode": "basic",
+  "exclude": [
+    "tests/**",
+    "**/__pycache__/**",
+    "**/.pixi/**",
+    "**/*.pyc",
+    "**/.git/**",
+    "**/pixi.lock"
+  ]
+}

requirements.txt

@@ -0,0 +1,12 @@
+numpy>=1.26.4,<2
+pandas>=2.3.3,<3
+fastapi>=0.128.0,<0.129
+lightfm>=1.17,<2
+uvicorn>=0.40.0,<0.41
+scikit-learn>=1.8.0,<2
+transformers>=4.57.3,<5
+torch>=2.0.0,<3
+psycopg2-binary>=2.9.11,<3
+huggingface_hub>=0.26.0
+mab2rec>=1.3.1,<2
+python-dotenv>=1.0.0

routes/__init__.py

@@ -0,0 +1,8 @@
+"""Routes package - API endpoint modules."""
+
+from routes.movies import router as movies_router
+from routes.songs import router as songs_router
+from routes.recommend import router as recommend_router
+from routes.stress import router as stress_router
+
+__all__ = ["movies_router", "songs_router", "recommend_router", "stress_router"]