Adding Readme

README.md

@@ -1,561 +1,11 @@
-# 🚀 SLAQ Version C AI Engine
-
-**FastAPI-based Stutter Detection API for SLAQ Django Application**
-
-This is the AI engine microservice that provides stuttering analysis capabilities for the SLAQ Django application. It uses advanced ML models (MMS-1B) to detect and analyze stuttering events in audio recordings, with support for multiple Indian languages.
-
----
-
-## 📋 Table of Contents
-
-- [Overview](#overview)
-- [API Endpoints](#api-endpoints)
-- [Request/Response Formats](#requestresponse-formats)
-- [Language Support](#language-support)
-- [Integration with Django App](#integration-with-django-app)
-- [Configuration](#configuration)
-- [Error Handling](#error-handling)
-- [Health Checks](#health-checks)
-- [Deployment](#deployment)
-- [Recent Enhancements](#recent-enhancements)
-
----
-
-## 🎯 Overview
-
-The SLAQ AI Engine is a FastAPI service that:
-
-- **Analyzes audio files** for stuttering patterns using Meta's MMS-1B model
-- **Supports 15+ Indian languages** including Hindi, Tamil, Telugu, Bengali, and more
-- **Provides detailed analysis** including:
-  - Transcription accuracy
-  - Stutter event detection (repetitions, prolongations, blocks)
-  - Severity classification (none, mild, moderate, severe)
-  - Confidence scores and timestamps
-- **Integrates seamlessly** with the Django SLAQ application via HTTP API
-
-**Base URL:** `https://anfastech-slaq-version-c-ai-enginee.hf.space`
-
----
-
-## 🔌 API Endpoints
-
-### 1. Health Check
-
-**Endpoint:** `GET /health`
-
-**Description:** Check if the API is healthy and models are loaded.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "models_loaded": true,
-  "timestamp": "2024-01-15 10:30:45"
-}
-```
-
-**Status Codes:**
-- `200`: Service is healthy
-- `503`: Models not loaded yet
-
----
-
-### 2. Analyze Audio
-
-**Endpoint:** `POST /analyze`
-
-**Description:** Analyze an audio file for stuttering patterns.
-
-**Request Format:** `multipart/form-data`
-
-**Parameters:**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `audio` | File | ✅ Yes | - | Audio file (WAV, MP3, OGG, WebM) |
-| `transcript` | String | ❌ No | `""` | Optional expected transcript for comparison |
-| `language` | String | ❌ No | `"english"` | Language code (see [Language Support](#language-support)) |
-
-**Example Request (cURL):**
-```bash
-curl -X POST "https://anfastech-slaq-version-c-ai-enginee.hf.space/analyze" \
-  -F "[email protected]" \
-  -F "transcript=Hello world" \
-  -F "language=hindi"
-```
-
-**Example Request (Python):**
-```python
-import requests
-
-files = {"audio": ("recording.wav", open("recording.wav", "rb"), "audio/wav")}
-data = {
-    "transcript": "Hello world",
-    "language": "hindi"
-}
-
-response = requests.post(
-    "https://anfastech-slaq-version-c-ai-enginee.hf.space/analyze",
-    files=files,
-    data=data
-)
-
-result = response.json()
-```
-
-**Response Format:**
-```json
-{
-  "actual_transcript": "Hello world",
-  "target_transcript": "Hello world",
-  "mismatched_chars": [],
-  "mismatch_percentage": 0.0,
-  "ctc_loss_score": 0.15,
-  "stutter_timestamps": [
-    {
-      "type": "repetition",
-      "start": 1.5,
-      "end": 2.0,
-      "duration": 0.5,
-      "confidence": 0.85,
-      "text": "he-he"
-    }
-  ],
-  "total_stutter_duration": 0.5,
-  "stutter_frequency": 2.5,
-  "severity": "mild",
-  "confidence_score": 0.92,
-  "analysis_duration_seconds": 3.45,
-  "model_version": "external-api-v1",
-  "language_detected": "hin"
-}
-```
-
-**Response Fields:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `actual_transcript` | String | Transcribed text from audio |
-| `target_transcript` | String | Expected transcript (if provided) |
-| `mismatched_chars` | Array | List of character-level mismatches |
-| `mismatch_percentage` | Float | Percentage of mismatched characters (0-100) |
-| `ctc_loss_score` | Float | CTC loss score from model |
-| `stutter_timestamps` | Array | List of detected stutter events |
-| `total_stutter_duration` | Float | Total duration of stuttering in seconds |
-| `stutter_frequency` | Float | Frequency of stuttering events per minute |
-| `severity` | String | Severity classification: `none`, `mild`, `moderate`, `severe` |
-| `confidence_score` | Float | Overall confidence in analysis (0-1) |
-| `analysis_duration_seconds` | Float | Time taken for analysis |
-| `model_version` | String | Version of the model used |
-| `language_detected` | String | Detected/used language code |
-
-**Stutter Event Format:**
-```json
-{
-  "type": "repetition" | "prolongation" | "block" | "dysfluency",
-  "start": 1.5,
-  "end": 2.0,
-  "duration": 0.5,
-  "confidence": 0.85,
-  "text": "he-he"
-}
-```
-
-**Status Codes:**
-- `200`: Analysis successful
-- `400`: Invalid request (missing audio file, invalid format)
-- `500`: Analysis failed (internal error)
-- `503`: Models not loaded yet
-
----
-
-### 3. API Documentation
-
-**Endpoint:** `GET /`
-
-**Description:** Get API information and documentation.
-
-**Response:**
-```json
-{
-  "name": "SLAQ Stutter Detector API",
-  "version": "1.0.0",
-  "status": "running",
-  "endpoints": {
-    "health": "GET /health",
-    "analyze": "POST /analyze (multipart form: audio file, transcript (optional), language (optional, default: 'english'))",
-    "docs": "GET /docs (interactive API docs)"
-  },
-  "models": {
-    "base": "facebook/wav2vec2-base-960h",
-    "large": "facebook/wav2vec2-large-960h-lv60-self",
-    "xlsr": "jonatasgrosman/wav2vec2-large-xlsr-53-english"
-  }
-}
-```
-
-**Interactive Docs:** `GET /docs` (Swagger UI)
-
----
-
-## 🌐 Language Support
-
-The API supports **15+ Indian languages** through the MMS-1B model:
-
-### Supported Languages
-
-| Language | Code | Language | Code |
-|----------|------|----------|------|
-| Hindi | `hindi` / `hin` | Tamil | `tamil` / `tam` |
-| Telugu | `telugu` / `tel` | Bengali | `bengali` / `ben` |
-| Marathi | `marathi` / `mar` | Gujarati | `gujarati` / `guj` |
-| Kannada | `kannada` / `kan` | Malayalam | `malayalam` / `mal` |
-| Punjabi | `punjabi` / `pan` | Urdu | `urdu` / `urd` |
-| Assamese | `assamese` / `asm` | Odia | `odia` / `ory` |
-| Bhojpuri | `bhojpuri` / `bho` | Maithili | `maithili` / `mai` |
-| English | `english` / `eng` | - | - |
-
-**Usage:**
-- You can use either the full language name (`"hindi"`) or the 3-letter code (`"hin"`)
-- Default language is `"english"` if not specified
-- Language is automatically resolved to the correct MMS language code
-
----
-
-## 🔗 Integration with Django App
-
-### Django Configuration
-
-The Django application (`slaq-version-c`) connects to this AI engine via HTTP API. Configuration is done in `slaq_project/settings.py`:
-
-```python
-# AI Engine API Configuration
-STUTTER_API_URL = env('STUTTER_API_URL', default='https://anfastech-slaq-version-c-ai-enginee.hf.space/analyze')
-STUTTER_API_TIMEOUT = env.int('STUTTER_API_TIMEOUT', default=300)  # 5 minutes
-DEFAULT_LANGUAGE = env('DEFAULT_LANGUAGE', default='hindi')
-STUTTER_API_MAX_RETRIES = env.int('STUTTER_API_MAX_RETRIES', default=3)
-STUTTER_API_RETRY_DELAY = env.int('STUTTER_API_RETRY_DELAY', default=5)  # seconds
-```
-
-### Environment Variables
-
-Add to your Django `.env` file:
-
-```env
-STUTTER_API_URL=https://anfastech-slaq-version-c-ai-enginee.hf.space/analyze
-STUTTER_API_TIMEOUT=300
-DEFAULT_LANGUAGE=hindi
-STUTTER_API_MAX_RETRIES=3
-STUTTER_API_RETRY_DELAY=5
-```
-
-### Django Integration Flow
-
-1. **User uploads audio** via Django web interface
-2. **Django creates Celery task** (`process_audio_recording`)
-3. **Celery worker calls** `StutterDetector.analyze_audio()`
-4. **StutterDetector sends HTTP POST** to this AI engine API
-5. **AI engine processes audio** using MMS-1B model
-6. **Results returned** to Django and saved to database
-
-### Request/Response Compatibility
-
-✅ **Verified Compatible:**
-
-- **Django sends:** `multipart/form-data` with:
-  - `files={"audio": (filename, file_obj, mime_type)}`
-  - `data={"transcript": "...", "language": "..."}`
-  
-- **FastAPI receives:** 
-  - `audio: UploadFile = File(...)`
-  - `transcript: str = Form("")`
-  - `language: str = Form("english")`
-
-✅ **Format is fully compatible and tested.**
-
----
-
-## ⚙️ Configuration
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `7860` | Server port (HuggingFace Spaces uses 7860) |
-| `PYTHONUNBUFFERED` | `1` | Enable unbuffered Python output |
-
-### Model Configuration
-
-Models are loaded automatically on startup:
-- **MMS-1B Model:** `facebook/mms-1b-all` (for transcription)
-- **Language ID Model:** `facebook/mms-lid-126` (for language detection)
-- **Device:** Auto-detects CUDA if available, otherwise CPU
-
----
-
-## 🛡️ Error Handling
-
-### Error Response Format
-
-```json
-{
-  "detail": "Error message describing what went wrong"
-}
-```
-
-### Common Error Scenarios
-
-| Status Code | Scenario | Solution |
-|------------|----------|----------|
-| `400` | Missing audio file | Ensure `audio` parameter is included |
-| `400` | Invalid file format | Use supported formats: WAV, MP3, OGG, WebM |
-| `500` | Analysis failed | Check logs for detailed error, retry request |
-| `503` | Models not loaded | Wait a few seconds and retry (models load on startup) |
-| `504` | Request timeout | Increase timeout or use smaller audio file |
-
-### Retry Logic (Django Side)
-
-The Django application implements automatic retry logic:
-
-- **Max Retries:** 3 attempts (configurable)
-- **Retry Delay:** 5 seconds between retries (configurable)
-- **Retries on:** Connection errors, timeouts, 503 (Service Unavailable)
-- **No retry on:** 4xx errors (except 503), invalid requests
-
----
-
-## 🏥 Health Checks
-
-### Health Check Endpoint
-
-**Endpoint:** `GET /health`
-
-**Use Case:** Monitor API availability and model loading status.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "models_loaded": true,
-  "timestamp": "2024-01-15 10:30:45"
-}
-```
-
-### Django Health Check Integration
-
-The Django app includes a `check_api_health()` method in `StutterDetector`:
-
-```python
-from diagnosis.ai_engine.detect_stuttering import StutterDetector
-
-detector = StutterDetector()
-health = detector.check_api_health()
-
-if health['healthy']:
-    print(f"✅ API is healthy (response time: {health['response_time']}s)")
-else:
-    print(f"❌ API is unhealthy: {health['message']}")
-```
-
-**Health Check Response:**
-```python
-{
-    'healthy': True,
-    'status_code': 200,
-    'message': 'API is healthy and accessible',
-    'response_time': 0.15,  # seconds
-    'details': {
-        'status': 'healthy',
-        'models_loaded': True
-    }
-}
-```
-
----
-
-## 🚀 Deployment
-
-### HuggingFace Spaces
-
-This AI engine is deployed on **HuggingFace Spaces**:
-
-**Space URL:** `https://huggingface.co/spaces/anfastech/slaq-version-c-ai-enginee`
-
-**Deployment Configuration:**
-- **SDK:** Docker
-- **Hardware:** GPU (if available)
-- **Port:** 7860 (HuggingFace default)
-
-### Local Development
-
-1. **Install Dependencies:**
-```bash
-pip install -r requirements.txt
-```
-
-2. **Run Locally:**
-```bash
-python app.py
-```
-
-3. **Access API:**
-- API: `http://localhost:7860`
-- Docs: `http://localhost:7860/docs`
-- Health: `http://localhost:7860/health`
-
-### Docker Deployment
-
-```bash
-docker build -t slaq-ai-engine .
-docker run -p 7860:7860 slaq-ai-engine
-```
-
----
-
-## ✨ Recent Enhancements
-
-### Version 1.0.0 (Latest)
-
-#### ✅ 1. Fixed API URL
-- **Changed:** API URL updated from `slaq-version-d-ai-test-engine` to `slaq-version-c-ai-enginee`
-- **Location:** `slaq-version-c/diagnosis/ai_engine/detect_stuttering.py:25`
-- **Impact:** Django app now correctly points to the version C AI engine
-
-#### ✅ 2. Language Parameter Support
-- **Added:** `language` parameter to `/analyze` endpoint
-- **Format:** `Form("english")` - accepts language name or code
-- **Default:** `"english"` if not provided
-- **Impact:** Enables multi-language stutter detection
-
-#### ✅ 3. Django Settings Configuration
-- **Added:** Configurable API settings via environment variables
-  - `STUTTER_API_URL`
-  - `STUTTER_API_TIMEOUT`
-  - `DEFAULT_LANGUAGE`
-  - `STUTTER_API_MAX_RETRIES`
-  - `STUTTER_API_RETRY_DELAY`
-- **Impact:** Easy configuration without code changes
-
-#### ✅ 4. Enhanced Error Handling & Retry Logic
-- **Added:** Automatic retry mechanism (3 attempts by default)
-- **Features:**
-  - Configurable retry count and delay
-  - Smart retry on transient errors (timeout, connection errors, 503)
-  - No retry on permanent errors (4xx except 503)
-  - Detailed logging for each attempt
-- **Impact:** Improved reliability and resilience
-
-#### ✅ 5. Health Check Functionality
-- **Added:** `check_api_health()` method in Django `StutterDetector`
-- **Features:**
-  - Checks API connectivity
-  - Measures response time
-  - Returns detailed health status
-- **Impact:** Better monitoring and debugging
-
-#### ✅ 6. Request/Response Format Verification
-- **Verified:** Full compatibility between Django and FastAPI
-- **Format:** `multipart/form-data` with proper field mapping
-- **Impact:** Reliable integration between services
-
----
-
-## 📊 Performance
-
-### Typical Response Times
-
-| Audio Duration | Analysis Time | Total Time (with network) |
-|---------------|---------------|---------------------------|
-| 5 seconds | ~2-3 seconds | ~3-4 seconds |
-| 30 seconds | ~5-8 seconds | ~6-10 seconds |
-| 2 minutes | ~15-25 seconds | ~20-30 seconds |
-| 5 minutes | ~40-60 seconds | ~50-70 seconds |
-
-*Times may vary based on audio complexity, language, and server load.*
-
-### Timeout Configuration
-
-- **Default Timeout:** 300 seconds (5 minutes)
-- **Configurable:** Via `STUTTER_API_TIMEOUT` environment variable
-- **Recommendation:** Set timeout to at least 2x expected analysis time
-
 ---
-
-## 🔍 Troubleshooting
-
-### Common Issues
-
-#### 1. Models Not Loading
-**Symptom:** `503 Service Unavailable` or `models_loaded: false`
-
-**Solution:**
-- Wait 30-60 seconds after deployment (models load on startup)
-- Check logs for model loading errors
-- Verify sufficient memory/GPU resources
-
-#### 2. Request Timeout
-**Symptom:** `504 Gateway Timeout` or timeout errors
-
-**Solution:**
-- Increase `STUTTER_API_TIMEOUT` in Django settings
-- Use shorter audio files for testing
-- Check network connectivity
-
-#### 3. Language Not Supported
-**Symptom:** Incorrect transcription or errors
-
-**Solution:**
-- Verify language code is in supported list
-- Use full language name or 3-letter code
-- Check language code mapping in Django `detect_stuttering.py`
-
-#### 4. File Format Issues
-**Symptom:** `400 Bad Request` or analysis fails
-
-**Solution:**
-- Use supported formats: WAV, MP3, OGG, WebM
-- Ensure file is valid audio (not corrupted)
-- Check file size (max recommended: 10MB)
-
----
-
-## 📝 API Changelog
-
-### 2024-01-15 - Version 1.0.0
-- ✅ Added language parameter support
-- ✅ Enhanced error handling
-- ✅ Added health check endpoint
-- ✅ Improved logging and monitoring
-- ✅ Fixed API URL to point to version C engine
-
----
-
-## 📚 Additional Resources
-
-- **Django Integration:** See `slaq-version-c/diagnosis/ai_engine/detect_stuttering.py`
-- **API Documentation:** Visit `/docs` endpoint for interactive Swagger UI
-- **HuggingFace Spaces:** https://huggingface.co/docs/hub/spaces
-- **FastAPI Docs:** https://fastapi.tiangolo.com/
-
----
-
-## 📄 License
-
-This project is part of the SLAQ (Speech Language Assessment & Quantification) system.
-
----
-
-## 🤝 Support
-
-For issues or questions:
-1. Check the troubleshooting section above
-2. Review API logs for detailed error messages
-3. Verify Django configuration matches this documentation
-4. Check health endpoint: `GET /health`
-
+title: Slaq Version C Ai Enginee
+emoji: 🐠
+colorFrom: yellow
+colorTo: red
+sdk: docker
+pinned: false
+short_description: slaq version c ai enginee deployment
 ---
 
-**Last Updated:** 2024-01-15  
-**API Version:** 1.0.0  
-**Status:** ✅ Production Ready
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference