{"id":31045651,"url":"https://github.com/yonatankinfe/ecommerce-recommendation-system-api","last_synced_at":"2025-10-13T16:36:06.249Z","repository":{"id":299994993,"uuid":"1004850617","full_name":"Yonatankinfe/ecommerce-recommendation-system-api","owner":"Yonatankinfe","description":"A plug-and-play recommendation engine to boost sales on your e-commerce site. Power personalized product suggestions with your own data.","archived":false,"fork":false,"pushed_at":"2025-06-24T11:25:38.000Z","size":88,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T17:18:05.744Z","etag":null,"topics":["ai","algorithms","api","csv","deep-learning","deep-learning-algorithms","docker","ecommerce","embeddings","ml","model-as-a-service","recommender-system","training"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yonatankinfe.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}},"created_at":"2025-06-19T09:22:33.000Z","updated_at":"2025-08-22T16:16:55.000Z","dependencies_parsed_at":"2025-06-19T10:42:17.191Z","dependency_job_id":"cdc46721-6e46-40c7-b6cf-dad474c98af7","html_url":"https://github.com/Yonatankinfe/ecommerce-recommendation-system-api","commit_stats":null,"previous_names":["yonatankinfe/ecommerce-recommendation-system-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yonatankinfe/ecommerce-recommendation-system-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Fecommerce-recommendation-system-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Fecommerce-recommendation-system-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Fecommerce-recommendation-system-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Fecommerce-recommendation-system-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yonatankinfe","download_url":"https://codeload.github.com/Yonatankinfe/ecommerce-recommendation-system-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Fecommerce-recommendation-system-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279016091,"owners_count":26085802,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"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":["ai","algorithms","api","csv","deep-learning","deep-learning-algorithms","docker","ecommerce","embeddings","ml","model-as-a-service","recommender-system","training"],"created_at":"2025-09-14T17:12:13.242Z","updated_at":"2025-10-13T16:36:06.244Z","avatar_url":"https://github.com/Yonatankinfe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# E-commerce Recommendation System API\n\nThis project provides a \"model-as-a-service\" API for generating product recommendations based on user interaction data. It uses a Neural Collaborative Filtering (NCF) model.\n\n## ✨ Features ✨\n\n*   **Trainable Recommendation Model:** Upload your own dataset (CSV format) to train a custom recommendation model.\n*   **NCF Architecture:** Utilizes a hybrid Neural Collaborative Filtering model to capture both linear and non-linear user-item interactions.\n*   **RESTful API:**\n    *   `POST /v1/train`: To upload data and initiate model training. Returns an API key upon completion.\n    *   `POST /v1/recommendations`: To get product recommendations for a given user.\n*   **API Key Authentication:** Secure access to the recommendation service.\n*   **Containerized:** Easy to deploy using Docker.\n\n## 🛠️ How it Works 🛠️\n\nThe system consists of three main components:\n\n1.  **Data Ingestion \u0026 Training Service:**\n    *   Accepts CSV data with `user_id`, `item_id`, and optional `interaction_score` and `timestamp`.\n    *   Performs preprocessing:\n        *   **Entity Mapping:** Maps `user_id`s and `item_id`s to integer indices.\n        *   **Negative Sampling:** Generates negative samples for implicit feedback datasets.\n    *   Trains an NCF model:\n        *   **Embedding Layers:** Create dense vector representations for users and items.\n        *   **GMF Path (Generalized Matrix Factorization):** Element-wise product of user and item embeddings to capture linear interactions.\n        *   **MLP Path (Multi-Layer Perceptron):** Concatenated embeddings fed through dense layers to capture non-linear interactions.\n        *   **Output Layer:** Combines GMF and MLP outputs with a Sigmoid activation for a probability score.\n    *   Uses Binary Cross-Entropy loss and Adam optimizer.\n    *   Serializes the trained model (.h5) and index mappings (JSON).\n    *   (Future: Asynchronous training via a task queue).\n\n2.  **Model Registry \u0026 Storage (Conceptual):**\n    *   Trained models and mappings are stored (e.g., locally in a `models` directory, or conceptually in an S3-like object store for larger scale).\n    *   Each model version is associated with an API key.\n\n3.  **Inference API Service:**\n    *   Built with FastAPI for high performance.\n    *   Authenticates requests via `X-API-Key` header.\n    *   `POST /v1/recommendations` endpoint:\n        *   Loads the appropriate model and mappings based on the API key.\n        *   Converts the input `user_id` to its integer index.\n        *   Generates candidate items (all items not yet interacted with by the user).\n        *   Predicts interaction scores for candidate items.\n        *   Returns the top N recommended `item_id`s.\n    *   (Future: In-memory caching for frequently accessed models and user recommendations).\n\n## 🚀 Getting Started (High-Level) 🚀\n\n1.  **Prepare your data:** Create a CSV file with columns `user_id`, `item_id`, and optionally `interaction_score`, `timestamp`.\n2.  **Train a model:** Send a `POST` request to `/v1/train` with your CSV data. You'll receive an API key.\n3.  **Get recommendations:** Send a `POST` request to `/v1/recommendations` with your `user_id` and the desired number of recommendations, including your API key in the `X-API-Key` header.\n\n*(More detailed setup and API usage instructions will be added as development progresses, especially regarding running the Docker container.)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonatankinfe%2Fecommerce-recommendation-system-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyonatankinfe%2Fecommerce-recommendation-system-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonatankinfe%2Fecommerce-recommendation-system-api/lists"}