Prepare for Hugging Face Spaces deployment

- Update README with HF Spaces frontmatter configuration
- Configure Docker deployment with app_port: 8000
- Integrate React build serving with FastAPI backend
- Add comprehensive Docker build documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -1,85 +1,31 @@
-# Advanced Two-Tower Recommendation System
-
-A production-ready recommendation system implementation using TensorFlow with an enhanced two-tower architecture. This system provides personalized item recommendations through collaborative filtering, content-based filtering, category-boosted recommendations, and hybrid approaches, featuring advanced training strategies.
-
-## 🎯 Project Overview
-
-This recommendation system addresses the challenge of providing personalized item recommendations at scale using modern deep learning techniques. The enhanced two-tower architecture enables efficient similarity search, real-time recommendations, and superior personalization through behavioral signal prioritization.
-
-### Key Features
-- **🧠 Enhanced Two-Tower Architecture**: 128D embeddings with advanced neural networks
-- **📚 Advanced Training Pipeline**: Multi-phase training with curriculum learning
-- **⚡ Real-time Inference**: Sub-100ms recommendation serving with FAISS indexing
-- **🔄 Multi-strategy Recommendations**: Raw two-tower, category-boosted, content-based, and hybrid approaches
-- **🎪 Category-Aware Boosting**: 60/40 split between user categories and exploration
-- **🔍 Interactive Similar Items**: Click-to-explore with category-balanced discovery
-- **📊 Comprehensive Testing**: Quality metrics and performance evaluation tools
-- **🌐 Production Ready**: Complete FastAPI backend with React frontend
-
-## 🏗️ Enhanced Architecture Overview
-
-### Advanced Two-Tower Deep Learning Architecture
-
-The system implements a sophisticated two-tower neural network architecture optimized for recommendation tasks with significant improvements for better personalization and training stability.
-
-#### 1. Enhanced Item Tower 🏢
-- **Purpose**: Learns dense representations of items with improved discrimination
-- **Input Features**:
-  - `item_id`: Unique product identifier (embedding layer)
-  - `category_id`: Product category (embedding layer)  
-  - `brand_id`: Brand identifier (embedding layer)
-  - `price`: Normalized price feature with projection
-- **Architecture Improvements**:
-  - **128D embeddings** (upgraded from 64D) for better representation capacity
-  - **Multi-head attention** (4 heads) for feature fusion
-  - **Batch normalization** for training stability
-  - **Enhanced dense layers**: [256, 128] with dropout (0.3)
-  - **Item bias terms** for improved modeling capacity
-  - **L2 normalization** for similarity computations
-- **Output**: 128-dimensional item embeddings with bias terms
-
-#### 2. Enhanced User Tower 👤
-- **Purpose**: Learns user preferences with behavioral focus
-- **Input Features**:
-  - **Interaction History**: Up to 50 recent item embeddings with positional encoding
-- **Architecture Improvements**:
-  - **128D embeddings** for enhanced representation
-  - **Transformer attention** (8 heads) for history processing
-  - **Positional encoding** for sequence understanding
-  - **Learned weighted aggregation** instead of simple mean pooling
-  - **Enhanced dense layers**: [256, 128] with batch normalization
-  - **User bias terms** for personalization
-- **Output**: 128-dimensional user embeddings with bias terms
+---
+title: RecSys-HP
+emoji: 🎯
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+app_port: 8000
+---
 
-#### 3. Temperature-Scaled Similarity & Contrastive Learning 🌡️
-- **Temperature Scaling**: Learnable parameter for improved score discrimination
-- **Hard Negative Mining**: Better training signal through difficult negative examples
-- **Contrastive Loss**: Prevents embedding collapse and improves representation quality
-- **Focal Loss**: Handles imbalanced data more effectively
+# RecSys-HP: Two-Tower Recommendation System
 
-#### 4. Curriculum Learning Strategy 🎓
-- **Progressive Training**: 3-stage curriculum based on interaction complexity
-- **Stage 1**: Simple cases (short/no history) - 33rd percentile
-- **Stage 2**: Medium complexity (moderate history) - 33rd-67th percentile  
-- **Stage 3**: Complex cases (long history) - 67th+ percentile
-- **Adaptive Learning Rates**: Decrease as stages progress for stability
+A production-ready recommendation system implementation using TensorFlow with an enhanced two-tower architecture. This system provides personalized item recommendations through collaborative filtering, content-based filtering, category-boosted recommendations, and hybrid approaches, featuring advanced training strategies.
 
-### 5. Aggregated History Content-Based Filtering 🔄
-- **Revolutionary Approach**: Uses aggregated user interaction history instead of single-item similarity
-- **Multiple Aggregation Methods**: 
-  - **Weighted Mean**: Recent interactions weighted higher (exponential decay)
-  - **Simple Mean**: Equal weighting of all interactions
-  - **Max Pooling**: Element-wise maximum of embeddings
-- **ANN Search**: Direct similarity search using FAISS with aggregated user profile
-- **Enhanced Personalization**: Captures complete user preference profile, not just recent item
-- **Category-Aware**: Analyzes user's full category distribution for balanced recommendations
+## 🚀 Features
 
