{"id":31698851,"url":"https://github.com/triiju/hybrid-recommendation-engine","last_synced_at":"2026-05-18T02:02:40.381Z","repository":{"id":317849124,"uuid":"1068943360","full_name":"triiJU/hybrid-recommendation-engine","owner":"triiJU","description":"Tri-Weight Hybrid Recommendation Engine API","archived":false,"fork":false,"pushed_at":"2025-11-01T06:46:26.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-01T08:30:23.552Z","etag":null,"topics":["collaborative-filtering","content-based-filtering","fastapi","hybrid-recommendation","machine-learning","neural-cf","personalisation","python","ranking-algorithm","recommendation-engine","recommender-system"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/triiJU.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T06:44:51.000Z","updated_at":"2025-11-01T06:46:30.000Z","dependencies_parsed_at":"2025-10-03T13:26:03.334Z","dependency_job_id":"d82d422d-cd69-4113-a82e-6f69072d4956","html_url":"https://github.com/triiJU/hybrid-recommendation-engine","commit_stats":null,"previous_names":["triiju/hybrid-recommendation-engine"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/triiJU/hybrid-recommendation-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triiJU%2Fhybrid-recommendation-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triiJU%2Fhybrid-recommendation-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triiJU%2Fhybrid-recommendation-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triiJU%2Fhybrid-recommendation-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/triiJU","download_url":"https://codeload.github.com/triiJU/hybrid-recommendation-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/triiJU%2Fhybrid-recommendation-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33162446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"online","status_checked_at":"2026-05-18T02:00:06.436Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collaborative-filtering","content-based-filtering","fastapi","hybrid-recommendation","machine-learning","neural-cf","personalisation","python","ranking-algorithm","recommendation-engine","recommender-system"],"created_at":"2025-10-08T19:11:15.567Z","updated_at":"2026-05-18T02:02:40.375Z","avatar_url":"https://github.com/triiJU.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hybrid Recommendation Engine\n\n## Overview\nA modular hybrid recommender system supporting:\n- Popularity baseline\n- Collaborative Filtering (user–user \u0026 item–item cosine)\n- Content-Based Ranking (TF-IDF over item metadata)\n- Neural Collaborative Filtering (PyTorch embeddings + MLP)\n- Hybrid Blending (tri-weight: CF, content, neural)\n- Alpha sweep \u0026 Optuna hyperparameter tuning\n- Cold-start evaluation (new / sparse users \u0026 items)\n- Ranking Metrics: Precision@K, Recall@K, NDCG@K, Coverage, Item Diversity\n- Reproducible pipeline (Makefile + scripts)\n\n## Why Hybrid?\nPure collaborative filtering struggles with cold-start and sparse data. Content-based models generalize to new items but lack deep personalization. Neural CF captures non-linear interactions. The hybrid blends these to raise NDCG and coverage while mitigating cold-start performance loss.\n\n## Features\n| Component | File | Description |\n|-----------|------|-------------|\n| Data download | `src/data_loading.py` | MovieLens 100K fetch \u0026 extract |\n| Preprocessing | `src/preprocess.py` | Filtering low-interaction users, train/test split |\n| Popularity baseline | `src/popularity.py` | Global item ranking |\n| Collaborative Filtering | `src/cf_baseline.py` | User–User / Item–Item cosine similarity |\n| Content-based | `src/content_based.py` | TF-IDF item embeddings \u0026 similarity |\n| Neural CF | `src/neural_cf.py` | Embeddings + MLP (explicit ratings regression) |\n| Hybrid blend | `src/hybrid.py` | Tri-weight combination of CF + content + neural |\n| Metrics | `src/metrics.py` | Precision@K, Recall@K, NDCG@K, Coverage, Diversity |\n| Evaluation | `src/evaluation.py` | Unified baseline evaluation |\n| Alpha sweep | `scripts/alpha_sweep.py` | Evaluate multiple α values |\n| Optuna tuning | `src/optuna_tune.py` | Optimize CF neighbor count / mode |\n| Cold-start eval | `src/cold_start.py` | Segment sparse users/items |\n| Logging | `src/logging_config.py` | Structured logging |\n| Pipeline script | `scripts/run_pipeline.sh` | End-to-end automation |\n| Make targets | `Makefile` | Reproducible commands |\n\n## Metrics (Example / Placeholder)\n| Model                 | P@10 | R@10 | NDCG@10 | Coverage | Diversity |\n|-----------------------|------|------|---------|----------|-----------|\n| Popularity            | 0.18 | 0.09 | 0.11    | 0.04     | 0.21      |\n| User-CF               | 0.27 | 0.14 | 0.21    | 0.33     | 0.37      |\n| Item-CF               | 0.26 | 0.13 | 0.20    | 0.29     | 0.35      |\n| Content (TF-IDF)      | 0.19 | 0.10 | 0.15    | 0.41     | 0.49      |\n| Neural CF             | 0.29 | 0.16 | 0.23    | 0.36     | 0.39      |\n| Hybrid (CF=0.6, Content=0.4)        | 0.31 | 0.17 | 0.24    | 0.44     | 0.46      |\n| Hybrid (CF=0.5, Content=0.3, Neural=0.2) | 0.32 | 0.18 | 0.25    | 0.45     | 0.45      |\n\n(Replace with real outputs after running.)\n\n## Cold-Start (Example)\n| Segment | P@10 (User-CF) | P@10 (Content) | P@10 (Hybrid) |\n|---------|----------------|----------------|---------------|\n| New Users (≤4 ratings) | 0.09 | 0.15 | 0.19 |\n| New Items (low exposure) | 0.06 | 0.14 | 0.17 |\n\n## Directory Structure\n```\n.\n├── README.md\n├── LICENSE\n├── Makefile\n├── requirements.txt\n├── models/\n├── experiments/\n├── scripts/\n└── src/\n```\n\n## Quick Start\n```bash\npython -m venv .venv\nsource .venv/bin/activate         # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\n\nmake download\nmake preprocess\nmake baselines\nmake neural\nmake hybrid\nmake evaluate\nmake alpha\nmake coldstart\n```\n\n## Example Hybrid Run\n\n### Tri-Weight Blending\n```bash\n# CF + Content blend (no neural)\npython -m src.hybrid --w_cf 0.6 --w_content 0.4 --w_neural 0.0 \\\n  --train_path data/processed/train.csv \\\n  --test_path data/processed/test.csv \\\n  --items_path data/ml-100k/u.item\n\n# CF + Content + Neural blend (neural weight ignored if model not found)\npython -m src.hybrid --w_cf 0.5 --w_content 0.3 --w_neural 0.2 \\\n  --train_path data/processed/train.csv \\\n  --test_path data/processed/test.csv \\\n  --items_path data/ml-100k/u.item \\\n  --neural_model_path models/neural_cf.pt\n```\n\n**Note:** If the neural model is not trained/available, the neural weight will be automatically set to 0 and weights will be renormalized.\n\n## API Usage\n\nThe system provides a FastAPI-based REST API for serving recommendations:\n\n```bash\n# Start the API server\nuvicorn api.app:app --reload\n\n# Get recommendations with custom weights\ncurl \"http://localhost:8000/recommend?user_id=1\u0026k=10\u0026w_cf=0.6\u0026w_content=0.4\u0026w_neural=0.0\"\n\n# Check API health\ncurl \"http://localhost:8000/health\"\n\n# Get metadata\ncurl \"http://localhost:8000/meta\"\n```\n\n## Alpha Sweep\n```bash\npython scripts/alpha_sweep.py --alphas 0.3 0.5 0.7 0.9 --k 10\n```\n\n## Optuna Hyperparameter Tuning\n```bash\npython -m src.optuna_tune --trials 30\n```\n\n## Cold-Start Evaluation\n```bash\npython -m src.cold_start --train_path data/processed/train.csv \\\n  --test_path data/processed/test.csv --k 10\n```\n\n## Scalability (Interview Talking Points)\n- Replace brute-force similarity with ANN (Faiss)\n- Offline batch refresh + incremental updates\n- Candidate generation → re-ranking pipeline\n- Feature store for user/item embeddings\n\n```\nhttps://gpt-website-builder-1-0.onrender.com/gpt/0acbab5a.html\n```\n\n## Future Work\n- Transformer text embeddings\n- Implicit feedback (BPR / WARP)\n- Meta-learning blend weights\n- MLflow tracking\n- A/B simulation harness\n\n## License\nMIT\n\n## Citation\nMovieLens datasets: © GroupLens Research Group.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriiju%2Fhybrid-recommendation-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftriiju%2Fhybrid-recommendation-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftriiju%2Fhybrid-recommendation-engine/lists"}