Initial commit

DEPLOYMENT.md

@@ -0,0 +1,257 @@
+# 🐟 Marine Species Identification API - Deployment Guide
+
+## Quick Start
+
+### 1. Local Development
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Start the API (with automatic model download)
+python start_api.py
+
+# Or start directly with uvicorn
+uvicorn app.main:app --host 0.0.0.0 --port 7860
+```
+
+### 2. Docker Deployment
+
+```bash
+# Build the Docker image
+docker build -t marine-species-api .
+
+# Run the container
+docker run -p 7860:7860 marine-species-api
+```
+
+### 3. HuggingFace Spaces Deployment
+
+1. Create a new Space on HuggingFace Hub
+2. Set SDK to "Docker"
+3. Upload all files to your Space repository
+4. The Space will automatically build and deploy
+
+## Configuration
+
+### Environment Variables
+
+Copy `.env.example` to `.env` and modify as needed:
+
+```bash
+# Model Configuration
+HUGGINGFACE_REPO=your-username/your-model-repo
+MODEL_NAME=marina-benthic-33k
+
+# Performance
+ENABLE_MODEL_WARMUP=true
+MAX_FILE_SIZE=10485760
+
+# Server
+HOST=0.0.0.0
+PORT=7860
+```
+
+### Model Setup
+
+The API will automatically download the model from HuggingFace Hub on first startup. Ensure your model repository contains:
+
+- `marina-benthic-33k.pt` - The YOLOv5 model file
+- `marina-benthic-33k.names` - Class names file (optional)
+
+## Testing
+
+### Run All Tests
+```bash
+python run_tests.py
+```
+
+### Test API Manually
+```bash
+# Start the API
+python start_api.py
+
+# In another terminal, test the API
+python test_api_simple.py
+```
+
+### Test Specific Endpoints
+```bash
+# Health check
+curl http://localhost:7860/api/v1/health
+
+# API info
+curl http://localhost:7860/api/v1/info
+
+# List species
+curl http://localhost:7860/api/v1/species
+```
+
+## API Usage
+
+### Detect Marine Species
+
+```python
+import requests
+import base64
+
+# Read and encode image
+with open("marine_image.jpg", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode()
+
+# Make detection request
+response = requests.post("http://localhost:7860/api/v1/detect", json={
+    "image": image_data,
+    "confidence_threshold": 0.25,
+    "return_annotated_image": True
+})
+
+result = response.json()
+print(f"Found {len(result['detections'])} marine species")
+```
+
+### JavaScript Example
+
+```javascript
+// Convert image to base64
+const imageBase64 = await convertImageToBase64(imageFile);
+
+// Make detection request
+const response = await fetch('/api/v1/detect', {
+    method: 'POST',
+    headers: {
+        'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+        image: imageBase64,
+        confidence_threshold: 0.25,
+        return_annotated_image: true
+    })
+});
+
+const result = await response.json();
+console.log('Detections:', result.detections);
+```
+
+## Performance Optimization
+
+### Model Caching
+- Model is loaded once on startup and cached in memory
+- Supports model warmup for faster first inference
+
+### Request Caching
+- Optional caching of inference results
+- Configurable TTL and cache size
+
+### Monitoring
+- Built-in performance metrics
+- System resource monitoring
+- Request timing and success rates
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Model Download Fails**
+   ```bash
+   # Check repository access
+   python -c "from huggingface_hub import list_repo_files; print(list_repo_files('your-repo'))"
+   
+   # Manual download
+   python app/utils/model_utils.py --download
+   ```
+
+2. **Out of Memory**
+   - Reduce `image_size` parameter
+   - Use CPU instead of GPU for inference
+   - Increase Docker memory limits
+
+3. **Slow Inference**
+   - Enable model warmup
+   - Use GPU if available
+   - Optimize image preprocessing
+
+### Health Checks
+
+```bash
+# Basic health
+curl http://localhost:7860/health
+
+# Detailed health with model status
+curl http://localhost:7860/api/v1/health
+
+# Readiness probe (for Kubernetes)
+curl http://localhost:7860/api/v1/ready
+
+# Liveness probe
+curl http://localhost:7860/api/v1/live
+```
+
+## Production Deployment
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+services:
+  marine-api:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - ENABLE_MODEL_WARMUP=true
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+### Kubernetes
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: marine-species-api
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: marine-species-api
+  template:
+    metadata:
+      labels:
+        app: marine-species-api
+    spec:
+      containers:
+      - name: api
+        image: marine-species-api:latest
+        ports:
+        - containerPort: 7860
+        livenessProbe:
+          httpGet:
+            path: /api/v1/live
+            port: 7860
+          initialDelaySeconds: 60
+        readinessProbe:
+          httpGet:
+            path: /api/v1/ready
+            port: 7860
+          initialDelaySeconds: 30
+```
+
+## Security Considerations
+
+- Configure CORS appropriately for production
+- Add rate limiting for public APIs
+- Validate and sanitize all inputs
+- Use HTTPS in production
+- Monitor for unusual usage patterns
+
+## Monitoring and Logging
+
+- Structured logging with configurable levels
+- Performance metrics collection
+- Health check endpoints for monitoring systems
+- Error tracking and alerting

Dockerfile

@@ -0,0 +1,101 @@
+# Dockerfile for Marine Species Identification API on HuggingFace Spaces
+# Multi-stage build to handle model downloading with proper permissions
+
+# Stage 1: Download models as root
+FROM python:3.10-slim AS model-builder
+
+# Install system dependencies for model downloading
+RUN apt-get update && apt-get install -y \
+    wget \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install huggingface_hub for downloading models
+RUN pip install huggingface_hub
+
+# Create models directory
+RUN mkdir -p /models
+
+# Download models from HuggingFace Hub
+# Note: Replace 'seamo-ai/marina-species-v1' with your actual HF repo
+RUN python -c "\
+from huggingface_hub import hf_hub_download; \
+import os; \
+try: \
+    hf_hub_download('seamo-ai/marina-species-v1', 'marina-benthic-33k.pt', local_dir='/models', local_dir_use_symlinks=False); \
+    print('Model downloaded successfully'); \
+except Exception as e: \
+    print(f'Model download failed: {e}'); \
+    # Create a placeholder file to prevent build failure \
+    with open('/models/marina-benthic-33k.pt', 'w') as f: \
+        f.write('placeholder'); \
+"
+
+# Try to download class names file
+RUN python -c "\
+from huggingface_hub import hf_hub_download; \
+try: \
+    hf_hub_download('seamo-ai/marina-species-v1', 'marina-benthic-33k.names', local_dir='/models', local_dir_use_symlinks=False); \
+    print('Class names downloaded successfully'); \
+except Exception as e: \
+    print(f'Class names download failed: {e}'); \
+"
+
+# Stage 2: Build the application
+FROM python:3.10-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    ffmpeg \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libglib2.0-0 \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Set environment variables for HuggingFace and ML libraries
+ENV HF_HUB_OFFLINE=1
+ENV TRANSFORMERS_NO_ADVISORY_WARNINGS=1
+ENV PYTHONPATH=$HOME/app
+ENV TORCH_HOME=$HOME/.cache/torch
+ENV HF_HOME=$HOME/.cache/huggingface
+
+# Copy the requirements file and install dependencies
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade pip
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# Copy the downloaded models from the builder stage
+COPY --chown=user --from=model-builder /models $HOME/app/models
+
+# Copy the application code
+COPY --chown=user ./app app
+
+# Create necessary directories
+RUN mkdir -p $HOME/.cache/huggingface $HOME/.cache/torch
+
+# Expose port 7860 (HuggingFace Spaces standard)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=30s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Tell uvicorn to run on port 7860, which is the standard for HF Spaces
+# Use 0.0.0.0 to make it accessible from outside the container
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/__init__.py

