protoype integration completed

DataService/README.md

@@ -0,0 +1,391 @@
+# Metro Train Scheduling System - DataService API
+
+A comprehensive FastAPI-based service for generating synthetic metro train scheduling data and optimizing daily train operations.
+
+## 🎯 Overview
+
+This system generates realistic metro train schedules for a single-line metro network with:
+- **25-40 trainsets** with varying health status
+- **25 stations** on a bidirectional route
+- **Operating hours**: 5:00 AM - 11:00 PM
+- **Real-world constraints**: maintenance, fitness certificates, branding priorities, mileage balancing
+
+## 🚇 Features
+
+### Data Generation
+- **Train Health Status**: Fully healthy, partially available, or under maintenance
+- **Fitness Certificates**: Rolling stock, signalling, and telecom certificates with expiry tracking
+- **Job Cards**: Open maintenance tasks with blocking status
+- **Component Health**: IoT-style monitoring of brakes, HVAC, doors, bogies, etc.
+- **Branding/Advertising**: Contract tracking with exposure priorities
+- **Depot Layout**: Stabling bays, IBL bays, and washing bays
+
+### Schedule Optimization
+- **Multi-objective optimization** balancing:
+  - Service readiness (35%)
+  - Mileage balancing (25%)
+  - Branding priority (20%)
+  - Operational cost (20%)
+- **Constraint satisfaction**: Fitness certificates, maintenance requirements, availability windows
+- **Service block generation**: Optimal trip assignments throughout the day
+- **Fleet allocation**: Revenue service, standby, maintenance, and cleaning assignments
+
+### API Endpoints
+
+#### Generate Complete Schedule
+```bash
+POST /api/v1/generate
+Content-Type: application/json
+
+{
+  "date": "2025-10-25",
+  "num_trains": 30,
+  "num_stations": 25,
+  "route_name": "Aluva-Pettah Line",
+  "depot_name": "Muttom_Depot",
+  "min_service_trains": 22,
+  "min_standby_trains": 3,
+  "max_daily_km_per_train": 300,
+  "balance_mileage": true,
+  "prioritize_branding": true
+}
+```
+
+#### Quick Schedule Generation
+```bash
+POST /api/v1/generate/quick?date=2025-10-25&num_trains=30&num_stations=25
+```
+
+#### Get Example Schedule
+```bash
+GET /api/v1/schedule/example
+```
+
+#### Get Route Information
+```bash
+GET /api/v1/route/25
+```
+
+#### Get Train Health Status
+```bash
+GET /api/v1/trains/health/30
+```
+
+#### Get Depot Layout
+```bash
+GET /api/v1/depot/layout
+```
+
+## 📦 Installation
+
+### Prerequisites
+- Python 3.8+
+- pip
+
+### Setup
+
+1. **Clone the repository**
+```bash
+cd /home/arpbansal/code/sih2025/mlservice
+```
+
+2. **Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+Requirements include:
+- `fastapi>=0.104.1` - Web framework
+- `uvicorn[standard]>=0.24.0` - ASGI server
+- `pydantic>=2.5.0` - Data validation
+- `ortools>=9.14.6206` - Optimization (optional)
+
+## 🚀 Usage
+
+### Option 1: Run Demo Script
+
+Test the system without starting the API:
+
+```bash
+python demo_schedule.py
+```
+
+This will:
+- Generate synthetic metro data
+- Optimize a daily schedule
+- Display comprehensive results
+- Save output to `sample_schedule.json`
+
+### Option 2: Start FastAPI Server
+
+```bash
+python run_api.py
+```
+
+The API will be available at:
+- **Base URL**: http://localhost:8000
+- **Interactive Docs**: http://localhost:8000/docs
+- **Alternative Docs**: http://localhost:8000/redoc
+
+### Option 3: Use uvicorn directly
+
+```bash
+uvicorn DataService.api:app --reload --host 0.0.0.0 --port 8000
+```
+
+## 📊 Schedule Output Structure
+
+```json
+{
+  "schedule_id": "KMRL-2025-10-25-DAWN",
+  "generated_at": "2025-10-24T23:45:00+05:30",
+  "valid_from": "2025-10-25T05:00:00+05:30",
+  "valid_until": "2025-10-25T23:00:00+05:30",
+  "depot": "Muttom_Depot",
+  
+  "trainsets": [
+    {
+      "trainset_id": "TS-001",
+      "status": "REVENUE_SERVICE",
+      "priority_rank": 1,
+      "assigned_duty": "DUTY-A1",
+      "service_blocks": [
+        {
+          "block_id": "BLK-001",
+          "departure_time": "05:30",
+          "origin": "Aluva",
+          "destination": "Pettah",
+          "trip_count": 3,
+          "estimated_km": 96
+        }
+      ],
+      "daily_km_allocation": 224,
+      "cumulative_km": 145620,
+      "fitness_certificates": {
+        "rolling_stock": {"valid_until": "2025-11-15", "status": "VALID"},
+        "signalling": {"valid_until": "2025-10-30", "status": "VALID"},
+        "telecom": {"valid_until": "2025-11-20", "status": "VALID"}
+      },
+      "job_cards": {"open": 0, "blocking": []},
+      "branding": {
+        "advertiser": "COCACOLA-2024",
+        "contract_hours_remaining": 340,
+        "exposure_priority": "HIGH"
+      },
+      "readiness_score": 0.98,
+      "constraints_met": true
+    }
+  ],
+  
+  "fleet_summary": {
+    "total_trainsets": 30,
+    "revenue_service": 22,
+    "standby": 4,
+    "maintenance": 2,
+    "cleaning": 2,
+    "availability_percent": 93.3
+  },
+  
+  "optimization_metrics": {
+    "mileage_variance_coefficient": 0.042,
+    "avg_readiness_score": 0.91,
+    "branding_sla_compliance": 1.0,
+    "shunting_movements_required": 8,
+    "total_planned_km": 5280,
+    "fitness_expiry_violations": 0
+  },
+  
+  "conflicts_and_alerts": [...],
+  "decision_rationale": {...}
+}
+```
+
+## 🏗️ Architecture
+
+```
+mlservice/
+├── DataService/
+│   ├── __init__.py
+│   ├── api.py                    # FastAPI application
+│   ├── metro_models.py           # Pydantic data models
+│   ├── metro_data_generator.py   # Synthetic data generation
+│   ├── schedule_optimizer.py     # Schedule optimization logic
+│   ├── enhanced_generator.py     # (existing)
+│   ├── synthetic_base.py         # (existing)
+│   └── synthetic_extend.py       # (existing)
+├── greedyOptim/                  # Optimization algorithms
+├── demo_schedule.py              # Demo/test script
+├── run_api.py                    # API startup script
+├── requirements.txt
+└── README.md
+```
+
+## 🔧 Configuration
+
+### Train Health Categories
+
+- **Fully Healthy** (65%): Available entire operational day
+- **Partially Healthy** (20%): Available for limited hours
+- **Unavailable** (15%): Not available for service (maintenance/repairs)
+
+### Train Status Types
+
+- `REVENUE_SERVICE`: Active passenger service
+- `STANDBY`: Ready for deployment
+- `MAINTENANCE`: Under repair/inspection
+- `CLEANING`: Washing/interior cleaning
+- `OUT_OF_SERVICE`: Long-term unavailable
+
+### Optimization Weights
+
+Default objective weights (configurable):
+```python
+{
+  "service_readiness": 0.35,
+  "mileage_balancing": 0.25,
+  "branding_priority": 0.20,
+  "operational_cost": 0.20
+}
+```
+
+## 📝 API Examples
+
+### cURL Examples
+
+**Generate schedule:**
+```bash
+curl -X POST "http://localhost:8000/api/v1/generate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "date": "2025-10-25",
+    "num_trains": 30,
+    "num_stations": 25,
+    "min_service_trains": 22
+  }'
+```
+
+**Quick generation:**
+```bash
+curl "http://localhost:8000/api/v1/generate/quick?date=2025-10-25&num_trains=30"
+```
+
+**Health check:**
+```bash
+curl "http://localhost:8000/health"
+```
+
+### Python Client Example
+
+```python
+import requests
+
+# Generate schedule
+response = requests.post(
+    "http://localhost:8000/api/v1/generate",
+    json={
+        "date": "2025-10-25",
+        "num_trains": 30,
+        "num_stations": 25,
+        "min_service_trains": 22,
+        "min_standby_trains": 3
+    }
+)
+
+schedule = response.json()
+print(f"Schedule ID: {schedule['schedule_id']}")
+print(f"Trains in service: {schedule['fleet_summary']['revenue_service']}")
+```
+
+## 🧪 Testing
+
+Run the demo script to test all functionality:
+
+```bash
+python demo_schedule.py
+```
+
+Expected output:
+- ✓ Data generation statistics
+- ✓ Route information
+- ✓ Train health summary
+- ✓ Optimization results
+- ✓ Fleet status breakdown
+- ✓ Sample train details
+- ✓ JSON export
+
+## 🎨 Key Concepts
+
+### Service Blocks
+Continuous operating periods with specific origin/destination and trip counts. Each block represents a trainset's assignment for part of the day.
+
+### Readiness Score
+Computed metric (0.0-1.0) considering:
+- Fitness certificate validity
+- Open/blocking job cards
+- Component health scores
+- Days since maintenance
+
+### Mileage Balancing
+Distributes daily kilometers to equalize cumulative mileage across the fleet, extending overall fleet life.
+
+### Branding Priority
+Trains with active advertising contracts get preferential assignment to maximize exposure (revenue optimization).
+
+## 🔍 Monitoring & Alerts
+
+The system generates alerts for:
+- Certificate expirations (EXPIRING_SOON, EXPIRED)
+- Blocking maintenance (job cards preventing service)
+- Fitness violations
+- Constraint conflicts
+
+## 🤝 Integration
+
+### With Existing Optimizer
+
+The DataService can integrate with existing `greedyOptim` algorithms:
+
+```python
+from greedyOptim.scheduler import TrainsetSchedulingOptimizer
+from DataService.metro_data_generator import MetroDataGenerator
+
+# Generate synthetic data
+generator = MetroDataGenerator(num_trains=30)
+# ... use with existing optimizer
+```
+
+### As Microservice
+
+Deploy as standalone microservice:
+```bash
+docker build -t metro-scheduler .
+docker run -p 8000:8000 metro-scheduler
+```
+
+## 📈 Future Enhancements
+
+- [ ] Real-time schedule adjustments
+- [ ] Machine learning for demand prediction
+- [ ] Driver/crew scheduling integration
+- [ ] Energy consumption optimization
+- [ ] Passenger flow simulation
+- [ ] Weather impact modeling
+- [ ] Multi-line network support
+
+## 📄 License
+
+[Add your license information]
+
+## 👥 Contributors
+
+[Add contributor information]
+
+## 📞 Support
+
+For issues, questions, or contributions:
+- GitHub Issues: [repository URL]
+- Email: [contact email]
+
+---
+
+**Built for Smart India Hackathon 2025** 🇮🇳

