{"id":28232208,"url":"https://github.com/yonatankinfe/tf-recommender-lightweight-system","last_synced_at":"2026-01-26T17:03:11.767Z","repository":{"id":290556728,"uuid":"974845678","full_name":"Yonatankinfe/tf-recommender-lightweight-system","owner":"Yonatankinfe","description":"A lightweight content-based recommendation system built with Python and TensorFlow/Keras, exposed via a simple REST API with automatic API key generation.","archived":false,"fork":false,"pushed_at":"2025-06-10T08:28:58.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T09:34:31.834Z","etag":null,"topics":["machine-learning","nerual-network","python","recommendation-algorithm","recommender-system","tensorflow"],"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/Yonatankinfe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-04-29T11:51:24.000Z","updated_at":"2025-06-10T08:29:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"a95ab482-7768-4ca2-b028-ff93104124ab","html_url":"https://github.com/Yonatankinfe/tf-recommender-lightweight-system","commit_stats":null,"previous_names":["yonatankinfe/tf-recommender-lightweight-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Yonatankinfe/tf-recommender-lightweight-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Ftf-recommender-lightweight-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Ftf-recommender-lightweight-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Ftf-recommender-lightweight-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Ftf-recommender-lightweight-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yonatankinfe","download_url":"https://codeload.github.com/Yonatankinfe/tf-recommender-lightweight-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yonatankinfe%2Ftf-recommender-lightweight-system/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259823408,"owners_count":22917051,"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","nerual-network","python","recommendation-algorithm","recommender-system","tensorflow"],"created_at":"2025-05-18T20:08:40.039Z","updated_at":"2026-01-26T17:03:06.725Z","avatar_url":"https://github.com/Yonatankinfe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Content-Based Recommendation System\n\nThis project implements a lightweight recommendation system, simple content-based recommendation system using Python, TensorFlow/Keras for neural network embeddings, and FastAPI for the RESTful API.\n\n## Features\n\n*   **Content-Based Recommendations:** Recommends items similar to a given item based on their content (title, description, tags).\n*   **Neural Network Embeddings:** Uses a simple Multi-Layer Perceptron (MLP) trained like an autoencoder on TF-IDF features to generate item embeddings.\n*   **TF-IDF:** Utilizes TF-IDF for initial text feature extraction.\n*   **RESTful API:** Exposes recommendation functionality via a FastAPI application.\n*   **API Key Authentication:** Secures the recommendation endpoint using API keys stored in a `.env` file.\n*   **Automatic Key Generation:** Includes an endpoint (or initial setup) to generate API keys.\n\n## Project Structure\n\n```\nrecommendation_system/\n├── data/\n│   └── items.csv           # Example item data\n├── models/                 # Saved models and artifacts (created by train.py)\n│   ├── tfidf_vectorizer.pkl\n│   ├── embedding_model.keras\n│   └── item_embeddings.pkl\n├── src/\n│   ├── __init__.py\n│   ├── auth.py             # API key handling and authentication\n│   ├── data_loader.py      # Loads and prepares data\n│   ├── main.py             # FastAPI application\n│   ├── model.py            # Keras model definition\n│   ├── preprocessing.py    # Text preprocessing and TF-IDF\n│   ├── recommender.py      # Recommendation logic (cosine similarity)\n│   ├── train.py            # Training script\n│   └── utils.py            # Utility functions (saving/loading artifacts)\n├── venv/                   # Virtual environment\n├── .env                    # Stores API keys (created automatically)\n├── README.md               # This file\n└── requirements.txt        # Python dependencies\n```\n\n## Setup\n\n1.  **Clone the repository (or place the project files):**\n    ```bash\n    # Assuming you have the project folder\n    cd recommendation_system\n    ```\n\n2.  **Create and activate a virtual environment:**\n    ```bash\n    python3 -m venv venv\n    source venv/bin/activate\n    ```\n\n3.  **Install dependencies:**\n    ```bash\n    pip install -r requirements.txt\n    ```\n    *(Note: The `requirements.txt` file needs to be generated first if not provided. See step below.)*\n\n## Training\n\nRun the training script to process the data, train the model, and generate the necessary artifacts (`tfidf_vectorizer.pkl`, `embedding_model.keras`, `item_embeddings.pkl`) in the `models/` directory.\n\n```bash\ncd src\npython train.py\ncd ..\n```\n\nThis script performs the following steps:\n*   Loads data from `data/items.csv`.\n*   Preprocesses the text content.\n*   Creates and fits a TF-IDF vectorizer.\n*   Builds and trains the neural network model (autoencoder-style).\n*   Generates embeddings for all items using the trained base model.\n*   Saves the vectorizer, the base embedding model, and the item embeddings to the `models/` directory.\n\n## Running the API Server\n\n1.  **Ensure artifacts are generated:** Make sure you have run the `train.py` script successfully and the `models/` directory contains the required files.\n\n2.  **Generate an initial API Key (if needed):** The API server will automatically generate an initial API key and save it to the `.env` file if no keys are found upon startup. Check the console output when starting the server for the generated key.\n\n3.  **Start the FastAPI server using Uvicorn:**\n    ```bash\n    cd src\n    uvicorn main:app --host 0.0.0.0 --port 8000\n    ```\n    *   `--host 0.0.0.0` makes the server accessible within the network.\n    *   `--port 8000` specifies the port.\n    *   Use `--reload` during development for automatic code reloading.\n\n## API Usage\n\nThe API provides two main endpoints:\n\n### 1. Get Recommendations\n\n*   **URL:** `/recommend`\n*   **Method:** `GET`\n*   **Headers:**\n    *   `X-API-Key`: `\u003cyour_api_key\u003e` (Required)\n*   **Query Parameters:**\n    *   `item_id` (string, required): The ID of the item you want recommendations for (e.g., `item_1`).\n    *   `n` (integer, optional, default=5): The number of recommendations to return.\n*   **Example Request (using curl):**\n    ```bash\n    curl -X GET \"http://localhost:8000/recommend?item_id=item_3\u0026n=3\" -H \"X-API-Key: \u003cyour_api_key\u003e\"\n    ```\n*   **Success Response (200 OK):**\n    ```json\n    {\n      \"input_item_id\": \"item_3\",\n      \"recommendations\": [\n        \"item_4\",\n        \"item_5\",\n        \"item_1\"\n      ]\n    }\n    ```\n*   **Error Responses:**\n    *   `401 Unauthorized`: If the API key is missing or invalid.\n    *   `404 Not Found`: If the provided `item_id` does not exist.\n    *   `422 Unprocessable Entity`: If query parameters are invalid.\n    *   `503 Service Unavailable`: If the model artifacts haven't been loaded correctly.\n\n### 2. Generate New API Key (Admin)\n\n*   **URL:** `/admin/generate-key`\n*   **Method:** `POST`\n*   **Authentication:** *Note: This endpoint is not secured by default in this simple implementation. Secure it appropriately in a production environment (e.g., require a master admin key, restrict access).* \n*   **Example Request (using curl):**\n    ```bash\n    curl -X POST \"http://localhost:8000/admin/generate-key\"\n    ```\n*   **Success Response (200 OK):**\n    ```json\n    {\n      \"api_key\": \"\u003cnewly_generated_api_key\u003e\",\n      \"message\": \"Key generated and added successfully.\"\n    }\n    ```\n    The new key is automatically added to the `.env` file.\n\n## Notes\n\n*   The neural network training is minimal, primarily serving to create embeddings from TF-IDF. More sophisticated training (e.g., using contrastive loss) could improve embedding quality.\n*   Text preprocessing is simplified (lowercase, remove punctuation/numbers, remove stopwords, basic split). Stemming was removed due to NLTK resource issues during testing.\n*   API key storage uses a simple `.env` file. For production, consider more secure storage like a database or secrets manager.\n*   The `/admin/generate-key` endpoint lacks robust security in this example.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonatankinfe%2Ftf-recommender-lightweight-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyonatankinfe%2Ftf-recommender-lightweight-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonatankinfe%2Ftf-recommender-lightweight-system/lists"}