@@ -0,0 +1,9 @@
+"""
+FastAPI Marine Species Identification API
+
+A scalable API for marine species identification using YOLOv5 model.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Seamo AI"
+__description__ = "Marine Species Identification API"

app/api/__init__.py

@@ -0,0 +1 @@
+# API package

app/api/dependencies.py

@@ -0,0 +1,47 @@
+"""
+FastAPI dependencies for the marine species identification API.
+"""
+
+from fastapi import HTTPException, status
+from app.services.model_service import model_service
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+async def get_model_service():
+    """
+    Dependency to get the model service.
+    Ensures the model is loaded and available.
+    """
+    try:
+        await model_service.ensure_model_available()
+        return model_service
+    except Exception as e:
+        logger.error(f"Failed to initialize model service: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail=f"Model service unavailable: {str(e)}"
+        )
+
+
+async def validate_model_health():
+    """
+    Dependency to validate model health before processing requests.
+    """
+    try:
+        health_status = await model_service.health_check()
+        if not health_status.get("model_loaded", False):
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Model is not loaded or unhealthy"
+            )
+        return True
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Model health check failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Model health check failed"
+        )

app/api/v1/__init__.py

@@ -0,0 +1 @@
+# API v1 package

app/api/v1/api.py

@@ -0,0 +1,20 @@
+"""
+API v1 router configuration.
+"""
+
+from fastapi import APIRouter
+
+from app.api.v1.endpoints import inference, health
+
+api_router = APIRouter()
+
+# Include endpoint routers
+api_router.include_router(
+    inference.router,
+    tags=["Marine Species Detection"]
+)
+
+api_router.include_router(
+    health.router,
+    tags=["Health & Status"]
+)

app/api/v1/endpoints/__init__.py

@@ -0,0 +1 @@
+# API v1 endpoints

app/api/v1/endpoints/health.py

@@ -0,0 +1,150 @@
+"""
+Health check and system status endpoints.
+"""
+
+from datetime import datetime
+from fastapi import APIRouter, HTTPException, status
+
+from app.models.inference import HealthResponse, APIInfo, ModelInfo, ErrorResponse
+from app.services.model_service import model_service
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Health Check",
+    description="Check the health status of the API and model"
+)
+async def health_check() -> HealthResponse:
+    """
+    Perform a comprehensive health check of the API and model.
+    
+    Returns the current status of the API, model loading status, and basic model information.
+    This endpoint can be used for monitoring and load balancer health checks.
+    """
+    try:
+        logger.debug("Performing health check")
+        
+        # Check model health
+        health_status = await model_service.health_check()
+        
+        model_info = None
+        if health_status.get("model_loaded", False):
+            model_info_dict = health_status.get("model_info", {})
+            if model_info_dict:
+                model_info = ModelInfo(**model_info_dict)
+        
+        return HealthResponse(
+            status="healthy" if health_status.get("model_loaded", False) else "degraded",
+            model_loaded=health_status.get("model_loaded", False),
+            model_info=model_info,
+            timestamp=datetime.utcnow().isoformat()
+        )
+        
+    except Exception as e:
+        logger.error(f"Health check failed: {str(e)}")
+        return HealthResponse(
+            status="unhealthy",
+            model_loaded=False,
+            model_info=None,
+            timestamp=datetime.utcnow().isoformat()
+        )
+
+
+@router.get(
+    "/info",
+    response_model=APIInfo,
+    summary="API Information",
+    description="Get comprehensive information about the API and model"
+)
+async def get_api_info() -> APIInfo:
+    """
+    Get comprehensive information about the API.
+    
+    Returns detailed information about the API version, capabilities, model information,
+    and available endpoints.
+    """
+    try:
+        logger.debug("Fetching API information")
+        
+        # Get model information
+        model_info_dict = model_service.get_model_info()
+        model_info = ModelInfo(**model_info_dict)
+        
+        # Define available endpoints
+        endpoints = [
+            f"{settings.API_V1_STR}/detect",
+            f"{settings.API_V1_STR}/species",
+            f"{settings.API_V1_STR}/species/{{class_id}}",
+            f"{settings.API_V1_STR}/health",
+            f"{settings.API_V1_STR}/info"
+        ]
+        
+        return APIInfo(
+            name=settings.PROJECT_NAME,
+            version=settings.VERSION,
+            description=settings.DESCRIPTION,
+            model_info=model_info,
+            endpoints=endpoints
+        )
+        
+    except Exception as e:
+        logger.error(f"Failed to get API info: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get API information: {str(e)}"
+        )
+
+
+@router.get(
+    "/ready",
+    summary="Readiness Check",
+    description="Check if the API is ready to serve requests"
+)
+async def readiness_check() -> dict:
+    """
+    Check if the API is ready to serve requests.
+    
+    This endpoint is specifically designed for Kubernetes readiness probes.
+    It returns 200 OK only when the model is loaded and ready to process requests.
+    """
+    try:
+        health_status = await model_service.health_check()
+        
+        if health_status.get("model_loaded", False):
+            return {"status": "ready"}
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Model not ready"
+            )
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Readiness check failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Service not ready"
+        )
+
+
+@router.get(
+    "/live",
+    summary="Liveness Check", 
+    description="Check if the API is alive"
+)
+async def liveness_check() -> dict:
+    """
+    Check if the API is alive.
+    
+    This endpoint is designed for Kubernetes liveness probes.
+    It performs a minimal check to ensure the API process is running.
+    """
+    return {"status": "alive", "timestamp": datetime.utcnow().isoformat()}

app/api/v1/endpoints/inference.py

@@ -0,0 +1,163 @@
+"""
+Marine species detection inference endpoints.
+"""
+
+from fastapi import APIRouter, HTTPException, status, Depends
+from typing import List
+
+from app.models.inference import (
+    InferenceRequest, 
+    InferenceResponse, 
+    SpeciesListResponse,
+    SpeciesInfo,
+    ErrorResponse
+)
+from app.services.inference_service import inference_service
+from app.api.dependencies import validate_model_health
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+
+@router.post(
+    "/detect",
+    response_model=InferenceResponse,
+    responses={
+        400: {"model": ErrorResponse, "description": "Bad Request"},
+        503: {"model": ErrorResponse, "description": "Service Unavailable"},
+    },
+    summary="Detect Marine Species",
+    description="Detect and identify marine species in an uploaded image using YOLOv5 model"
+)
+async def detect_marine_species(
+    request: InferenceRequest,
+    _: bool = Depends(validate_model_health)
+) -> InferenceResponse:
+    """
+    Detect marine species in an image.
+    
+    - **image**: Base64 encoded image data
+    - **confidence_threshold**: Minimum confidence for detections (0.0-1.0)
+    - **iou_threshold**: IoU threshold for non-maximum suppression (0.0-1.0)
+    - **image_size**: Input image size for inference (320-1280)
+    - **return_annotated_image**: Whether to return annotated image with bounding boxes
+    - **classes**: Optional list of class IDs to filter detections
+    
+    Returns detection results with bounding boxes, confidence scores, and species names.
+    """
+    try:
+        logger.info("Processing marine species detection request")
+        
+        result = await inference_service.detect_species(
+            image_data=request.image,
+            confidence_threshold=request.confidence_threshold,
+            iou_threshold=request.iou_threshold,
+            image_size=request.image_size,
+            return_annotated_image=request.return_annotated_image,
+            classes=request.classes
+        )
+        
+        logger.info(f"Detection completed: {len(result.detections)} species found")
+        return result
+        
+    except ValueError as e:
+        logger.error(f"Invalid input data: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid input: {str(e)}"
+        )
+    except Exception as e:
+        logger.error(f"Detection failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Detection failed: {str(e)}"
+        )
+
+
+@router.get(
+    "/species",
+    response_model=SpeciesListResponse,
+    summary="List Supported Species",
+    description="Get a list of all marine species that can be detected by the model"
+)
+async def list_supported_species(
+    _: bool = Depends(validate_model_health)
+) -> SpeciesListResponse:
+    """
+    Get a list of all supported marine species.
+    
+    Returns a comprehensive list of all marine species that the model can detect,
+    including their class IDs and scientific/common names.
+    """
+    try:
+        logger.info("Fetching supported species list")
+        
+        species_data = await inference_service.get_supported_species()
+        
+        species_list = [
+            SpeciesInfo(class_id=item["class_id"], class_name=item["class_name"])
+            for item in species_data
+        ]
+        
+        return SpeciesListResponse(
+            species=species_list,
+            total_count=len(species_list)
+        )
+        
+    except Exception as e:
+        logger.error(f"Failed to fetch species list: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch species list: {str(e)}"
+        )
+
+
+@router.get(
+    "/species/{class_id}",
+    response_model=SpeciesInfo,
+    responses={
+        404: {"model": ErrorResponse, "description": "Species Not Found"},
+    },
+    summary="Get Species Information",
+    description="Get information about a specific marine species by class ID"
+)
+async def get_species_info(
+    class_id: int,
+    _: bool = Depends(validate_model_health)
+) -> SpeciesInfo:
+    """
+    Get information about a specific marine species.
+    
+    - **class_id**: The class ID of the species to look up
+    
+    Returns detailed information about the specified marine species.
+    """
+    try:
+        logger.info(f"Fetching species info for class_id: {class_id}")
+        
+        species_data = await inference_service.get_supported_species()
+        
+        # Find the species with the given class_id
+        for species in species_data:
+            if species["class_id"] == class_id:
+                return SpeciesInfo(
+                    class_id=species["class_id"],
+                    class_name=species["class_name"]
+                )
+        
+        # Species not found
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Species with class_id {class_id} not found"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to fetch species info: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch species info: {str(e)}"
+        )

app/core/__init__.py

@@ -0,0 +1 @@
+# Core configuration and utilities

app/core/config.py

@@ -0,0 +1,54 @@
+"""
+Configuration management for the FastAPI application.
+"""
+
+import os
+from typing import Optional
+from pydantic import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings."""
+    
+    # API Configuration
+    API_V1_STR: str = "/api/v1"
+    PROJECT_NAME: str = "Marine Species Identification API"
+    VERSION: str = "1.0.0"
+    DESCRIPTION: str = "FastAPI-based marine species identification using YOLOv5"
+    
+    # Model Configuration
+    MODEL_NAME: str = "marina-benthic-33k"
+    MODEL_PATH: str = "models/marina-benthic-33k.pt"
+    HUGGINGFACE_REPO: str = "seamo-ai/marina-species-v1"
+    DEVICE: Optional[str] = None  # Auto-detect if None
+    
+    # Inference Configuration
+    DEFAULT_CONFIDENCE_THRESHOLD: float = 0.25
+    DEFAULT_IOU_THRESHOLD: float = 0.45
+    DEFAULT_IMAGE_SIZE: int = 720
+    MAX_IMAGE_SIZE: int = 1280
+    MIN_IMAGE_SIZE: int = 320
+    
+    # File Upload Configuration
+    MAX_FILE_SIZE: int = 10 * 1024 * 1024  # 10MB
+    ALLOWED_EXTENSIONS: set = {".jpg", ".jpeg", ".png", ".bmp", ".tiff", ".webp"}
+    
+    # Performance Configuration
+    MODEL_CACHE_SIZE: int = 1
+    ENABLE_MODEL_WARMUP: bool = True
+    
+    # HuggingFace Configuration
+    HF_HUB_OFFLINE: bool = os.getenv("HF_HUB_OFFLINE", "0") == "1"
+    TRANSFORMERS_NO_ADVISORY_WARNINGS: bool = True
+    
+    # Server Configuration
+    HOST: str = "0.0.0.0"
+    PORT: int = 7860  # HuggingFace Spaces standard
+    
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+
+# Global settings instance
+settings = Settings()