DataService/__init__.py

@@ -0,0 +1,29 @@
+"""
+DataService - Metro Train Scheduling Data Generation and API
+"""
+
+from .metro_models import (
+    DaySchedule, Trainset, TrainStatus, ServiceBlock,
+    ScheduleRequest, Route, Station, TrainHealthStatus,
+    FitnessCertificates, JobCards, Branding
+)
+from .metro_data_generator import MetroDataGenerator
+from .schedule_optimizer import MetroScheduleOptimizer
+
+__all__ = [
+    'DaySchedule',
+    'Trainset',
+    'TrainStatus',
+    'ServiceBlock',
+    'ScheduleRequest',
+    'Route',
+    'Station',
+    'TrainHealthStatus',
+    'FitnessCertificates',
+    'JobCards',
+    'Branding',
+    'MetroDataGenerator',
+    'MetroScheduleOptimizer',
+]
+
+__version__ = '1.0.0'

DataService/api.py

@@ -0,0 +1,275 @@
+"""
+FastAPI Service for Metro Train Schedule Generation
+Provides endpoints for synthetic data generation and schedule optimization
+"""
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import ValidationError
+from datetime import datetime
+import logging
+
+from .metro_models import (
+    DaySchedule, ScheduleRequest, Route, TrainHealthStatus
+)
+from .metro_data_generator import MetroDataGenerator
+from .schedule_optimizer import MetroScheduleOptimizer
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Create FastAPI app
+app = FastAPI(
+    title="Metro Train Scheduling API",
+    description="Generate synthetic metro data and optimize daily train schedules",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure appropriately for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/")
+async def root():
+    """Root endpoint with API information"""
+    return {
+        "service": "Metro Train Scheduling API",
+        "version": "1.0.0",
+        "endpoints": {
+            "schedule": "/api/v1/schedule",
+            "generate": "/api/v1/generate",
+            "health": "/health",
+            "docs": "/docs"
+        }
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "timestamp": datetime.now().isoformat(),
+        "service": "metro-scheduling-api"
+    }
+
+
+@app.post("/api/v1/generate", response_model=DaySchedule)
+async def generate_schedule(request: ScheduleRequest):
+    """
+    Generate optimized daily train schedule
+    
+    Args:
+        request: Schedule request with date, train count, and optimization parameters
+        
+    Returns:
+        DaySchedule: Complete optimized schedule with all trainset assignments
+        
+    Example:
+        POST /api/v1/generate
+        {
+            "date": "2025-10-25",
+            "num_trains": 30,
+            "num_stations": 25,
+            "min_service_trains": 22,
+            "min_standby_trains": 3
+        }
+    """
+    try:
+        logger.info(f"Generating schedule for {request.date} with {request.num_trains} trains")
+        
+        # Initialize data generator
+        generator = MetroDataGenerator(
+            num_trains=request.num_trains,
+            num_stations=request.num_stations
+        )
+        
+        # Generate route
+        route = generator.generate_route(request.route_name)
+        logger.info(f"Generated route: {route.name} with {len(route.stations)} stations")
+        
+        # Generate or use provided train health data
+        if request.train_health_overrides:
+            train_health = request.train_health_overrides
+        else:
+            train_health = generator.generate_train_health_statuses()
+        
+        logger.info(f"Train health data: {len(train_health)} trains initialized")
+        
+        # Initialize optimizer
+        optimizer = MetroScheduleOptimizer(
+            date=request.date,
+            num_trains=request.num_trains,
+            route=route,
+            train_health=train_health,
+            depot_name=request.depot_name
+        )
+        
+        # Optimize schedule
+        schedule = optimizer.optimize_schedule(
+            min_service_trains=request.min_service_trains,
+            min_standby=request.min_standby_trains,
+            max_daily_km=request.max_daily_km_per_train
+        )
+        
+        logger.info(
+            f"Schedule generated: {schedule.schedule_id}, "
+            f"{schedule.fleet_summary.revenue_service} trains in service, "
+            f"{schedule.optimization_metrics.total_planned_km} km planned"
+        )
+        
+        return schedule
+        
+    except ValidationError as e:
+        logger.error(f"Validation error: {e}")
+        raise HTTPException(status_code=422, detail=str(e))
+    except Exception as e:
+        logger.error(f"Error generating schedule: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+
+@app.post("/api/v1/generate/quick")
+async def generate_quick_schedule(
+    date: str = "2025-10-25",
+    num_trains: int = 25,
+    num_stations: int = 25
+):
+    """
+    Quick schedule generation with default parameters
+    
+    Query Parameters:
+        - date: Schedule date (YYYY-MM-DD)
+        - num_trains: Number of trains in fleet (default: 25)
+        - num_stations: Number of stations on route (default: 25)
+    """
+    request = ScheduleRequest(
+        date=date,
+        num_trains=num_trains,
+        num_stations=num_stations
+    )
+    return await generate_schedule(request)
+
+
+@app.get("/api/v1/route/{num_stations}")
+async def get_route_info(num_stations: int = 25):
+    """
+    Get metro route information
+    
+    Args:
+        num_stations: Number of stations to include (default: 25)
+        
+    Returns:
+        Route information with all stations
+    """
+    try:
+        generator = MetroDataGenerator(num_stations=num_stations)
+        route = generator.generate_route()
+        
+        return {
+            "route": route.model_dump(),
+            "one_way_time_minutes": int((route.total_distance_km / route.avg_speed_kmh) * 60),
+            "round_trip_time_minutes": int((route.total_distance_km / route.avg_speed_kmh) * 60 * 2) + route.turnaround_time_minutes * 2
+        }
+    except Exception as e:
+        logger.error(f"Error generating route: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/trains/health/{num_trains}")
+async def get_train_health(num_trains: int = 25):
+    """
+    Generate train health status data
+    
+    Args:
+        num_trains: Number of trains (default: 25)
+        
+    Returns:
+        List of train health statuses
+    """
+    try:
+        generator = MetroDataGenerator(num_trains=num_trains)
+        health_data = generator.generate_train_health_statuses()
+        
+        summary = {
+            "total": len(health_data),
+            "fully_healthy": sum(1 for h in health_data if h.is_fully_healthy),
+            "partial": sum(1 for h in health_data if not h.is_fully_healthy and h.available_hours),
+            "unavailable": sum(1 for h in health_data if not h.is_fully_healthy and not h.available_hours)
+        }
+        
+        return {
+            "summary": summary,
+            "trains": [h.dict() for h in health_data]
+        }
+    except Exception as e:
+        logger.error(f"Error generating train health: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/depot/layout")
+async def get_depot_layout():
+    """Get depot bay layout information"""
+    try:
+        generator = MetroDataGenerator()
+        layout = generator.generate_depot_layout()
+        
+        return {
+            "depot": "Muttom_Depot",
+            "layout": layout,
+            "total_bays": sum(len(bays) for bays in layout.values())
+        }
+    except Exception as e:
+        logger.error(f"Error generating depot layout: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/v1/schedule/example")
+async def get_example_schedule():
+    """Get an example schedule for demonstration"""
+    request = ScheduleRequest(
+        date=datetime.now().strftime("%Y-%m-%d"),
+        num_trains=30,
+        num_stations=25,
+        min_service_trains=22,
+        min_standby_trains=4
+    )
+    return await generate_schedule(request)
+
+
+# Error handlers
+@app.exception_handler(404)
+async def not_found_handler(request, exc):
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": "Not Found",
+            "message": "The requested resource was not found",
+            "path": str(request.url)
+        }
+    )
+
+
+@app.exception_handler(500)
+async def internal_error_handler(request, exc):
+    logger.error(f"Internal server error: {exc}", exc_info=True)
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": "Internal Server Error",
+            "message": "An unexpected error occurred"
+        }
+    )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000, log_level="info")

DataService/metro_data_generator.py

