docs/API_GUIDE.md

# DCRM Analysis API - Quick Start Guide

## 📋 Overview
This FastAPI wrapper provides a REST API endpoint for DCRM (Dynamic Contact Resistance Measurement) analysis. It accepts CSV uploads and returns comprehensive JSON analysis reports.

## 🚀 Quick Start

### 1. Install Dependencies
```bash

pip install -r requirements_api.txt

```

### 2. Configure Deployment URL
Open `dcrm_api.py` and update line 46:
```python

DEPLOYMENT_URL = "http://localhost:5000"  # Change to your deployed URL

```

### 3. Run the API Server
```bash

python dcrm_api.py

```

The API will start on `http://localhost:5000`

## 📡 API Endpoints

### Main Analysis Endpoint
**POST** `/api/circuit-breakers/{breaker_id}/tests/upload`

**Parameters:**
- `breaker_id` (path parameter): Circuit breaker identifier
- `file` (form-data): CSV file with DCRM test data

**Example Request (using curl):**
```bash

curl -X POST \

  "http://localhost:5000/api/circuit-breakers/6926e63d4614721a79b7b24e/tests/upload" \

  -F "file=@df3_final.csv"

```

**Example Request (using Python requests):**
```python

import requests



url = "http://localhost:5000/api/circuit-breakers/6926e63d4614721a79b7b24e/tests/upload"

files = {'file': open('df3_final.csv', 'rb')}

response = requests.post(url, files=files)

print(response.json())

```

**Example Request (using JavaScript/Fetch):**
```javascript

const formData = new FormData();

formData.append('file', csvFile);  // csvFile is a File object



fetch('http://localhost:5000/api/circuit-breakers/6926e63d4614721a79b7b24e/tests/upload', {

  method: 'POST',

  body: formData

})

.then(response => response.json())

.then(data => console.log(data));

```

### Health Check Endpoints

**GET** `/`
- Simple health check
- Returns API status and version

**GET** `/api/health`
- Detailed health check
- Returns status of all components (LLM, ViT model, etc.)

## 📄 CSV Format Requirements

The uploaded CSV must contain these columns:
- `Time_ms` - Time in milliseconds
- `Resistance` - Resistance values in µΩ
- `Current` - Current values
- `Travel` - Travel distance
- `Close_Coil` - Close coil current
- `Trip_Coil_1` - Trip coil 1 current
- `Trip_Coil_2` - Trip coil 2 current

**Minimum rows:** 100 (typically ~400 rows)

## 📤 Response Format

The API returns a comprehensive JSON report matching the structure in `data/dcrm-sample-response.txt`, including:

- **aiVerdict**: AI-generated fault analysis and recommendations
- **breakerId**: Circuit breaker ID from the request
- **cbhi**: Composite Breaker Health Index with history
- **kpis**: Array of Key Performance Indicators
- **phaseWiseAnalysis**: Detailed analysis of 5 operational phases
- **waveform**: Time-series data with SHAP values
- **findings**: Summary of detected faults
- **healthScore**: Overall health score (0-100)

## ⚠️ Error Handling

The API returns detailed error messages for common issues:

### Invalid File Type (400)
```json

{

  "error": "Invalid file type",

  "message": "Only CSV files are accepted",

  "received": "data.xlsx"

}

```

### Missing Columns (400)
```json

{

  "error": "Missing required columns",

  "missing": ["Travel", "Current"],

  "required": ["Time_ms", "Resistance", "Current", ...],

  "found": ["Time_ms", "Resistance", ...]

}

```

### Insufficient Data (400)
```json

{

  "error": "Insufficient data",

  "message": "CSV must contain at least 100 rows of data",

  "received_rows": 50

}

```

### Analysis Failure (500)
```json

{

  "error": "Analysis failed",

  "message": "An error occurred during DCRM analysis",

  "error_type": "ValueError",

  "error_details": "..."

}

```

## 🔧 Configuration Options

### Change Port
Edit the last line in `dcrm_api.py`:
```python

uvicorn.run(app, host="0.0.0.0", port=5000)  # Change port here

```

### Enable/Disable CORS
Modify the CORS middleware settings (line 60):
```python

app.add_middleware(

    CORSMiddleware,

    allow_origins=["*"],  # Change to specific domains for security

    ...

)

```

### Update Google API Key
Change the API key on line 20:
```python

os.environ["GOOGLE_API_KEY"] = "your-api-key-here"

```

## 🌐 Deployment

### Local Development
```bash

python dcrm_api.py

```

### Production (using Gunicorn + Uvicorn)
```bash

pip install gunicorn

gunicorn dcrm_api:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:5000

```

### Docker Deployment
Create a `Dockerfile`:
```dockerfile

FROM python:3.10-slim

WORKDIR /app

COPY requirements_api.txt .

RUN pip install -r requirements_api.txt

COPY . .

CMD ["python", "dcrm_api.py"]

```

Build and run:
```bash

docker build -t dcrm-api .

docker run -p 5000:5000 dcrm-api

```

## 📊 API Documentation

Once the server is running, visit:
- **Swagger UI**: http://localhost:5000/docs
- **ReDoc**: http://localhost:5000/redoc

These provide interactive API documentation and testing interfaces.

## 🧪 Testing

Test with the sample CSV:
```bash

curl -X POST \

  "http://localhost:5000/api/circuit-breakers/test-123/tests/upload" \

  -F "file=@df3_final (1).csv" \

  -o response.json

```

## 🔍 Monitoring

The API logs all requests and errors to the console. For production, consider:
- Setting up proper logging (to files or logging services)
- Adding request/response monitoring
- Implementing rate limiting
- Adding authentication if needed

## 💡 Tips

1. **Processing Time**: Analysis typically takes 30-60 seconds due to AI processing
2. **Concurrent Requests**: The API can handle multiple requests, but heavy AI processing may slow down responses
3. **File Size**: Keep CSV files under 5MB for optimal performance
4. **Caching**: Consider implementing caching for repeated analyses of the same data

## 📞 Support

For issues or questions, check:
- API logs in the console
- Error messages in the response
- The `/api/health` endpoint for component status