app/core/logging.py

@@ -0,0 +1,41 @@
+"""
+Logging configuration for the FastAPI application.
+"""
+
+import logging
+import sys
+from typing import Dict, Any
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """
+    Setup logging configuration.
+    
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    """
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[
+            logging.StreamHandler(sys.stdout)
+        ]
+    )
+    
+    # Set specific loggers
+    logging.getLogger("uvicorn").setLevel(logging.INFO)
+    logging.getLogger("fastapi").setLevel(logging.INFO)
+    logging.getLogger("yolov5").setLevel(logging.WARNING)  # Reduce YOLOv5 verbosity
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance.
+    
+    Args:
+        name: Logger name
+        
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

app/main.py

@@ -0,0 +1,119 @@
+"""
+FastAPI Marine Species Identification API
+
+Main application entry point for the marine species identification API.
+"""
+
+import asyncio
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+import uvicorn
+
+from app.core.config import settings
+from app.core.logging import setup_logging, get_logger
+from app.api.v1.api import api_router
+from app.services.model_service import model_service
+
+# Setup logging
+setup_logging()
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan manager.
+    Handles startup and shutdown events.
+    """
+    # Startup
+    logger.info("Starting Marine Species Identification API...")
+    
+    try:
+        # Ensure model is available and loaded
+        await model_service.ensure_model_available()
+        logger.info("Model loaded successfully")
+    except Exception as e:
+        logger.error(f"Failed to load model during startup: {str(e)}")
+        # Don't fail startup - let health checks handle this
+    
+    logger.info("API startup completed")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down Marine Species Identification API...")
+
+
+# Create FastAPI application
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    version=settings.VERSION,
+    description=settings.DESCRIPTION,
+    openapi_url=f"{settings.API_V1_STR}/openapi.json",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure appropriately for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Global exception handler
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    """Global exception handler for unhandled errors."""
+    logger.error(f"Unhandled exception: {str(exc)}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal Server Error",
+            "message": "An unexpected error occurred",
+            "details": str(exc) if settings.DEBUG else None
+        }
+    )
+
+
+# Include API router
+app.include_router(api_router, prefix=settings.API_V1_STR)
+
+
+# Root endpoint
+@app.get("/", tags=["Root"])
+async def root():
+    """
+    Root endpoint providing basic API information.
+    """
+    return {
+        "message": "Marine Species Identification API",
+        "version": settings.VERSION,
+        "docs": "/docs",
+        "health": f"{settings.API_V1_STR}/health",
+        "api_info": f"{settings.API_V1_STR}/info"
+    }
+
+
+# Health check endpoint at root level (for load balancers)
+@app.get("/health", tags=["Health"])
+async def root_health():
+    """Simple health check at root level."""
+    return {"status": "ok"}
+
+
+if __name__ == "__main__":
+    # Run the application
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=False,  # Set to True for development
+        log_level="info"
+    )

app/models/__init__.py

@@ -0,0 +1 @@
+# Pydantic models and YOLOv5 wrapper

app/models/inference.py

@@ -0,0 +1,123 @@
+"""
+Pydantic models for API requests and responses.
+"""
+
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field, validator
+import base64
+
+
+class BoundingBox(BaseModel):
+    """Bounding box coordinates."""
+    x: float = Field(..., description="X coordinate of top-left corner")
+    y: float = Field(..., description="Y coordinate of top-left corner") 
+    width: float = Field(..., description="Width of bounding box")
+    height: float = Field(..., description="Height of bounding box")
+
+
+class Detection(BaseModel):
+    """Single detection result."""
+    class_id: int = Field(..., description="Class ID of detected species")
+    class_name: str = Field(..., description="Name of detected marine species")
+    confidence: float = Field(..., ge=0.0, le=1.0, description="Detection confidence score")
+    bbox: BoundingBox = Field(..., description="Bounding box coordinates")
+
+
+class ModelInfo(BaseModel):
+    """Model information."""
+    model_name: str = Field(..., description="Name of the model")
+    total_classes: int = Field(..., description="Total number of species classes")
+    device: str = Field(..., description="Device used for inference")
+    model_path: str = Field(..., description="Path to model file")
+
+
+class InferenceRequest(BaseModel):
+    """Request model for marine species detection."""
+    image: str = Field(..., description="Base64 encoded image data")
+    confidence_threshold: float = Field(
+        default=0.25, 
+        ge=0.0, 
+        le=1.0, 
+        description="Confidence threshold for detections"
+    )
+    iou_threshold: float = Field(
+        default=0.45,
+        ge=0.0,
+        le=1.0, 
+        description="IoU threshold for non-maximum suppression"
+    )
+    image_size: int = Field(
+        default=720,
+        ge=320,
+        le=1280,
+        description="Input image size for inference"
+    )
+    return_annotated_image: bool = Field(
+        default=True,
+        description="Whether to return annotated image with detections"
+    )
+    classes: Optional[List[int]] = Field(
+        default=None,
+        description="List of class IDs to filter (None for all classes)"
+    )
+    
+    @validator('image')
+    def validate_image(cls, v):
+        """Validate base64 image data."""
+        try:
+            # Try to decode base64 to ensure it's valid
+            base64.b64decode(v)
+            return v
+        except Exception:
+            raise ValueError("Invalid base64 image data")
+
+
+class InferenceResponse(BaseModel):
+    """Response model for marine species detection."""
+    detections: List[Detection] = Field(..., description="List of detected marine species")
+    annotated_image: Optional[str] = Field(
+        default=None, 
+        description="Base64 encoded annotated image (if requested)"
+    )
+    processing_time: float = Field(..., description="Processing time in seconds")
+    model_info: ModelInfo = Field(..., description="Information about the model used")
+    image_dimensions: Dict[str, int] = Field(
+        ..., 
+        description="Original image dimensions (width, height)"
+    )
+
+
+class SpeciesInfo(BaseModel):
+    """Information about a marine species."""
+    class_id: int = Field(..., description="Class ID")
+    class_name: str = Field(..., description="Species name")
+
+
+class SpeciesListResponse(BaseModel):
+    """Response model for species list endpoint."""
+    species: List[SpeciesInfo] = Field(..., description="List of all supported marine species")
+    total_count: int = Field(..., description="Total number of species")
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check."""
+    status: str = Field(..., description="API status")
+    model_loaded: bool = Field(..., description="Whether the model is loaded")
+    model_info: Optional[ModelInfo] = Field(default=None, description="Model information")
+    timestamp: str = Field(..., description="Response timestamp")
+
+
+class ErrorResponse(BaseModel):
+    """Error response model."""
+    error: str = Field(..., description="Error type")
+    message: str = Field(..., description="Error message")
+    details: Optional[Dict[str, Any]] = Field(default=None, description="Additional error details")
+
+
+class APIInfo(BaseModel):
+    """API information response."""
+    name: str = Field(..., description="API name")
+    version: str = Field(..., description="API version")
+    description: str = Field(..., description="API description")
+    model_info: ModelInfo = Field(..., description="Model information")
+    endpoints: List[str] = Field(..., description="Available endpoints")

app/models/yolo.py