@@ -0,0 +1,233 @@
+"""
+Enhanced Metro Synthetic Data Generator
+Generates realistic metro train scheduling data with time-based constraints
+"""
+import random
+import uuid
+from datetime import datetime, timedelta, time
+from typing import List, Dict, Tuple
+from .metro_models import (
+    TrainHealthStatus, Station, Route, FitnessCertificates,
+    FitnessCertificate, CertificateStatus, JobCards, Branding
+)
+
+
+class MetroDataGenerator:
+    """Generate synthetic data for metro train scheduling"""
+    
+    STATIONS_ALUVA_PETTAH = [
+        "Aluva", "Pulinchodu", "Companypadi", "Ambattukavu", "Muttom",
+        "Kalamassery", "Cochin University", "Pathadipalam", "Edapally",
+        "Changampuzha Park", "Palarivattom", "J.L.N Stadium", "Kaloor",
+        "Town Hall", "M.G. Road", "Maharaja's College", "Ernakulam South",
+        "Kadavanthra", "Elamkulam", "Vyttila", "Thaikoodam", "Petta",
+        "Vadakkekotta", "SN Junction", "Pettah"
+    ]
+    
+    DEPOT_BAYS = [f"BAY-{str(i).zfill(2)}" for i in range(1, 16)]
+    IBL_BAYS = [f"IBL-{str(i).zfill(2)}" for i in range(1, 6)]
+    WASH_BAYS = [f"WASH-BAY-{str(i).zfill(2)}" for i in range(1, 4)]
+    
+    ADVERTISERS = [
+        "COCACOLA-2024", "FLIPKART-FESTIVE", "AMAZON-PRIME",
+        "RELIANCE-JIO", "TATA-MOTORS", "SAMSUNG-GALAXY",
+        "NONE"
+    ]
+    
+    UNAVAILABLE_REASONS = [
+        "SCHEDULED_MAINTENANCE", "BRAKE_SYSTEM_REPAIR",
+        "HVAC_REPLACEMENT", "BOGIE_OVERHAUL", "ELECTRICAL_FAULT",
+        "ACCIDENT_DAMAGE", "PANTOGRAPH_REPAIR", "DOOR_SYSTEM_FAULT"
+    ]
+    
+    def __init__(self, num_trains: int = 25, num_stations: int = 25):
+        self.num_trains = num_trains
+        self.num_stations = min(num_stations, len(self.STATIONS_ALUVA_PETTAH))
+        self.trainset_ids = [f"TS-{str(i+1).zfill(3)}" for i in range(num_trains)]
+        
+    def generate_route(self, route_name: str = "Aluva-Pettah Line") -> Route:
+        """Generate metro route with stations"""
+        stations = []
+        total_distance = 25.612  # Actual KMRL distance
+        
+        for i in range(self.num_stations):
+            distance = (total_distance / (self.num_stations - 1)) * i
+            station = Station(
+                station_id=f"STN-{str(i+1).zfill(3)}",
+                name=self.STATIONS_ALUVA_PETTAH[i],
+                sequence=i + 1,
+                distance_from_origin_km=round(distance, 2),
+                avg_dwell_time_seconds=random.randint(20, 45)
+            )
+            stations.append(station)
+        
+        return Route(
+            route_id="KMRL-LINE-01",
+            name=route_name,
+            stations=stations,
+            total_distance_km=total_distance,
+            avg_speed_kmh=random.randint(32, 38),
+            turnaround_time_minutes=random.randint(8, 12)
+        )
+    
+    def generate_train_health_statuses(self) -> List[TrainHealthStatus]:
+        """Generate health status for all trains"""
+        statuses = []
+        
+        for i, ts_id in enumerate(self.trainset_ids):
+            # Determine train health category
+            health_roll = random.random()
+            
+            if health_roll < 0.65:  # 65% fully healthy
+                is_healthy = True
+                available_hours = None
+                reason = None
+            elif health_roll < 0.85:  # 20% partially healthy
+                is_healthy = False
+                # Random availability window
+                start_hour = random.randint(5, 12)
+                end_hour = random.randint(start_hour + 4, 23)
+                available_hours = [(time(start_hour, 0), time(end_hour, 0))]
+                reason = f"Limited availability: {random.choice(['Minor repairs', 'Partial maintenance', 'Certificate renewal pending'])}"
+            else:  # 15% unavailable
+                is_healthy = False
+                available_hours = []
+                reason = random.choice(self.UNAVAILABLE_REASONS)
+            
+            status = TrainHealthStatus(
+                trainset_id=ts_id,
+                is_fully_healthy=is_healthy,
+                available_hours=available_hours,
+                unavailable_reason=reason,
+                cumulative_mileage=random.randint(50000, 200000),
+                days_since_maintenance=random.randint(1, 45),
+                component_health={
+                    "brakes": random.uniform(0.7, 1.0),
+                    "hvac": random.uniform(0.65, 1.0),
+                    "doors": random.uniform(0.7, 1.0),
+                    "bogies": random.uniform(0.75, 1.0),
+                    "pantograph": random.uniform(0.7, 1.0),
+                    "battery": random.uniform(0.65, 1.0),
+                    "motor": random.uniform(0.75, 1.0)
+                }
+            )
+            statuses.append(status)
+        
+        return statuses
+    
+    def generate_fitness_certificates(self, train_id: str) -> FitnessCertificates:
+        """Generate fitness certificates for a train"""
+        now = datetime.now()
+        
+        def random_cert_status() -> Tuple[str, CertificateStatus]:
+            roll = random.random()
+            if roll < 0.75:  # 75% valid
+                days_valid = random.randint(10, 60)
+                return (now + timedelta(days=days_valid)).isoformat(), CertificateStatus.VALID
+            elif roll < 0.90:  # 15% expiring soon
+                days_valid = random.randint(1, 9)
+                return (now + timedelta(days=days_valid)).isoformat(), CertificateStatus.EXPIRING_SOON
+            else:  # 10% expired
+                days_expired = random.randint(1, 5)
+                return (now - timedelta(days=days_expired)).isoformat(), CertificateStatus.EXPIRED
+        
+        rs_date, rs_status = random_cert_status()
+        sig_date, sig_status = random_cert_status()
+        tel_date, tel_status = random_cert_status()
+        
+        return FitnessCertificates(
+            rolling_stock=FitnessCertificate(valid_until=rs_date, status=rs_status),
+            signalling=FitnessCertificate(valid_until=sig_date, status=sig_status),
+            telecom=FitnessCertificate(valid_until=tel_date, status=tel_status)
+        )
+    
+    def generate_job_cards(self, train_id: str) -> JobCards:
+        """Generate job cards for a train"""
+        num_open = random.choices([0, 1, 2, 3, 4, 5], weights=[50, 25, 15, 7, 2, 1])[0]
+        
+        blocking = []
+        if num_open > 0:
+            num_blocking = random.choices([0, 1, 2, 3], weights=[70, 20, 8, 2])[0]
+            if num_blocking > 0:
+                components = ["BRAKE", "HVAC", "DOOR", "BOGIE", "PANTOGRAPH", "ELECTRICAL"]
+                selected = random.sample(components, min(num_blocking, len(components)))
+                blocking = [f"JC-{random.randint(40000, 49999)}-{comp}" for comp in selected]
+        
+        return JobCards(open=num_open, blocking=blocking)
+    
+    def generate_branding(self) -> Branding:
+        """Generate branding information"""
+        advertiser = random.choice(self.ADVERTISERS)
+        
+        if advertiser == "NONE":
+            return Branding(
+                advertiser="NONE",
+                contract_hours_remaining=0,
+                exposure_priority="NONE"
+            )
+        
+        return Branding(
+            advertiser=advertiser,
+            contract_hours_remaining=random.randint(50, 500),
+            exposure_priority=random.choice(["LOW", "MEDIUM", "HIGH", "CRITICAL"])
+        )
+    
+    def calculate_readiness_score(
+        self,
+        fitness_certs: FitnessCertificates,
+        job_cards: JobCards,
+        component_health: Dict[str, float]
+    ) -> float:
+        """Calculate overall readiness score for a train"""
+        score = 1.0
+        
+        # Certificate penalties
+        if fitness_certs.rolling_stock.status == CertificateStatus.EXPIRED:
+            score -= 0.4
+        elif fitness_certs.rolling_stock.status == CertificateStatus.EXPIRING_SOON:
+            score -= 0.1
+            
+        if fitness_certs.signalling.status == CertificateStatus.EXPIRED:
+            score -= 0.3
+        elif fitness_certs.signalling.status == CertificateStatus.EXPIRING_SOON:
+            score -= 0.05
+            
+        if fitness_certs.telecom.status == CertificateStatus.EXPIRED:
+            score -= 0.2
+        elif fitness_certs.telecom.status == CertificateStatus.EXPIRING_SOON:
+            score -= 0.05
+        
+        # Job card penalties
+        if job_cards.open > 0:
+            score -= min(0.15, job_cards.open * 0.03)
+        if len(job_cards.blocking) > 0:
+            score -= min(0.25, len(job_cards.blocking) * 0.1)
+        
+        # Component health impact
+        avg_health = sum(component_health.values()) / len(component_health)
+        health_factor = (avg_health - 0.5) * 0.2  # -0.1 to +0.1
+        score += health_factor
+        
+        return max(0.0, min(1.0, score))
+    
+    def generate_depot_layout(self) -> Dict[str, List[str]]:
+        """Generate depot bay layout"""
+        return {
+            "stabling_bays": self.DEPOT_BAYS.copy(),
+            "ibl_bays": self.IBL_BAYS.copy(),
+            "wash_bays": self.WASH_BAYS.copy()
+        }
+    
+    def get_realistic_mileage_distribution(self, num_trains: int) -> List[int]:
+        """Generate realistic cumulative mileage distribution"""
+        # Create a distribution with some variance
+        base_mileage = 120000
+        mileages = []
+        
+        for i in range(num_trains):
+            # Add variance based on age and usage patterns
+            variance = random.randint(-40000, 50000)
+            mileage = base_mileage + variance
+            mileages.append(max(50000, min(200000, mileage)))
+        
+        return mileages

DataService/metro_models.py