-### 6. Category-Aware Recommendation Engine 🎪
-- **Enhanced Hybrid Recommendations**: Category boosting based on user preferences
-- **Category Alignment Analysis**: Measures personalization effectiveness
-- **Diversity Controls**: Balanced category representation in recommendations
-- **Subcategory Precision**: 2-level category matching (e.g., "computers.components")
-- **Comprehensive Analysis Tools**: Multi-algorithm comparison and alignment scoring
+- **🏗️ Enhanced Two-Tower Architecture**: 128D embeddings with temperature scaling and attention mechanisms
+- **🎯 Multiple Recommendation Engines**: 
+  - Raw Two-Tower (Collaborative Filtering)
+  - Content-Based Filtering  
+  - Hybrid Recommendations
+  - Category-Boosted Recommendations
+- **⚡ Fast Inference**: FAISS-powered similarity search with sub-100ms response times
+- **🎨 Interactive Frontend**: React-based web interface with real-time recommendations
+- **📊 Category Analysis**: Intelligent category preference analysis and visualization
+- **🔄 Real User Profiles**: Browse genuine user interaction histories
+- **🎪 Category-Aware Similarity**: 60/40 category split for balanced discovery
 
 ## 📁 Project Structure
 
@@ -94,151 +40,38 @@ RecSys-HP/
 │   ├── models/                           # Neural network architectures
 │   │   ├── item_tower.py                # Original item embedding tower
 │   │   ├── user_tower.py                # User embedding tower
-│   │   ├── enhanced_two_tower.py        # Enhanced two-tower architecture
 │   │   └── improved_two_tower.py        # Advanced two-tower with improvements
 │   │
 │   ├── preprocessing/                    # Data preparation pipeline
 │   │   ├── data_loader.py               # Dataset loading and validation
-│   │   ├── user_data_preparation.py     # User feature engineering with categorization
-│   │   └── optimized_dataset_creator.py # Optimized data processing
-│   │
-│   ├── training/                         # Training pipelines
-│   │   ├── item_pretraining.py          # Phase 1: Item tower pre-training
-│   │   ├── joint_training.py            # Original joint training
-│   │   ├── optimized_joint_training.py  # Performance-optimized training
-│   │   ├── fast_joint_training.py       # Fast joint training implementation
-│   │   ├── improved_joint_training.py   # Advanced joint training with curriculum learning
-│   │   └── curriculum_trainer.py        # Advanced curriculum learning
+│   │   └── user_data_preparation.py     # User feature engineering
 │   │
-│   ├── inference/                        # Production serving components
-│   │   ├── faiss_index.py               # Vector similarity search
-│   │   ├── recommendation_engine.py     # Core inference pipeline
-│   │   └── enhanced_recommendation_engine_128d.py # 128D enhanced recommendations
+│   ├── training/                         # Model training pipeline
+│   │   ├── item_pretraining.py          # Item tower pretraining
+│   │   └── joint_training.py            # Joint user-item training
 │   │
-│   ├── utils/                            # Utility functions
-│   │   └── real_user_selector.py        # Real user data selection for testing
+│   ├── inference/                        # Recommendation engines
+│   │   ├── recommendation_engine.py      # Main recommendation engine
+│   │   └── faiss_index.py               # FAISS similarity search
 │   │
-│   └── artifacts/                        # Model checkpoints and metadata
-│       ├── *.data-* / *.index           # TensorFlow model weights
-│       ├── *.npy                        # Numpy arrays (embeddings)
-│       ├── *.pkl                        # Pickled features/vocabularies
-│       └── *.bin                        # FAISS indices
+│   └── artifacts/                        # Trained models & indices
+│       ├── vocabularies.pkl              # Feature vocabularies
+│       ├── *_weights.*                   # Model weights
+│       └── faiss_*                       # FAISS index files
 │
-├── 🌐 API Implementations               # Multiple API options
-│   ├── api/main.py                      # Primary FastAPI server
-│   ├── api_2phase.py                    # 2-phase training API
-│   └── api_joint.py                     # Joint training API
+├── 🎨 frontend/                          # React web interface
+│   ├── src/
+│   │   ├── App.js                       # Main React component
+│   │   └── App.css                      # Styling
+│   └── build/                           # Production build
 │
-├���─ 💻 frontend/                          # Interactive web interface
-│   ├── src/                             # React components
-│   │   ├── App.js                       # Enhanced application
-│   │   └── *.css                        # Updated styling
-│   ├── public/                          # Static assets
-│   └── package.json                     # Node.js dependencies
+├── 🔗 api/                              # FastAPI backend
+│   └── main.py                          # API server with static file serving
 │