@@ -0,0 +1,186 @@
+"""
+YOLOv5 model wrapper adapted from the original Gradio implementation.
+Compatible with the existing marina-benthic-33k.pt model.
+"""
+
+import torch
+import yolov5
+import numpy as np
+from typing import Optional, List, Union, Dict, Any
+from pathlib import Path
+
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class MarineSpeciesYOLO:
+    """
+    Wrapper class for loading and running the marine species YOLOv5 model.
+    Adapted from the original inference.py to work with FastAPI.
+    """
+    
+    def __init__(self, model_path: str, device: Optional[str] = None):
+        """
+        Initialize the YOLO model.
+        
+        Args:
+            model_path: Path to the YOLOv5 model file
+            device: Device to run inference on ('cpu', 'cuda', etc.)
+        """
+        self.model_path = model_path
+        self.device = device or self._get_device()
+        self.model = None
+        self._class_names = None
+        
+        logger.info(f"Initializing MarineSpeciesYOLO with device: {self.device}")
+        self._load_model()
+    
+    def _get_device(self) -> str:
+        """Auto-detect the best available device."""
+        if torch.cuda.is_available():
+            return "cuda"
+        elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
+            return "mps"  # Apple Silicon
+        else:
+            return "cpu"
+    
+    def _load_model(self) -> None:
+        """Load the YOLOv5 model."""
+        try:
+            if not Path(self.model_path).exists():
+                raise FileNotFoundError(f"Model file not found: {self.model_path}")
+            
+            logger.info(f"Loading YOLOv5 model from: {self.model_path}")
+            self.model = yolov5.load(self.model_path, device=self.device)
+            
+            # Get class names if available
+            if hasattr(self.model, 'names'):
+                self._class_names = self.model.names
+                logger.info(f"Loaded model with {len(self._class_names)} classes")
+            
+            logger.info("YOLOv5 model loaded successfully")
+            
+        except Exception as e:
+            logger.error(f"Failed to load YOLOv5 model: {str(e)}")
+            raise
+    
+    def predict(
+        self,
+        image: Union[str, np.ndarray],
+        conf_threshold: float = 0.25,
+        iou_threshold: float = 0.45,
+        image_size: int = 720,
+        classes: Optional[List[int]] = None
+    ) -> torch.Tensor:
+        """
+        Run inference on an image.
+        
+        Args:
+            image: Input image (file path or numpy array)
+            conf_threshold: Confidence threshold for detections
+            iou_threshold: IoU threshold for NMS
+            image_size: Input image size for inference
+            classes: List of class IDs to filter (None for all classes)
+            
+        Returns:
+            YOLOv5 detection results
+        """
+        if self.model is None:
+            raise RuntimeError("Model not loaded")
+        
+        # Set model parameters
+        self.model.conf = conf_threshold
+        self.model.iou = iou_threshold
+        
+        if classes is not None:
+            self.model.classes = classes
+        
+        # Run inference
+        try:
+            detections = self.model(image, size=image_size)
+            return detections
+        except Exception as e:
+            logger.error(f"Inference failed: {str(e)}")
+            raise
+    
+    def get_class_names(self) -> Optional[Dict[int, str]]:
+        """Get the class names mapping."""
+        return self._class_names
+    
+    def get_model_info(self) -> Dict[str, Any]:
+        """Get model information."""
+        return {
+            "model_path": self.model_path,
+            "device": self.device,
+            "num_classes": len(self._class_names) if self._class_names else None,
+            "class_names": self._class_names
+        }
+    
+    def warmup(self, image_size: int = 720) -> None:
+        """
+        Warm up the model with a dummy inference.
+        
+        Args:
+            image_size: Size for warmup inference
+        """
+        if self.model is None:
+            return
+        
+        try:
+            logger.info("Warming up model...")
+            # Create a dummy image
+            dummy_image = np.random.randint(0, 255, (image_size, image_size, 3), dtype=np.uint8)
+            self.predict(dummy_image, conf_threshold=0.1)
+            logger.info("Model warmup completed")
+        except Exception as e:
+            logger.warning(f"Model warmup failed: {str(e)}")
+
+
+# Global model instance (singleton pattern)
+_model_instance: Optional[MarineSpeciesYOLO] = None
+
+
+def get_model() -> MarineSpeciesYOLO:
+    """
+    Get the global model instance (singleton pattern).
+    
+    Returns:
+        MarineSpeciesYOLO instance
+    """
+    global _model_instance
+    
+    if _model_instance is None:
+        _model_instance = MarineSpeciesYOLO(
+            model_path=settings.MODEL_PATH,
+            device=settings.DEVICE
+        )
+        
+        # Warm up the model if enabled
+        if settings.ENABLE_MODEL_WARMUP:
+            _model_instance.warmup()
+    
+    return _model_instance
+
+
+def load_class_names(names_file: str) -> Dict[int, str]:
+    """
+    Load class names from a .names file.
+    
+    Args:
+        names_file: Path to the .names file
+        
+    Returns:
+        Dictionary mapping class IDs to names
+    """
+    class_names = {}
+    try:
+        with open(names_file, 'r') as f:
+            for idx, line in enumerate(f):
+                class_names[idx] = line.strip()
+        logger.info(f"Loaded {len(class_names)} class names from {names_file}")
+    except Exception as e:
+        logger.error(f"Failed to load class names: {str(e)}")
+    
+    return class_names

app/services/__init__.py

@@ -0,0 +1 @@
+# Services layer for business logic

app/services/inference_service.py

@@ -0,0 +1,201 @@
+"""
+Inference service for marine species detection.
+"""
+
+import time
+import base64
+import io
+from typing import List, Optional, Dict, Tuple
+import numpy as np
+from PIL import Image
+import cv2
+
+from app.core.config import settings
+from app.core.logging import get_logger
+from app.models.inference import Detection, BoundingBox, InferenceResponse, ModelInfo
+from app.services.model_service import model_service
+from app.utils.image_processing import decode_base64_image, encode_image_to_base64
+
+logger = get_logger(__name__)
+
+
+class InferenceService:
+    """Service for running marine species detection inference."""
+    
+    def __init__(self):
+        self.model_service = model_service
+    
+    async def detect_species(
+        self,
+        image_data: str,
+        confidence_threshold: float = 0.25,
+        iou_threshold: float = 0.45,
+        image_size: int = 720,
+        return_annotated_image: bool = True,
+        classes: Optional[List[int]] = None
+    ) -> InferenceResponse:
+        """
+        Detect marine species in an image.
+        
+        Args:
+            image_data: Base64 encoded image
+            confidence_threshold: Confidence threshold for detections
+            iou_threshold: IoU threshold for NMS
+            image_size: Input image size for inference
+            return_annotated_image: Whether to return annotated image
+            classes: List of class IDs to filter
+            
+        Returns:
+            InferenceResponse with detection results
+        """
+        start_time = time.time()
+        
+        try:
+            # Decode the image
+            image, original_dims = decode_base64_image(image_data)
+            logger.info(f"Processing image with dimensions: {original_dims}")
+            
+            # Get the model
+            model = self.model_service.get_model()
+            
+            # Run inference
+            predictions = model.predict(
+                image=image,
+                conf_threshold=confidence_threshold,
+                iou_threshold=iou_threshold,
+                image_size=image_size,
+                classes=classes
+            )
+            
+            # Process predictions
+            detections = self._process_predictions(predictions)
+            
+            # Generate annotated image if requested
+            annotated_image_b64 = None
+            if return_annotated_image and detections:
+                annotated_image = self._create_annotated_image(image, predictions)
+                annotated_image_b64 = encode_image_to_base64(annotated_image)
+            
+            # Get model info
+            model_info_dict = self.model_service.get_model_info()
+            model_info = ModelInfo(**model_info_dict)
+            
+            processing_time = time.time() - start_time
+            
+            logger.info(f"Inference completed in {processing_time:.3f}s, found {len(detections)} detections")
+            
+            return InferenceResponse(
+                detections=detections,
+                annotated_image=annotated_image_b64,
+                processing_time=processing_time,
+                model_info=model_info,
+                image_dimensions={"width": original_dims[0], "height": original_dims[1]}
+            )
+            
+        except Exception as e:
+            logger.error(f"Inference failed: {str(e)}")
+            raise
+    
+    def _process_predictions(self, predictions) -> List[Detection]:
+        """
+        Process YOLOv5 predictions into Detection objects.
+        
+        Args:
+            predictions: YOLOv5 prediction results
+            
+        Returns:
+            List of Detection objects
+        """
+        detections = []
+        class_names = self.model_service.get_class_names()
+        
+        try:
+            # Get predictions as pandas DataFrame
+            pred_df = predictions.pandas().xyxy[0]
+            
+            for _, row in pred_df.iterrows():
+                # Extract bounding box coordinates
+                x1, y1, x2, y2 = row['xmin'], row['ymin'], row['xmax'], row['ymax']
+                width = x2 - x1
+                height = y2 - y1
+                
+                # Get class information
+                class_id = int(row['class'])
+                confidence = float(row['confidence'])
+                
+                # Get class name
+                if class_names and class_id in class_names:
+                    class_name = class_names[class_id]
+                else:
+                    class_name = f"class_{class_id}"
+                
+                # Create detection object
+                detection = Detection(
+                    class_id=class_id,
+                    class_name=class_name,
+                    confidence=confidence,
+                    bbox=BoundingBox(
+                        x=float(x1),
+                        y=float(y1),
+                        width=float(width),
+                        height=float(height)
+                    )
+                )
+                
+                detections.append(detection)
+                
+        except Exception as e:
+            logger.error(f"Failed to process predictions: {str(e)}")
+            raise
+        
+        return detections
+    
+    def _create_annotated_image(self, original_image: np.ndarray, predictions) -> np.ndarray:
+        """
+        Create an annotated image with detection boxes and labels.
+        
+        Args:
+            original_image: Original input image
+            predictions: YOLOv5 prediction results
+            
+        Returns:
+            Annotated image as numpy array
+        """
+        try:
+            # Use YOLOv5's built-in rendering
+            rendered_imgs = predictions.render()
+            if rendered_imgs and len(rendered_imgs) > 0:
+                return rendered_imgs[0]
+            else:
+                # Fallback: return original image if rendering fails
+                return original_image
+                
+        except Exception as e:
+            logger.error(f"Failed to create annotated image: {str(e)}")
+            # Return original image as fallback
+            return original_image
+    
+    async def get_supported_species(self) -> List[Dict]:
+        """
+        Get list of all supported marine species.
+        
+        Returns:
+            List of species information
+        """
+        class_names = self.model_service.get_class_names()
+        
+        if not class_names:
+            return []
+        
+        species_list = []
+        for class_id, class_name in class_names.items():
+            species_list.append({
+                "class_id": class_id,
+                "class_name": class_name
+            })
+        
+        return sorted(species_list, key=lambda x: x["class_name"])
+
+
+# Global service instance
+inference_service = InferenceService()

app/services/model_service.py

