# CalorIA 🍎
A comprehensive full-stack calorie tracking application built with Flask backend, React frontend, MongoDB database, and a custom CLI for easy management. The application is fully containerized with Docker for seamless deployment.
<img width="902" height="476" alt="image" src="https://github.com/user-attachments/assets/cb519f18-3b48-4117-8ea6-9e4c7fadd9f6" />
## ✨ Features
- **🏗️ Full-Stack Architecture**: Flask REST API backend with React frontend
- **🗄️ MongoDB Database**: NoSQL database for flexible data storage
- **⚡ Custom CLI Tool**: Command-line interface for managing the application
- **🐳 Docker Support**: Fully containerized with docker-compose
- **👤 User Management**: User registration and profile management
- **🍽️ Meal Tracking**: Log and track daily meals and nutrition
- **❤️ Health Monitoring**: Track weight and water intake
- **💻 Modern UI**: Responsive React frontend with component-based architecture
- **🔗 REST API**: Comprehensive API endpoints for all features
- **🌱 Database Seeding**: Built-in script for populating test data
- **🧪 AI-Powered Research**: Intelligent ingredient and recipe discovery using OpenAI or Ollama
- **📝 Letter-Based Research**: Systematic research organized by alphabet for comprehensive coverage
## 📁 Project Structure
```
CalorIA/
├── CalorIA/
│ ├── __init__.py # Python package initialization
│ ├── cli.py # Custom CLI commands
│ ├── types.py # Type definitions
│ ├── research/ # AI-powered research system
│ │ ├── __init__.py # Research package initialization
│ │ ├── tools.py # Base research classes and utilities
│ │ ├── ingredients.py # Ingredient research functionality
│ │ └── recipes.py # Recipe research functionality
│ ├── backend/ # Flask backend application
│ │ ├── app.py # Main Flask application
│ │ ├── requirements.txt # Python dependencies
│ │ └── package-lock.json
│ ├── frontend/ # React frontend application
│ │ ├── src/ # React source code
│ │ ├── public/ # Public assets
│ │ ├── package.json # Node.js dependencies
│ │ └── build/ # Production build (generated)
│ └── mixins/ # Shared modules and routes
│ ├── modules/ # Business logic modules
│ │ ├── activities.py # Activity tracking functionality
│ │ ├── ingredients.py # Ingredient management
│ │ ├── meals.py # Meal tracking and management
│ │ ├── recipes.py # Recipe management
│ │ ├── users.py # User management
│ │ ├── water.py # Water intake tracking
│ │ └── weight.py # Weight tracking
│ ├── routes/ # API route handlers
│ │ ├── __init__.py
│ │ ├── activity_routes.py # Activity endpoints
│ │ ├── auth_routes.py # Authentication endpoints
│ │ ├── dashboard_routes.py # Dashboard data endpoints
│ │ ├── health_routes.py # Health monitoring endpoints
│ │ ├── ingredient_routes.py # Ingredient CRUD endpoints
│ │ ├── meal_routes.py # Meal tracking endpoints
│ │ ├── recipe_routes.py # Recipe management endpoints
│ │ ├── user_routes.py # User management endpoints
│ │ ├── water_routes.py # Water intake endpoints
│ │ └── weight_routes.py # Weight tracking endpoints
│ ├── jwt_utils.py # JWT utilities
│ ├── mongo.py # MongoDB connection utilities
│ └── tools.py # General utilities
├── docker-compose.yml # Docker composition configuration
├── Dockerfile # Docker image configuration
├── setup.py # Python package setup
├── .env.copy # Environment variables template
└── README.md # This file
```
## 🚀 Local Development Setup
### Prerequisites
Before running the application locally, ensure you have the following installed:
- **Python 3.7+**: Download from [python.org](https://www.python.org/downloads/)
- **Node.js 16+**: Download from [nodejs.org](https://nodejs.org/downloads/)
- **MongoDB**: Download from [mongodb.com](https://www.mongodb.com/try/download/community)
### Environment Configuration
1. Copy the environment template and configure your settings:
```bash
cp .env.copy .env
```
2. Edit the `.env` file with your configuration:
```
MONGODB_URI=mongodb://localhost:27017/caloria
FLASK_DEBUG=1
SECRET_KEY=your-secret-key-here
# AI Research Configuration (optional)
AI_PROVIDER=openai # or 'ollama'
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama2
```
### Installation Steps
1. **Clone the repository**:
```bash
git clone <repository-url>
cd CalorIA
```
2. **Install Python dependencies**:
```bash
pip install -r CalorIA/backend/requirements.txt
```
3. **Install Node.js dependencies**:
```bash
cd CalorIA/frontend
npm install
cd ../..
```
4. **Install the CLI tool**:
```bash
pip install -e .
```
5. **Start MongoDB** (if running locally):
```bash
mongod
```
6. **Seed the database** (optional):
```bash
caloria seed
```
## 💻 CLI Usage
The `caloria` CLI provides several commands to manage the application:
### Available Commands
- **`caloria backend`** - Start the Flask backend server
```bash
caloria backend --host 127.0.0.1 --port 4032 --debug
```
- `--host`: Host to bind to (default: 127.0.0.1)
- `--port`: Port to bind to (default: 4032)
- `--debug`: Run in debug mode
- **`caloria frontend`** - Start the React development server
```bash
caloria frontend --port 3000
```
- `--port`: Port for development server (default: 3000)
- **`caloria build`** - Build the React frontend for production
```bash
caloria build --output-dir build
```
- `--output-dir`: Output directory for build (default: build)
- **`caloria seed`** - Seed the database with sample data
```bash
caloria seed
```
- **`caloria unseed`** - Remove all system-generated sample data from the database
```bash
caloria unseed --confirm
```
- `--confirm`: Confirm deletion without prompting
- **`caloria research-ingredients`** - Research and add missing ingredients using AI
```bash
caloria research-ingredients --category Vegetables --letters A,B,C --max-ingredients 10
```
- `--category`: Specific category to research (Vegetables, Proteins, Fruits, etc.)
- `--letters`: Comma-separated letters to research (e.g., "A,B,C")
- `--max-ingredients`: Maximum number of ingredients to add
- `--dry-run`: Show what would be added without actually adding
- **`caloria research-recipes`** - Research and add missing recipes using AI
```bash
caloria research-recipes --category breakfast --letters A,B,C --max-recipes 5
```
- `--category`: Specific category to research (breakfast, lunch, dinner, etc.)
- `--letters`: Comma-separated letters to research (e.g., "A,B,C")
- `--max-recipes`: Maximum number of recipes to add
- `--dry-run`: Show what would be added without actually adding
### Example Usage
1. **Start the full application** (recommended for development):
```bash
# Terminal 1: Start the backend (includes building frontend)
caloria backend --debug
# Terminal 2: Start the frontend dev server (for hot reloading)
caloria frontend
```
2. **Production build**:
```bash
caloria build
caloria backend --host 0.0.0.0 --port 4032
```
3. **AI Research Examples**:
```bash
# Research vegetables starting with A, B, C
caloria research-ingredients --category Vegetables --letters A,B,C --max-ingredients 15
# Research breakfast recipes (dry run)
caloria research-recipes --category breakfast --dry-run
# Research proteins systematically
caloria research-ingredients --category Proteins --max-ingredients 20
```
## 🐳 Docker Usage
### Quick Start with Docker
1. **Build and run the entire application**:
```bash
docker-compose up --build
```
2. **Run in detached mode**:
```bash
docker-compose up -d --build
```
3. **Stop the application**:
```bash
docker-compose down
```
4. **View logs**:
```bash
docker-compose logs -f
```
### Docker Services
The docker-compose configuration includes:
- **app**: The main CalorIA application (Flask + React)
- Exposed on port 4032
- Automatically builds frontend and runs backend
- **mongo**: MongoDB database
- Exposed on port 27017
- Data persisted in `mongo-data` volume
## 🧪 AI-Powered Research
CalorIA includes an intelligent AI-powered research system that can discover and add missing ingredients and recipes to your database. The system supports both OpenAI and Ollama as AI providers.
### Research Features
- **Letter-Based Research**: Systematically research ingredients/recipes by alphabet for comprehensive coverage
- **Category-Specific**: Research specific categories like Vegetables, Proteins, Fruits, etc.
- **Duplicate Prevention**: Automatically checks for existing items before adding
- **Dry Run Mode**: Test research without modifying the database
- **Batch Processing**: Process multiple items efficiently with progress tracking
### AI Providers
#### OpenAI (Default)
- Requires API key
- Supports GPT-3.5-turbo and GPT-4 models
- Higher quality responses
- Requires internet connection
#### Ollama (Local)
- Runs locally on your machine
- Supports various open-source models (Llama, Mistral, etc.)
- No API costs
- Works offline
### Research Categories
**Ingredients:**
- Vegetables, Fruits, Proteins, Grains & Starches
- Dairy, Oils & Fats, Nuts & Seeds
- Condiments & Sauces, Sweeteners, Spices
- Beverages, Supplements, Baking & Flours
**Recipes:**
- Breakfast, Lunch, Dinner, Snacks
- Desserts, Beverages, Appetizers
- Soups, Salads, Main Courses, Side Dishes
### Usage Examples
```bash
# Research vegetables starting with specific letters
caloria research-ingredients --category Vegetables --letters A,B,C,D,E
# Research breakfast recipes (systematic approach)
caloria research-recipes --category breakfast --max-recipes 10
# Dry run to see what would be added
caloria research-ingredients --category Proteins --dry-run
# Research with custom limits
caloria research-recipes --category dinner --max-recipes 5 --letters M,N,O
```
### Setting Up AI Providers
#### For OpenAI:
1. Get an API key from [OpenAI](https://platform.openai.com/api-keys)
2. Add to your `.env` file:
```
AI_PROVIDER=openai
OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4
```
#### For Ollama:
1. Install Ollama from [ollama.ai](https://ollama.ai)
2. Pull a model: `ollama pull llama2`
3. Add to your `.env` file:
```
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama2
```
## 🌐 API Endpoints
The CalorIA REST API provides the following endpoint categories:
### Authentication
- **POST** `/api/auth/login` - User login
- **POST** `/api/auth/register` - User registration
- **POST** `/api/auth/logout` - User logout
### User Management
- **GET** `/api/user/<user_id>` - Get user information
- **POST** `/api/user` - Create new user
- **PUT** `/api/user/<user_id>` - Update user information
- **DELETE** `/api/user/<user_id>` - Delete user
### Ingredients
- **GET** `/api/ingredients` - Get all ingredients (with pagination and search)
- Query parameters: `page`, `limit`, `search`, `is_system`
- **GET** `/api/ingredients/<ingredient_id>` - Get specific ingredient
- **POST** `/api/ingredients` - Create new ingredient
- **PUT** `/api/ingredients/<ingredient_id>` - Update ingredient
- **DELETE** `/api/ingredients/<ingredient_id>` - Delete ingredient
### Recipes
- **GET** `/api/recipes` - Get all recipes (with pagination and search)
- **GET** `/api/recipes/<recipe_id>` - Get specific recipe
- **POST** `/api/recipes` - Create new recipe
- **PUT** `/api/recipes/<recipe_id>` - Update recipe
- **DELETE** `/api/recipes/<recipe_id>` - Delete recipe
### Meal Tracking
- **GET** `/api/meals/<user_id>` - Get user's meals
- **POST** `/api/meals` - Log a new meal
- **PUT** `/api/meals/<meal_id>` - Update meal information
- **DELETE** `/api/meals/<meal_id>` - Delete meal
### Health Monitoring
- **GET** `/api/health/<user_id>` - Get health status
- **POST** `/api/health` - Update health metrics
### Weight Tracking
- **GET** `/api/weight/<user_id>` - Get weight history
- **POST** `/api/weight` - Log weight entry
- **PUT** `/api/weight/<entry_id>` - Update weight entry
- **DELETE** `/api/weight/<entry_id>` - Delete weight entry
### Water Intake
- **GET** `/api/water/<user_id>` - Get water intake history
- **POST** `/api/water` - Log water intake
- **PUT** `/api/water/<entry_id>` - Update water entry
- **DELETE** `/api/water/<entry_id>` - Delete water entry
### Dashboard
- **GET** `/api/dashboard/<user_id>` - Get user dashboard data
## Development
### Project Architecture
- **Backend**: Flask application with Blueprint-based routing
- **Frontend**: React application with component-based architecture
- **Database**: MongoDB with PyMongo driver
- **CLI**: Click-based command-line interface
- **Containerization**: Docker with multi-stage builds
### Key Technologies
- **Backend**: Flask, PyMongo, Click
- **Frontend**: React, Node.js, npm
- **Database**: MongoDB
- **DevOps**: Docker, docker-compose
- **Python**: 3.7+ compatible
### Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and test them
4. Commit your changes: `git commit -m 'Add feature'`
5. Push to the branch: `git push origin feature-name`
6. Submit a pull request
### Screenshots
<img width="1791" height="945" alt="Screenshot 2025-08-30 033434" src="https://github.com/user-attachments/assets/37013304-2d84-44fb-b7a7-054099ce9f9d" />
<img width="1791" height="951" alt="Screenshot 2025-08-30 033509" src="https://github.com/user-attachments/assets/644c7e46-c6da-4920-8a3f-77c01a796428" />
<img width="1791" height="476" alt="image" src="https://github.com/user-attachments/assets/bdf4a36e-5f36-4004-bdea-52643aba9eb7" />
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/jhd3197/CalorIA",
"name": "caloria",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "caloria nutrition calories tracking flask react mongodb ai",
"author": "Juan Denis",
"author_email": "juan@vene.co",
"download_url": "https://files.pythonhosted.org/packages/52/26/d6352997b9a01da77a24cfde8b6d341065492ba0fbde48ed759586744a78/caloria-1.0.0.tar.gz",
"platform": null,
"description": "# CalorIA \ud83c\udf4e\r\n\r\nA comprehensive full-stack calorie tracking application built with Flask backend, React frontend, MongoDB database, and a custom CLI for easy management. The application is fully containerized with Docker for seamless deployment.\r\n<img width=\"902\" height=\"476\" alt=\"image\" src=\"https://github.com/user-attachments/assets/cb519f18-3b48-4117-8ea6-9e4c7fadd9f6\" />\r\n\r\n## \u2728 Features\r\n\r\n- **\ud83c\udfd7\ufe0f Full-Stack Architecture**: Flask REST API backend with React frontend\r\n- **\ud83d\uddc4\ufe0f MongoDB Database**: NoSQL database for flexible data storage\r\n- **\u26a1 Custom CLI Tool**: Command-line interface for managing the application\r\n- **\ud83d\udc33 Docker Support**: Fully containerized with docker-compose\r\n- **\ud83d\udc64 User Management**: User registration and profile management\r\n- **\ud83c\udf7d\ufe0f Meal Tracking**: Log and track daily meals and nutrition\r\n- **\u2764\ufe0f Health Monitoring**: Track weight and water intake\r\n- **\ud83d\udcbb Modern UI**: Responsive React frontend with component-based architecture\r\n- **\ud83d\udd17 REST API**: Comprehensive API endpoints for all features\r\n- **\ud83c\udf31 Database Seeding**: Built-in script for populating test data\r\n- **\ud83e\uddea AI-Powered Research**: Intelligent ingredient and recipe discovery using OpenAI or Ollama\r\n- **\ud83d\udcdd Letter-Based Research**: Systematic research organized by alphabet for comprehensive coverage\r\n\r\n## \ud83d\udcc1 Project Structure\r\n\r\n```\r\nCalorIA/\r\n\u251c\u2500\u2500 CalorIA/\r\n\u2502 \u251c\u2500\u2500 __init__.py # Python package initialization\r\n\u2502 \u251c\u2500\u2500 cli.py # Custom CLI commands\r\n\u2502 \u251c\u2500\u2500 types.py # Type definitions\r\n\u2502 \u251c\u2500\u2500 research/ # AI-powered research system\r\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Research package initialization\r\n\u2502 \u2502 \u251c\u2500\u2500 tools.py # Base research classes and utilities\r\n\u2502 \u2502 \u251c\u2500\u2500 ingredients.py # Ingredient research functionality\r\n\u2502 \u2502 \u2514\u2500\u2500 recipes.py # Recipe research functionality\r\n\u2502 \u251c\u2500\u2500 backend/ # Flask backend application\r\n\u2502 \u2502 \u251c\u2500\u2500 app.py # Main Flask application\r\n\u2502 \u2502 \u251c\u2500\u2500 requirements.txt # Python dependencies\r\n\u2502 \u2502 \u2514\u2500\u2500 package-lock.json\r\n\u2502 \u251c\u2500\u2500 frontend/ # React frontend application\r\n\u2502 \u2502 \u251c\u2500\u2500 src/ # React source code\r\n\u2502 \u2502 \u251c\u2500\u2500 public/ # Public assets\r\n\u2502 \u2502 \u251c\u2500\u2500 package.json # Node.js dependencies\r\n\u2502 \u2502 \u2514\u2500\u2500 build/ # Production build (generated)\r\n\u2502 \u2514\u2500\u2500 mixins/ # Shared modules and routes\r\n\u2502 \u251c\u2500\u2500 modules/ # Business logic modules\r\n\u2502 \u2502 \u251c\u2500\u2500 activities.py # Activity tracking functionality\r\n\u2502 \u2502 \u251c\u2500\u2500 ingredients.py # Ingredient management\r\n\u2502 \u2502 \u251c\u2500\u2500 meals.py # Meal tracking and management\r\n\u2502 \u2502 \u251c\u2500\u2500 recipes.py # Recipe management\r\n\u2502 \u2502 \u251c\u2500\u2500 users.py # User management\r\n\u2502 \u2502 \u251c\u2500\u2500 water.py # Water intake tracking\r\n\u2502 \u2502 \u2514\u2500\u2500 weight.py # Weight tracking\r\n\u2502 \u251c\u2500\u2500 routes/ # API route handlers\r\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2502 \u251c\u2500\u2500 activity_routes.py # Activity endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 auth_routes.py # Authentication endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 dashboard_routes.py # Dashboard data endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 health_routes.py # Health monitoring endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 ingredient_routes.py # Ingredient CRUD endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 meal_routes.py # Meal tracking endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 recipe_routes.py # Recipe management endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 user_routes.py # User management endpoints\r\n\u2502 \u2502 \u251c\u2500\u2500 water_routes.py # Water intake endpoints\r\n\u2502 \u2502 \u2514\u2500\u2500 weight_routes.py # Weight tracking endpoints\r\n\u2502 \u251c\u2500\u2500 jwt_utils.py # JWT utilities\r\n\u2502 \u251c\u2500\u2500 mongo.py # MongoDB connection utilities\r\n\u2502 \u2514\u2500\u2500 tools.py # General utilities\r\n\u251c\u2500\u2500 docker-compose.yml # Docker composition configuration\r\n\u251c\u2500\u2500 Dockerfile # Docker image configuration\r\n\u251c\u2500\u2500 setup.py # Python package setup\r\n\u251c\u2500\u2500 .env.copy # Environment variables template\r\n\u2514\u2500\u2500 README.md # This file\r\n```\r\n\r\n## \ud83d\ude80 Local Development Setup\r\n\r\n### Prerequisites\r\n\r\nBefore running the application locally, ensure you have the following installed:\r\n\r\n- **Python 3.7+**: Download from [python.org](https://www.python.org/downloads/)\r\n- **Node.js 16+**: Download from [nodejs.org](https://nodejs.org/downloads/)\r\n- **MongoDB**: Download from [mongodb.com](https://www.mongodb.com/try/download/community)\r\n\r\n### Environment Configuration\r\n\r\n1. Copy the environment template and configure your settings:\r\n ```bash\r\n cp .env.copy .env\r\n ```\r\n\r\n2. Edit the `.env` file with your configuration:\r\n ```\r\n MONGODB_URI=mongodb://localhost:27017/caloria\r\n FLASK_DEBUG=1\r\n SECRET_KEY=your-secret-key-here\r\n\r\n # AI Research Configuration (optional)\r\n AI_PROVIDER=openai # or 'ollama'\r\n OPENAI_API_KEY=your_openai_api_key_here\r\n OPENAI_MODEL=gpt-4\r\n OLLAMA_BASE_URL=http://localhost:11434\r\n OLLAMA_MODEL=llama2\r\n ```\r\n\r\n### Installation Steps\r\n\r\n1. **Clone the repository**:\r\n ```bash\r\n git clone <repository-url>\r\n cd CalorIA\r\n ```\r\n\r\n2. **Install Python dependencies**:\r\n ```bash\r\n pip install -r CalorIA/backend/requirements.txt\r\n ```\r\n\r\n3. **Install Node.js dependencies**:\r\n ```bash\r\n cd CalorIA/frontend\r\n npm install\r\n cd ../..\r\n ```\r\n\r\n4. **Install the CLI tool**:\r\n ```bash\r\n pip install -e .\r\n ```\r\n\r\n5. **Start MongoDB** (if running locally):\r\n ```bash\r\n mongod\r\n ```\r\n\r\n6. **Seed the database** (optional):\r\n ```bash\r\n caloria seed\r\n ```\r\n\r\n## \ud83d\udcbb CLI Usage\r\n\r\nThe `caloria` CLI provides several commands to manage the application:\r\n\r\n### Available Commands\r\n\r\n- **`caloria backend`** - Start the Flask backend server\r\n ```bash\r\n caloria backend --host 127.0.0.1 --port 4032 --debug\r\n ```\r\n - `--host`: Host to bind to (default: 127.0.0.1)\r\n - `--port`: Port to bind to (default: 4032)\r\n - `--debug`: Run in debug mode\r\n\r\n- **`caloria frontend`** - Start the React development server\r\n ```bash\r\n caloria frontend --port 3000\r\n ```\r\n - `--port`: Port for development server (default: 3000)\r\n\r\n- **`caloria build`** - Build the React frontend for production\r\n ```bash\r\n caloria build --output-dir build\r\n ```\r\n - `--output-dir`: Output directory for build (default: build)\r\n\r\n- **`caloria seed`** - Seed the database with sample data\r\n ```bash\r\n caloria seed\r\n ```\r\n\r\n- **`caloria unseed`** - Remove all system-generated sample data from the database\r\n ```bash\r\n caloria unseed --confirm\r\n ```\r\n - `--confirm`: Confirm deletion without prompting\r\n\r\n- **`caloria research-ingredients`** - Research and add missing ingredients using AI\r\n ```bash\r\n caloria research-ingredients --category Vegetables --letters A,B,C --max-ingredients 10\r\n ```\r\n - `--category`: Specific category to research (Vegetables, Proteins, Fruits, etc.)\r\n - `--letters`: Comma-separated letters to research (e.g., \"A,B,C\")\r\n - `--max-ingredients`: Maximum number of ingredients to add\r\n - `--dry-run`: Show what would be added without actually adding\r\n\r\n- **`caloria research-recipes`** - Research and add missing recipes using AI\r\n ```bash\r\n caloria research-recipes --category breakfast --letters A,B,C --max-recipes 5\r\n ```\r\n - `--category`: Specific category to research (breakfast, lunch, dinner, etc.)\r\n - `--letters`: Comma-separated letters to research (e.g., \"A,B,C\")\r\n - `--max-recipes`: Maximum number of recipes to add\r\n - `--dry-run`: Show what would be added without actually adding\r\n\r\n### Example Usage\r\n\r\n1. **Start the full application** (recommended for development):\r\n ```bash\r\n # Terminal 1: Start the backend (includes building frontend)\r\n caloria backend --debug\r\n \r\n # Terminal 2: Start the frontend dev server (for hot reloading)\r\n caloria frontend\r\n ```\r\n\r\n2. **Production build**:\r\n ```bash\r\n caloria build\r\n caloria backend --host 0.0.0.0 --port 4032\r\n ```\r\n\r\n3. **AI Research Examples**:\r\n ```bash\r\n # Research vegetables starting with A, B, C\r\n caloria research-ingredients --category Vegetables --letters A,B,C --max-ingredients 15\r\n\r\n # Research breakfast recipes (dry run)\r\n caloria research-recipes --category breakfast --dry-run\r\n\r\n # Research proteins systematically\r\n caloria research-ingredients --category Proteins --max-ingredients 20\r\n ```\r\n\r\n## \ud83d\udc33 Docker Usage\r\n\r\n### Quick Start with Docker\r\n\r\n1. **Build and run the entire application**:\r\n ```bash\r\n docker-compose up --build\r\n ```\r\n\r\n2. **Run in detached mode**:\r\n ```bash\r\n docker-compose up -d --build\r\n ```\r\n\r\n3. **Stop the application**:\r\n ```bash\r\n docker-compose down\r\n ```\r\n\r\n4. **View logs**:\r\n ```bash\r\n docker-compose logs -f\r\n ```\r\n\r\n### Docker Services\r\n\r\nThe docker-compose configuration includes:\r\n\r\n- **app**: The main CalorIA application (Flask + React)\r\n - Exposed on port 4032\r\n - Automatically builds frontend and runs backend\r\n- **mongo**: MongoDB database\r\n - Exposed on port 27017\r\n - Data persisted in `mongo-data` volume\r\n\r\n## \ud83e\uddea AI-Powered Research\r\n\r\nCalorIA includes an intelligent AI-powered research system that can discover and add missing ingredients and recipes to your database. The system supports both OpenAI and Ollama as AI providers.\r\n\r\n### Research Features\r\n\r\n- **Letter-Based Research**: Systematically research ingredients/recipes by alphabet for comprehensive coverage\r\n- **Category-Specific**: Research specific categories like Vegetables, Proteins, Fruits, etc.\r\n- **Duplicate Prevention**: Automatically checks for existing items before adding\r\n- **Dry Run Mode**: Test research without modifying the database\r\n- **Batch Processing**: Process multiple items efficiently with progress tracking\r\n\r\n### AI Providers\r\n\r\n#### OpenAI (Default)\r\n- Requires API key\r\n- Supports GPT-3.5-turbo and GPT-4 models\r\n- Higher quality responses\r\n- Requires internet connection\r\n\r\n#### Ollama (Local)\r\n- Runs locally on your machine\r\n- Supports various open-source models (Llama, Mistral, etc.)\r\n- No API costs\r\n- Works offline\r\n\r\n### Research Categories\r\n\r\n**Ingredients:**\r\n- Vegetables, Fruits, Proteins, Grains & Starches\r\n- Dairy, Oils & Fats, Nuts & Seeds\r\n- Condiments & Sauces, Sweeteners, Spices\r\n- Beverages, Supplements, Baking & Flours\r\n\r\n**Recipes:**\r\n- Breakfast, Lunch, Dinner, Snacks\r\n- Desserts, Beverages, Appetizers\r\n- Soups, Salads, Main Courses, Side Dishes\r\n\r\n### Usage Examples\r\n\r\n```bash\r\n# Research vegetables starting with specific letters\r\ncaloria research-ingredients --category Vegetables --letters A,B,C,D,E\r\n\r\n# Research breakfast recipes (systematic approach)\r\ncaloria research-recipes --category breakfast --max-recipes 10\r\n\r\n# Dry run to see what would be added\r\ncaloria research-ingredients --category Proteins --dry-run\r\n\r\n# Research with custom limits\r\ncaloria research-recipes --category dinner --max-recipes 5 --letters M,N,O\r\n```\r\n\r\n### Setting Up AI Providers\r\n\r\n#### For OpenAI:\r\n1. Get an API key from [OpenAI](https://platform.openai.com/api-keys)\r\n2. Add to your `.env` file:\r\n ```\r\n AI_PROVIDER=openai\r\n OPENAI_API_KEY=your_api_key_here\r\n OPENAI_MODEL=gpt-4\r\n ```\r\n\r\n#### For Ollama:\r\n1. Install Ollama from [ollama.ai](https://ollama.ai)\r\n2. Pull a model: `ollama pull llama2`\r\n3. Add to your `.env` file:\r\n ```\r\n AI_PROVIDER=ollama\r\n OLLAMA_BASE_URL=http://localhost:11434\r\n OLLAMA_MODEL=llama2\r\n ```\r\n\r\n## \ud83c\udf10 API Endpoints\r\n\r\nThe CalorIA REST API provides the following endpoint categories:\r\n\r\n### Authentication\r\n- **POST** `/api/auth/login` - User login\r\n- **POST** `/api/auth/register` - User registration\r\n- **POST** `/api/auth/logout` - User logout\r\n\r\n### User Management\r\n- **GET** `/api/user/<user_id>` - Get user information\r\n- **POST** `/api/user` - Create new user\r\n- **PUT** `/api/user/<user_id>` - Update user information\r\n- **DELETE** `/api/user/<user_id>` - Delete user\r\n\r\n### Ingredients\r\n- **GET** `/api/ingredients` - Get all ingredients (with pagination and search)\r\n - Query parameters: `page`, `limit`, `search`, `is_system`\r\n- **GET** `/api/ingredients/<ingredient_id>` - Get specific ingredient\r\n- **POST** `/api/ingredients` - Create new ingredient\r\n- **PUT** `/api/ingredients/<ingredient_id>` - Update ingredient\r\n- **DELETE** `/api/ingredients/<ingredient_id>` - Delete ingredient\r\n\r\n### Recipes\r\n- **GET** `/api/recipes` - Get all recipes (with pagination and search)\r\n- **GET** `/api/recipes/<recipe_id>` - Get specific recipe\r\n- **POST** `/api/recipes` - Create new recipe\r\n- **PUT** `/api/recipes/<recipe_id>` - Update recipe\r\n- **DELETE** `/api/recipes/<recipe_id>` - Delete recipe\r\n\r\n### Meal Tracking\r\n- **GET** `/api/meals/<user_id>` - Get user's meals\r\n- **POST** `/api/meals` - Log a new meal\r\n- **PUT** `/api/meals/<meal_id>` - Update meal information\r\n- **DELETE** `/api/meals/<meal_id>` - Delete meal\r\n\r\n### Health Monitoring\r\n- **GET** `/api/health/<user_id>` - Get health status\r\n- **POST** `/api/health` - Update health metrics\r\n\r\n### Weight Tracking\r\n- **GET** `/api/weight/<user_id>` - Get weight history\r\n- **POST** `/api/weight` - Log weight entry\r\n- **PUT** `/api/weight/<entry_id>` - Update weight entry\r\n- **DELETE** `/api/weight/<entry_id>` - Delete weight entry\r\n\r\n### Water Intake\r\n- **GET** `/api/water/<user_id>` - Get water intake history\r\n- **POST** `/api/water` - Log water intake\r\n- **PUT** `/api/water/<entry_id>` - Update water entry\r\n- **DELETE** `/api/water/<entry_id>` - Delete water entry\r\n\r\n### Dashboard\r\n- **GET** `/api/dashboard/<user_id>` - Get user dashboard data\r\n\r\n## Development\r\n\r\n### Project Architecture\r\n\r\n- **Backend**: Flask application with Blueprint-based routing\r\n- **Frontend**: React application with component-based architecture\r\n- **Database**: MongoDB with PyMongo driver\r\n- **CLI**: Click-based command-line interface\r\n- **Containerization**: Docker with multi-stage builds\r\n\r\n### Key Technologies\r\n\r\n- **Backend**: Flask, PyMongo, Click\r\n- **Frontend**: React, Node.js, npm\r\n- **Database**: MongoDB\r\n- **DevOps**: Docker, docker-compose\r\n- **Python**: 3.7+ compatible\r\n\r\n### Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature-name`\r\n3. Make your changes and test them\r\n4. Commit your changes: `git commit -m 'Add feature'`\r\n5. Push to the branch: `git push origin feature-name`\r\n6. Submit a pull request\r\n\r\n### Screenshots\r\n<img width=\"1791\" height=\"945\" alt=\"Screenshot 2025-08-30 033434\" src=\"https://github.com/user-attachments/assets/37013304-2d84-44fb-b7a7-054099ce9f9d\" />\r\n<img width=\"1791\" height=\"951\" alt=\"Screenshot 2025-08-30 033509\" src=\"https://github.com/user-attachments/assets/644c7e46-c6da-4920-8a3f-77c01a796428\" />\r\n<img width=\"1791\" height=\"476\" alt=\"image\" src=\"https://github.com/user-attachments/assets/bdf4a36e-5f36-4004-bdea-52643aba9eb7\" />\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive full-stack calorie tracking application with Flask backend, React frontend, and AI-powered features",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/CalorIA/issues",
"Documentation": "https://github.com/yourusername/CalorIA#readme",
"Homepage": "https://github.com/jhd3197/CalorIA",
"Source": "https://github.com/yourusername/CalorIA"
},
"split_keywords": [
"caloria",
"nutrition",
"calories",
"tracking",
"flask",
"react",
"mongodb",
"ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8212c2b6e08ebf4c5e549cecacf70cd0f61a773eb9de901f7a8a12702d28010d",
"md5": "2a86f26114f7e070ee8de7ddd2e0cf1a",
"sha256": "b5a5e6c930faef65b9c61cbb707786d1917a5a31f0c692b543fba454060d35b0"
},
"downloads": -1,
"filename": "caloria-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a86f26114f7e070ee8de7ddd2e0cf1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 116610,
"upload_time": "2025-08-30T07:58:46",
"upload_time_iso_8601": "2025-08-30T07:58:46.489622Z",
"url": "https://files.pythonhosted.org/packages/82/12/c2b6e08ebf4c5e549cecacf70cd0f61a773eb9de901f7a8a12702d28010d/caloria-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5226d6352997b9a01da77a24cfde8b6d341065492ba0fbde48ed759586744a78",
"md5": "378bd96dac416021f12eb1b0cfca68dd",
"sha256": "84bd7d5f92e419141706b65c2590593f32a86f2e76af1d0ff6a0af486f359b5d"
},
"downloads": -1,
"filename": "caloria-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "378bd96dac416021f12eb1b0cfca68dd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 88072,
"upload_time": "2025-08-30T07:58:48",
"upload_time_iso_8601": "2025-08-30T07:58:48.193179Z",
"url": "https://files.pythonhosted.org/packages/52/26/d6352997b9a01da77a24cfde8b6d341065492ba0fbde48ed759586744a78/caloria-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 07:58:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jhd3197",
"github_project": "CalorIA",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "caloria"
}
JSON