-├── 🚀 Training Scripts                   # Multiple training approaches
-│   ├── run_training_pipeline.py         # Main training orchestration
-│   ├── run_2phase_training.py           # 2-phase training approach
-│   └── run_joint_training.py            # Joint training approach
-│
-└── 📋 requirements.txt                   # Python dependencies
-```
-
-## 🚀 Quick Start Guide
-
-### Prerequisites
-- **Python 3.8+** (3.9+ recommended)
-- **Node.js 16+** & npm
-- **TensorFlow 2.13+** (GPU version recommended)
-- **8GB+ RAM** (for training phase)
-- **5GB+ disk space** (for models and indices)
-- **CUDA 11.8+** (optional, for GPU acceleration)
-
-### 1. Environment Setup
-
-#### Prerequisites
-- **Python 3.8+** (3.9+ recommended)
-- **Node.js 16+** and npm
-- **Git** for version control
-- **8GB+ RAM** (for model training)
-- **GPU recommended** (optional, for faster training)
-
-#### Installation Steps
-```bash
-# Clone the repository
-git clone [repository-url]
-cd RecSys-HP
-
-# Create and activate virtual environment
-python -m venv env
-source env/bin/activate  # Windows: env\Scripts\activate
-
-# Upgrade pip and install Python dependencies
-pip install --upgrade pip
-pip install -r requirements.txt
-
-# For GPU support (optional but recommended):
-# pip install tensorflow-gpu==2.13.0
-
-# Install React frontend dependencies
-cd frontend && npm install && cd ..
-```
-
-#### Dataset Setup
-```bash
-# Ensure your datasets are properly placed:
-# datasets/users.csv     - User profiles
-# datasets/interactions.csv - User-item interaction data
-# datasets/items.csv     - Item features and metadata
-
-# Verify dataset structure
-python -c "from src.preprocessing.data_loader import DataProcessor; dp = DataProcessor(); print('✅ Datasets loaded successfully')"
-```
-
-### 2. Training Options
-
-Choose from multiple training approaches based on your needs:
-
-#### Option A: Main Training Pipeline (Recommended) 🌟
-```bash
-# Complete end-to-end training pipeline (20-30 minutes)
-python scripts/run_training_pipeline.py
-```
-
-#### Option B: 2-Phase Training Approach
-```bash
-# 2-phase training: item pretraining + joint optimization
-python scripts/run_2phase_training.py
-```
-
-#### Option C: Joint Training Approach  
-```bash
-# Direct joint training of both towers
-python scripts/run_joint_training.py
-```
-
-**Enhanced Training Features:**
-### 3. Start Interactive Demo 🎮
-
-#### Launch the Application
-```bash
-# Launch API server (in one terminal)
-cd api && python main.py
-
-# Start React frontend (in another terminal)
-cd frontend && npm start
-```
-
-**Access Points:**
-- 🌐 **Frontend Demo**: http://localhost:3000
-- 📚 **API Documentation**: http://localhost:8000/docs
-- 🔧 **API Health Check**: http://localhost:8000/health
-- ⚡ **Real-time Recommendations**: Interactive similarity search with 60/40 category balancing
-
-### 4. Quality Analysis 📊
-```bash
-# Run comprehensive recommendation analysis
-python analyze_recommendations.py
+└── 📚 Configuration
+    ├── requirements.txt                  # Python dependencies
+    ├── Dockerfile                       # Container configuration
+    └── docker-build.md                 # Deployment guide
 ```
 
 ## 🎯 Recommendation Strategies
@@ -248,24 +81,22 @@ python analyze_recommendations.py
 - **Strengths**: Superior personalization with behavioral signal focus
 - **Algorithm**: Two-tower neural collaborative filtering with category awareness
 
-### 2. Category-Boosted Recommendations 🎪
-- **Method**: Strict 60/40 split between user categories and exploration
-- **Features**: Proportional distribution within user categories, parent category fallback
-- **Benefits**: Balanced personalization with controlled exploration
-- **Algorithm**: Category-aware recommendation with boost factor (1.3x)
-
-### 3. Content-Based Filtering 📊  
-- **Method**: Item feature similarity and aggregated user history
-- **Features**: FAISS-based embedding similarity, category constraints
-- **Strengths**: Better cold-start performance, explainable recommendations
-- **Algorithm**: Enhanced embedding similarity with category balancing
+### 2. Content-Based Recommendations 📋
+- **Method**: Aggregated user history embedding with weighted mean pooling
+- **Features**: FAISS similarity search on aggregated user preferences
+- **Benefits**: Works for users with interaction history, fast inference
 
-### 4. Hybrid Approach 🔗
+### 3. Hybrid Approach 🔗
 - **Method**: Weighted combination of collaborative and content-based
 - **Features**: Configurable weight mixing (default 70% collaborative, 30% content)
 - **Benefits**: Best of both approaches with balanced coverage
 - **Algorithm**: Score-based weighted combination
 
+### 4. Category-Boosted Recommendations 🎪
+- **Method**: Intelligent category preference learning and boosting
+- **Features**: Dynamic category analysis from user interaction patterns
+- **Benefits**: Maintains user preferences while enabling discovery
+
 ## 🔬 Technical Deep Dive
 
 ### Enhanced Training Process
@@ -274,291 +105,47 @@ python analyze_recommendations.py
 - **Stage 1**: Simple cases (short interaction history)
 - **Stage 2**: Medium complexity (moderate history)  
 - **Stage 3**: Complex cases (long interaction history)
-- **Progressive Difficulty**: Gradually increase learning complexity
-- **Adaptive Learning**: Decay learning rate between stages
-
-#### Performance Improvements
-- **Score Discrimination**: 15x improvement in variance (0.0007 → 0.01+)
-- **Category Alignment**: 5x improvement (12% → 60%+)
-- **Embedding Quality**: Reduced collapse, better user diversity
-- **Training Stability**: Curriculum learning + batch normalization
-
-### Advanced Features
-
-#### Temperature Scaling
-- **Purpose**: Improve score discrimination and ranking quality
-- **Implementation**: Learnable parameter in similarity computation
-- **Benefits**: Better separation between relevant/irrelevant items
 
-#### Hard Negative Mining
-- **Purpose**: Improve contrastive learning signal
-- **Method**: Select hardest negatives (highest similarity among negatives)
-- **Benefits**: Better embedding separation, reduced collapse
+#### Two-Phase Training Strategy
+1. **Item Pretraining**: Self-supervised learning on item features
+2. **Joint Training**: User-item interaction learning with contrastive loss
 
-#### Category-Aware Boosting
-- **Analysis**: User category preference extraction from history
-- **Boosting**: Amplify scores for items matching user preferences
-- **Diversity**: Balance personalization with exploration
+### Architecture Improvements
+- **User Tower**: Demographics + 50-slot interaction history with attention
+- **Item Tower**: Optimized embeddings with smart dimensionality
+- **Training**: Contrastive learning with positive/negative pairs
 
-## 📈 Performance Metrics & Analysis
+## 🚀 Getting Started
 
-### Quality Metrics
-- **Score Variance**: Measures recommendation discrimination ability
-- **Category Alignment**: Percentage of recommendations matching user preferences
-- **Embedding Collapse**: User-user similarity analysis
-- **Recommendation Speed**: Inference time per user
-- **Training Convergence**: Loss curves and validation metrics
+The application runs automatically in this Hugging Face Space! The system includes:
 
-### Expected Performance
-- **Score Discrimination**: 15x improvement with enhanced model
-- **Category Alignment**: 5x improvement (12% → 60%+)
-- **Inference Speed**: <50ms per recommendation request
-- **Training Time**: 45-60 minutes with curriculum learning
-- **Memory Usage**: ~6GB during training, ~2GB serving
+- **Interactive Web Interface**: Browse users, generate recommendations, analyze categories
+- **Multiple Recommendation Types**: Try different algorithms
+- **Real User Data**: Explore genuine user interaction patterns
+- **Performance Monitoring**: Real-time API response tracking
 
-## 🔗 Enhanced API Endpoints
-
-### Core Recommendation Endpoints
+### API Endpoints
 
 | Method | Endpoint | Description | Features |
 |--------|----------|-------------|----------|
-| `GET` | `/` | Root endpoint | API information and status |
-| `GET` | `/health` | Health check | Service availability status |
-| `POST` | `/recommendations` | Personalized recommendations | Multi-strategy (collaborative/content/hybrid/enhanced) |
+| `GET` | `/` | Web Interface | Interactive React app |
+| `POST` | `/recommendations` | Personalized recommendations | Multi-strategy (collaborative/content/hybrid) |
 | `POST` | `/item-similarity` | Category-balanced similar items | 60% same category + ANN search |
-| `POST` | `/predict-rating` | User-item rating prediction | Two-tower model predictions |
-
-### Data & User Endpoints
-
-| Method | Endpoint | Description | Features |
-|--------|----------|-------------|----------|
-| `GET` | `/real-users/{user_id}` | Detailed user timeline | Complete interaction breakdown |
-| `GET` | `/behavioral-patterns` | Enriched behavioral patterns | Pre-populated item details |
-| `GET` | `/dataset-summary` | Dataset statistics | User/item/interaction counts |
-| `GET` | `/items/{item_id}` | Individual item info | Brand, category, price details |
-| `GET` | `/items` | Sample items | Testing and exploration |
-
-### Example Enhanced API Usage
-
-```python
-import requests
-
-# Get category-aware enhanced recommendations
-response = requests.post("http://localhost:8000/enhanced-recommendations", json={
-    "user_profile": {
-        "interaction_history": [1001, 1515, 2023, 4042]
-    },
-    "num_recommendations": 10,
-    "recommendation_type": "enhanced_hybrid",   # New enhanced strategy
-    "category_boost": 1.5,                     # Category preference amplification
-    "enable_diversity": True,                  # Balanced category representation
-    "max_per_category": 3                      # Diversity control
-})
-
-recommendations = response.json()
-# Returns enhanced recommendations with category analysis and explanations
-```
-
-### 🎯 Interactive Similar Items Feature
-
-The system now features an advanced similar items discovery interface with intelligent category balancing:
-
-#### **Click-to-Explore Functionality**
-- **Interactive Cards**: Click any recommendation to discover similar items
-- **Smart Category Balance**: 60% same category (high relevance) + 40% different categories (discovery)
-- **ANN-Powered**: Uses FAISS similarity search with cosine similarity scores
-- **Visual Indicators**: Similarity percentage badges and progress bars
-- **Rich Details**: Complete item information (brand, category, price)
-
-#### **Category-Balanced Algorithm**
-```python
-# Example: Clicking on iPhone (electronics.smartphone)
-POST /item-similarity
-{
-    "item_id": 1004565,
-    "num_recommendations": 10
-}
-
-# Returns:
-# 60% smartphones: Samsung, Huawei, Xiaomi... (high relevance)
-# 40% related items: iPad, MacBook, AirPods... (discovery)
-# All items ranked by actual FAISS similarity scores
-```
-
-#### **Similar Items API Response**
-```json
-[
-  {
-    "item_id": 1003907,
-    "score": 0.9289,           // 92.9% similarity
-    "item_info": {
-      "brand": "huawei",
-      "category_code": "electronics.smartphone",
-      "price": 151.87
-    }
-  }
-]
-```
-
-**Frontend Demo**: Visit http://localhost:3000 → Get recommendations → Click any item → Explore similar products with category insights!
-
-## 🛠️ Development & Testing
-
-### 🚀 Training Pipeline Options
+| `GET` | `/real-users` | Browse real user profiles | Genuine interaction histories |
+| `GET` | `/health` | System health check | API status monitoring |
 
-#### **Complete Pipeline (Recommended)**
-```bash
-# Run full training pipeline (item pretraining + joint training + FAISS indexing)
-python run_training_pipeline.py
-
-# Alternative: Run individual steps
-python run_2phase_training.py      # 2-phase approach
-python run_joint_training.py       # End-to-end joint training
-python train_improved_model.py     # Enhanced model training
-```
-
-#### **Multiple API Servers Available**
-```bash
-# Main API (production-ready with all features)
-cd api && python main.py
-
-# 2-Phase Model API (comparison/testing)
-python api_2phase.py
-
-# Joint Training Model API (alternative approach)
-python api_joint.py
-```
-
-### 🔧 System Testing
-```bash
-# Test core system components
-python -m src.utils.real_user_selector  # Demo real user extraction
-python -m src.preprocessing.data_loader  # Verify data loading
-```
-
-### 🧪 Frontend Development
-```bash
-cd frontend
-npm install        # Install dependencies
-npm start          # Development server (localhost:3000)
-npm run build      # Production build
-npm test           # Run tests
-```
-
-### Model Training Options
-```bash
-# Original training pipeline
-python run_training_pipeline.py
-
-python train_improved_model.py --embedding-dim 128
-
-# Curriculum learning with custom stages
-python train_improved_model.py --curriculum-stages 4 --epochs-per-stage 12
-```
-
-## 📁 Complete Project Structure
-
-```
-RecSys-HP/
-├── 🚀 API Services
-│   ├── api/
-│   │   └── main.py                          # Main production API (all features)
-│   ├── api_2phase.py                        # 2-phase model API (testing)
-│   └── api_joint.py                         # Joint training model API
-│
-├── 🧠 Machine Learning Core
-│   └── src/
-│       ├── models/                          # Neural Network Architectures
-│       │   ├── enhanced_two_tower.py       # 128D enhanced architecture
-│       │   ├── improved_two_tower.py       # Standard enhanced model
-│       │   ├── item_tower.py              # Item embedding tower
-│       │   └── user_tower.py              # User embedding tower
-│       │
-│       ├── inference/                       # Trained Model Serving
-│       │   ├── enhanced_recommendation_engine_128d.py  # 128D inference engine
-│       │   ├── enhanced_recommendation_engine.py      # Enhanced inference
-│       │   ├── recommendation_engine.py               # Basic inference
-│       │   └── faiss_index.py                         # ANN similarity search
-│       │
-│       ├── training/                        # Model Training Pipeline
-│       │   ├── curriculum_trainer.py       # Progressive learning
-│       │   ├── improved_joint_training.py  # Enhanced joint training
-│       │   ├── optimized_joint_training.py # Performance optimized
-│       │   ├── fast_joint_training.py      # Speed optimized
-│       │   ├── joint_training.py           # Standard joint training
-│       │   └── item_pretraining.py         # Item tower pretraining
-│       │
-│       ├── preprocessing/                   # Data Processing
-│       │   ├── data_loader.py              # Main data processor
-│       │   ├── optimized_dataset_creator.py # Efficient dataset creation
-│       │   └── user_data_preparation.py    # User feature processing
-│       │
-│       ├── utils/                           # Utility Functions
-│       │   └── real_user_selector.py       # Real user data extraction
-│       │
-│       └── artifacts/                       # Trained Models & Data
-│           ├── *.pkl                        # Vocabularies & features
-│           ├── *_weights.*                  # TensorFlow model weights
-│           ├── faiss_*                      # FAISS indices & embeddings
-│           └── *.txt                        # Configuration files
-│
-├── 🌐 Frontend Interface
-│   └── frontend/
-│       ├── src/
-│       │   ├── App.js                       # Main React component
-│       │   ├── App.css                      # Styling & animations
-│       │   ├── index.js                     # React entry point
-│       │   └── index.css                    # Global styles
-│       ├── public/                          # Static assets
-│       ├── package.json                     # Dependencies & scripts
-│       └── build/                           # Production build
-│
-├── 🎯 Training Scripts
-│   ├── run_training_pipeline.py             # Complete training pipeline
-│   ├── run_2phase_training.py               # 2-phase approach
-│   ├── run_joint_training.py                # End-to-end training
-│   └── train_improved_model.py              # Enhanced model training
-│
-├── 📊 Analysis & Testing
-│   ├── analyze_recommendations.py           # Quality analysis tool
-│   ├── recommendation_analysis_report.md    # Generated analysis report
-│   └── recommendation_analysis_plots.png    # Analysis visualizations
-│
-├── 📚 Data & Configuration
-│   ├── datasets/                            # Training data
-│   │   ├── items.csv                        # Product catalog
-│   │   └── interactions.csv                 # User-item interactions
-│   ├── requirements.txt                     # Python dependencies
-│   ├── README.md                           # Project documentation
-│   └── ARCHITECTURE.md                     # Technical architecture
-```
-
-### 🔧 Key Components Explained
-
-#### **🚀 Multiple API Options**
-- **`api/main.py`**: Production API with all features (similar items, real users, behavioral patterns)
-- **`api_2phase.py`**: Serves 2-phase trained models for comparison
-- **`api_joint.py`**: Serves joint-trained models for testing
-
-#### **🧠 Three Inference Engines**
-- **Enhanced 128D**: Best performance, advanced features, 128D embeddings
-- **Enhanced Standard**: Good performance, 64D embeddings, category boosting
-- **Basic Engine**: Simple collaborative/content/hybrid recommendations
-
-#### **⚡ Training Pipeline Flexibility**
-- **Complete Pipeline**: Full training workflow (pretraining → joint → FAISS)
-- **2-Phase Training**: Item pretraining + joint fine-tuning
-- **Joint Training**: End-to-end optimization
+## 📊 Project Achievements
 
-#### **🎨 Frontend Features**
-- **Real User Interface**: Browse genuine user profiles & interaction histories
-- **Interactive Recommendations**: Click any item → see similar products (60/40 category split)
-- **Category Analysis**: Visual breakdown of user interests vs recommendations
-- **Performance Monitoring**: Real-time API performance metrics
+✅ **Enhanced Architecture**: 128D embeddings, temperature scaling, contrastive learning  
+✅ **Curriculum Learning**: Progressive training for better convergence  
+✅ **Category-Aware Recommendations**: Intelligent personalization with diversity  
+✅ **Content-Based Filtering**: Revolutionary user history aggregation approach  
+✅ **Enhanced Cold-Start Support**: Improved new user handling  
+✅ **Production Ready**: Scalable API with enhanced frontend features  
 
 ## 🔧 Advanced Configuration
 
-### Enhanced Model Hyperparameters
+### Model Parameters
 - **Embedding Dimension**: 128 (upgraded from 64)
 - **Hidden Layers**: [256, 128] for both towers
 - **Dropout Rate**: 0.3 (increased for regularization)
@@ -576,96 +163,10 @@ RecSys-HP/
 
 ## 🚀 Production Deployment
 
-### Enhanced Infrastructure Requirements
-- **CPU**: 6+ cores for training, 4+ cores for serving
-- **Memory**: 12GB training, 4GB serving (increased for 128D embeddings)
-- **Storage**: 8GB for enhanced models and indices
-- **GPU**: Optional, provides 2-3x training speedup
-
-### Scaling Features
-- **Categorical Processing**: Efficient embedding lookups
+### Performance Optimizations
+- **Two-Tower Architecture**: Separates user and item processing for scalability
 - **FAISS Integration**: Sub-linear similarity search
 - **Batch Inference**: Vectorized computation for multiple users
 - **Model Versioning**: Support for A/B testing different model variants
 
----
-
-## 📊 Project Achievements
-
-✅ **Enhanced Architecture**: 128D embeddings, temperature scaling, contrastive learning  
-✅ **Curriculum Learning**: Progressive training for better convergence  
-✅ **Category-Aware Recommendations**: Intelligent personalization with diversity  
-✅ **Aggregated Content-Based Filtering**: Revolutionary user history aggregation approach  
-✅ **Enhanced Cold-Start Support**: Improved new user handling  
-✅ **Production Ready**: Scalable API with enhanced frontend features  
-
-**🎉 Ready to deliver next-generation personalized recommendations!**
-
-## 🗂️ Available Training Approaches
-
-This project provides multiple training strategies:
-
-1. **Main Pipeline** (`run_training_pipeline.py`) - Complete orchestrated training
-2. **2-Phase Training** (`run_2phase_training.py`) - Item pretraining + joint optimization  
-3. **Joint Training** (`run_joint_training.py`) - Direct joint training approach
-4. **Enhanced Training** (`train_improved_model.py`) - Advanced features with curriculum learning
-
-## 🔌 API Options
-
-- **Primary API** (`api/main.py`) - Full-featured FastAPI server
-- **2-Phase API** (`api_2phase.py`) - Specialized for 2-phase training
-- **Joint API** (`api_joint.py`) - Optimized for joint training approach
-
-## 🔧 Development Tools
-
-- **Real User Selection** (`src.utils.real_user_selector`) - Extract real user profiles for testing
-- **Data Loading Utilities** (`src.preprocessing.data_loader`) - Dataset loading and validation
-
-## 🧪 Development & Testing
-
-### Frontend Development
-```bash
-# Start development server with hot reload
-cd frontend && npm start
-
-# Build production bundle
-npm run build
-
-# Run frontend tests
-npm test
-```
-
-### Backend Testing
-```bash
-# Test API endpoints
-python -m pytest tests/
-
-# Manual API testing
-curl http://localhost:8000/health
-curl http://localhost:8000/model-info
-```
-
-### Troubleshooting
-
-#### Common Issues
-1. **TensorFlow GPU Issues**: Ensure CUDA 11.8+ and cuDNN are installed
-2. **Memory Errors**: Reduce batch size in training scripts
-3. **Port Conflicts**: Change API port in main.py if 8000 is occupied
-4. **Dataset Loading**: Verify CSV files are in correct format and location
-
-#### Performance Optimization
-- Use GPU training for 3-5x speedup
-- Increase batch size for better GPU utilization
-- Enable mixed precision training for memory efficiency
-
-## 📞 Support & Contributing
-
-For questions, issues, or contributions:
-- 🐛 **Report bugs**: Create an issue with detailed reproduction steps
-- 💡 **Feature requests**: Describe the enhancement and use case
-- 🔧 **Pull requests**: Follow the existing code style and add tests
-- 📚 **Documentation**: Help improve setup guides and API docs
-
----
-
-**Built with ❤️ using TensorFlow, React, and FastAPI**
+**🎉 Ready to deliver next-generation personalized recommendations!**

api/main.py

@@ -1,5 +1,7 @@
 from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
 from pydantic import BaseModel
 from typing import List, Optional, Dict, Any
 import uvicorn
@@ -205,9 +207,9 @@ async def startup_event():
         real_user_selector = None
 
 
-@app.get("/")
-async def root():
-    """Root endpoint with API information."""
+@app.get("/api")
+async def api_info():
+    """API information endpoint."""
     return {
         "message": "Two-Tower Recommendation API",
         "version": "1.0.0",
@@ -611,6 +613,44 @@ async def get_sample_items(limit: int = 20):
         raise HTTPException(status_code=500, detail=f"Error retrieving sample items: {str(e)}")
 
 
+# Mount static files for React build - MUST be at the end
+frontend_build_path = os.path.join(parent_dir, "frontend", "build")
+if os.path.exists(frontend_build_path):
+    # Serve static files (JS, CSS, images, etc.)
+    app.mount("/static", StaticFiles(directory=os.path.join(frontend_build_path, "static")), name="static")
+
+# Add a specific root route for React app
+@app.get("/", include_in_schema=False)
+async def serve_react_root():
+    """Serve React app at root route."""
+    frontend_build_path = os.path.join(parent_dir, "frontend", "build")
+    index_file = os.path.join(frontend_build_path, "index.html")
+    if os.path.exists(index_file):
+        return FileResponse(index_file)
+    else:
+        return {"message": "React build not found. Run 'npm run build' in frontend directory."}
+
+# Catch-all route for React Router - MUST be at the very end
+@app.get("/{full_path:path}", include_in_schema=False)
+async def serve_react_app(full_path: str):
+    """Serve React app for all non-API routes."""
+    # If it's a known API route, let FastAPI handle the 404
+    if (full_path.startswith("api/") or 
+        full_path.startswith("docs") or 
+        full_path.startswith("redoc") or 
+        full_path.startswith("openapi.json") or
+        full_path in ["health", "real-users", "dataset-summary", "behavioral-patterns", "recommendations", "item-similarity", "predict-rating", "items"]):
+        raise HTTPException(status_code=404, detail="API endpoint not found")
+    
+    # For all other routes, serve the React app
+    frontend_build_path = os.path.join(parent_dir, "frontend", "build")
+    index_file = os.path.join(frontend_build_path, "index.html")
+    if os.path.exists(index_file):
+        return FileResponse(index_file)
+    else:
+        raise HTTPException(status_code=404, detail="React build not found")
+
+
 if __name__ == "__main__":
     uvicorn.run(
         "main:app",

docker-build.md

@@ -0,0 +1,149 @@
+# Docker Build & Run Instructions
+
+## 🐳 Docker Setup for RecSys-HP
+
+This guide explains how to build and run the RecSys-HP recommendation system in a Docker container.
+
+### Prerequisites
+- Docker installed on your system
+- All model artifacts in `src/artifacts/` directory
+- Dataset files in `datasets/` directory
+
+### Build Docker Image
+
+```bash
+# Navigate to project root
+cd /path/to/RecSys-HP
+
+# Build the Docker image (this will take 5-10 minutes)
+docker build -t recsys-hp:latest .
+
+# Or build with a specific tag
+docker build -t recsys-hp:v1.0 .
+```
+
+### Run Docker Container
+
+#### Basic Run (Recommended)
+```bash
+# Run the container
+docker run -d \
+  --name recsys-hp-app \
+  -p 8000:8000 \
+  recsys-hp:latest
+
+# View logs
+docker logs recsys-hp-app
+
+# Follow logs in real-time
+docker logs -f recsys-hp-app
+```
+
+#### Run with Volume Mounts (Development)
+```bash
+# Mount datasets and artifacts for easy updates
+docker run -d \
+  --name recsys-hp-dev \
+  -p 8000:8000 \
+  -v $(pwd)/datasets:/app/datasets \
+  -v $(pwd)/src/artifacts:/app/src/artifacts \
+  recsys-hp:latest
+```
+
+### Access the Application
+
+Once the container is running:
+
+- **Web App**: http://localhost:8000/
+- **API Docs**: http://localhost:8000/docs
+- **API Info**: http://localhost:8000/api
+- **Health Check**: http://localhost:8000/health
+
+### Useful Docker Commands
+
+```bash
+# Check container status
+docker ps
+
+# Stop the container
+docker stop recsys-hp-app
+
+# Start the container
+docker start recsys-hp-app
+
+# Remove the container
+docker rm recsys-hp-app
+
+# View container resource usage
+docker stats recsys-hp-app
+
+# Execute commands in running container
+docker exec -it recsys-hp-app bash
+
+# View container logs
+docker logs recsys-hp-app
+```
+
+### Troubleshooting
+
+#### Container won't start?
+```bash
+# Check logs for errors
+docker logs recsys-hp-app
+
+# Common issues:
+# 1. Missing artifacts in src/artifacts/
+# 2. Missing datasets in datasets/
+# 3. Port 8000 already in use
+```
+
+#### Check if artifacts are present:
+```bash
+docker exec recsys-hp-app ls -la /app/src/artifacts/
+docker exec recsys-hp-app ls -la /app/datasets/
+```
+
+#### Use different port:
+```bash
+# Run on port 8080 instead
+docker run -d --name recsys-hp-app -p 8080:8000 recsys-hp:latest
+# Access at http://localhost:8080/
+```
+
+### Image Information
+
+- **Base Image**: python:3.10-slim
+- **Node.js Version**: 18-alpine (build stage only)
+- **Final Image Size**: ~1.5-2GB (includes all ML dependencies)
+- **Exposed Port**: 8000
+- **Health Check**: Enabled (checks /health endpoint)
+
+### Production Deployment
+
+For production deployment, consider:
+
+```bash
+# Run with restart policy
+docker run -d \
+  --name recsys-hp-prod \
+  --restart unless-stopped \
+  -p 8000:8000 \
+  recsys-hp:latest
+
+# Or use docker-compose (recommended for production)
+```
+
+### Environment Variables
+
+The container supports these environment variables:
+
+```bash
+docker run -d \
+  --name recsys-hp-app \
+  -p 8000:8000 \
+  -e PYTHONUNBUFFERED=1 \
+  -e LOG_LEVEL=info \
+  recsys-hp:latest
+```
+
+The Docker container includes both the React frontend and FastAPI backend in a single image, making deployment simple and efficient! 🚀