@@ -0,0 +1,166 @@
+"""
+Model service for managing YOLOv5 model lifecycle and operations.
+"""
+
+import os
+from pathlib import Path
+from typing import Dict, Optional
+from huggingface_hub import hf_hub_download
+
+from app.core.config import settings
+from app.core.logging import get_logger
+from app.models.yolo import MarineSpeciesYOLO, get_model
+
+logger = get_logger(__name__)
+
+
+class ModelService:
+    """Service for managing the marine species detection model."""
+    
+    def __init__(self):
+        self._model: Optional[MarineSpeciesYOLO] = None
+        self._class_names: Optional[Dict[int, str]] = None
+    
+    async def ensure_model_available(self) -> None:
+        """
+        Ensure the model is downloaded and available.
+        Downloads from HuggingFace Hub if not present locally.
+        """
+        model_path = Path(settings.MODEL_PATH)
+        
+        # Check if model exists locally
+        if not model_path.exists():
+            logger.info(f"Model not found at {model_path}, downloading from HuggingFace Hub...")
+            await self._download_model()
+        
+        # Load class names if available
+        await self._load_class_names()
+    
+    async def _download_model(self) -> None:
+        """Download model from HuggingFace Hub."""
+        try:
+            # Create models directory if it doesn't exist
+            model_dir = Path(settings.MODEL_PATH).parent
+            model_dir.mkdir(parents=True, exist_ok=True)
+            
+            # Download the model file
+            logger.info(f"Downloading model from {settings.HUGGINGFACE_REPO}")
+            
+            # Download the .pt model file
+            model_filename = f"{settings.MODEL_NAME}.pt"
+            downloaded_path = hf_hub_download(
+                repo_id=settings.HUGGINGFACE_REPO,
+                filename=model_filename,
+                cache_dir=str(model_dir.parent / ".cache"),
+                local_dir=str(model_dir),
+                local_dir_use_symlinks=False
+            )
+            
+            logger.info(f"Model downloaded successfully to: {downloaded_path}")
+            
+            # Also download the .names file if available
+            try:
+                names_filename = f"{settings.MODEL_NAME}.names"
+                names_path = hf_hub_download(
+                    repo_id=settings.HUGGINGFACE_REPO,
+                    filename=names_filename,
+                    cache_dir=str(model_dir.parent / ".cache"),
+                    local_dir=str(model_dir),
+                    local_dir_use_symlinks=False
+                )
+                logger.info(f"Class names file downloaded to: {names_path}")
+            except Exception as e:
+                logger.warning(f"Could not download .names file: {str(e)}")
+                
+        except Exception as e:
+            logger.error(f"Failed to download model: {str(e)}")
+            raise RuntimeError(f"Model download failed: {str(e)}")
+    
+    async def _load_class_names(self) -> None:
+        """Load class names from .names file."""
+        names_file = Path(settings.MODEL_PATH).with_suffix('.names')
+        
+        if names_file.exists():
+            try:
+                class_names = {}
+                with open(names_file, 'r') as f:
+                    for idx, line in enumerate(f):
+                        class_names[idx] = line.strip()
+                
+                self._class_names = class_names
+                logger.info(f"Loaded {len(class_names)} class names")
+            except Exception as e:
+                logger.error(f"Failed to load class names: {str(e)}")
+        else:
+            logger.warning(f"Class names file not found: {names_file}")
+    
+    def get_model(self) -> MarineSpeciesYOLO:
+        """
+        Get the model instance.
+        
+        Returns:
+            MarineSpeciesYOLO instance
+        """
+        if self._model is None:
+            self._model = get_model()
+        return self._model
+    
+    def get_class_names(self) -> Optional[Dict[int, str]]:
+        """
+        Get class names mapping.
+        
+        Returns:
+            Dictionary mapping class IDs to names
+        """
+        if self._class_names is None:
+            # Try to get from model
+            model = self.get_model()
+            self._class_names = model.get_class_names()
+        
+        return self._class_names
+    
+    def get_model_info(self) -> Dict:
+        """
+        Get comprehensive model information.
+        
+        Returns:
+            Dictionary with model information
+        """
+        model = self.get_model()
+        class_names = self.get_class_names()
+        
+        return {
+            "model_name": settings.MODEL_NAME,
+            "total_classes": len(class_names) if class_names else 0,
+            "device": model.device,
+            "model_path": settings.MODEL_PATH,
+            "huggingface_repo": settings.HUGGINGFACE_REPO
+        }
+    
+    async def health_check(self) -> Dict:
+        """
+        Perform a health check on the model.
+        
+        Returns:
+            Dictionary with health status
+        """
+        try:
+            model = self.get_model()
+            model_info = self.get_model_info()
+            
+            return {
+                "status": "healthy",
+                "model_loaded": True,
+                "model_info": model_info
+            }
+        except Exception as e:
+            logger.error(f"Model health check failed: {str(e)}")
+            return {
+                "status": "unhealthy",
+                "model_loaded": False,
+                "error": str(e)
+            }
+
+
+# Global service instance
+model_service = ModelService()

app/utils/__init__.py

@@ -0,0 +1 @@
+# Utility functions

app/utils/image_processing.py

@@ -0,0 +1,193 @@
+"""
+Image processing utilities for the FastAPI application.
+"""
+
+import base64
+import io
+from typing import Tuple
+import numpy as np
+from PIL import Image
+import cv2
+
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def decode_base64_image(image_data: str) -> Tuple[np.ndarray, Tuple[int, int]]:
+    """
+    Decode base64 image data to numpy array.
+    
+    Args:
+        image_data: Base64 encoded image string
+        
+    Returns:
+        Tuple of (image_array, (width, height))
+    """
+    try:
+        # Remove data URL prefix if present
+        if image_data.startswith('data:image'):
+            image_data = image_data.split(',')[1]
+        
+        # Decode base64
+        image_bytes = base64.b64decode(image_data)
+        
+        # Open with PIL
+        pil_image = Image.open(io.BytesIO(image_bytes))
+        
+        # Convert to RGB if necessary
+        if pil_image.mode != 'RGB':
+            pil_image = pil_image.convert('RGB')
+        
+        # Get original dimensions
+        original_dims = pil_image.size  # (width, height)
+        
+        # Convert to numpy array
+        image_array = np.array(pil_image)
+        
+        logger.debug(f"Decoded image with shape: {image_array.shape}")
+        
+        return image_array, original_dims
+        
+    except Exception as e:
+        logger.error(f"Failed to decode base64 image: {str(e)}")
+        raise ValueError(f"Invalid image data: {str(e)}")
+
+
+def encode_image_to_base64(image: np.ndarray, format: str = "JPEG", quality: int = 95) -> str:
+    """
+    Encode numpy array image to base64 string.
+    
+    Args:
+        image: Image as numpy array
+        format: Image format (JPEG, PNG, etc.)
+        quality: JPEG quality (1-100)
+        
+    Returns:
+        Base64 encoded image string
+    """
+    try:
+        # Convert numpy array to PIL Image
+        if image.dtype != np.uint8:
+            image = (image * 255).astype(np.uint8)
+        
+        pil_image = Image.fromarray(image)
+        
+        # Save to bytes buffer
+        buffer = io.BytesIO()
+        save_kwargs = {"format": format}
+        
+        if format.upper() == "JPEG":
+            save_kwargs["quality"] = quality
+            save_kwargs["optimize"] = True
+        
+        pil_image.save(buffer, **save_kwargs)
+        
+        # Encode to base64
+        image_bytes = buffer.getvalue()
+        base64_string = base64.b64encode(image_bytes).decode('utf-8')
+        
+        return base64_string
+        
+    except Exception as e:
+        logger.error(f"Failed to encode image to base64: {str(e)}")
+        raise ValueError(f"Image encoding failed: {str(e)}")
+
+
+def validate_image_size(image: np.ndarray) -> bool:
+    """
+    Validate image dimensions.
+    
+    Args:
+        image: Image as numpy array
+        
+    Returns:
+        True if image size is valid
+    """
+    height, width = image.shape[:2]
+    
+    # Check minimum and maximum dimensions
+    min_dim = min(width, height)
+    max_dim = max(width, height)
+    
+    if min_dim < 32:  # Too small
+        return False
+    
+    if max_dim > 4096:  # Too large
+        return False
+    
+    return True
+
+
+def resize_image_if_needed(image: np.ndarray, max_size: int = 1280) -> np.ndarray:
+    """
+    Resize image if it's too large while maintaining aspect ratio.
+    
+    Args:
+        image: Image as numpy array
+        max_size: Maximum dimension size
+        
+    Returns:
+        Resized image
+    """
+    height, width = image.shape[:2]
+    
+    if max(height, width) <= max_size:
+        return image
+    
+    # Calculate new dimensions
+    if width > height:
+        new_width = max_size
+        new_height = int(height * (max_size / width))
+    else:
+        new_height = max_size
+        new_width = int(width * (max_size / height))
+    
+    # Resize using PIL for better quality
+    pil_image = Image.fromarray(image)
+    resized_pil = pil_image.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    
+    return np.array(resized_pil)
+
+
+def validate_image_format(image_bytes: bytes) -> bool:
+    """
+    Validate if the image format is supported.
+    
+    Args:
+        image_bytes: Raw image bytes
+        
+    Returns:
+        True if format is supported
+    """
+    try:
+        with Image.open(io.BytesIO(image_bytes)) as img:
+            # Check if format is in allowed extensions
+            format_lower = img.format.lower() if img.format else ""
+            allowed_formats = {"jpeg", "jpg", "png", "bmp", "tiff", "webp"}
+            return format_lower in allowed_formats
+    except Exception:
+        return False
+
+
+def get_image_info(image: np.ndarray) -> dict:
+    """
+    Get information about an image.
+    
+    Args:
+        image: Image as numpy array
+        
+    Returns:
+        Dictionary with image information
+    """
+    height, width = image.shape[:2]
+    channels = image.shape[2] if len(image.shape) > 2 else 1
+    
+    return {
+        "width": width,
+        "height": height,
+        "channels": channels,
+        "dtype": str(image.dtype),
+        "size_mb": image.nbytes / (1024 * 1024)
+    }

app/utils/model_utils.py