@@ -0,0 +1,232 @@
+"""
+Data models for Metro Train Scheduling System
+Comprehensive models matching the KMRL (Kochi Metro Rail Limited) structure
+"""
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Literal
+from datetime import datetime, time
+from enum import Enum
+
+
+class TrainStatus(str, Enum):
+    """Train operational status"""
+    REVENUE_SERVICE = "REVENUE_SERVICE"
+    STANDBY = "STANDBY"
+    MAINTENANCE = "MAINTENANCE"
+    CLEANING = "CLEANING"
+    OUT_OF_SERVICE = "OUT_OF_SERVICE"
+
+
+class CertificateStatus(str, Enum):
+    """Fitness certificate status"""
+    VALID = "VALID"
+    EXPIRING_SOON = "EXPIRING_SOON"
+    EXPIRED = "EXPIRED"
+
+
+class MaintenanceType(str, Enum):
+    """Types of maintenance operations"""
+    SCHEDULED_INSPECTION = "SCHEDULED_INSPECTION"
+    PREVENTIVE = "PREVENTIVE"
+    CORRECTIVE = "CORRECTIVE"
+    BREAKDOWN = "BREAKDOWN"
+
+
+class Severity(str, Enum):
+    """Alert severity levels"""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+
+class FitnessCertificate(BaseModel):
+    """Individual fitness certificate"""
+    valid_until: str  # ISO format date
+    status: CertificateStatus
+
+
+class FitnessCertificates(BaseModel):
+    """All fitness certificates for a trainset"""
+    rolling_stock: FitnessCertificate
+    signalling: FitnessCertificate
+    telecom: FitnessCertificate
+
+
+class JobCards(BaseModel):
+    """Job cards and maintenance tasks"""
+    open: int
+    blocking: List[str] = Field(default_factory=list)
+
+
+class Branding(BaseModel):
+    """Advertising/branding information"""
+    advertiser: str
+    contract_hours_remaining: int
+    exposure_priority: Literal["NONE", "LOW", "MEDIUM", "HIGH", "CRITICAL"]
+
+
+class ServiceBlock(BaseModel):
+    """A service block represents a continuous operating period"""
+    block_id: str
+    departure_time: str  # HH:MM format
+    origin: str
+    destination: str
+    trip_count: int  # Number of round trips in this block
+    estimated_km: int
+
+
+class Trainset(BaseModel):
+    """Complete trainset information"""
+    trainset_id: str
+    status: TrainStatus
+    priority_rank: Optional[int] = None
+    assigned_duty: Optional[str] = None
+    
+    # Service blocks for revenue service trains
+    service_blocks: List[ServiceBlock] = Field(default_factory=list)
+    
+    # Maintenance information
+    maintenance_type: Optional[MaintenanceType] = None
+    ibl_bay: Optional[str] = None  # Inspection/Berthing Location
+    estimated_completion: Optional[str] = None
+    
+    # Cleaning information
+    cleaning_bay: Optional[str] = None
+    cleaning_type: Optional[str] = None
+    scheduled_service_start: Optional[str] = None
+    
+    # Operational metrics
+    daily_km_allocation: int
+    cumulative_km: int
+    stabling_bay: Optional[str] = None
+    
+    # Compliance and health
+    fitness_certificates: FitnessCertificates
+    job_cards: JobCards
+    
+    # Branding
+    branding: Optional[Branding] = None
+    
+    # Computed scores
+    readiness_score: float = Field(ge=0.0, le=1.0)
+    constraints_met: bool
+    
+    # Alerts
+    alerts: List[str] = Field(default_factory=list)
+    standby_reason: Optional[str] = None
+
+
+class FleetSummary(BaseModel):
+    """Summary statistics for the entire fleet"""
+    total_trainsets: int
+    revenue_service: int
+    standby: int
+    maintenance: int
+    cleaning: int
+    availability_percent: float
+
+
+class OptimizationMetrics(BaseModel):
+    """Metrics about the optimization result"""
+    mileage_variance_coefficient: float
+    avg_readiness_score: float
+    branding_sla_compliance: float
+    shunting_movements_required: int
+    total_planned_km: int
+    fitness_expiry_violations: int
+    optimization_runtime_ms: int = 0
+
+
+class Alert(BaseModel):
+    """Alert or conflict in the schedule"""
+    trainset_id: str
+    severity: Severity
+    type: str
+    message: str
+
+
+class DecisionRationale(BaseModel):
+    """Explanation of optimization decisions"""
+    algorithm_version: str
+    objective_weights: Dict[str, float]
+    constraint_violations: int
+    optimization_runtime_ms: int
+
+
+class DaySchedule(BaseModel):
+    """Complete daily schedule for all trains"""
+    schedule_id: str
+    generated_at: str  # ISO format with timezone
+    valid_from: str  # ISO format
+    valid_until: str  # ISO format
+    depot: str
+    
+    trainsets: List[Trainset]
+    fleet_summary: FleetSummary
+    optimization_metrics: OptimizationMetrics
+    conflicts_and_alerts: List[Alert]
+    decision_rationale: DecisionRationale
+
+
+class Station(BaseModel):
+    """Metro station information"""
+    station_id: str
+    name: str
+    sequence: int  # Position in the line (1-25)
+    distance_from_origin_km: float
+    avg_dwell_time_seconds: int = 30  # Average stopping time
+
+
+class Route(BaseModel):
+    """Single metro line route"""
+    route_id: str
+    name: str
+    stations: List[Station]
+    total_distance_km: float
+    avg_speed_kmh: float = 35
+    turnaround_time_minutes: int = 10  # Time needed at terminals
+
+
+class OperationalHours(BaseModel):
+    """Service hours configuration"""
+    start_time: time = time(5, 0)  # 5:00 AM
+    end_time: time = time(23, 0)  # 11:00 PM
+    peak_hours: List[tuple] = Field(
+        default_factory=lambda: [
+            (time(7, 0), time(10, 0)),   # Morning peak
+            (time(17, 0), time(20, 0))   # Evening peak
+        ]
+    )
+    peak_frequency_minutes: int = 5  # Train every 5 minutes during peak
+    off_peak_frequency_minutes: int = 10  # Train every 10 minutes off-peak
+
+
+class TrainHealthStatus(BaseModel):
+    """Health status for optimization"""
+    trainset_id: str
+    is_fully_healthy: bool
+    available_hours: Optional[List[tuple]] = None  # (start_hour, end_hour) if partial
+    unavailable_reason: Optional[str] = None
+    cumulative_mileage: int
+    days_since_maintenance: int
+    component_health: Dict[str, float]  # Component: health_score (0-1)
+
+
+class ScheduleRequest(BaseModel):
+    """Request for schedule generation"""
+    date: str  # YYYY-MM-DD
+    num_trains: int = Field(default=25, ge=15, le=40)
+    num_stations: int = Field(default=25, ge=10, le=50)
+    route_name: str = "Aluva-Pettah Line"
+    depot_name: str = "Muttom_Depot"
+    
+    # Optional: override train health
+    train_health_overrides: Optional[List[TrainHealthStatus]] = None
+    
+    # Optimization parameters
+    min_service_trains: int = 20
+    min_standby_trains: int = 2
+    max_daily_km_per_train: int = 300
+    balance_mileage: bool = True
+    prioritize_branding: bool = True

DataService/schedule_optimizer.py

