Victus AI Service

FastAPI-based AI prediction service with YOLOv10 object detection capabilities for integration with Go backend.

📋 Requirements

• Python 3.10+
• Docker & Docker Compose (optional)

📦 Project Structure

victus-AI/
├── main.py                    # FastAPI application
├── requirements.txt          # Python dependencies
├── Dockerfile               # Docker configuration
├── docker-compose.yml       # Docker Compose configuration
├── models/                  # YOLOv10 model files directory
│   └── .gitkeep            # Placeholder for git tracking
├── .gitignore              # Git ignore rules
└── README.md               # This file

🚀 Getting Started

Local Development

1. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -r requirements.txt

3. Run the service:

   python main.py

   The service will start at http://localhost:8000

Docker Deployment

1. Using Docker Compose (recommended):

   docker-compose up --build

2. Using Docker directly:

   docker build -t victus-ai:latest .
   docker run -p 8000:8000 -v $(pwd)/models:/app/models victus-ai:latest

📡 API Endpoints

Health Check

GET /health

Response:
{
  "status": "healthy",
  "service": "Victus AI Service",
  "timestamp": "2024-03-25T10:30:45.123456"
}

Prediction

POST /predict

Request:
{
  "image_url": "https://example.com/image.jpg"
}

Response:
{
  "success": true,
  "message": "Prediction completed successfully",
  "timestamp": "2024-03-25T10:30:45.123456",
  "data": {
    "detections": [
      {
        "class": "person",
        "confidence": 0.95,
        "bbox": [100, 50, 200, 300]
      }
    ],
    "inference_time_ms": 45.2,
    "model_version": "yolov10n"
  }
}

🔧 Configuration

Environment Variables

• PYTHONUNBUFFERED: Set to 1 (default in Dockerfile)
• PYTHONDONTWRITEBYTECODE: Set to 1 (default in Dockerfile)

Supabase Integration (Optional)

The service supports dynamic nutrition database lookup via Supabase. If Supabase credentials are not provided, it falls back to the local static nutrition database.

1. Set up Supabase credentials:

   Create a .env file in the root directory (use .env.example as reference):

   SUPABASE_URL=https://your-project-id.supabase.co
   SUPABASE_KEY=your-supabase-anon-key
   

2. Create the foods table in Supabase:

   CREATE TABLE foods (
     id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
     name TEXT NOT NULL UNIQUE,
     calories_per_100g FLOAT NOT NULL,
     protein FLOAT NOT NULL,
     carbs FLOAT NOT NULL,
     fat FLOAT NOT NULL,
     created_at TIMESTAMP DEFAULT NOW()
   );
   
   CREATE INDEX foods_name_idx ON foods USING GIN(name gin_trgm_ops);

3. Populate the foods table with sample data:

   INSERT INTO foods (name, calories_per_100g, protein, carbs, fat) VALUES
   ('apple', 52.0, 0.3, 14.0, 0.2),
   ('banana', 89.0, 1.1, 23.0, 0.3),
   ('chicken breast', 165.0, 31.0, 0.0, 3.6),
   ('rice', 130.0, 2.7, 28.0, 0.3),
   ('broccoli', 34.0, 2.8, 7.0, 0.4);

4. How it works:

   • The fetch_nutrition_from_supabase() function queries the foods table using:
     • Exact match (first attempt, most accurate)
     • ILIKE pattern match (fallback for variations like "chicken breast" vs "chicken")
   • If the food is not found in Supabase, it falls back to the local NUTRITION_DATABASE
   • If local DB doesn't have it either, it uses default values

Model Setup

Place YOLOv10 model files in the models/ directory:

• models/yolov10n.pt - Nano model
• models/yolov10s.pt - Small model
• models/yolov10m.pt - Medium model
• etc.

🔌 Integration with Go Backend

The service accepts POST requests from Go backend with the following format:

{
  "image_url": "https://your-server/image.jpg"
}

Example Go client request:

type PredictionRequest struct {
    ImageURL string `json:"image_url"`
}

// Send POST request to http://localhost:8000/predict

📚 Interactive API Documentation

Once the service is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🛠️ Development

Add new dependencies:

pip install <package>
pip freeze > requirements.txt

Future Implementation

The /predict endpoint currently returns dummy data. To implement actual YOLOv10 inference:

1. Place your trained YOLOv10 model in models/ directory
2. Update the prediction logic in main.py (marked with TODO)
3. Load model: from ultralytics import YOLO
4. Run inference and return actual predictions

Logging

Service logs are configured to show:

• Timestamp
• Logger name
• Log level
• Message

📝 License

Add your license information here

👥 Contributors

• Your Name

---

Status: ✅ Ready for integration with Go backend