@@ -0,0 +1,227 @@
+"""
+Model utilities for downloading and managing the marine species model.
+"""
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional, Dict, Any
+from huggingface_hub import hf_hub_download, list_repo_files
+
+from app.core.config import settings
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def download_model_from_hf(
+    repo_id: str,
+    model_filename: str,
+    local_dir: str,
+    force_download: bool = False
+) -> str:
+    """
+    Download model from HuggingFace Hub.
+    
+    Args:
+        repo_id: HuggingFace repository ID
+        model_filename: Name of the model file
+        local_dir: Local directory to save the model
+        force_download: Whether to force re-download if file exists
+        
+    Returns:
+        Path to the downloaded model file
+    """
+    try:
+        # Create local directory if it doesn't exist
+        Path(local_dir).mkdir(parents=True, exist_ok=True)
+        
+        local_path = Path(local_dir) / model_filename
+        
+        # Check if file already exists and force_download is False
+        if local_path.exists() and not force_download:
+            logger.info(f"Model already exists at {local_path}")
+            return str(local_path)
+        
+        logger.info(f"Downloading {model_filename} from {repo_id}...")
+        
+        downloaded_path = hf_hub_download(
+            repo_id=repo_id,
+            filename=model_filename,
+            local_dir=local_dir,
+            local_dir_use_symlinks=False,
+            force_download=force_download
+        )
+        
+        logger.info(f"Model downloaded successfully to: {downloaded_path}")
+        return downloaded_path
+        
+    except Exception as e:
+        logger.error(f"Failed to download model: {str(e)}")
+        raise
+
+
+def list_available_files(repo_id: str) -> list:
+    """
+    List all available files in a HuggingFace repository.
+    
+    Args:
+        repo_id: HuggingFace repository ID
+        
+    Returns:
+        List of available files
+    """
+    try:
+        files = list_repo_files(repo_id)
+        return files
+    except Exception as e:
+        logger.error(f"Failed to list repository files: {str(e)}")
+        return []
+
+
+def verify_model_file(model_path: str) -> bool:
+    """
+    Verify that a model file exists and is valid.
+    
+    Args:
+        model_path: Path to the model file
+        
+    Returns:
+        True if model file is valid
+    """
+    try:
+        path = Path(model_path)
+        
+        # Check if file exists
+        if not path.exists():
+            logger.error(f"Model file does not exist: {model_path}")
+            return False
+        
+        # Check file size (should be > 1MB for a real model)
+        file_size = path.stat().st_size
+        if file_size < 1024 * 1024:  # 1MB
+            logger.warning(f"Model file seems too small: {file_size} bytes")
+            return False
+        
+        # Check file extension
+        if not path.suffix.lower() in ['.pt', '.pth']:
+            logger.warning(f"Unexpected model file extension: {path.suffix}")
+        
+        logger.info(f"Model file verified: {model_path} ({file_size / (1024*1024):.1f} MB)")
+        return True
+        
+    except Exception as e:
+        logger.error(f"Failed to verify model file: {str(e)}")
+        return False
+
+
+def get_model_info(model_path: str) -> Dict[str, Any]:
+    """
+    Get information about a model file.
+    
+    Args:
+        model_path: Path to the model file
+        
+    Returns:
+        Dictionary with model information
+    """
+    info = {
+        "path": model_path,
+        "exists": False,
+        "size_mb": 0,
+        "size_bytes": 0
+    }
+    
+    try:
+        path = Path(model_path)
+        
+        if path.exists():
+            info["exists"] = True
+            size_bytes = path.stat().st_size
+            info["size_bytes"] = size_bytes
+            info["size_mb"] = size_bytes / (1024 * 1024)
+            info["modified_time"] = path.stat().st_mtime
+        
+    except Exception as e:
+        logger.error(f"Failed to get model info: {str(e)}")
+    
+    return info
+
+
+def cleanup_model_cache(cache_dir: Optional[str] = None) -> None:
+    """
+    Clean up model cache directory.
+    
+    Args:
+        cache_dir: Cache directory to clean (uses default if None)
+    """
+    try:
+        if cache_dir is None:
+            cache_dir = Path.home() / ".cache" / "huggingface"
+        
+        cache_path = Path(cache_dir)
+        
+        if cache_path.exists():
+            logger.info(f"Cleaning up cache directory: {cache_path}")
+            shutil.rmtree(cache_path)
+            logger.info("Cache cleanup completed")
+        else:
+            logger.info("Cache directory does not exist")
+            
+    except Exception as e:
+        logger.error(f"Failed to cleanup cache: {str(e)}")
+
+
+def setup_model_directory() -> str:
+    """
+    Setup the model directory and ensure it exists.
+    
+    Returns:
+        Path to the model directory
+    """
+    model_dir = Path(settings.MODEL_PATH).parent
+    model_dir.mkdir(parents=True, exist_ok=True)
+    
+    logger.info(f"Model directory setup: {model_dir}")
+    return str(model_dir)
+
+
+if __name__ == "__main__":
+    # Command line utility for model management
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Model management utility")
+    parser.add_argument("--download", action="store_true", help="Download model from HuggingFace")
+    parser.add_argument("--verify", action="store_true", help="Verify model file")
+    parser.add_argument("--info", action="store_true", help="Show model information")
+    parser.add_argument("--list-files", action="store_true", help="List available files in HF repo")
+    parser.add_argument("--cleanup-cache", action="store_true", help="Cleanup model cache")
+    parser.add_argument("--force", action="store_true", help="Force download even if file exists")
+    
+    args = parser.parse_args()
+    
+    if args.download:
+        setup_model_directory()
+        download_model_from_hf(
+            repo_id=settings.HUGGINGFACE_REPO,
+            model_filename=f"{settings.MODEL_NAME}.pt",
+            local_dir=str(Path(settings.MODEL_PATH).parent),
+            force_download=args.force
+        )
+    
+    if args.verify:
+        is_valid = verify_model_file(settings.MODEL_PATH)
+        print(f"Model valid: {is_valid}")
+    
+    if args.info:
+        info = get_model_info(settings.MODEL_PATH)
+        print(f"Model info: {info}")
+    
+    if args.list_files:
+        files = list_available_files(settings.HUGGINGFACE_REPO)
+        print(f"Available files in {settings.HUGGINGFACE_REPO}:")
+        for file in files:
+            print(f"  - {file}")
+    
+    if args.cleanup_cache:
+        cleanup_model_cache()

app/utils/performance.py

@@ -0,0 +1,237 @@
+"""
+Performance monitoring and optimization utilities.
+"""
+
+import time
+import psutil
+import functools
+from typing import Dict, Any, Callable, Optional
+from contextlib import contextmanager
+
+from app.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class PerformanceMonitor:
+    """Performance monitoring utility."""
+    
+    def __init__(self):
+        self.metrics = {
+            "requests_total": 0,
+            "requests_successful": 0,
+            "requests_failed": 0,
+            "total_processing_time": 0.0,
+            "average_processing_time": 0.0,
+            "min_processing_time": float('inf'),
+            "max_processing_time": 0.0
+        }
+    
+    def record_request(self, processing_time: float, success: bool = True):
+        """Record a request's performance metrics."""
+        self.metrics["requests_total"] += 1
+        
+        if success:
+            self.metrics["requests_successful"] += 1
+        else:
+            self.metrics["requests_failed"] += 1
+        
+        self.metrics["total_processing_time"] += processing_time
+        self.metrics["average_processing_time"] = (
+            self.metrics["total_processing_time"] / self.metrics["requests_total"]
+        )
+        
+        if processing_time < self.metrics["min_processing_time"]:
+            self.metrics["min_processing_time"] = processing_time
+        
+        if processing_time > self.metrics["max_processing_time"]:
+            self.metrics["max_processing_time"] = processing_time
+    
+    def get_metrics(self) -> Dict[str, Any]:
+        """Get current performance metrics."""
+        metrics = self.metrics.copy()
+        
+        # Add system metrics
+        try:
+            metrics.update({
+                "cpu_percent": psutil.cpu_percent(),
+                "memory_percent": psutil.virtual_memory().percent,
+                "memory_available_mb": psutil.virtual_memory().available / (1024 * 1024)
+            })
+        except Exception as e:
+            logger.warning(f"Failed to get system metrics: {str(e)}")
+        
+        return metrics
+    
+    def reset_metrics(self):
+        """Reset all metrics."""
+        self.metrics = {
+            "requests_total": 0,
+            "requests_successful": 0,
+            "requests_failed": 0,
+            "total_processing_time": 0.0,
+            "average_processing_time": 0.0,
+            "min_processing_time": float('inf'),
+            "max_processing_time": 0.0
+        }
+
+
+# Global performance monitor instance
+performance_monitor = PerformanceMonitor()
+
+
+@contextmanager
+def measure_time():
+    """Context manager to measure execution time."""
+    start_time = time.time()
+    try:
+        yield
+    finally:
+        end_time = time.time()
+        execution_time = end_time - start_time
+        logger.debug(f"Execution time: {execution_time:.3f}s")
+
+
+def timed_function(func: Callable) -> Callable:
+    """Decorator to measure function execution time."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        try:
+            result = func(*args, **kwargs)
+            success = True
+            return result
+        except Exception as e:
+            success = False
+            raise
+        finally:
+            end_time = time.time()
+            execution_time = end_time - start_time
+            performance_monitor.record_request(execution_time, success)
+            logger.debug(f"{func.__name__} execution time: {execution_time:.3f}s")
+    
+    return wrapper
+
+
+async def timed_async_function(func: Callable) -> Callable:
+    """Decorator to measure async function execution time."""
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        start_time = time.time()
+        try:
+            result = await func(*args, **kwargs)
+            success = True
+            return result
+        except Exception as e:
+            success = False
+            raise
+        finally:
+            end_time = time.time()
+            execution_time = end_time - start_time
+            performance_monitor.record_request(execution_time, success)
+            logger.debug(f"{func.__name__} execution time: {execution_time:.3f}s")
+    
+    return wrapper
+
+
+class SimpleCache:
+    """Simple in-memory cache for inference results."""
+    
+    def __init__(self, max_size: int = 100, ttl: int = 3600):
+        """
+        Initialize cache.
+        
+        Args:
+            max_size: Maximum number of items to cache
+            ttl: Time to live in seconds
+        """
+        self.max_size = max_size
+        self.ttl = ttl
+        self.cache = {}
+        self.access_times = {}
+    
+    def _is_expired(self, key: str) -> bool:
+        """Check if a cache entry is expired."""
+        if key not in self.access_times:
+            return True
+        
+        return time.time() - self.access_times[key] > self.ttl
+    
+    def _evict_expired(self):
+        """Remove expired entries."""
+        current_time = time.time()
+        expired_keys = [
+            key for key, access_time in self.access_times.items()
+            if current_time - access_time > self.ttl
+        ]
+        
+        for key in expired_keys:
+            self.cache.pop(key, None)
+            self.access_times.pop(key, None)
+    
+    def _evict_lru(self):
+        """Remove least recently used entry."""
+        if not self.access_times:
+            return
+        
+        lru_key = min(self.access_times.keys(), key=lambda k: self.access_times[k])
+        self.cache.pop(lru_key, None)
+        self.access_times.pop(lru_key, None)
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get item from cache."""
+        if key not in self.cache or self._is_expired(key):
+            return None
+        
+        self.access_times[key] = time.time()
+        return self.cache[key]
+    
+    def set(self, key: str, value: Any):
+        """Set item in cache."""
+        # Clean up expired entries
+        self._evict_expired()
+        
+        # Evict LRU if at max size
+        while len(self.cache) >= self.max_size:
+            self._evict_lru()
+        
+        self.cache[key] = value
+        self.access_times[key] = time.time()
+    
+    def clear(self):
+        """Clear all cache entries."""
+        self.cache.clear()
+        self.access_times.clear()
+    
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self.cache)
+    
+    def stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        return {
+            "size": len(self.cache),
+            "max_size": self.max_size,
+            "ttl": self.ttl,
+            "hit_ratio": getattr(self, '_hits', 0) / max(getattr(self, '_requests', 1), 1)
+        }
+
+
+# Global cache instance
+inference_cache = SimpleCache(max_size=50, ttl=1800)  # 30 minutes TTL
+
+
+def get_system_info() -> Dict[str, Any]:
+    """Get system information."""
+    try:
+        return {
+            "cpu_count": psutil.cpu_count(),
+            "cpu_percent": psutil.cpu_percent(interval=1),
+            "memory_total_gb": psutil.virtual_memory().total / (1024**3),
+            "memory_available_gb": psutil.virtual_memory().available / (1024**3),
+            "memory_percent": psutil.virtual_memory().percent,
+            "disk_usage_percent": psutil.disk_usage('/').percent
+        }
+    except Exception as e:
+        logger.error(f"Failed to get system info: {str(e)}")
+        return {"error": str(e)}

