API_DOCUMENTATION.md

Drug-Food Interaction Prediction API Documentation

Overview

This API provides endpoints for predicting drug-food interactions using machine learning models trained on molecular descriptors and nutritional data.

Base URL

http://localhost:8000

Authentication

No authentication required for this demo API.

Endpoints

1. Health Check

GET /api/health

Returns the health status of the API and whether models are loaded.

Response:

{
  "status": "healthy",
  "models_loaded": true,
  "version": "1.0.0"
}

2. Get Drug Canonical SMILES

POST /api/drug/canonical

Get canonical SMILES representation for a drug from NCI Chemical Identifier Resolver.

Request Body:

{
  "drug_name": "aspirin"
}

Response:

{
  "drug_name": "aspirin",
  "canonical_smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"
}

3. Get Drug Molecular Descriptors

POST /api/drug/descriptors

Calculate molecular descriptors for a drug using RDKit.

Request Body:

{
  "drug_name": "aspirin"
}

Response:

{
  "drug_name": "aspirin",
  "canonical_smiles": "CC(=O)OC1=CC=CC=C1C(=O)O",
  "descriptors": {
    "MolWt": 180.16,
    "LogP": 1.19,
    "HBA": 4,
    "HBD": 1,
    "TPSA": 63.6,
    "RotBonds": 3,
    "RingCount": 1,
    "FractionCSP3": 0.1,
    "BalabanJ": 1.23,
    "BertzCT": 456.78,
    "FP_0": 0,
    "FP_1": 1,
    ...
  }
}

4. Get Food Nutrients

POST /api/food/nutrients

Get nutritional information for a food from USDA FoodData Central API.

Request Body:

{
  "food_name": "apple"
}

Response:

{
  "food_name": "apple",
  "nutrients": {
    "Fat": 0.2,
    "Carbohydrates": 14.0,
    "Protein": 0.3,
    "Vitamin_C": 4.6,
    "Vitamin_D": 0.0,
    "Vitamin_B12": 0.0,
    "Calcium": 6.0,
    "Iron": 0.12,
    "Magnesium": 5.0,
    "Potassium": 107.0,
    "Sodium": 1.0,
    "Zinc": 0.04
  }
}

5. Predict Drug-Food Interaction

POST /api/predict

Predict the interaction between a drug and food using trained XGBoost models.

Request Body:

{
  "drug_name": "warfarin",
  "food_name": "spinach"
}

Response:

{
  "effect": "harmful",
  "confidence": 0.94,
  "explanation": "High vitamin K content in spinach can counteract warfarin's anticoagulant effects. Monitor INR levels closely and consider dose adjustment.",
  "drug_properties": {
    "MolWt": 308.33,
    "LogP": 2.7,
    "HBA": 5,
    "HBD": 1,
    "TPSA": 63.6,
    "RotBonds": 4,
    "RingCount": 3,
    "FractionCSP3": 0.15,
    "BalabanJ": 1.45,
    "BertzCT": 789.12
  },
  "food_nutrients": {
    "Fat": 0.4,
    "Carbohydrates": 3.6,
    "Protein": 2.9,
    "Vitamin_C": 28.1,
    "Vitamin_D": 0.0,
    "Vitamin_B12": 0.0,
    "Calcium": 99.0,
    "Iron": 2.7,
    "Magnesium": 79.0,
    "Potassium": 558.0,
    "Sodium": 79.0,
    "Zinc": 0.53
  }
}

Effect Classifications

• harmful: Significant negative interaction that may cause adverse effects
• negative: Minor negative interaction that may reduce drug effectiveness
• no effect: No significant interaction expected
• positive: Beneficial interaction that may enhance drug effects
• possible: Potential interaction requiring monitoring

Error Responses

All endpoints may return the following error responses:

404 Not Found

{
  "detail": "Drug 'unknown_drug' not found in NCI database"
}

408 Request Timeout

{
  "detail": "NCI API timeout"
}

500 Internal Server Error

{
  "detail": "Error retrieving drug information: <error_message>"
}

Rate Limits

• NCI API: No specific limits documented
• USDA API: 1,000 requests per hour per IP address

Data Sources

1. NCI Chemical Identifier Resolver: https://cactus.nci.nih.gov/chemical/structure
2. USDA FoodData Central: https://fdc.nal.usda.gov/
3. RDKit: Molecular descriptor calculations
4. XGBoost: Machine learning predictions

Model Information

The prediction models were trained on a dataset of 23,950 drug-food interaction pairs with:

• Features: 2,082 total (molecular descriptors + nutritional data)
• Classes: 5 interaction types (harmful, negative, no effect, positive, possible)
• Accuracy: 88.3% on test set
• Algorithm: XGBoost Classifier

Usage Examples

Python Example

import requests

# Predict interaction
response = requests.post(
    "http://localhost:8000/api/predict",
    json={"drug_name": "aspirin", "food_name": "apple"}
)
result = response.json()
print(f"Effect: {result['effect']}")
print(f"Confidence: {result['confidence']:.2f}")

JavaScript Example

// Predict interaction
fetch('http://localhost:8000/api/predict', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        drug_name: 'aspirin',
        food_name: 'apple'
    })
})
.then(response => response.json())
.then(data => {
    console.log(`Effect: ${data.effect}`);
    console.log(`Confidence: ${data.confidence.toFixed(2)}`);
});

Support

For issues or questions, please refer to the API documentation at /docs when the server is running.