Cal AI

AI-powered meal tracking and nutrition analysis app with GPT-4o vision.

Features

🔍 Meal Analysis

• Analyze meal images to estimate calories and nutritional content
• Multi-language support (English and Turkish)
• Clarification questions for uncertain food items
• Macro breakdown (Protein, Carbs, Fat)

👤 User Management

• JWT-based authentication
• User registration and login
• Customizable nutritional goals
• Profile management

📊 Food Logging

• Save analyzed meals to your food diary
• Track meals by date and type (breakfast, lunch, dinner, snack)
• View historical food logs
• Delete entries

📈 Dashboard & Analytics

• Today's nutritional summary
• Weekly statistics
• Monthly progress tracking
• Progress towards calorie and macro goals
• Meal frequency analysis

💾 Data Persistence

• PostgreSQL database
• Local image storage
• Secure password hashing

Quick Start

Automated Setup

# Run the setup script
./scripts/setup_dev.sh

Manual Setup

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

# 2. Start PostgreSQL
docker-compose up -d

# 3. Setup environment
cp env.example .env
# Edit .env and set OPENAI_API_KEY and JWT_SECRET_KEY

# 4. Run migrations
alembic upgrade head

# 5. Start server
uvicorn cal_ai.main:app --reload

See SETUP_GUIDE.md for detailed instructions.

API Documentation

Once running, visit:

• Interactive Docs: http://localhost:8000/docs
• Alternative Docs: http://localhost:8000/redoc

API Overview

Authentication

• POST /v1/auth/register - Create account
• POST /v1/auth/login - Login
• POST /v1/auth/refresh - Refresh token
• POST /v1/auth/logout - Logout
• GET /v1/auth/me - Get current user

User Profile

• GET /v1/users/me/profile - Get profile
• PATCH /v1/users/me/goals - Set calorie/macro goals

Meal Analysis

• POST /v1/analyze - Analyze meal image
• POST /v1/analyze/{id}/clarify - Answer questions

Food Logs

• POST /v1/food-logs - Save meal
• GET /v1/food-logs - Get history

Dashboard

• GET /v1/dashboard/today - Today's summary
• GET /v1/dashboard/week - Weekly stats

Configuration

Required environment variables:

• OPENAI_API_KEY - Your OpenAI API key
• JWT_SECRET_KEY - Secret for JWT tokens (generate with: python -c "import secrets; print(secrets.token_urlsafe(32))")
• DATABASE_URL - PostgreSQL connection string

See env.example for all configuration options.

Mobile App Support

The API is designed to work with mobile apps. See docs/FRONTEND_INTEGRATION.md for complete integration guide.

Key flows:

1. Registration/Login → Get JWT tokens
2. Set Goals → Define calorie and macro targets
3. Analyze Meal → Take photo, get nutritional info
4. Save to Log → Add to food diary
5. View Dashboard → Track progress

The frontend guide includes:

• Complete API reference with examples
• TypeScript data models
• Screen-by-screen integration guide
• React Native code examples
• Authentication & error handling
• Best practices for offline support, caching, and image optimization

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=cal_ai

# Test specific module
pytest tests/test_analyzer.py

Database Management

# Create migration after model changes
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

Documentation

For Backend Developers

• SETUP_GUIDE.md - Complete setup instructions
• MIGRATION_SUMMARY.md - What's new in v0.2.0
• docs/DATABASE_SETUP.md - Database management
• docs/ARCHITECTURE.md - System architecture

For Frontend Developers

• docs/FRONTEND_INTEGRATION.md - Complete mobile app integration guide with examples

Technology Stack

• Backend: FastAPI, Python 3.11+
• Database: PostgreSQL with SQLAlchemy (async)
• AI: OpenAI GPT-4o Vision
• Auth: JWT with bcrypt
• Migrations: Alembic

Project Structure

cal_ai/
├── src/cal_ai/
│   ├── api/              # API routes
│   ├── auth/             # Authentication
│   ├── database/         # Database models
│   ├── agent/            # AI analysis logic
│   ├── models/           # Pydantic models
│   ├── utils/            # Utilities
│   └── main.py           # Application entry
├── alembic/              # Database migrations
├── docs/                 # Documentation
├── tests/                # Tests
└── scripts/              # Setup scripts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

License

[Your License Here]