@@ -0,0 +1,405 @@
+"""
+Metro Train Schedule Optimizer
+Generates optimal daily schedules from 5:00 AM to 11:00 PM
+Considers train health, maintenance, branding, and mileage balancing
+"""
+import random
+from datetime import datetime, time, timedelta
+from typing import List, Dict, Tuple, Optional
+from .metro_models import (
+    DaySchedule, Trainset, TrainStatus, ServiceBlock, FleetSummary,
+    OptimizationMetrics, Alert, Severity, DecisionRationale,
+    TrainHealthStatus, Route, OperationalHours, FitnessCertificates,
+    JobCards, Branding, CertificateStatus, MaintenanceType
+)
+from .metro_data_generator import MetroDataGenerator
+
+
+class MetroScheduleOptimizer:
+    """Optimize daily metro train schedules"""
+    
+    def __init__(
+        self,
+        date: str,
+        num_trains: int,
+        route: Route,
+        train_health: List[TrainHealthStatus],
+        depot_name: str = "Muttom_Depot"
+    ):
+        self.date = date
+        self.num_trains = num_trains
+        self.route = route
+        self.train_health = {t.trainset_id: t for t in train_health}
+        self.depot_name = depot_name
+        self.generator = MetroDataGenerator(num_trains)
+        
+        # Operating parameters
+        self.op_hours = OperationalHours()
+        self.one_way_time_minutes = int(
+            (route.total_distance_km / route.avg_speed_kmh) * 60
+        )
+        self.round_trip_time_minutes = (
+            self.one_way_time_minutes * 2 + route.turnaround_time_minutes * 2
+        )
+        
+        # Pre-generate train data
+        self.train_data = self._initialize_train_data()
+    
+    def _initialize_train_data(self) -> Dict[str, Dict]:
+        """Initialize all train-specific data"""
+        data = {}
+        mileages = self.generator.get_realistic_mileage_distribution(self.num_trains)
+        
+        for i, train_id in enumerate(self.generator.trainset_ids):
+            health = self.train_health[train_id]
+            fitness_certs = self.generator.generate_fitness_certificates(train_id)
+            job_cards = self.generator.generate_job_cards(train_id)
+            branding = self.generator.generate_branding()
+            
+            readiness = self.generator.calculate_readiness_score(
+                fitness_certs, job_cards, health.component_health
+            )
+            
+            data[train_id] = {
+                "health": health,
+                "fitness_certs": fitness_certs,
+                "job_cards": job_cards,
+                "branding": branding,
+                "readiness_score": readiness,
+                "cumulative_km": mileages[i],
+                "stabling_bay": random.choice(self.generator.DEPOT_BAYS)
+            }
+        
+        return data
+    
+    def _calculate_service_hours(self) -> int:
+        """Calculate total service hours in a day"""
+        start = datetime.combine(datetime.today(), self.op_hours.start_time)
+        end = datetime.combine(datetime.today(), self.op_hours.end_time)
+        return int((end - start).total_seconds() / 3600)
+    
+    def _is_train_available(
+        self,
+        train_id: str,
+        start_hour: int,
+        end_hour: int
+    ) -> bool:
+        """Check if train is available for given time window"""
+        health = self.train_data[train_id]["health"]
+        
+        if health.is_fully_healthy:
+            return True
+        
+        if not health.available_hours:
+            return False
+        
+        # Check if requested window overlaps with available hours
+        for avail_start, avail_end in health.available_hours:
+            req_start = time(start_hour, 0)
+            req_end = time(end_hour, 0)
+            
+            if req_start >= avail_start and req_end <= avail_end:
+                return True
+        
+        return False
+    
+    def _rank_trains_for_service(self) -> List[Tuple[str, float]]:
+        """Rank trains by suitability for revenue service"""
+        rankings = []
+        
+        for train_id, data in self.train_data.items():
+            score = 0.0
+            
+            # Base readiness score (40% weight)
+            score += data["readiness_score"] * 0.4
+            
+            # Certificate validity (20% weight)
+            certs = data["fitness_certs"]
+            if certs.rolling_stock.status == CertificateStatus.VALID:
+                score += 0.15
+            if certs.signalling.status == CertificateStatus.VALID:
+                score += 0.05
+                
+            # No blocking job cards (15% weight)
+            if len(data["job_cards"].blocking) == 0:
+                score += 0.15
+            
+            # Branding priority (15% weight)
+            branding = data["branding"]
+            if branding.exposure_priority == "CRITICAL":
+                score += 0.15
+            elif branding.exposure_priority == "HIGH":
+                score += 0.10
+            elif branding.exposure_priority == "MEDIUM":
+                score += 0.05
+            
+            # Mileage balancing (10% weight) - prefer lower mileage
+            max_mileage = 200000
+            mileage_factor = 1.0 - (data["cumulative_km"] / max_mileage)
+            score += mileage_factor * 0.10
+            
+            rankings.append((train_id, score))
+        
+        return sorted(rankings, key=lambda x: x[1], reverse=True)
+    
+    def _generate_service_blocks(
+        self,
+        train_id: str,
+        duty_name: str,
+        num_blocks: int = 2
+    ) -> Tuple[List[ServiceBlock], int]:
+        """Generate service blocks for a train"""
+        blocks = []
+        total_km = 0
+        
+        # Distribute service across the day
+        service_hours = self._calculate_service_hours()
+        block_duration_hours = service_hours // num_blocks
+        
+        current_hour = self.op_hours.start_time.hour
+        
+        for i in range(num_blocks):
+            block_start_hour = current_hour + (i * block_duration_hours)
+            if block_start_hour >= self.op_hours.end_time.hour:
+                break
+            
+            # Calculate trips for this block
+            block_minutes = block_duration_hours * 60
+            trips = max(1, block_minutes // self.round_trip_time_minutes)
+            
+            # Alternate origin/destination
+            if i % 2 == 0:
+                origin = self.route.stations[0].name
+                destination = self.route.stations[-1].name
+            else:
+                origin = self.route.stations[-1].name
+                destination = self.route.stations[0].name
+            
+            block_km = int(trips * self.route.total_distance_km * 2)  # Round trips
+            total_km += block_km
+            
+            block = ServiceBlock(
+                block_id=f"BLK-{random.randint(1, 999):03d}",
+                departure_time=f"{block_start_hour:02d}:{random.randint(0, 45):02d}",
+                origin=origin,
+                destination=destination,
+                trip_count=trips,
+                estimated_km=block_km
+            )
+            blocks.append(block)
+        
+        return blocks, total_km
+    
+    def _assign_train_status(
+        self,
+        train_id: str,
+        rank: int,
+        required_service: int,
+        min_standby: int
+    ) -> Tuple[TrainStatus, Optional[str], List[ServiceBlock], int]:
+        """Assign status and duty to a train"""
+        data = self.train_data[train_id]
+        health = data["health"]
+        
+        # Check if train is unavailable
+        if not health.is_fully_healthy and not health.available_hours:
+            # Determine maintenance or out of service
+            if data["job_cards"].open > 0 or len(data["job_cards"].blocking) > 0:
+                return TrainStatus.MAINTENANCE, None, [], 0
+            else:
+                return TrainStatus.MAINTENANCE, None, [], 0
+        
+        # Check for blocking maintenance
+        if len(data["job_cards"].blocking) > 0:
+            return TrainStatus.MAINTENANCE, None, [], 0
+        
+        # Check for expired certificates
+        certs = data["fitness_certs"]
+        if certs.rolling_stock.status == CertificateStatus.EXPIRED:
+            return TrainStatus.MAINTENANCE, None, [], 0
+        
+        # Assign to revenue service
+        if rank <= required_service:
+            # Check availability for full day
+            if self._is_train_available(
+                train_id,
+                self.op_hours.start_time.hour,
+                self.op_hours.end_time.hour
+            ):
+                duty = f"DUTY-{chr(65 + (rank-1) // 10)}{(rank-1) % 10 + 1}"
+                blocks, km = self._generate_service_blocks(train_id, duty)
+                return TrainStatus.REVENUE_SERVICE, duty, blocks, km
+        
+        # Assign to standby
+        if rank <= required_service + min_standby:
+            return TrainStatus.STANDBY, None, [], 0
+        
+        # Random assignment of remaining trains
+        roll = random.random()
+        if roll < 0.05:
+            return TrainStatus.CLEANING, None, [], 0
+        elif roll < 0.15:
+            return TrainStatus.STANDBY, None, [], 0
+        else:
+            return TrainStatus.MAINTENANCE, None, [], 0
+    
+    def optimize_schedule(
+        self,
+        min_service_trains: int = 20,
+        min_standby: int = 2,
+        max_daily_km: int = 300
+    ) -> DaySchedule:
+        """Generate optimized daily schedule"""
+        start_time = datetime.now()
+        
+        # Rank trains
+        rankings = self._rank_trains_for_service()
+        
+        # Build trainset list
+        trainsets = []
+        status_counts = {
+            TrainStatus.REVENUE_SERVICE: 0,
+            TrainStatus.STANDBY: 0,
+            TrainStatus.MAINTENANCE: 0,
+            TrainStatus.CLEANING: 0
+        }
+        total_km = 0
+        readiness_scores = []
+        
+        for rank, (train_id, score) in enumerate(rankings, 1):
+            data = self.train_data[train_id]
+            
+            # Assign status and blocks
+            status, duty, blocks, daily_km = self._assign_train_status(
+                train_id, rank, min_service_trains, min_standby
+            )
+            
+            status_counts[status] += 1
+            total_km += daily_km
+            readiness_scores.append(data["readiness_score"])
+            
+            # Build trainset object
+            trainset = Trainset(
+                trainset_id=train_id,
+                status=status,
+                priority_rank=rank if status == TrainStatus.REVENUE_SERVICE else None,
+                assigned_duty=duty,
+                service_blocks=blocks,
+                daily_km_allocation=daily_km,
+                cumulative_km=data["cumulative_km"],
+                stabling_bay=data["stabling_bay"] if status != TrainStatus.MAINTENANCE else None,
+                fitness_certificates=data["fitness_certs"],
+                job_cards=data["job_cards"],
+                branding=data["branding"],
+                readiness_score=data["readiness_score"],
+                constraints_met=data["readiness_score"] >= 0.7
+            )
+            
+            # Add status-specific fields
+            if status == TrainStatus.MAINTENANCE:
+                trainset.maintenance_type = MaintenanceType.SCHEDULED_INSPECTION
+                trainset.ibl_bay = random.choice(self.generator.IBL_BAYS)
+                completion_time = datetime.now() + timedelta(hours=random.randint(4, 12))
+                trainset.estimated_completion = completion_time.isoformat()
+            elif status == TrainStatus.CLEANING:
+                trainset.cleaning_bay = random.choice(self.generator.WASH_BAYS)
+                trainset.cleaning_type = random.choice(["DEEP_INTERIOR", "EXTERIOR", "FULL"])
+                completion_time = datetime.now() + timedelta(hours=random.randint(2, 4))
+                trainset.estimated_completion = completion_time.isoformat()
+                trainset.scheduled_service_start = f"{random.randint(12, 18):02d}:30"
+            elif status == TrainStatus.STANDBY:
+                trainset.standby_reason = random.choice([
+                    "MILEAGE_BALANCING", "EMERGENCY_BACKUP", "PEAK_HOUR_RESERVE"
+                ])
+            
+            # Generate alerts
+            alerts = []
+            if data["fitness_certs"].telecom.status == CertificateStatus.EXPIRING_SOON:
+                alerts.append("TELECOM_CERT_EXPIRES_SOON")
+            if len(data["job_cards"].blocking) > 0:
+                alerts.append(f"{len(data['job_cards'].blocking)}_BLOCKING_JOB_CARDS")
+            trainset.alerts = alerts
+            
+            trainsets.append(trainset)
+        
+        # Build fleet summary
+        fleet_summary = FleetSummary(
+            total_trainsets=self.num_trains,
+            revenue_service=status_counts[TrainStatus.REVENUE_SERVICE],
+            standby=status_counts[TrainStatus.STANDBY],
+            maintenance=status_counts[TrainStatus.MAINTENANCE],
+            cleaning=status_counts[TrainStatus.CLEANING],
+            availability_percent=round(
+                (status_counts[TrainStatus.REVENUE_SERVICE] + status_counts[TrainStatus.STANDBY])
+                / self.num_trains * 100, 1
+            )
+        )
+        
+        # Calculate optimization metrics
+        mileages = [data["cumulative_km"] for data in self.train_data.values()]
+        variance = (max(mileages) - min(mileages)) / (sum(mileages) / len(mileages))
+        
+        optimization_metrics = OptimizationMetrics(
+            mileage_variance_coefficient=round(variance, 3),
+            avg_readiness_score=round(sum(readiness_scores) / len(readiness_scores), 2),
+            branding_sla_compliance=1.0,  # Placeholder
+            shunting_movements_required=random.randint(5, 15),
+            total_planned_km=total_km,
+            fitness_expiry_violations=0
+        )
+        
+        # Generate alerts
+        conflicts = []
+        for trainset in trainsets:
+            data = self.train_data[trainset.trainset_id]
+            
+            if data["fitness_certs"].telecom.status == CertificateStatus.EXPIRING_SOON:
+                conflicts.append(Alert(
+                    trainset_id=trainset.trainset_id,
+                    severity=Severity.MEDIUM,
+                    type="CERTIFICATE_EXPIRING",
+                    message="Telecom certificate expires soon"
+                ))
+            
+            if len(data["job_cards"].blocking) > 0:
+                conflicts.append(Alert(
+                    trainset_id=trainset.trainset_id,
+                    severity=Severity.HIGH,
+                    type="BLOCKING_MAINTENANCE",
+                    message=f"{len(data['job_cards'].blocking)} open job cards preventing service"
+                ))
+        
+        # Decision rationale
+        end_time = datetime.now()
+        runtime_ms = int((end_time - start_time).total_seconds() * 1000)
+        
+        rationale = DecisionRationale(
+            algorithm_version="v2.5.0",
+            objective_weights={
+                "service_readiness": 0.35,
+                "mileage_balancing": 0.25,
+                "branding_priority": 0.20,
+                "operational_cost": 0.20
+            },
+            constraint_violations=0,
+            optimization_runtime_ms=runtime_ms
+        )
+        
+        # Build complete schedule
+        schedule_id = f"KMRL-{self.date}-{random.choice(['DAWN', 'ALPHA', 'PRIME'])}"
+        now = datetime.now()
+        
+        schedule = DaySchedule(
+            schedule_id=schedule_id,
+            generated_at=now.isoformat(),
+            valid_from=f"{self.date}T{self.op_hours.start_time.isoformat()}+05:30",
+            valid_until=f"{self.date}T{self.op_hours.end_time.isoformat()}+05:30",
+            depot=self.depot_name,
+            trainsets=trainsets,
+            fleet_summary=fleet_summary,
+            optimization_metrics=optimization_metrics,
+            conflicts_and_alerts=conflicts,
+            decision_rationale=rationale
+        )
+        
+        return schedule

demo_schedule.py

@@ -0,0 +1,262 @@
+"""
+Demo script to test Metro Train Scheduling System
+Generates sample schedules and displays key information
+"""
+import sys
+import os
+from datetime import datetime
+import json
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from DataService.metro_data_generator import MetroDataGenerator
+from DataService.schedule_optimizer import MetroScheduleOptimizer
+from DataService.metro_models import ScheduleRequest
+
+
+def print_section(title: str):
+    """Print a section header"""
+    print("\n" + "=" * 70)
+    print(f"  {title}")
+    print("=" * 70)
+
+
+def demo_data_generation():
+    """Demonstrate data generation capabilities"""
+    print_section("DATA GENERATION DEMO")
+    
+    # Initialize generator
+    generator = MetroDataGenerator(num_trains=30, num_stations=25)
+    print(f"\n✓ Initialized generator for {len(generator.trainset_ids)} trains")
+    
+    # Generate route
+    route = generator.generate_route()
+    print(f"\n✓ Route: {route.name}")
+    print(f"  - Total distance: {route.total_distance_km} km")
+    print(f"  - Stations: {len(route.stations)}")
+    print(f"  - First: {route.stations[0].name}")
+    print(f"  - Last: {route.stations[-1].name}")
+    
+    # Generate train health
+    health_statuses = generator.generate_train_health_statuses()
+    fully_healthy = sum(1 for h in health_statuses if h.is_fully_healthy)
+    partial = sum(1 for h in health_statuses if not h.is_fully_healthy and h.available_hours)
+    unavailable = sum(1 for h in health_statuses if not h.is_fully_healthy and not h.available_hours)
+    
+    print(f"\n✓ Train Health Status:")
+    print(f"  - Fully healthy: {fully_healthy} ({fully_healthy/len(health_statuses)*100:.1f}%)")
+    print(f"  - Partially available: {partial} ({partial/len(health_statuses)*100:.1f}%)")
+    print(f"  - Unavailable: {unavailable} ({unavailable/len(health_statuses)*100:.1f}%)")
+    
+    # Show sample train details
+    sample_train = health_statuses[0]
+    print(f"\n✓ Sample Train: {sample_train.trainset_id}")
+    print(f"  - Healthy: {sample_train.is_fully_healthy}")
+    print(f"  - Cumulative mileage: {sample_train.cumulative_mileage:,} km")
+    print(f"  - Days since maintenance: {sample_train.days_since_maintenance}")
+    print(f"  - Component health: {len(sample_train.component_health)} components monitored")
+    
+    return generator, route, health_statuses
+
+
+def demo_schedule_optimization(generator, route, health_statuses):
+    """Demonstrate schedule optimization"""
+    print_section("SCHEDULE OPTIMIZATION DEMO")
+    
+    date = datetime.now().strftime("%Y-%m-%d")
+    print(f"\n✓ Optimizing schedule for: {date}")
+    
+    # Initialize optimizer
+    optimizer = MetroScheduleOptimizer(
+        date=date,
+        num_trains=30,
+        route=route,
+        train_health=health_statuses,
+        depot_name="Muttom_Depot"
+    )
+    
+    print(f"  - Operating hours: 5:00 AM - 11:00 PM")
+    print(f"  - One-way trip time: {optimizer.one_way_time_minutes} minutes")
+    print(f"  - Round trip time: {optimizer.round_trip_time_minutes} minutes")
+    
+    # Run optimization
+    print("\n✓ Running optimization...")
+    schedule = optimizer.optimize_schedule(
+        min_service_trains=22,
+        min_standby=3,
+        max_daily_km=300
+    )
+    
+    print(f"\n✓ Schedule Generated: {schedule.schedule_id}")
+    print(f"  - Generated at: {schedule.generated_at}")
+    print(f"  - Valid period: {schedule.valid_from} to {schedule.valid_until}")
+    print(f"  - Depot: {schedule.depot}")
+    
+    return schedule
+
+
+def display_schedule_summary(schedule):
+    """Display comprehensive schedule summary"""
+    print_section("SCHEDULE SUMMARY")
+    
+    # Fleet summary
+    fs = schedule.fleet_summary
+    print(f"\n📊 Fleet Status:")
+    print(f"  - Total trainsets: {fs.total_trainsets}")
+    print(f"  - Revenue service: {fs.revenue_service}")
+    print(f"  - Standby: {fs.standby}")
+    print(f"  - Maintenance: {fs.maintenance}")
+    print(f"  - Cleaning: {fs.cleaning}")
+    print(f"  - Availability: {fs.availability_percent}%")
+    
+    # Optimization metrics
+    om = schedule.optimization_metrics
+    print(f"\n📈 Optimization Metrics:")
+    print(f"  - Total planned km: {om.total_planned_km:,} km")
+    print(f"  - Avg readiness score: {om.avg_readiness_score:.2f}")
+    print(f"  - Mileage variance: {om.mileage_variance_coefficient:.3f}")
+    print(f"  - Branding SLA: {om.branding_sla_compliance:.1%}")
+    print(f"  - Shunting movements: {om.shunting_movements_required}")
+    print(f"  - Runtime: {om.optimization_runtime_ms} ms")
+    
+    # Conflicts and alerts
+    if schedule.conflicts_and_alerts:
+        print(f"\n⚠️  Alerts and Conflicts: {len(schedule.conflicts_and_alerts)}")
+        for alert in schedule.conflicts_and_alerts[:5]:  # Show first 5
+            print(f"  - [{alert.severity}] {alert.trainset_id}: {alert.message}")
+    else:
+        print(f"\n✓ No conflicts or alerts")
+    
+    # Decision rationale
+    dr = schedule.decision_rationale
+    print(f"\n🎯 Decision Rationale:")
+    print(f"  - Algorithm version: {dr.algorithm_version}")
+    print(f"  - Constraint violations: {dr.constraint_violations}")
+    print(f"  - Objective weights:")
+    for obj, weight in dr.objective_weights.items():
+        print(f"    • {obj}: {weight:.0%}")
+
+
+def display_train_details(schedule):
+    """Display details for selected trains"""
+    print_section("SAMPLE TRAIN DETAILS")
+    
+    # Show one train from each status category
+    categories = {
+        "REVENUE_SERVICE": None,
+        "STANDBY": None,
+        "MAINTENANCE": None,
+        "CLEANING": None
+    }
+    
+    for trainset in schedule.trainsets:
+        status = trainset.status.value
+        if status in categories and categories[status] is None:
+            categories[status] = trainset
+    
+    for status, trainset in categories.items():
+        if trainset is None:
+            continue
+            
+        print(f"\n🚇 {trainset.trainset_id} - {status}")
+        print(f"  - Readiness score: {trainset.readiness_score:.2f}")
+        print(f"  - Cumulative km: {trainset.cumulative_km:,} km")
+        print(f"  - Daily km allocation: {trainset.daily_km_allocation} km")
+        
+        if trainset.assigned_duty:
+            print(f"  - Assigned duty: {trainset.assigned_duty}")
+        
+        if trainset.service_blocks:
+            # Guard against non-iterable sentinel values (e.g., typing.Never) by
+            # ensuring we have a real sequence before slicing/iterating.
+            blocks = None
+            if isinstance(trainset.service_blocks, (list, tuple)):
+                blocks = trainset.service_blocks
+            else:
+                try:
+                    blocks = list(trainset.service_blocks)
+                except Exception:
+                    blocks = []
+            print(f"  - Service blocks: {len(blocks)}")
+            for block in blocks[:2]:  # Show first 2
+                print(f"    • {block.block_id}: {block.origin} → {block.destination}")
+                print(f"      Depart: {block.departure_time}, Trips: {block.trip_count}, Est: {block.estimated_km} km")
+        
+        # Certificates
+        certs = trainset.fitness_certificates
+        print(f"  - Certificates:")
+        print(f"    • Rolling Stock: {certs.rolling_stock.status.value}")
+        print(f"    • Signalling: {certs.signalling.status.value}")
+        print(f"    • Telecom: {certs.telecom.status.value}")
+        
+        # Job cards
+        if trainset.job_cards.open > 0:
+            print(f"  - Job cards: {trainset.job_cards.open} open")
+            if trainset.job_cards.blocking:
+                print(f"    • Blocking: {', '.join(trainset.job_cards.blocking)}")
+        
+        # Branding
+        if trainset.branding and trainset.branding.advertiser != "NONE":
+            print(f"  - Branding: {trainset.branding.advertiser}")
+            print(f"    • Priority: {trainset.branding.exposure_priority}")
+            print(f"    • Hours remaining: {trainset.branding.contract_hours_remaining}")
+        
+        if trainset.alerts:
+            print(f"  - Alerts: {', '.join(trainset.alerts)}")
+
+
+def save_schedule_json(schedule, filename="sample_schedule.json"):
+    """Save schedule to JSON file"""
+    print_section("SAVING SCHEDULE")
+    
+    schedule_dict = schedule.model_dump()
+    
+    with open(filename, 'w') as f:
+        json.dump(schedule_dict, f, indent=2, default=str)
+    
+    print(f"\n✓ Schedule saved to: {filename}")
+    print(f"  - Size: {os.path.getsize(filename) / 1024:.1f} KB")
+    print(f"  - Trainsets: {len(schedule_dict['trainsets'])}")
+
+
+def main():
+    """Main demo function"""
+    print("\n" + "🚇" * 35)
+    print("  METRO TRAIN SCHEDULING SYSTEM - DEMO")
+    print("🚇" * 35)
+    
+    try:
+        # Step 1: Data generation
+        generator, route, health_statuses = demo_data_generation()
+        
+        # Step 2: Schedule optimization
+        schedule = demo_schedule_optimization(generator, route, health_statuses)
+        
+        # Step 3: Display results
+        display_schedule_summary(schedule)
+        display_train_details(schedule)
+        
+        # Step 4: Save to file
+        save_schedule_json(schedule)
+        
+        print_section("DEMO COMPLETE")
+        print("\n✓ All systems operational!")
+        print("\nNext steps:")
+        print("  1. Review sample_schedule.json for full schedule details")
+        print("  2. Run 'python run_api.py' to start the FastAPI service")
+        print("  3. Visit http://localhost:8000/docs for API documentation")
+        print("  4. Test with: curl http://localhost:8000/api/v1/schedule/example")
+        print()
+        
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return 1
+    
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quickstart.py

@@ -0,0 +1,257 @@
+"""
+Quick Start Guide - Metro Train Scheduling System
+
+This script shows the basic usage patterns for the Metro Train Scheduling System.
+"""
+
+from datetime import datetime
+from DataService import (
+    MetroDataGenerator,
+    MetroScheduleOptimizer,
+    ScheduleRequest
+)
+
+
+def example_1_basic_data_generation():
+    """Example 1: Generate basic metro data"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 1: Basic Data Generation")
+    print("=" * 60)
+    
+    # Create generator for 25 trains
+    generator = MetroDataGenerator(num_trains=25, num_stations=25)
+    
+    # Generate route
+    route = generator.generate_route("Aluva-Pettah Line")
+    print(f"\nRoute: {route.name}")
+    print(f"Distance: {route.total_distance_km} km")
+    print(f"Stations: {len(route.stations)}")
+    
+    # Generate train health status
+    health_statuses = generator.generate_train_health_statuses()
+    print(f"\nGenerated health status for {len(health_statuses)} trains")
+    
+    # Count by category
+    healthy = sum(1 for h in health_statuses if h.is_fully_healthy)
+    print(f"  - Fully healthy: {healthy}")
+    print(f"  - Need attention: {len(health_statuses) - healthy}")
+    
+    return generator, route, health_statuses
+
+
+def example_2_simple_schedule():
+    """Example 2: Generate a simple schedule"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 2: Generate Simple Schedule")
+    print("=" * 60)
+    
+    # Setup
+    generator = MetroDataGenerator(num_trains=30)
+    route = generator.generate_route()
+    health_statuses = generator.generate_train_health_statuses()
+    
+    # Create optimizer
+    optimizer = MetroScheduleOptimizer(
+        date="2025-10-25",
+        num_trains=30,
+        route=route,
+        train_health=health_statuses
+    )
+    
+    # Generate schedule
+    schedule = optimizer.optimize_schedule(
+        min_service_trains=22,
+        min_standby=3
+    )
+    
+    print(f"\nSchedule ID: {schedule.schedule_id}")
+    print(f"Valid: {schedule.valid_from} to {schedule.valid_until}")
+    print(f"\nFleet Status:")
+    print(f"  - In service: {schedule.fleet_summary.revenue_service}")
+    print(f"  - Standby: {schedule.fleet_summary.standby}")
+    print(f"  - Maintenance: {schedule.fleet_summary.maintenance}")
+    print(f"  - Cleaning: {schedule.fleet_summary.cleaning}")
+    
+    return schedule
+
+
+def example_3_detailed_schedule():
+    """Example 3: Generate schedule with custom parameters"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 3: Custom Schedule Parameters")
+    print("=" * 60)
+    
+    generator = MetroDataGenerator(num_trains=35)
+    route = generator.generate_route()
+    health_statuses = generator.generate_train_health_statuses()
+    
+    optimizer = MetroScheduleOptimizer(
+        date=datetime.now().strftime("%Y-%m-%d"),
+        num_trains=35,
+        route=route,
+        train_health=health_statuses,
+        depot_name="Custom_Depot"
+    )
+    
+    # Custom optimization parameters
+    schedule = optimizer.optimize_schedule(
+        min_service_trains=25,  # More trains in service
+        min_standby=5,          # More standby trains
+        max_daily_km=280        # Lower km limit per train
+    )
+    
+    print(f"\nSchedule optimized with custom parameters:")
+    print(f"  - Total planned km: {schedule.optimization_metrics.total_planned_km:,}")
+    print(f"  - Avg readiness: {schedule.optimization_metrics.avg_readiness_score:.2f}")
+    print(f"  - Runtime: {schedule.optimization_metrics.optimization_runtime_ms} ms")
+    
+    return schedule
+
+
+def example_4_train_details():
+    """Example 4: Access detailed train information"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 4: Detailed Train Information")
+    print("=" * 60)
+    
+    generator = MetroDataGenerator(num_trains=30)
+    route = generator.generate_route()
+    health_statuses = generator.generate_train_health_statuses()
+    
+    optimizer = MetroScheduleOptimizer(
+        date="2025-10-25",
+        num_trains=30,
+        route=route,
+        train_health=health_statuses
+    )
+    
+    schedule = optimizer.optimize_schedule()
+    
+    # Find first train in revenue service
+    service_train = next(
+        (t for t in schedule.trainsets if t.status.value == "REVENUE_SERVICE"),
+        None
+    )
+    
+    if service_train:
+        print(f"\nTrain: {service_train.trainset_id}")
+        print(f"Status: {service_train.status.value}")
+        print(f"Duty: {service_train.assigned_duty}")
+        print(f"Daily km: {service_train.daily_km_allocation} km")
+        print(f"Readiness: {service_train.readiness_score:.2f}")
+        
+        if service_train.service_blocks:
+            print(f"\nService Blocks: {len(service_train.service_blocks)}")
+            for i, block in enumerate(service_train.service_blocks[:3], 1):
+                print(f"  {i}. {block.origin} → {block.destination}")
+                print(f"     Depart: {block.departure_time}, Trips: {block.trip_count}")
+        
+        print(f"\nFitness Certificates:")
+        certs = service_train.fitness_certificates
+        print(f"  - Rolling Stock: {certs.rolling_stock.status.value}")
+        print(f"  - Signalling: {certs.signalling.status.value}")
+        print(f"  - Telecom: {certs.telecom.status.value}")
+        
+        if service_train.branding and service_train.branding.advertiser != "NONE":
+            print(f"\nBranding:")
+            print(f"  - Advertiser: {service_train.branding.advertiser}")
+            print(f"  - Priority: {service_train.branding.exposure_priority}")
+
+
+def example_5_schedule_request_model():
+    """Example 5: Using ScheduleRequest model (for API)"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 5: Schedule Request Model")
+    print("=" * 60)
+    
+    # Create a request (as would be done via API)
+    request = ScheduleRequest(
+        date="2025-10-25",
+        num_trains=30,
+        num_stations=25,
+        route_name="Aluva-Pettah Line",
+        depot_name="Muttom_Depot",
+        min_service_trains=22,
+        min_standby_trains=3,
+        max_daily_km_per_train=300,
+        balance_mileage=True,
+        prioritize_branding=True
+    )
+    
+    print(f"\nSchedule Request:")
+    print(f"  - Date: {request.date}")
+    print(f"  - Trains: {request.num_trains}")
+    print(f"  - Stations: {request.num_stations}")
+    print(f"  - Min service: {request.min_service_trains}")
+    print(f"  - Max daily km: {request.max_daily_km_per_train}")
+    
+    # This request can be sent to the API:
+    # POST /api/v1/generate with request.model_dump() as JSON
+    
+    return request
+
+
+def example_6_save_schedule():
+    """Example 6: Save schedule to JSON file"""
+    print("\n" + "=" * 60)
+    print("EXAMPLE 6: Save Schedule to File")
+    print("=" * 60)
+    
+    import json
+    
+    generator = MetroDataGenerator(num_trains=25)
+    route = generator.generate_route()
+    health_statuses = generator.generate_train_health_statuses()
+    
+    optimizer = MetroScheduleOptimizer(
+        date="2025-10-25",
+        num_trains=25,
+        route=route,
+        train_health=health_statuses
+    )
+    
+    schedule = optimizer.optimize_schedule()
+    
+    # Convert to dict and save
+    schedule_dict = schedule.model_dump()
+    
+    filename = f"schedule_{schedule.schedule_id}.json"
+    with open(filename, 'w') as f:
+        json.dump(schedule_dict, f, indent=2, default=str)
+    
+    print(f"\nSchedule saved to: {filename}")
+    print(f"Contains {len(schedule_dict['trainsets'])} trainsets")
+
+
+def main():
+    """Run all examples"""
+    print("\n" + "🚇" * 30)
+    print("  METRO TRAIN SCHEDULING - QUICK START EXAMPLES")
+    print("🚇" * 30)
+    
+    try:
+        # Run examples
+        example_1_basic_data_generation()
+        example_2_simple_schedule()
+        example_3_detailed_schedule()
+        example_4_train_details()
+        example_5_schedule_request_model()
+        example_6_save_schedule()
+        
+        print("\n" + "=" * 60)
+        print("ALL EXAMPLES COMPLETED SUCCESSFULLY!")
+        print("=" * 60)
+        print("\nNext steps:")
+        print("  1. Run 'python demo_schedule.py' for a comprehensive demo")
+        print("  2. Run 'python run_api.py' to start the FastAPI service")
+        print("  3. Visit http://localhost:8000/docs for API documentation")
+        print()
+        
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -1 +1,5 @@
-ortools==9.14.6206
+ortools==9.14.6206
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+pydantic==2.5.0
+python-multipart==0.0.6

run_api.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""
+Startup script for Metro Train Scheduling API
+"""
+import uvicorn
+import sys
+import os
+
+# Add parent directory to path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("Metro Train Scheduling API")
+    print("=" * 60)
+    print()
+    print("Starting FastAPI server...")
+    print("API Documentation: http://localhost:8000/docs")
+    print("Alternative Docs: http://localhost:8000/redoc")
+    print()
+    print("Example endpoints:")
+    print("  - GET  /health")
+    print("  - GET  /api/v1/schedule/example")
+    print("  - POST /api/v1/generate")
+    print("  - POST /api/v1/generate/quick?date=2025-10-25&num_trains=30")
+    print()
+    print("Press CTRL+C to stop the server")
+    print("=" * 60)
+    print()
+    
+    uvicorn.run(
+        "DataService.api:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        log_level="info"
+    )

