added API docs

docs/API_DOCUMENTATION.md

@@ -0,0 +1,629 @@
+# GreedyOptim Scheduling API Documentation
+
+## Overview
+
+The GreedyOptim API provides advanced train scheduling optimization using multiple algorithms including Genetic Algorithms, Particle Swarm Optimization, CMA-ES, and more. This API allows you to submit your own trainset data and receive optimized scheduling recommendations.
+
+**Base URL:** `http://localhost:8001`
+
+**API Version:** 2.0.0
+
+---
+
+## Quick Start
+
+### 1. Start the API Server
+
+```bash
+python api/run_greedyoptim_api.py
+```
+
+The API will be available at:
+- **API Endpoint:** http://localhost:8001
+- **Interactive Docs:** http://localhost:8001/docs
+- **Alternative Docs:** http://localhost:8001/redoc
+
+### 2. Test the API
+
+```bash
+python api/test_greedyoptim_api.py
+```
+
+---
+
+## Authentication
+
+Currently, the API does not require authentication. Configure authentication as needed for production use.
+
+---
+
+## Endpoints
+
+### 1. Health Check
+
+**GET** `/health`
+
+Check if the API is running.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2025-11-09T10:30:00",
+  "service": "greedyoptim-api"
+}
+```
+
+---
+
+### 2. List Available Methods
+
+**GET** `/methods`
+
+Get information about all available optimization methods.
+
+**Response:**
+```json
+{
+  "available_methods": {
+    "ga": {
+      "name": "Genetic Algorithm",
+      "description": "Evolutionary optimization using selection, crossover, and mutation",
+      "typical_time": "medium",
+      "solution_quality": "high"
+    },
+    "pso": {
+      "name": "Particle Swarm Optimization",
+      "description": "Swarm intelligence-based optimization",
+      "typical_time": "medium",
+      "solution_quality": "high"
+    },
+    "cmaes": {
+      "name": "CMA-ES",
+      "description": "Covariance Matrix Adaptation Evolution Strategy",
+      "typical_time": "medium-high",
+      "solution_quality": "very high"
+    },
+    ...
+  },
+  "default_method": "ga",
+  "recommended_for_speed": "ga",
+  "recommended_for_quality": "ensemble"
+}
+```
+
+---
+
+### 3. Optimize Schedule
+
+**POST** `/optimize`
+
+Submit trainset data and receive an optimized schedule.
+
+**Request Body:**
+```json
+{
+  "trainset_status": [
+    {
+      "trainset_id": "KMRL-01",
+      "operational_status": "Available",
+      "last_maintenance_date": "2025-10-01",
+      "total_mileage_km": 45000.0,
+      "age_years": 3.5
+    },
+    ...
+  ],
+  "fitness_certificates": [
+    {
+      "trainset_id": "KMRL-01",
+      "department": "Safety",
+      "status": "Valid",
+      "issue_date": "2025-01-01",
+      "expiry_date": "2026-01-01"
+    },
+    ...
+  ],
+  "job_cards": [
+    {
+      "trainset_id": "KMRL-01",
+      "job_id": "JOB-001",
+      "priority": "Medium",
+      "status": "Closed",
+      "description": "Routine inspection",
+      "estimated_hours": 2.0
+    },
+    ...
+  ],
+  "component_health": [
+    {
+      "trainset_id": "KMRL-01",
+      "component": "Brakes",
+      "status": "Good",
+      "wear_level": 25.0,
+      "last_inspection": "2025-10-15"
+    },
+    ...
+  ],
+  "method": "ga",
+  "config": {
+    "required_service_trains": 15,
+    "min_standby": 2,
+    "population_size": 50,
+    "generations": 100,
+    "mutation_rate": 0.1,
+    "crossover_rate": 0.8,
+    "elite_size": 5
+  }
+}
+```
+
+**Field Descriptions:**
+
+**trainset_status** (required):
+- `trainset_id`: Unique identifier (string)
+- `operational_status`: One of: `Available`, `In-Service`, `Maintenance`, `Standby`, `Out-of-Order`
+- `last_maintenance_date`: ISO date string (optional)
+- `total_mileage_km`: Total kilometers traveled (optional)
+- `age_years`: Age of trainset in years (optional)
+
+**fitness_certificates** (required):
+- `trainset_id`: Must match trainset_status
+- `department`: One of: `Safety`, `Operations`, `Technical`, `Electrical`, `Mechanical`
+- `status`: One of: `Valid`, `Expired`, `Expiring-Soon`, `Suspended`
+- `issue_date`: ISO date string (optional)
+- `expiry_date`: ISO date string (optional)
+
+**job_cards** (required, can be empty array):
+- `trainset_id`: Must match trainset_status
+- `job_id`: Unique job identifier
+- `priority`: One of: `Critical`, `High`, `Medium`, `Low`
+- `status`: One of: `Open`, `In-Progress`, `Closed`, `Pending-Parts`
+- `description`: Job description (optional)
+- `estimated_hours`: Estimated completion time (optional)
+
+**component_health** (required):
+- `trainset_id`: Must match trainset_status
+- `component`: Component name (e.g., `Brakes`, `HVAC`, `Doors`, `Propulsion`)
+- `status`: One of: `Good`, `Fair`, `Warning`, `Critical`
+- `wear_level`: Wear percentage 0-100 (optional)
+- `last_inspection`: ISO date string (optional)
+
+**method** (optional, default: "ga"):
+- `ga`: Genetic Algorithm (recommended for most cases)
+- `pso`: Particle Swarm Optimization
+- `cmaes`: CMA-ES (best quality, slower)
+- `sa`: Simulated Annealing
+- `nsga2`: Multi-objective optimization
+- `adaptive`: Auto-selects best method
+- `ensemble`: Runs multiple methods (best quality, slowest)
+
+**config** (optional):
+- `required_service_trains`: Minimum trains needed in service (default: 15)
+- `min_standby`: Minimum standby trains (default: 2)
+- `population_size`: Algorithm population size (default: 50, range: 10-200)
+- `generations`: Number of iterations (default: 100, range: 10-1000)
+- `mutation_rate`: Mutation probability (default: 0.1, range: 0.0-1.0)
+- `crossover_rate`: Crossover probability (default: 0.8, range: 0.0-1.0)
+- `elite_size`: Number of elite solutions preserved (default: 5)
+
+**Response:**
+```json
+{
+  "success": true,
+  "method": "ga",
+  "fitness_score": 0.8542,
+  "service_trains": ["KMRL-01", "KMRL-02", "KMRL-03", ...],
+  "standby_trains": ["KMRL-15", "KMRL-16"],
+  "maintenance_trains": ["KMRL-17", "KMRL-18"],
+  "unavailable_trains": [],
+  "num_service": 15,
+  "num_standby": 2,
+  "num_maintenance": 2,
+  "num_unavailable": 0,
+  "service_score": 0.95,
+  "standby_score": 0.85,
+  "health_score": 0.78,
+  "certificate_score": 0.92,
+  "execution_time_seconds": 2.341,
+  "timestamp": "2025-11-09T10:35:00",
+  "constraints_satisfied": true,
+  "warnings": null
+}
+```
+
+---
+
+### 4. Compare Methods
+
+**POST** `/compare`
+
+Compare multiple optimization methods on the same data.
+
+**Request Body:**
+```json
+{
+  "trainset_status": [...],
+  "fitness_certificates": [...],
+  "job_cards": [...],
+  "component_health": [...],
+  "methods": ["ga", "pso", "cmaes"],
+  "config": {
+    "required_service_trains": 15,
+    "min_standby": 2,
+    "population_size": 30,
+    "generations": 50
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "methods": {
+    "ga": {
+      "success": true,
+      "method": "ga",
+      "fitness_score": 0.8542,
+      "service_trains": [...],
+      "execution_time_seconds": 1.234,
+      ...
+    },
+    "pso": {
+      "success": true,
+      "method": "pso",
+      "fitness_score": 0.8398,
+      ...
+    },
+    "cmaes": {
+      "success": true,
+      "method": "cmaes",
+      "fitness_score": 0.8721,
+      ...
+    }
+  },
+  "summary": {
+    "total_execution_time": 5.678,
+    "methods_compared": 3,
+    "best_method": "cmaes",
+    "best_score": 0.8721,
+    "timestamp": "2025-11-09T10:40:00"
+  }
+}
+```
+
+---
+
+### 5. Generate Synthetic Data
+
+**POST** `/generate-synthetic`
+
+Generate synthetic test data for testing purposes.
+
+**Request Body:**
+```json
+{
+  "num_trainsets": 25,
+  "maintenance_rate": 0.1,
+  "availability_rate": 0.8
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "trainset_status": [...],
+    "fitness_certificates": [...],
+    "job_cards": [...],
+    "component_health": [...],
+    "metadata": {...}
+  },
+  "metadata": {
+    "num_trainsets": 25,
+    "num_fitness_certificates": 125,
+    "num_job_cards": 50,
+    "num_component_health": 150,
+    "generated_at": "2025-11-09T10:45:00"
+  }
+}
+```
+
+---
+
+### 6. Validate Data
+
+**POST** `/validate`
+
+Validate your data structure before submitting for optimization.
+
+**Request Body:**
+```json
+{
+  "trainset_status": [...],
+  "fitness_certificates": [...],
+  "job_cards": [...],
+  "component_health": [...],
+  "method": "ga"
+}
+```
+
+**Response (Valid):**
+```json
+{
+  "valid": true,
+  "message": "Data structure is valid",
+  "num_trainsets": 25,
+  "num_certificates": 125,
+  "num_job_cards": 50,
+  "num_component_health": 150
+}
+```
+
+**Response (Invalid):**
+```json
+{
+  "valid": false,
+  "validation_errors": [
+    "Missing required data section: trainset_status",
+    "Invalid operational_status value: 'Running' for trainset KMRL-05"
+  ],
+  "suggestions": [
+    "Check that all trainset_ids are consistent across sections",
+    "Ensure operational_status values are valid (Available, In-Service, Maintenance, Standby, Out-of-Order)",
+    "Verify certificate status values are valid (Valid, Expired, Expiring-Soon, Suspended)",
+    "Verify certificate expiry dates are in ISO format",
+    "Confirm component wear_level is between 0-100 if provided"
+  ]
+}
+```
+
+---
+
+## Usage Examples
+
+### Example 1: Basic Optimization (Python)
+
+```python
+import requests
+
+# Your trainset data
+data = {
+    "trainset_status": [
+        {"trainset_id": "KMRL-01", "operational_status": "Available"},
+        {"trainset_id": "KMRL-02", "operational_status": "Available"},
+        # ... more trainsets
+    ],
+    "fitness_certificates": [
+        {
+            "trainset_id": "KMRL-01",
+            "department": "Safety",
+            "status": "Valid",
+            "expiry_date": "2026-01-01"
+        },
+        # ... more certificates
+    ],
+    "job_cards": [],  # No pending jobs
+    "component_health": [
+        {
+            "trainset_id": "KMRL-01",
+            "component": "Brakes",
+            "status": "Good",
+            "wear_level": 20.0
+        },
+        # ... more components
+    ],
+    "method": "ga",
+    "config": {
+        "required_service_trains": 15,
+        "min_standby": 2
+    }
+}
+
+# Send request
+response = requests.post("http://localhost:8001/optimize", json=data)
+result = response.json()
+
+print(f"Fitness Score: {result['fitness_score']}")
+print(f"Service Trains: {result['num_service']}")
+print(f"Execution Time: {result['execution_time_seconds']}s")
+```
+
+### Example 2: Compare Methods (cURL)
+
+```bash
+curl -X POST "http://localhost:8001/compare" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "trainset_status": [...],
+    "fitness_certificates": [...],
+    "job_cards": [],
+    "component_health": [...],
+    "methods": ["ga", "pso"],
+    "config": {
+      "population_size": 30,
+      "generations": 50
+    }
+  }'
+```
+
+### Example 3: Validate Before Optimizing (JavaScript)
+
+```javascript
+const data = {
+  trainset_status: [...],
+  fitness_certificates: [...],
+  job_cards: [],
+  component_health: [...],
+  method: "ga"
+};
+
+// Validate first
+const validateResponse = await fetch('http://localhost:8001/validate', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(data)
+});
+
+const validation = await validateResponse.json();
+
+if (validation.valid) {
+  // Now optimize
+  const optimizeResponse = await fetch('http://localhost:8001/optimize', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data)
+  });
+  
+  const result = await optimizeResponse.json();
+  console.log('Optimization successful:', result);
+} else {
+  console.error('Validation errors:', validation.validation_errors);
+}
+```
+
+---
+
+## Error Handling
+
+### HTTP Status Codes
+
+- **200**: Success
+- **400**: Bad Request (validation error)
+- **500**: Internal Server Error
+
+### Error Response Format
+
+```json
+{
+  "error": "Data validation failed",
+  "validation_errors": [
+    "Missing required field: trainset_id in trainset_status",
+    "Invalid operational_status value"
+  ],
+  "message": "Please fix the data structure and try again"
+}
+```
+
+---
+
+## Data Requirements
+
+### Minimum Required Data
+
+To successfully optimize a schedule, you must provide:
+
+1. **At least 10 trainsets** in `trainset_status`
+2. **At least one fitness certificate** per trainset
+3. **Component health data** for each trainset
+4. **job_cards** can be an empty array if no maintenance is pending
+
+### Valid Status Values
+
+**Operational Status:**
+- `Available` - Ready for service
+- `In-Service` - Currently operating
+- `Maintenance` - Under maintenance
+- `Standby` - On standby
+- `Out-of-Order` - Not operational
+
+**Certificate Status:**
+- `Valid` - Certificate is valid
+- `Expired` - Certificate has expired
+- `Expiring-Soon` - Certificate expires within 30 days
+- `Suspended` - Certificate suspended
+
+**Job Priority:**
+- `Critical` - Must be addressed immediately
+- `High` - High priority
+- `Medium` - Medium priority
+- `Low` - Low priority
+
+**Job Status:**
+- `Open` - Not started
+- `In-Progress` - Currently being worked on
+- `Closed` - Completed
+- `Pending-Parts` - Waiting for parts
+
+**Component Status:**
+- `Good` - Component in good condition
+- `Fair` - Component acceptable
+- `Warning` - Component needs attention soon
+- `Critical` - Component requires immediate attention
+
+---
+
+## Performance Tips
+
+### For Faster Results:
+- Use `method: "ga"` (Genetic Algorithm)
+- Reduce `population_size` (e.g., 30)
+- Reduce `generations` (e.g., 50)
+- Test with fewer trainsets first
+
+### For Best Quality:
+- Use `method: "ensemble"` (runs multiple algorithms)
+- Increase `population_size` (e.g., 100)
+- Increase `generations` (e.g., 200)
+- Use `method: "cmaes"` for single-method optimization
+
+### Recommended Configurations:
+
+**Quick Testing (< 1 second):**
+```json
+{
+  "method": "ga",
+  "config": {
+    "population_size": 20,
+    "generations": 30
+  }
+}
+```
+
+**Production Use (2-5 seconds):**
+```json
+{
+  "method": "ga",
+  "config": {
+    "population_size": 50,
+    "generations": 100
+  }
+}
+```
+
+**High Quality (10-30 seconds):**
+```json
+{
+  "method": "ensemble",
+  "config": {
+    "population_size": 100,
+    "generations": 200
+  }
+}
+```
+
+---
+
+## Rate Limits
+
+Currently, no rate limits are enforced. Implement rate limiting for production use.
+
+---
+
+## Support
+
+For issues or questions:
+- Check the interactive documentation: http://localhost:8001/docs
+- Run the test suite: `python api/test_greedyoptim_api.py`
+- Review validation errors carefully - they indicate exactly what's wrong
+
+---
+
+## Changelog
+
+### Version 2.0.0 (2025-11-09)
+- Initial release of GreedyOptim API
+- Support for multiple optimization algorithms
+- Custom data input support
+- Validation and synthetic data generation
+- Method comparison capabilities