requirements.txt

@@ -0,0 +1,29 @@
+# FastAPI and web server
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+
+# Machine Learning and Computer Vision
+torch>=1.13.0
+torchvision>=0.14.0
+yolov5==7.0.13
+opencv-python-headless==4.8.1.78
+Pillow==10.1.0
+numpy==1.24.3
+
+# Data handling and validation
+pydantic==2.5.0
+pydantic-settings==2.1.0
+
+# HuggingFace integration
+huggingface-hub==0.19.4
+
+# Utilities
+python-multipart==0.0.6
+aiofiles==23.2.1
+
+# Performance monitoring and optimization
+psutil==5.9.6
+
+# Testing (optional, for development)
+pytest==7.4.3
+httpx==0.25.2

run_tests.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+Test runner script for the Marine Species Identification API.
+"""
+
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+def run_pytest():
+    """Run pytest tests."""
+    print("🧪 Running pytest tests...")
+    try:
+        result = subprocess.run([
+            sys.executable, "-m", "pytest", 
+            "tests/", 
+            "-v", 
+            "--tb=short"
+        ], check=True)
+        print("✅ All pytest tests passed!")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Some pytest tests failed (exit code: {e.returncode})")
+        return False
+    except FileNotFoundError:
+        print("⚠️  pytest not found, skipping pytest tests")
+        return True
+
+def run_simple_test():
+    """Run the simple API test."""
+    print("🧪 Running simple API test...")
+    try:
+        result = subprocess.run([
+            sys.executable, "test_api_simple.py"
+        ], check=True)
+        print("✅ Simple API test completed!")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Simple API test failed (exit code: {e.returncode})")
+        return False
+
+def main():
+    """Main test runner."""
+    print("🐟 Marine Species Identification API - Test Runner")
+    print("=" * 55)
+    
+    # Change to project directory
+    project_dir = Path(__file__).parent
+    os.chdir(project_dir)
+    
+    success = True
+    
+    # Run pytest tests
+    if not run_pytest():
+        success = False
+    
+    print()
+    
+    # Note about simple test
+    print("📝 Note: To run the simple API test, start the API first:")
+    print("   python start_api.py")
+    print("   # Then in another terminal:")
+    print("   python test_api_simple.py")
+    
+    print("=" * 55)
+    
+    if success:
+        print("🎉 All available tests completed successfully!")
+        return 0
+    else:
+        print("❌ Some tests failed")
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

start_api.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Startup script for the Marine Species Identification API.
+This script handles model downloading and API startup.
+"""
+
+import asyncio
+import sys
+import os
+from pathlib import Path
+
+# Add the app directory to Python path
+sys.path.insert(0, str(Path(__file__).parent))
+
+from app.core.config import settings
+from app.core.logging import setup_logging, get_logger
+from app.utils.model_utils import (
+    download_model_from_hf, 
+    verify_model_file, 
+    setup_model_directory,
+    list_available_files
+)
+
+# Setup logging
+setup_logging()
+logger = get_logger(__name__)
+
+
+async def ensure_model_available():
+    """Ensure the model is downloaded and available."""
+    logger.info("🔍 Checking model availability...")
+    
+    # Setup model directory
+    model_dir = setup_model_directory()
+    logger.info(f"Model directory: {model_dir}")
+    
+    # Check if model file exists
+    if verify_model_file(settings.MODEL_PATH):
+        logger.info("✅ Model file found and verified")
+        return True
+    
+    logger.info("📥 Model not found locally, attempting to download...")
+    
+    try:
+        # List available files in the repository
+        logger.info(f"Checking repository: {settings.HUGGINGFACE_REPO}")
+        available_files = list_available_files(settings.HUGGINGFACE_REPO)
+        
+        if available_files:
+            logger.info(f"Available files in repository:")
+            for file in available_files[:10]:  # Show first 10 files
+                logger.info(f"  - {file}")
+            if len(available_files) > 10:
+                logger.info(f"  ... and {len(available_files) - 10} more files")
+        
+        # Download the model
+        model_filename = f"{settings.MODEL_NAME}.pt"
+        
+        if model_filename in available_files:
+            download_model_from_hf(
+                repo_id=settings.HUGGINGFACE_REPO,
+                model_filename=model_filename,
+                local_dir=model_dir,
+                force_download=False
+            )
+            
+            # Verify the downloaded model
+            if verify_model_file(settings.MODEL_PATH):
+                logger.info("✅ Model downloaded and verified successfully")
+                return True
+            else:
+                logger.error("❌ Downloaded model failed verification")
+                return False
+        else:
+            logger.error(f"❌ Model file '{model_filename}' not found in repository")
+            logger.info("Available .pt files:")
+            pt_files = [f for f in available_files if f.endswith('.pt')]
+            for pt_file in pt_files:
+                logger.info(f"  - {pt_file}")
+            return False
+            
+    except Exception as e:
+        logger.error(f"❌ Failed to download model: {str(e)}")
+        return False
+
+
+def start_api():
+    """Start the FastAPI application."""
+    import uvicorn
+    
+    logger.info("🚀 Starting Marine Species Identification API...")
+    logger.info(f"Host: {settings.HOST}")
+    logger.info(f"Port: {settings.PORT}")
+    logger.info(f"Docs: http://{settings.HOST}:{settings.PORT}/docs")
+    
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=False,
+        log_level="info",
+        access_log=True
+    )
+
+
+async def main():
+    """Main startup function."""
+    logger.info("🐟 Marine Species Identification API Startup")
+    logger.info("=" * 50)
+    
+    # Check model availability
+    model_available = await ensure_model_available()
+    
+    if not model_available:
+        logger.warning("⚠️  Model not available - API will start but inference may fail")
+        logger.info("The API will still start and you can check /health for status")
+    
+    logger.info("=" * 50)
+    
+    # Start the API
+    start_api()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("🛑 API startup interrupted by user")
+    except Exception as e:
+        logger.error(f"❌ Failed to start API: {str(e)}")
+        sys.exit(1)

