initial project setup with README and ignore

app/models/__init__.py

@@ -0,0 +1,21 @@
+"""Models package."""
+
+from .schemas import (
+    Location,
+    Delivery,
+    RouteOptimizationRequest,
+    RouteStep,
+    OptimizedRoute,
+    PickupLocation,
+    DeliveryLocation
+)
+
+__all__ = [
+    "Location",
+    "Delivery",
+    "RouteOptimizationRequest",
+    "RouteStep",
+    "OptimizedRoute",
+    "PickupLocation",
+    "DeliveryLocation"
+]

app/models/errors.py

@@ -0,0 +1,45 @@
+"""Professional error response models for API."""
+
+from typing import Optional, Any, Dict
+from pydantic import BaseModel, Field
+from datetime import datetime
+
+
+class ErrorDetail(BaseModel):
+    """Detailed error information."""
+    field: Optional[str] = Field(None, description="Field name that caused the error")
+    message: str = Field(..., description="Error message")
+    code: Optional[str] = Field(None, description="Error code")
+
+
+class ErrorResponse(BaseModel):
+    """Standardized error response model."""
+    success: bool = Field(False, description="Request success status")
+    error: ErrorDetail = Field(..., description="Error details")
+    timestamp: str = Field(default_factory=lambda: datetime.utcnow().isoformat(), description="Error timestamp")
+    path: Optional[str] = Field(None, description="Request path")
+    request_id: Optional[str] = Field(None, description="Request ID for tracing")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "success": False,
+                "error": {
+                    "field": "pickup_location",
+                    "message": "Pickup location is required",
+                    "code": "VALIDATION_ERROR"
+                },
+                "timestamp": "2024-01-15T10:30:00.000Z",
+                "path": "/api/v1/optimization/single-route",
+                "request_id": "req-123456"
+            }
+        }
+
+
+class SuccessResponse(BaseModel):
+    """Standardized success response wrapper."""
+    success: bool = Field(True, description="Request success status")
+    data: Any = Field(..., description="Response data")
+    timestamp: str = Field(default_factory=lambda: datetime.utcnow().isoformat(), description="Response timestamp")
+    request_id: Optional[str] = Field(None, description="Request ID for tracing")
+

app/models/schemas.py

@@ -0,0 +1,167 @@
+"""Professional Pydantic models for request/response validation."""
+
+from typing import List, Optional
+from pydantic import BaseModel, Field, field_validator
+from datetime import datetime
+
+
+class Location(BaseModel):
+    """Location model with latitude and longitude."""
+    lat: float = Field(..., description="Latitude")
+    lng: float = Field(..., description="Longitude")
+
+
+class PickupLocation(BaseModel):
+    """Pickup location model with latitude and longitude."""
+    pickuplat: float = Field(
+        ..., 
+        description="Pickup latitude",
+        ge=-90, 
+        le=90,
+        examples=[11.0050534]
+    )
+    pickuplon: float = Field(
+        ..., 
+        description="Pickup longitude",
+        ge=-180, 
+        le=180,
+        examples=[76.9508991]
+    )
+    
+    @field_validator("pickuplat", "pickuplon")
+    @classmethod
+    def validate_coordinates(cls, v):
+        """Validate coordinate values."""
+        if v is None:
+            raise ValueError("Coordinate cannot be None")
+        return float(v)
+
+
+class DeliveryLocation(BaseModel):
+    """Delivery location model with latitude and longitude."""
+    deliverylat: float = Field(
+        ..., 
+        description="Delivery latitude",
+        ge=-90, 
+        le=90,
+        examples=[11.0309723]
+    )
+    deliverylong: float = Field(
+        ..., 
+        description="Delivery longitude",
+        ge=-180, 
+        le=180,
+        examples=[77.0004574]
+    )
+    
+    @field_validator("deliverylat", "deliverylong")
+    @classmethod
+    def validate_coordinates(cls, v):
+        """Validate coordinate values."""
+        if v is None:
+            raise ValueError("Coordinate cannot be None")
+        return float(v)
+
+
+class Delivery(BaseModel):
+    """Delivery order model."""
+    deliveryid: str = Field(..., description="Unique delivery identifier")
+    deliverycustomerid: int = Field(..., description="Customer ID for this delivery")
+    location: DeliveryLocation = Field(..., description="Delivery location coordinates")
+
+
+class RouteOptimizationRequest(BaseModel):
+    """
+    Request model for route optimization.
+    
+    Optimizes delivery routes starting from a pickup location (warehouse/store) to multiple delivery locations.
+    Uses greedy nearest-neighbor algorithm for fast, efficient route calculation.
+    """
+    pickup_location: PickupLocation = Field(
+        ..., 
+        description="Pickup location (warehouse/store) coordinates - starting point for optimization"
+    )
+    pickup_location_id: Optional[int] = Field(
+        None, 
+        description="Optional pickup location ID for tracking purposes"
+    )
+    deliveries: List[Delivery] = Field(
+        ..., 
+        min_items=1,
+        max_items=50,
+        description="List of delivery locations to optimize (1-50 deliveries supported)"
+    )
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "pickup_location": {
+                    "pickuplat": 11.0050534,
+                    "pickuplon": 76.9508991
+                },
+                "pickup_location_id": 1,
+                "deliveries": [
+                    {
+                        "deliveryid": "90465",
+                        "deliverycustomerid": 1,
+                        "location": {
+                            "deliverylat": 11.0309723,
+                            "deliverylong": 77.0004574
+                        }
+                    }
+                ]
+            }
+        }
+
+
+class RouteStep(BaseModel):
+    """Single step in the optimized route."""
+    step_number: int = Field(..., description="Step number in the route")
+    delivery_id: str = Field(..., description="Delivery ID for this step")
+    delivery_customer_id: int = Field(..., description="Customer ID for this delivery")
+    location: DeliveryLocation = Field(..., description="Delivery location coordinates")
+    distance_from_previous_km: float = Field(..., description="Distance from previous step in kilometers")
+    cumulative_distance_km: float = Field(..., description="Total distance traveled so far in kilometers")
+
+
+class OptimizedRoute(BaseModel):
+    """
+    Optimized route response with step-by-step delivery sequence.
+    
+    Contains the optimized route starting from pickup location, with each step showing:
+    - Delivery order (Step 1, Step 2, etc.)
+    - Distance from previous step
+    - Cumulative distance traveled
+    """
+    route_id: str = Field(..., description="Unique route identifier (UUID)")
+    pickup_location_id: Optional[int] = Field(None, description="Pickup location ID")
+    pickup_location: PickupLocation = Field(..., description="Pickup location (warehouse/store) coordinates")
+    total_distance_km: float = Field(
+        ..., 
+        ge=0,
+        description="Total route distance in kilometers",
+        examples=[12.45]
+    )
+    total_deliveries: int = Field(
+        ..., 
+        ge=1,
+        description="Total number of deliveries in the route",
+        examples=[5]
+    )
+    optimization_algorithm: str = Field(
+        "greedy",
+        description="Algorithm used for optimization",
+        examples=["greedy"]
+    )
+    steps: List[RouteStep] = Field(
+        ..., 
+        description="Ordered list of route steps (Step 1 = nearest from pickup, Step 2 = nearest from Step 1, etc.)"
+    )
+    created_at: str = Field(
+        default_factory=lambda: datetime.utcnow().isoformat(),
+        description="Route creation timestamp (ISO 8601)"
+    )
+
+
+# Batch optimization removed - no rider support needed
+# Use single-route optimization for each pickup location