Mivro Python Server

This is the backend server for the Mivro project, built with Flask framework. It serves as the core of the Mivro ecosystem, handling several critical functions, including user authentication, data processing, and API integrations.

Maintained By: Areeb Ahmed

Repository Structure

Instructions (instructions/)

Contains templates used by the Gemini AI model for various functionalities:

• lumi_instructions.md: Template for analyzing nutrients and categorizing them into positive and negative.
• savora_instructions.md: Template for the recipe chatbot, guiding the AI in generating personalized recipe recommendations.
• swapr_instructions.md: Template for providing healthier product alternatives based on user preferences.

Metadata (metadata/)

Contains essential JSON files used for data processing and mapping:

• additives_names.json: Maps additive codes (e.g., "E100") to their corresponding names (e.g., "Curcumin"). This is used during data processing to convert numeric codes into readable names.
• food_categories.json: Maps food categories (e.g., "Milk") to broader categories (e.g., "Milk Products", "Milk Solids") to associate appropriate icons with nutrients.
• nutrient_limits.json: Defines the lower and upper limits for various nutrients (e.g., "calcium": { "unit": "mg", "lower_limit": 1000, "upper_limit": 1300 }). Although deprecated, it was originally used for sorting nutrients into positive and negative categories based on their range.
• product_schema.json: Specifies the required fields from the OpenFoodFacts API, defining the structure for product data.

Python Server (server/)

Contains the main application code, including routes, configurations, and utility functions:

• app.py: Defines the main application blueprint and routes.
• auth.py: Manages Firebase-based user authentication, including registration and login.
• chat.py: Handles routes for user chat functionalities, such as loading and updating messages.
• config.py: Contains environment variables and server configuration settings.
• database.py: Provides methods for interacting with the Firebase database, including data storage and retrieval.
• gemini.py: Interfaces with the Gemini AI model for nutrient analysis and product recommendations.
• mapping.py: Manages mappings for additives, NOVA groups, NutriScore grades, and food icons.
• metrics.py: Defines Prometheus metrics for monitoring the application.
• middleware.py: Implements global request authentication and error handling.
• models.py: Defines the database schema and model structures.
• search.py: Connects to the OpenFoodFacts API to process and map product data.
• user.py: Manages user profile routes, including profile updates and history management.
• utils.py: Contains utility functions for data processing and structuring API responses.

Getting Started

Follow these steps to set up and run the Mivro Python Server on your local machine, or you can watch the demo video.

Prerequisites

• Python >= 3.11.9: Download (for local setup)
• Docker: Docker Desktop (for Docker setup)
• Firebase account: Create a Firebase project here and download firebase-config.json
• Gemini API key: Get your API key here

Installation

Option 1: Docker Compose (Recommended)

1. Setup Environment Variables:

   • Create a .env file in the project root:

     FLASK_APP=server/app.py
     FLASK_ENV=development
     FLASK_DEBUG=1
     FLASK_RUN_HOST=0.0.0.0
     FLASK_RUN_PORT=5000
     FLASK_SECRET_KEY=your-secret-key
     GEMINI_API_KEY=your-gemini-api-key

   • Add your firebase-config.json file to the project root directory.

2. Run with Docker Compose:

   • Start the server:

     docker-compose up -d

   • View logs:

     docker-compose logs -f api

   • Stop the server:

     docker-compose down

Option 2: Docker Build

1. Setup Environment Variables:

   • Create a .env file in the project root:

     FLASK_APP=server/app.py
     FLASK_ENV=production
     FLASK_DEBUG=0
     FLASK_RUN_HOST=0.0.0.0
     FLASK_RUN_PORT=5000
     FLASK_SECRET_KEY=your-secret-key
     GEMINI_API_KEY=your-gemini-api-key

   • Add your firebase-config.json file to the project root directory.

2. Build and Run:

   • Build the Docker image:

     docker build -t mivro-server:latest .

   • Run the container:

     docker run -d -p 5000:5000 --env-file .env -v ./firebase-config.json:/app/firebase-config.json --name mivro-server mivro-server:latest

   • Check container logs:

     docker logs -f mivro-server

   • Stop the container:

     docker stop mivro-server && docker rm mivro-server

Option 3: Local Setup

1. Fork the Repository:

   • Go to the Mivro Python Server repository and click "Fork" to create a copy under your GitHub account.

2. Clone the Repository:

   git clone https://github.com/<your-username>/mivro-server.git

3. Create a Virtual Environment (Optional but Recommended):

   python -m venv .venv

4. Activate the Virtual Environment:

   • Windows:

     .venv\Scripts\activate

   • macOS and Linux:

     source .venv/bin/activate

5. Install Dependencies:

   pip install -r requirements.txt

6. Set Up Environment Variables:

   • Create a .env file in the project root directory with the following template:

     FLASK_APP=server/app.py
     FLASK_ENV=development
     FLASK_DEBUG=1
     FLASK_RUN_HOST=0.0.0.0
     FLASK_RUN_PORT=5000
     FLASK_SECRET_KEY=your-secret-key
     GEMINI_API_KEY=your-api-key

   • Create a firebase-config.json file in the project root directory with the following template:

     {
       "type": "service_account",
       "project_id": "your_project_id",
       "private_key_id": "your_private_key_id",
       "private_key": "-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----\n",
       "client_email": "your_client_email",
       "client_id": "your_client_id",
       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
       "token_uri": "https://oauth2.googleapis.com/token",
       "auth_provider_x509_cert_url": "https://googleapis.com/oauth2/v1/certs",
       "client_x509_cert_url": "https://googleapis.com/robot/v1/metadata/x509/your_client_email",
       "universe_domain": "googleapis.com"
     }

7. Run the Python Application:

   flask run

Usage

To interact with the Mivro Python Server, you can use API calls via Postman or any HTTP client. Below is an example of how to search for a product using its barcode.

NOTE: First, register your email at the /signup route (/api/v1/auth/signup). Replace Mivro-Email, Mivro-Password, and product_barcode with actual values depending on the route you are testing.

Example API Call

• Endpoint: /api/v1/search/barcode
• Method: GET
• Headers:
  • Mivro-Email: your_email@example.com
  • Mivro-Password: your_password
• Body (JSON):

  {
    "product_barcode": "8901719104046"
  }

Example Response

To see an example of the response you can expect, refer to the response-example.json file.

Documentation

For detailed documentation, please visit the Documentation Repository.

Contributing

We welcome contributions! Please follow the guidelines in our Contributing Guide to get started.

License

This project is licensed under the MIT License.

Acknowledgments

• Open Food Facts for providing access to a comprehensive food product database.
• All Contributors for their valuable contributions to the development and improvement of this project.