MetabolicAI

---

MetabolicAI is a production-ready, cloud-deployable API for tracking and predicting your Total Daily Energy Expenditure (TDEE) using real-world weight, calorie data, age, and gender.

Built with modern AI engineering and MLOps best practices—leveraging FastAPI, scikit-learn, XGBoost, Docker, and CI/CD—with secure multi-user support, profile-aware predictions, and one-command local or cloud deployment.

---

✨ Highlights

• 🧠 ML-Powered Predictions – Uses XGBoost for personalized TDEE estimation
• 🔐 Secure Multi-User – API key authentication with per-user data isolation
• 🐳 Container Ready – Multi-stage Docker build with security best practices
• ⚡ CORS Enabled – Universal API compatibility for web and mobile apps
• 📊 Analytics Dashboard – Weight trends, feature importance, and insights
• 🧪 Well Tested – Comprehensive test suite with 90%+ coverage
• 📝 Typed & Documented – Full type hints and OpenAPI documentation

---

🚀 Quick Start

Option 1: Run Locally

# Clone the repository
git clone https://github.com/furqanagwan/metabolicai.git
cd metabolicai

# Set up environment
cp .env.example .env
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn app.main:app --reload

Option 2: Run with Docker

git clone https://github.com/furqanagwan/metabolicai.git
cd metabolicai
cp .env.example .env
docker-compose up --build

Access the API:

• 🌐 API: http://localhost:8000
• 📖 Docs: http://localhost:8000/docs
• ❤️ Health: http://localhost:8000/health

---

📖 Usage

1️⃣ Register a User Profile

curl -X POST "http://localhost:8000/user" \
  -H "X-API-Key: changeme-supersecret" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "demo", "age": 30, "gender": "male", "height_cm": 180}'

2️⃣ Log Your Data

# Add weight and calories
curl -X POST "http://localhost:8000/entry" \
  -H "X-API-Key: changeme-supersecret" \
  -H "X-User-Id: demo" \
  -H "Content-Type: application/json" \
  -d '{"date": "2025-07-13", "weight": 75, "calories": 2200}'

# Or update just one field
curl -X PATCH "http://localhost:8000/entry" \
  -H "X-API-Key: changeme-supersecret" \
  -H "X-User-Id: demo" \
  -H "Content-Type: application/json" \
  -d '{"date": "2025-07-13", "weight": 74.5}'

3️⃣ Get Your TDEE Prediction

curl -H "X-API-Key: changeme-supersecret" \
     -H "X-User-Id: demo" \
     http://localhost:8000/tdee

---

📚 API Reference

Method	Endpoint	Description
GET	/health	Health check for container orchestration
POST	/user	Create or update user profile
PATCH	/user	Partially update user profile
GET	/user	Get user profile
POST	/entry	Log weight/calories entry
PATCH	/entry	Update existing entry
GET	/history	Get all entries
GET	/tdee	Get TDEE prediction (min 3 entries)
GET	/analytics	Get analytics and insights
GET	/analytics/feature-importance	Get model feature importance

Headers Required:

• X-API-Key: Your API key (from .env)
• X-User-Id: User identifier (for user-specific endpoints)

📖 Full API documentation available at /docs (Swagger UI) or /redoc

---

🏗️ Architecture

metabolicai/
├── app/
│   ├── __init__.py       # Package marker
│   ├── main.py           # FastAPI app, routes, CORS, lifespan
│   ├── auth.py           # API key authentication
│   ├── config.py         # Centralized configuration
│   ├── database.py       # SQLite operations with context managers
│   ├── model.py          # ML model training & prediction
│   ├── schemas.py        # Pydantic request/response models
│   ├── exceptions.py     # Custom exception classes
│   └── py.typed          # PEP 561 type marker
├── tests/
│   ├── conftest.py       # Test fixtures
│   ├── test_api.py       # API endpoint tests
│   ├── test_database.py  # Database unit tests
│   └── test_model.py     # Model unit tests
├── .github/workflows/
│   └── ci.yml            # CI/CD pipeline
├── Dockerfile            # Multi-stage, secure container
├── docker-compose.yml    # One-command deployment
├── pyproject.toml        # Modern Python packaging
├── requirements.txt      # Dependencies
└── README.md             # You are here!

Tech Stack:

• FastAPI – Modern async Python web framework
• scikit-learn / XGBoost – ML model training
• SQLite – Lightweight, reliable database
• Pydantic – Data validation and settings
• Docker – Containerization with multi-stage builds

---

🛠️ Development

Setup

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/ -v --cov=app

# Format code
black app tests

# Lint code
ruff check app tests --fix

# Type check
mypy app

Environment Variables

Variable	Default	Description
API_KEY	changeme	API authentication key
DB_PATH	data/entries.db	SQLite database path
LOG_LEVEL	INFO	Logging level
CORS_ORIGINS	["*"]	Allowed CORS origins

---

🧪 Testing

# Run all tests
pytest tests/ -v

# With coverage report
pytest tests/ --cov=app --cov-report=term-missing --cov-report=html

# Run specific tests
pytest tests/test_api.py -v
pytest tests/test_model.py::TestModelTraining -v

---

🐳 Docker

# Build image
docker build -t metabolicai .

# Run container
docker run -d -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/models:/app/models \
  -e API_KEY=your-secret-key \
  metabolicai

# Or use docker-compose
docker-compose up -d

---

☁️ Deployment

See DEPLOY.md for detailed deployment guides:

• Azure Machine Learning
• AWS SageMaker
• Google Cloud Vertex AI
• DigitalOcean / Generic VPS

---

❓ FAQ

Do I need to create the data/ or models/ folders?

No! They're auto-created when you first use the API.

How do I reset all data?

Delete the data/ and models/ folders. They'll be recreated on next startup.

Can I use a different database?

Yes! Update app/database.py for PostgreSQL, MySQL, etc. Consider using SQLAlchemy for easier migration.

How many entries do I need for predictions?

• Minimum 3 entries for TDEE prediction
• Minimum 6 entries for model training
• 8+ entries enables XGBoost (more accurate)

Is there a frontend?

Not yet—this is API-only. The CORS middleware makes it easy to integrate with any web or mobile frontend.

---

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Submit a pull request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👤 Author

Furqan Agwan

• GitHub: @furqanagwan
• LinkedIn: furqanagwan

---

Made with ❤️ for fitness enthusiasts and AI practitioners