test_api_simple.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+Simple test script for the Marine Species Identification API.
+This script can be used to quickly test the API functionality.
+"""
+
+import requests
+import base64
+import json
+import time
+from PIL import Image
+import numpy as np
+import io
+
+
+def create_test_image(width: int = 640, height: int = 480) -> str:
+    """Create a test image and return as base64 string."""
+    # Create a simple test image with some patterns
+    image = np.random.randint(0, 255, (height, width, 3), dtype=np.uint8)
+    
+    # Add some simple patterns to make it more interesting
+    image[100:200, 100:200] = [255, 0, 0]  # Red square
+    image[300:400, 300:400] = [0, 255, 0]  # Green square
+    
+    pil_image = Image.fromarray(image)
+    
+    # Convert to base64
+    buffer = io.BytesIO()
+    pil_image.save(buffer, format="JPEG", quality=85)
+    image_bytes = buffer.getvalue()
+    
+    return base64.b64encode(image_bytes).decode('utf-8')
+
+
+def test_api(base_url: str = "http://localhost:7860"):
+    """Test the API endpoints."""
+    
+    print(f"🧪 Testing Marine Species Identification API at {base_url}")
+    print("=" * 60)
+    
+    # Test 1: Root endpoint
+    print("1. Testing root endpoint...")
+    try:
+        response = requests.get(f"{base_url}/")
+        print(f"   Status: {response.status_code}")
+        if response.status_code == 200:
+            print(f"   Response: {response.json()}")
+        print()
+    except Exception as e:
+        print(f"   Error: {e}")
+        return
+    
+    # Test 2: Health check
+    print("2. Testing health check...")
+    try:
+        response = requests.get(f"{base_url}/api/v1/health")
+        print(f"   Status: {response.status_code}")
+        if response.status_code == 200:
+            health_data = response.json()
+            print(f"   API Status: {health_data.get('status')}")
+            print(f"   Model Loaded: {health_data.get('model_loaded')}")
+        print()
+    except Exception as e:
+        print(f"   Error: {e}")
+        print()
+    
+    # Test 3: API info
+    print("3. Testing API info...")
+    try:
+        response = requests.get(f"{base_url}/api/v1/info")
+        print(f"   Status: {response.status_code}")
+        if response.status_code == 200:
+            info_data = response.json()
+            print(f"   API Name: {info_data.get('name')}")
+            print(f"   Version: {info_data.get('version')}")
+            model_info = info_data.get('model_info', {})
+            print(f"   Model Classes: {model_info.get('total_classes')}")
+        print()
+    except Exception as e:
+        print(f"   Error: {e}")
+        print()
+    
+    # Test 4: Species list
+    print("4. Testing species list...")
+    try:
+        response = requests.get(f"{base_url}/api/v1/species")
+        print(f"   Status: {response.status_code}")
+        if response.status_code == 200:
+            species_data = response.json()
+            total_species = species_data.get('total_count', 0)
+            print(f"   Total Species: {total_species}")
+            if total_species > 0:
+                print(f"   First 3 species:")
+                for species in species_data.get('species', [])[:3]:
+                    print(f"     - {species.get('class_name')} (ID: {species.get('class_id')})")
+        print()
+    except Exception as e:
+        print(f"   Error: {e}")
+        print()
+    
+    # Test 5: Detection with test image
+    print("5. Testing marine species detection...")
+    try:
+        # Create a test image
+        print("   Creating test image...")
+        test_image_b64 = create_test_image()
+        
+        # Prepare request
+        detection_request = {
+            "image": test_image_b64,
+            "confidence_threshold": 0.25,
+            "iou_threshold": 0.45,
+            "image_size": 640,
+            "return_annotated_image": True
+        }
+        
+        print("   Sending detection request...")
+        start_time = time.time()
+        
+        response = requests.post(
+            f"{base_url}/api/v1/detect",
+            json=detection_request,
+            timeout=30
+        )
+        
+        end_time = time.time()
+        request_time = end_time - start_time
+        
+        print(f"   Status: {response.status_code}")
+        print(f"   Request Time: {request_time:.2f}s")
+        
+        if response.status_code == 200:
+            detection_data = response.json()
+            detections = detection_data.get('detections', [])
+            processing_time = detection_data.get('processing_time', 0)
+            
+            print(f"   Processing Time: {processing_time:.3f}s")
+            print(f"   Detections Found: {len(detections)}")
+            
+            if detections:
+                print("   Top detections:")
+                for i, detection in enumerate(detections[:3]):
+                    print(f"     {i+1}. {detection.get('class_name')} "
+                          f"(confidence: {detection.get('confidence'):.3f})")
+            
+            # Check if annotated image was returned
+            if detection_data.get('annotated_image'):
+                print("   ✅ Annotated image returned")
+            else:
+                print("   ❌ No annotated image returned")
+                
+        elif response.status_code == 503:
+            print("   ⚠️  Service unavailable (model may not be loaded)")
+        else:
+            print(f"   ❌ Error: {response.text}")
+        
+        print()
+        
+    except Exception as e:
+        print(f"   Error: {e}")
+        print()
+    
+    print("🎉 API testing completed!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    import sys
+    
+    # Allow custom base URL
+    base_url = sys.argv[1] if len(sys.argv) > 1 else "http://localhost:7860"
+    
+    test_api(base_url)

tests/__init__.py

@@ -0,0 +1 @@
+# Test package

tests/test_api.py

@@ -0,0 +1,175 @@
+"""
+Basic API tests for the Marine Species Identification API.
+"""
+
+import pytest
+import base64
+import io
+from PIL import Image
+import numpy as np
+from fastapi.testclient import TestClient
+
+from app.main import app
+
+client = TestClient(app)
+
+
+def create_test_image(width: int = 640, height: int = 480) -> str:
+    """Create a test image and return as base64 string."""
+    # Create a simple test image
+    image = np.random.randint(0, 255, (height, width, 3), dtype=np.uint8)
+    pil_image = Image.fromarray(image)
+    
+    # Convert to base64
+    buffer = io.BytesIO()
+    pil_image.save(buffer, format="JPEG")
+    image_bytes = buffer.getvalue()
+    
+    return base64.b64encode(image_bytes).decode('utf-8')
+
+
+class TestHealthEndpoints:
+    """Test health and status endpoints."""
+    
+    def test_root_endpoint(self):
+        """Test root endpoint."""
+        response = client.get("/")
+        assert response.status_code == 200
+        data = response.json()
+        assert "message" in data
+        assert "version" in data
+    
+    def test_root_health(self):
+        """Test root health endpoint."""
+        response = client.get("/health")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "ok"
+    
+    def test_health_check(self):
+        """Test detailed health check."""
+        response = client.get("/api/v1/health")
+        assert response.status_code == 200
+        data = response.json()
+        assert "status" in data
+        assert "model_loaded" in data
+        assert "timestamp" in data
+    
+    def test_api_info(self):
+        """Test API info endpoint."""
+        response = client.get("/api/v1/info")
+        assert response.status_code == 200
+        data = response.json()
+        assert "name" in data
+        assert "version" in data
+        assert "endpoints" in data
+    
+    def test_liveness_check(self):
+        """Test liveness probe."""
+        response = client.get("/api/v1/live")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["status"] == "alive"
+
+
+class TestSpeciesEndpoints:
+    """Test species-related endpoints."""
+    
+    def test_list_species(self):
+        """Test species list endpoint."""
+        response = client.get("/api/v1/species")
+        assert response.status_code in [200, 503]  # May fail if model not loaded
+        
+        if response.status_code == 200:
+            data = response.json()
+            assert "species" in data
+            assert "total_count" in data
+            assert isinstance(data["species"], list)
+    
+    def test_get_species_info(self):
+        """Test individual species info endpoint."""
+        # This may fail if model is not loaded, which is expected in test environment
+        response = client.get("/api/v1/species/0")
+        assert response.status_code in [200, 404, 503]
+
+
+class TestInferenceEndpoints:
+    """Test inference endpoints."""
+    
+    def test_detect_invalid_image(self):
+        """Test detection with invalid image data."""
+        response = client.post(
+            "/api/v1/detect",
+            json={
+                "image": "invalid_base64_data",
+                "confidence_threshold": 0.25
+            }
+        )
+        assert response.status_code in [400, 503]  # Bad request or service unavailable
+    
+    def test_detect_valid_request_format(self):
+        """Test detection with valid request format."""
+        test_image = create_test_image()
+        
+        response = client.post(
+            "/api/v1/detect",
+            json={
+                "image": test_image,
+                "confidence_threshold": 0.25,
+                "iou_threshold": 0.45,
+                "image_size": 640,
+                "return_annotated_image": True
+            }
+        )
+        
+        # May return 503 if model is not loaded, which is expected in test environment
+        assert response.status_code in [200, 503]
+        
+        if response.status_code == 200:
+            data = response.json()
+            assert "detections" in data
+            assert "processing_time" in data
+            assert "model_info" in data
+            assert "image_dimensions" in data
+    
+    def test_detect_parameter_validation(self):
+        """Test parameter validation."""
+        test_image = create_test_image()
+        
+        # Test invalid confidence threshold
+        response = client.post(
+            "/api/v1/detect",
+            json={
+                "image": test_image,
+                "confidence_threshold": 1.5  # Invalid: > 1.0
+            }
+        )
+        assert response.status_code == 422  # Validation error
+        
+        # Test invalid image size
+        response = client.post(
+            "/api/v1/detect",
+            json={
+                "image": test_image,
+                "image_size": 100  # Invalid: < 320
+            }
+        )
+        assert response.status_code == 422  # Validation error
+
+
+class TestErrorHandling:
+    """Test error handling."""
+    
+    def test_404_endpoint(self):
+        """Test non-existent endpoint."""
+        response = client.get("/api/v1/nonexistent")
+        assert response.status_code == 404
+    
+    def test_method_not_allowed(self):
+        """Test wrong HTTP method."""
+        response = client.get("/api/v1/detect")  # Should be POST
+        assert response.status_code == 405
+
+
+if __name__ == "__main__":
+    pytest.main([__file__])