{"id":27992728,"url":"https://github.com/samshad/mindful-eating-backend","last_synced_at":"2026-04-11T07:03:25.236Z","repository":{"id":290460456,"uuid":"973966227","full_name":"samshad/mindful-eating-backend","owner":"samshad","description":"A FastAPI-based backend system that delivers AI-generated mindful eating tips tailored to users’ Big Five personality traits and eating behaviors. Built with PostgreSQL, Docker, and fine-tuned LLaMA 3.2 models.","archived":false,"fork":false,"pushed_at":"2025-05-18T15:24:24.000Z","size":25117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-09T10:09:48.007Z","etag":null,"topics":["fastapi","finetuning-llms","llama3","ollama","postgres","python","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samshad.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-04-28T03:59:50.000Z","updated_at":"2025-05-18T15:24:27.000Z","dependencies_parsed_at":"2025-04-29T00:36:30.473Z","dependency_job_id":"553831e7-8727-4783-8151-eafc8a7d455a","html_url":"https://github.com/samshad/mindful-eating-backend","commit_stats":null,"previous_names":["samshad/mindful-eating-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samshad/mindful-eating-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samshad%2Fmindful-eating-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samshad%2Fmindful-eating-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samshad%2Fmindful-eating-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samshad%2Fmindful-eating-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samshad","download_url":"https://codeload.github.com/samshad/mindful-eating-backend/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samshad%2Fmindful-eating-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001322,"owners_count":26083040,"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-09T02:00:07.460Z","response_time":59,"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":["fastapi","finetuning-llms","llama3","ollama","postgres","python","sqlalchemy"],"created_at":"2025-05-08T18:41:23.674Z","updated_at":"2025-10-09T10:09:49.737Z","avatar_url":"https://github.com/samshad.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mindful Eating Backend🧘‍♀️🍲\n\n![License](https://img.shields.io/github/license/samshad/mindful-eating-backend)\n![Python](https://img.shields.io/badge/python-3.12-blue?style=flat)\n![Build](https://img.shields.io/badge/build-passing-brightgreen?style=flat)\n![FastAPI](https://img.shields.io/badge/FastAPI-009688.svg?style=flat\u0026logo=FastAPI\u0026logoColor=white)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1.svg?style=flat\u0026logo=PostgreSQL\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED.svg?style=flat\u0026logo=Docker\u0026logoColor=white)\n![LLaMA 3.2 Powered](https://img.shields.io/badge/LLaMA%203.2-Powered-blueviolet?style=flat)\n\n## Overview\nThe **Mindful Eating Backend** is a FastAPI‑powered service that blends behavioral data science with LLM.  \nIt integrates personality‑driven recommendations via two fine‑tuned **LLama3.2** language models, using **Big Five personality traits** and **mindful‑eating behavior classifications** to deliver daily, personalized tips.\n\nThis repository contains the backend for \"A Personalized Digital Intervention for Promoting Mindful Eating Through Real-time Behavioral Analysis and Adaptive Feedback.\" This project, developed as a capstone project for my Master of Applied Computer Science at Dalhousie University, aims to help users cultivate healthier eating patterns by providing daily, personalized tips.\n\nThe core innovation lies in leveraging Big Five personality traits and user-selected eating behaviors to generate adaptive feedback. I've fine-tuned two Large Language Models (LLMs): one to infer personality traits from user responses and another to generate customized mindful eating tips. The system is designed to move beyond generic advice, offering suggestions that resonate on a personal level.\n\nThe backend is built with **Python, FastAPI, and PostgreSQL**, serving a [React Native Expo mobile application (Mindful Eating Frontend)](https://github.com/samshad/mindful-eating-frontend).\n\n## Project Aim\n\nCurrent nutrition and eating apps often provide generic, one-size-fits-all suggestions, leading to low user engagement and motivation. This project addresses this gap by developing an AI-powered mobile system that:\n\n*   Analyzes users' Big Five personality traits from questionnaires and eating habit descriptions.\n*   Generates daily, behavior-specific tips aligned with the user's dominant Big Five trait and chosen focus areas (e.g., emotional eating, portion control).\n*   Delivers these tips within a mobile application that encourages food logging, goal setting, and user reflection.\n*   Provides a direct chat interface with an LLM for real-time, personalized advice on eating behaviors.\n\n## Features\n\n- **User Goal Management** – create, update, and retrieve daily eating goals.\n- **Personalized Tips** – AI‑generated tips informed by dominant Big5 traits.\n- **Questionnaire Handling** – capture user answers to refine recommendations.\n- **JWT Authentication** – secure access tokens for every request.\n- **SQLAlchemy + PostgreSQL** – robust relational data layer.\n\n## Technologies Used\n\n| Category          | Stack                        |\n|-------------------|------------------------------|\n| Web Framework     | FastAPI                      |\n| ORM \u0026 Migrations  | SQLAlchemy · Alembic         |\n| Data Validation   | Pydantic v2                  |\n| AI \u0026 LLM Serving  | Ollama · Unsloth · LLaMA 3.2 |\n| Containerisation  | Docker · Docker Compose      |\n| Production Server | Gunicorn + UvicornWorkers    |\n\n## AI Models Used\nThis project ships with two fine‑tuned LLMs:\n- **big5‑llama3.2** – predicts a user’s Big Five trait values from free‑text input.\n- **mindful-tips** – returns daily mindful‑eating tips tailored to the dominant trait and the user‑selected eating behavior.\n\n## File Structure\nThe codebase is organized into logical components:\n```\nmindful-eating-backend/\n├── app/\n│   ├── controllers/     # Business logic\n│   ├── models/          # Database models\n│   ├── routes/          # API endpoints\n│   ├── schemas/         # Data validation\n│   ├── services/        # Services layer\n│   └── utils/           # Utility functions\n├── data/                # Datasets for the application\n├── scripts/             # Standalone utility scripts\n├── migrations/          # Alembic migrations\n├── main.py              # Application entry point\n├── docker-compose.yml   # Docker configuration\n└── requirements.txt     # Dependencies\n```\n\n## System Architecture\nFor a complete overview of the data flow, consult the diagrams below:\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/samshad/mindful-eating-backend/refs/heads/master/assets/system-architecture.png\" alt=\"System Architecture\" width=\"600\"/\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eFigure 1: System Architecture Overview\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/samshad/mindful-eating-backend/refs/heads/master/assets/db-schema.png\" alt=\"Database Schema\" width=\"600\"/\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eFigure 2: Database Schema\u003c/em\u003e\n\u003c/p\u003e\n\n\u003c!---\n![System Architecture](https://raw.githubusercontent.com/samshad/mindful-eating-backend/refs/heads/master/assets/system-architecture.png)\n![Database Schema](https://raw.githubusercontent.com/samshad/mindful-eating-backend/refs/heads/master/assets/db-schema.png)\n---\u003e\n\n## Setup and Installation\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/samshad/mindful-eating-backend.git\n   cd mindful-eating-backend\n   ```\n2. Set up a virtual environment:\n   ```bash\n   python3 -m venv venv\n   source venv/bin/activate\n   ```\n3. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n4. Start the development server:\n   ```bash\n   uvicorn app.main:app --reload\n   ```\n\n### Configure environment variables\nCreate a`.env` file in the project root (refer to `.example.env`):\n```env\nDATABASE_URL=[URI to your PostgreSQL database]\nSECRET_KEY=your_jwt_secret\nOLLAMA_BASE_URL=[URL to your Ollama server]\nBIG_FIVE_MODEL=samshad/big5-llama3.2\nTIPS_GENERATOR_MODEL=samshad/mindful-tips\n```\n\n### Database migrations\nRun the following command to apply database migrations:\n```bash\nalembic upgrade head\n```\n\n\n## Running with Docker\n\nThis application can be easily set up and run using Docker, which ensures consistent environments across different development and deployment setups.\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/get-started) installed on your system\n- [Docker Compose](https://docs.docker.com/compose/install/) (usually included with Docker Desktop installations)\n\n### Running the Application with Docker\n\n#### Option 1: Using Docker Compose (Recommended)\n\nThis method sets up the entire application stack with a single command:\n\n1. Clone this repository to your local machine\n2. Navigate to the project directory\n3. Create a `.env` file based on the provided `.example.env` template\n4. Run the application:\n   ```bash\n   docker-compose up -d\n   ```\n5. To stop the application, run:\n   ```bash\n   docker-compose down\n   ```\n\n## API Endpoints\nOutlined below are a few key endpoints:\n- **Authentication routes**: `/auth/*` endpoints for user authentication\n- **Question routes**: `/question/*` endpoints for question-related operations\n- **Behavior routes**: `/behavior/*` endpoints for behavior-related features\n- **Goal routes**: `/goal/*` endpoints for goal management\n- **Tips routes**: `/tips/*` endpoints for retrieving tips\n- **Food update routes**: `/food-update/*` endpoints for food tracking updates\n- **Big Five routes**: `/big-five/*` endpoints related to a \"Big Five\" feature (dominant personality assessment)\n\n## Scripts and Data\nThe `scripts/` directory contains standalone utility scripts for tasks such as:\n- Data preprocessing\n- Model training\n- Model evaluation\n- Maintenance utilities\n\nThe `data/` directory contains datasets used by the application, including:\n- Training data for AI models\n- Reference datasets for behavioral analysis\n- Test datasets for validation\n- Project report\n- Presentation slides\n- Postman collection\n\n## Contribution Guidelines\nContributions are welcome! Please follow these steps:\n1. Fork the repository and create a new branch.\n2. Make your changes and test thoroughly.\n3. Submit a pull request with a clear description of the changes.\n\n## Acknowledgements\n\nThis project was undertaken as a research project for my Master of Applied Computer Science program at Persuasive Computing Lab, Dalhousie University.\n\n**Supervisors:** Dr. Rita Orji \u0026 Dr. Oladapo Oyebode\n\n## Companion Frontend Application\nThis backend serves the **Mindful Eating Frontend**, a mobile application built with React Native and Expo.\n- **Frontend Repository:** [samshad/mindful-eating-frontend](https://github.com/samshad/mindful-eating-frontend)\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0.  \nSee the [LICENSE](LICENSE) file for details.  \n© 2025 Md Samshad Rahman (Persuasive Computing Lab, Dalhousie University)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamshad%2Fmindful-eating-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamshad%2Fmindful-eating-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamshad%2Fmindful-eating-backend/lists"}