test_system.py

@@ -0,0 +1,214 @@
+"""
+Simple Test Script - Verify Metro Scheduling System
+Tests core functionality without requiring full API setup
+"""
+import sys
+import traceback
+
+
+def test_imports():
+    """Test that all modules can be imported"""
+    print("Testing imports...")
+    try:
+        from DataService import metro_models
+        from DataService import metro_data_generator
+        from DataService import schedule_optimizer
+        print("  ✓ DataService modules imported successfully")
+        return True
+    except Exception as e:
+        print(f"  ✗ Import failed: {e}")
+        traceback.print_exc()
+        return False
+
+
+def test_data_generation():
+    """Test data generation"""
+    print("\nTesting data generation...")
+    try:
+        from DataService.metro_data_generator import MetroDataGenerator
+        
+        generator = MetroDataGenerator(num_trains=10, num_stations=10)
+        print(f"  ✓ Generator created for {len(generator.trainset_ids)} trains")
+        
+        # Test route generation
+        route = generator.generate_route()
+        print(f"  ✓ Route generated: {route.name} with {len(route.stations)} stations")
+        
+        # Test train health
+        health = generator.generate_train_health_statuses()
+        print(f"  ✓ Generated health status for {len(health)} trains")
+        
+        # Test certificates
+        certs = generator.generate_fitness_certificates("TS-001")
+        print(f"  ✓ Generated fitness certificates")
+        
+        return True
+    except Exception as e:
+        print(f"  ✗ Data generation failed: {e}")
+        traceback.print_exc()
+        return False
+
+
+def test_schedule_optimization():
+    """Test schedule optimization"""
+    print("\nTesting schedule optimization...")
+    try:
+        from DataService.metro_data_generator import MetroDataGenerator
+        from DataService.schedule_optimizer import MetroScheduleOptimizer
+        from datetime import datetime
+        
+        # Setup
+        generator = MetroDataGenerator(num_trains=15, num_stations=15)
+        route = generator.generate_route()
+        health = generator.generate_train_health_statuses()
+        
+        # Create optimizer
+        optimizer = MetroScheduleOptimizer(
+            date=datetime.now().strftime("%Y-%m-%d"),
+            num_trains=15,
+            route=route,
+            train_health=health
+        )
+        print(f"  ✓ Optimizer created")
+        
+        # Generate schedule
+        schedule = optimizer.optimize_schedule(min_service_trains=10, min_standby=2)
+        print(f"  ✓ Schedule generated: {schedule.schedule_id}")
+        print(f"    - Trains in service: {schedule.fleet_summary.revenue_service}")
+        print(f"    - Total planned km: {schedule.optimization_metrics.total_planned_km}")
+        print(f"    - Optimization time: {schedule.optimization_metrics.optimization_runtime_ms} ms")
+        
+        return True
+    except Exception as e:
+        print(f"  ✗ Schedule optimization failed: {e}")
+        traceback.print_exc()
+        return False
+
+
+def test_models():
+    """Test Pydantic models"""
+    print("\nTesting data models...")
+    try:
+        from DataService.metro_models import (
+            ScheduleRequest, TrainHealthStatus, Route, Station
+        )
+        
+        # Test ScheduleRequest
+        request = ScheduleRequest(
+            date="2025-10-25",
+            num_trains=25,
+            num_stations=25
+        )
+        print(f"  ✓ ScheduleRequest model validated")
+        
+        # Test Station
+        station = Station(
+            station_id="STN-001",
+            name="Test Station",
+            sequence=1,
+            distance_from_origin_km=0.0
+        )
+        print(f"  ✓ Station model validated")
+        
+        return True
+    except Exception as e:
+        print(f"  ✗ Model validation failed: {e}")
+        traceback.print_exc()
+        return False
+
+
+def test_json_export():
+    """Test JSON export"""
+    print("\nTesting JSON export...")
+    try:
+        import json
+        from DataService.metro_data_generator import MetroDataGenerator
+        from DataService.schedule_optimizer import MetroScheduleOptimizer
+        from datetime import datetime
+        
+        generator = MetroDataGenerator(num_trains=10, num_stations=10)
+        route = generator.generate_route()
+        health = generator.generate_train_health_statuses()
+        
+        optimizer = MetroScheduleOptimizer(
+            date=datetime.now().strftime("%Y-%m-%d"),
+            num_trains=10,
+            route=route,
+            train_health=health
+        )
+        
+        schedule = optimizer.optimize_schedule()
+        
+        # Convert to dict and save
+        schedule_dict = schedule.model_dump()
+        
+        # Try to serialize to JSON
+        json_str = json.dumps(schedule_dict, indent=2, default=str)
+        
+        print(f"  ✓ Schedule exported to JSON ({len(json_str)} chars)")
+        print(f"    - Contains {len(schedule_dict['trainsets'])} trainsets")
+        
+        return True
+    except Exception as e:
+        print(f"  ✗ JSON export failed: {e}")
+        traceback.print_exc()
+        return False
+
+
+def main():
+    """Run all tests"""
+    print("=" * 70)
+    print("  METRO SCHEDULING SYSTEM - VERIFICATION TESTS")
+    print("=" * 70)
+    
+    tests = [
+        ("Imports", test_imports),
+        ("Data Generation", test_data_generation),
+        ("Schedule Optimization", test_schedule_optimization),
+        ("Data Models", test_models),
+        ("JSON Export", test_json_export)
+    ]
+    
+    results = []
+    
+    for name, test_func in tests:
+        try:
+            result = test_func()
+            results.append((name, result))
+        except Exception as e:
+            print(f"\n✗ {name} crashed: {e}")
+            results.append((name, False))
+    
+    # Summary
+    print("\n" + "=" * 70)
+    print("  TEST SUMMARY")
+    print("=" * 70)
+    
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+    
+    for name, result in results:
+        status = "✓ PASS" if result else "✗ FAIL"
+        print(f"  {status}: {name}")
+    
+    print("\n" + "-" * 70)
+    print(f"  Results: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print("\n  🎉 All tests passed! System is ready to use.")
+        print("\n  Next steps:")
+        print("    1. Run: python demo_schedule.py")
+        print("    2. Run: python run_api.py")
+        print("    3. Visit: http://localhost:8000/docs")
+    else:
+        print("\n  ⚠️  Some tests failed. Please check the errors above.")
+        print("     Make sure all dependencies are installed:")
+        print("     pip install -r requirements.txt")
+    
+    print("=" * 70)
+    
+    return 0 if passed == total else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())