{"id":25441920,"url":"https://github.com/nicolasvauche/vinylexplore_ml","last_synced_at":"2026-05-17T06:37:24.628Z","repository":{"id":277823606,"uuid":"932757944","full_name":"nicolasvauche/vinylexplore_ml","owner":"nicolasvauche","description":"VinyleXplore est un moteur de recommandation de vinyles intelligent basé sur l'humeur et le contexte d'écoute de l'utilisateur. Il utilise FastAPI pour exposer une API REST et scikit-learn pour entraîner un modèle de Machine Learning qui améliore la pertinence des suggestions.","archived":false,"fork":false,"pushed_at":"2025-02-16T11:04:28.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-16T12:18:06.652Z","etag":null,"topics":["machine-learning","python","scikit-learn","vinyle"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nicolasvauche.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-02-14T13:18:00.000Z","updated_at":"2025-02-16T11:04:31.000Z","dependencies_parsed_at":"2025-02-16T12:18:09.710Z","dependency_job_id":"17f9eef0-acab-40e4-ad58-ba4124a490d3","html_url":"https://github.com/nicolasvauche/vinylexplore_ml","commit_stats":null,"previous_names":["nicolasvauche/vinylexplore_ml"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasvauche%2Fvinylexplore_ml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasvauche%2Fvinylexplore_ml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasvauche%2Fvinylexplore_ml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nicolasvauche%2Fvinylexplore_ml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nicolasvauche","download_url":"https://codeload.github.com/nicolasvauche/vinylexplore_ml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239293947,"owners_count":19615043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["machine-learning","python","scikit-learn","vinyle"],"created_at":"2025-02-17T13:16:01.673Z","updated_at":"2025-10-16T09:59:17.287Z","avatar_url":"https://github.com/nicolasvauche.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VinyleXplore - Moteur de Recommandation de Vinyles 🎶\n\nVinyleXplore est un moteur de recommandation de vinyles intelligent basé sur l'humeur et le contexte d'écoute de\nl'utilisateur. Il utilise **FastAPI** pour exposer une API REST et **scikit-learn** pour entraîner un modèle de Machine\nLearning qui améliore la pertinence des suggestions.\n\n## Fonctionnalités\n\n- Recommandation d'albums en fonction :\n    - De l'**humeur** de l'utilisateur (motivé, paisible, amoureux, etc.).\n    - Du **moment de la journée** (matin, midi, soir...).\n    - De la **saison** actuelle.\n    - Du **lieu** où se trouve l'utilisateur.\n    - Du **nombre d'écoutes** passées.\n    - Du **genre et du style musical** des albums.\n- **Sélection aléatoire** d’un album si aucune humeur n'est définie.\n- **Moteur basé sur un modèle de Machine Learning** entraîné avec `RandomForestClassifier`.\n- **Exposition via une API REST** avec FastAPI.\n\n---\n\n## Installation\n\n### 1. Cloner le projet\n\n```bash\ngit clone [url_du_referentiel]\ncd vinylexplore_ml\n```\n\n### 2. Créer un environnement virtuel et installer les dépendances\n\n```bash\npython -m venv venv\nsource venv/bin/activate  # Mac/Linux\nvenv\\Scripts\\activate  # Windows\n\npip install -r requirements.txt\n```\n\n### 3. Lancer l'API FastAPI\n\n```bash\nuvicorn app.main:app --reload\n```\n\nL'API sera disponible à l'adresse http://127.0.0.1:8000.\n\n---\n\n## Endpoints de l'API\n\nRoute : `POST /recommend`\n\nCorps de la requête (JSON) :\n\n```json\n{\n  \"context\": {\n    \"dayOfWeek\": \"vendredi\",\n    \"timeOfDay\": \"soir\",\n    \"season\": \"hiver\",\n    \"mood\": \"motivé\",\n    \"location\": \"maison\"\n  },\n  \"albums\": [\n    {\n      \"id\": 1,\n      \"moods\": [\n        \"motivé\",\n        \"en soirée\"\n      ],\n      \"playCount\": 3,\n      \"lastPlayedAt\": 1700000000,\n      \"listeningHistory\": [],\n      \"ignoredCount\": 1,\n      \"listenedCount\": 2,\n      \"genre\": \"Rock\",\n      \"style\": \"Alternative Rock\"\n    },\n    {\n      \"id\": 2,\n      \"moods\": [\n        \"paisible\"\n      ],\n      \"playCount\": 10,\n      \"lastPlayedAt\": 1700000000,\n      \"listeningHistory\": [],\n      \"ignoredCount\": 3,\n      \"listenedCount\": 7,\n      \"genre\": \"Jazz\",\n      \"style\": \"Smooth Jazz\"\n    }\n  ]\n}\n```\n\nRéponse attendue :\n\n```json\n{\n  \"id\": 1,\n  \"moods\": [\n    \"motivé\",\n    \"en soirée\"\n  ],\n  \"playCount\": 3,\n  \"lastPlayedAt\": 1700000000,\n  \"listeningHistory\": [],\n  \"ignoredCount\": 1,\n  \"listenedCount\": 2,\n  \"genre\": \"Rock\",\n  \"style\": \"Alternative Rock\"\n}\n```\n\n---\n\n## Algorithme de Recommandation\n\n### 1. Prétraitement des Données :\n\nTransformation des catégories (dayOfWeek, mood, etc.) en valeurs numériques.\nGestion des valeurs None (remplacement par 0 si nécessaire).\nCréation d'un DataFrame pour la prédiction.\n\n### 2. Prédiction via Machine Learning :\n\nUtilisation d'un RandomForestClassifier entraîné sur des écoutes réelles.\nLe modèle classe les albums comme \"écouté\" ou \"ignoré\".\n\n### 3. Calcul du Score des Albums :\n\n- Diversité : Moins un album a été écouté, plus il est recommandé.\n- Match Humeur-Genre : Si le genre ou le style correspond à l'humeur, bonus de score.\n- Correspondance avec l’historique d’écoute : Les albums déjà appréciés sont favorisés.\n- Mélange des albums de score égal pour éviter la répétition.\n\n### 4. Sélection de l'album final :\n\n- Si mood est null → Sélection totalement aléatoire.\n- Sinon → Album avec le meilleur score et mélange des résultats.\n\n---\n\n## Entraînement du Modèle\n\nLe modèle est entraîné avec des données simulées dans `train_model.py` :\n\n```bash\npython app/train_model.py\n```\n\n---\n\n## Améliorations Futures\n\n- Ajout du filtrage temporel pour éviter de recommander un album écouté récemment.\n- Prise en compte des albums jamais écoutés dans la recommandation.\n- Affinage du modèle avec de véritables données d’écoute utilisateurs.\n\n---\n\n## Licence\n\nCe projet est sous licence MIT.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasvauche%2Fvinylexplore_ml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnicolasvauche%2Fvinylexplore_ml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnicolasvauche%2Fvinylexplore_ml/lists"}