Upload API_DOCUMENTATION.md

API_DOCUMENTATION.md

@@ -0,0 +1,264 @@
+# PPD Recommendation API - Documentation
+
+## Base URL
+```
+http://localhost:8000
+```
+
+## Authentication
+Currently no authentication required. For production, implement API key or JWT authentication.
+
+---
+
+## Endpoints
+
+### 1. Health Check
+**GET** `/`
+
+**Response:**
+```json
+{
+  "status": "online",
+  "engine_ready": true,
+  "version": "1.5"
+}
+```
+
+---
+
+### 2. Detailed Health Check
+**GET** `/api/health`
+
+**Description:** Container health monitoring endpoint
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2026-01-29T18:10:00",
+  "checks": {
+    "database": "ok",
+    "model": "ok",
+    "articles_loaded": 139
+  }
+}
+```
+
+---
+
+### 3. System Statistics
+**GET** `/api/stats`
+
+**Description:** Get system metrics and article counts
+
+**Response:**
+```json
+{
+  "total_articles": 139,
+  "articles_by_type": {
+    "pubmed": 136,
+    "text": 2,
+    "html": 1
+  },
+  "articles_by_risk": {
+    "All": 136,
+    "Moderate": 2,
+    "High": 1
+  },
+  "model_vocabulary_size": 20652,
+  "last_updated": "2026-01-29T18:10:00"
+}
+```
+
+---
+
+### 4. Get Recommendations (Main Endpoint)
+**POST** `/api/recommend`
+
+**Description:** Get personalized article recommendations based on symptoms and crisis level
+
+**Request Body:**
+```json
+{
+  "risk_level": "Moderate",
+  "symptoms_text": "I feel sad and have trouble sleeping",
+  "top_n": 5
+}
+```
+
+**Parameters:**
+- `risk_level` (string, required): One of "Low", "Moderate", "High"
+- `symptoms_text` (string, required): User's symptom description
+- `top_n` (integer, optional): Number of recommendations (default: 5)
+
+**Response:**
+```json
+{
+  "status": "success",
+  "risk_assessment": "Moderate",
+  "recommendations": [
+    {
+      "article_id": 134,
+      "title": "Sleep disturbances in postpartum depression",
+      "category": "General",
+      "risk_level": "All",
+      "format_type": "pubmed",
+      "external_url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
+      "access_type": "External Link",
+      "final_score": 0.856
+    }
+  ]
+}
+```
+
+---
+
+### 5. Get Article Content
+**GET** `/api/article/{article_id}`
+
+**Description:** Retrieve full content for a specific article
+
+**Parameters:**
+- `article_id` (integer, path): Article ID from recommendation
+
+**Response:**
+```json
+{
+  "article_id": 134,
+  "title": "Sleep disturbances in postpartum depression",
+  "category": "General",
+  "format_type": "pubmed",
+  "external_url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
+  "content": "Full article abstract or content..."
+}
+```
+
+**Error Response (404):**
+```json
+{
+  "detail": "Article not found"
+}
+```
+
+---
+
+### 3. Real-Time PubMed Search
+**GET** `/api/pubmed/search`
+
+**Description:** Proxy endpoint to fetch articles directly from PubMed in real-time.
+
+**Parameters:**
+- `query` (string, optional): Search term (default: "postpartum depression")
+- `limit` (int, optional): Number of results (default: 10)
+
+**Response:**
+```json
+{
+  "status": "success",
+  "count": 2,
+  "results": [
+    {
+      "title": "Article Title",
+      "content": "Abstract content...",
+      "url": "https://pubmed.ncbi.nlm.nih.gov/12345/"
+    }
+  ]
+}
+```
+
+---
+
+### 6. Rebuild TF-IDF Model (Admin)
+**POST** `/api/admin/rebuild-model`
+
+**Description:** Manually trigger model rebuild from existing database
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Weighted TF-IDF model rebuilt and reloaded."
+}
+```
+
+---
+
+### 7. Trigger PubMed Ingestion (Admin)
+**POST** `/api/admin/trigger-ingestion`
+
+**Description:** Manually fetch new articles from PubMed and rebuild model
+
+**Response:**
+```json
+{
+  "status": "success",
+  "message": "Ingested 15 new articles and rebuilt model."
+}
+```
+
+---
+
+## Error Responses
+
+All endpoints return standard HTTP status codes:
+- `200`: Success
+- `404`: Resource not found
+- `500`: Internal server error
+
+Error format:
+```json
+{
+  "detail": "Error message description"
+}
+```
+
+---
+
+## Integration Examples
+
+### JavaScript (Fetch API)
+```javascript
+// Get recommendations
+const response = await fetch('http://localhost:8000/api/recommend', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    risk_level: 'Moderate',
+    symptoms_text: 'anxiety and sleep problems',
+    top_n: 3
+  })
+});
+const data = await response.json();
+console.log(data.recommendations);
+```
+
+### Python (Requests)
+```python
+import requests
+
+response = requests.post('http://localhost:8000/api/recommend', json={
+    'risk_level': 'High',
+    'symptoms_text': 'severe depression and suicidal thoughts',
+    'top_n': 5
+})
+recommendations = response.json()['recommendations']
+```
+
+### cURL
+```bash
+curl -X POST http://localhost:8000/api/recommend \
+  -H "Content-Type: application/json" \
+  -d '{"risk_level":"Low","symptoms_text":"mild anxiety","top_n":3}'
+```
+
+---
+
+## Rate Limiting
+Currently no rate limiting. Recommended for production:
+- 100 requests per minute per IP
+- 1000 requests per hour per IP
+
+---
+
+## CORS
+CORS is enabled for all origins in development. For production, restrict to specific domains.