feat(api): production security, cors hardening, latency optimizations, postman artifacts & frontend documentation

2026-08-31 13:48:54 +05:30
parent 4e21d617ce
commit e91cdbae6e
48 changed files with 3742 additions and 65 deletions
@@ -0,0 +1,149 @@
+# Voice Onboarding & Audio API Reference
+
+**Implementation Sources**: [`app/api/voice_onboarding.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/voice_onboarding.py), [`app/services/voice_service.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/services/voice_service.py)
+
+---
+
+## 1. POST `/v1/voice-onboarding/start`
+
+Starts a voice-first onboarding session with Sarvam AI multilingual speech engine.
+
+### Request Body (`StartVoiceOnboardingRequest`):
+```json
+{
+  "patient": {
+    "id": "PAT-VOICE-1",
+    "name": "Ramesh G",
+    "age": 34,
+    "gender": "male"
+  },
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "ta-IN"
+}
+```
+
+### Supported Language Codes:
+- `en-IN` (Indian English)
+- `ta-IN` (Tamil)
+- `hi-IN` (Hindi)
+- `te-IN` (Telugu)
+- `kn-IN` (Kannada)
+- `ml-IN` (Malayalam)
+- `mr-IN` (Marathi)
+
+### Successful Response (`200 OK` - `StartVoiceOnboardingResponse`):
+```json
+{
+  "success": true,
+  "session_id": "VOICE-D3CAEA5C",
+  "patient_id": "PAT-VOICE-1",
+  "category": {
+    "type": "general",
+    "code": "general_medicine",
+    "name": "General Medicine"
+  },
+  "language": "ta-IN",
+  "status": "in_progress",
+  "stage": "greeting",
+  "greeting_text": "வணக்கம் Ramesh G, CureSelect மருத்துவமனைக்கு வரவேற்கிறோம். இன்று உங்களுக்கு என்ன சுகவீனம் உள்ளது?",
+  "audio_url": "/v1/voice-onboarding/audio/aud_a1b2c3d4e5f6",
+  "response_time_ms": 78.32,
+  "response_time_sec": 0.08
+}
+```
+
+---
+
+## 2. POST `/v1/voice-onboarding/{session_id}/turn`
+
+Processes a conversational voice turn using audio recording or text fallback.
+
+### Request Headers:
+```http
+Content-Type: multipart/form-data
+Authorization: Bearer test_token_PAT-VOICE-1
+```
+
+### Multipart Form Data Parameters:
+- `audio`: Binary audio recording file (`WAV`, `WEBM`, `MP3`, `OGG` up to 10MB).
+- `text_fallback`: String text transcript (used if WebSpeech STT processed client-side or audio is unprovided).
+
+*Note: At least one of `audio` or `text_fallback` must be provided.*
+
+### Successful Response (`200 OK` - `VoiceTurnResponse`):
+```json
+{
+  "success": true,
+  "session_id": "VOICE-D3CAEA5C",
+  "patient_transcript": "எனக்கு கடந்த 3 நாளா நெஞ்சு பாரமா இருக்குங்க.",
+  "ai_text": "நன்றி. இந்த நெஞ்சு பாரம் உடற்பயிற்சி செய்யும் போது அதிகமாகிறதா?",
+  "stage": "symptoms",
+  "completed": false,
+  "audio_url": "/v1/voice-onboarding/audio/aud_f9e8d7c6b5a4",
+  "audio_base64": null,
+  "suggested_specialty": {
+    "specialty": "Cardiology",
+    "reason": "Chest tightness reported"
+  },
+  "response_time_ms": 1412.37,
+  "response_time_sec": 1.41
+}
+```
+
+---
+
+## 3. GET `/v1/voice-onboarding/audio/{audio_id}`
+
+Streams generated TTS audio for browser or mobile playback.
+
+### Request Headers:
+No authentication required for audio file streaming.
+
+### Response Headers:
+```http
+HTTP/1.1 200 OK
+Content-Type: audio/wav (or audio/mpeg)
+Accept-Ranges: bytes
+Content-Length: 48290
+```
+
+### Frontend Audio Playback snippet:
+```javascript
+const audio = new Audio(`${BASE_URL}/v1/voice-onboarding/audio/${audioId}`);
+await audio.play();
+```
+
+---
+
+## 4. POST `/v1/voice-onboarding/{session_id}/complete`
+
+Finalizes a voice onboarding session.
+
+### Request Body:
+```json
+{
+  "confirmed": true
+}
+```
+
+### Successful Response (`200 OK`):
+```json
+{
+  "success": true,
+  "session_id": "VOICE-D3CAEA5C",
+  "status": "completed",
+  "result": {
+    "patient_id": "PAT-VOICE-1",
+    "chief_complaint": "Chest tightness for 3 days",
+    "language": "ta-IN",
+    "onboarding_completed": true
+  },
+  "message": "Voice onboarding successfully saved to patient record.",
+  "response_time_ms": 4121.79,
+  "response_time_sec": 4.12
+}
+```