fix(api): resolve SlowAPI request param conflict, update schema_extra naming, enhance tests, and serve Swagger UI at root

README.md

@@ -72,10 +72,10 @@ app/
 ## 🔗 API Endpoints
 
 ### Health & Monitoring
-- **`GET /`** - Basic health check
+- **`GET /`** - Interactive Swagger UI documentation
+- **`GET /status`** - Basic health check
 - **`GET /health`** - Detailed health monitoring
 - **`GET /metrics`** - Prometheus metrics
-- **`GET /docs`** - Swagger UI documentation
 - **`GET /redoc`** - ReDoc documentation
 
 ### Translation

app/api/v1/endpoints.py

@@ -48,13 +48,13 @@ router = APIRouter()
 
 
 @router.get(
-    "/",
+    "/status",
     response_model=HealthResponse,
     tags=["Health & Monitoring"],
     summary="Basic Health Check",
     description="Quick health check endpoint that returns basic API status information."
 )
-async def root():
+async def status_check():
     """
     ## Basic Health Check
 
@@ -182,8 +182,8 @@ async def get_metrics():
 )
 @limiter.limit(f"{settings.max_requests_per_minute}/minute")
 async def translate_endpoint(
-    request: TranslationRequest,
-    http_request: Request
+    translation_request: TranslationRequest,
+    request: Request
 ):
     """
     ## 🌍 Translate Text
@@ -239,47 +239,47 @@ async def translate_endpoint(
     - Unique request ID for debugging
     - Timestamp in Nairobi timezone
     """
-    request_id = http_request.state.request_id
+    request_id = request.state.request_id
 
     # Validate text length
-    if len(request.text) > settings.max_text_length:
+    if len(translation_request.text) > settings.max_text_length:
         raise HTTPException(
             status_code=413,
             detail=f"Text too long. Maximum {settings.max_text_length} characters allowed."
         )
 
     full_date, _ = get_nairobi_time()
-    character_count = len(request.text)
+    character_count = len(translation_request.text)
 
     # Log translation request
     logger.info(
         "translation_started",
         request_id=request_id,
-        source_language=request.source_language,
-        target_language=request.target_language,
+        source_language=translation_request.source_language,
+        target_language=translation_request.target_language,
         character_count=character_count
     )
 
     try:
-        if request.source_language:
+        if translation_request.source_language:
             # Use provided source language
             translated_text, inference_time = translate_with_source(
-                request.text,
-                request.source_language,
-                request.target_language
+                translation_request.text,
+                translation_request.source_language,
+                translation_request.target_language
             )
-            source_lang = request.source_language
+            source_lang = translation_request.source_language
         else:
             # Auto-detect source language
             source_lang, translated_text, inference_time = translate_with_detection(
-                request.text,
-                request.target_language
+                translation_request.text,
+                translation_request.target_language
             )
 
         # Update metrics
         TRANSLATION_COUNT.labels(
             source_lang=source_lang,
-            target_lang=request.target_language
+            target_lang=translation_request.target_language
         ).inc()
 
         CHARACTER_COUNT.inc(character_count)
@@ -289,7 +289,7 @@ async def translate_endpoint(
             "translation_completed",
             request_id=request_id,
             source_language=source_lang,
-            target_language=request.target_language,
+            target_language=translation_request.target_language,
             character_count=character_count,
             inference_time=inference_time
         )
@@ -297,7 +297,7 @@ async def translate_endpoint(
         return TranslationResponse(
             translated_text=translated_text,
             source_language=source_lang,
-            target_language=request.target_language,
+            target_language=translation_request.target_language,
             inference_time=inference_time,
             character_count=character_count,
             timestamp=full_date,
@@ -311,8 +311,8 @@ async def translate_endpoint(
             request_id=request_id,
             error=str(e),
             error_type=type(e).__name__,
-            source_language=request.source_language,
-            target_language=request.target_language
+            source_language=translation_request.source_language,
+            target_language=translation_request.target_language
         )
 
         # Update error metrics

app/main.py

@@ -68,7 +68,7 @@ curl -X POST "/translate" \\
 ```
         """,
         version=settings.app_version,
-        docs_url="/docs",
+        docs_url="/",
         redoc_url="/redoc",
         openapi_url="/openapi.json",
         contact={
@@ -114,7 +114,8 @@ curl -X POST "/translate" \\
 
     # Include API routes
     app.include_router(v1_router, prefix="/api/v1")
-    app.include_router(v1_router)  # Also include at root for backward compatibility
+    # Include routes at root level (excluding root path which is now Swagger UI)
+    app.include_router(v1_router, prefix="", include_in_schema=False)
 
     return app
 
@@ -137,9 +138,10 @@ async def startup_event():
         print("🎉 API started successfully!")
         print(f"📊 Metrics enabled: {settings.enable_metrics}")
         print(f"🔒 Environment: {settings.environment}")
-        print(f"📝 Documentation: /docs")
+        print(f"📝 Documentation: / (Swagger UI)")
         print(f"📈 Metrics: /metrics")
         print(f"❤️  Health: /health")
+        print(f"🔍 Status: /status")
         print(f"🔗 API v1: /api/v1/")
         print()
 

app/models/schemas.py

@@ -37,7 +37,7 @@ class TranslationRequest(BaseModel):
     )
 
     class Config:
-        schema_extra = {
+        json_schema_extra = {
             "examples": [
                 {
                     "summary": "Auto-detect source language",
@@ -128,7 +128,7 @@ class TranslationResponse(BaseModel):
     )
 
     class Config:
-        schema_extra = {
+        json_schema_extra = {
             "example": {
                 "translated_text": "Good morning",
                 "source_language": "swh_Latn",
@@ -184,7 +184,7 @@ class LanguagesResponse(BaseModel):
     total_count: int = Field(..., description="Total number of languages")
 
     class Config:
-        schema_extra = {
+        json_schema_extra = {
             "example": {
                 "languages": {
                     "swh_Latn": {
@@ -218,7 +218,7 @@ class LanguageStatsResponse(BaseModel):
     by_region: Dict[str, int] = Field(..., description="Language count by region")
 
     class Config:
-        schema_extra = {
+        json_schema_extra = {
             "example": {
                 "total_languages": 200,
                 "regions": 6,

curl_commands.md

@@ -0,0 +1,263 @@
+# Sema Translation API - Curl Commands
+
+## 🌐 Base URL
+```bash
+# Production
+API_URL="https://sematech-sema-api.hf.space"
+
+# Local development
+# API_URL="http://localhost:8000"
+```
+
+## 🏥 Health Check Endpoints
+
+### Basic Health Check
+```bash
+curl -X GET "$API_URL/status"
+```
+
+### Detailed Health Check
+```bash
+curl -X GET "$API_URL/health"
+```
+
+### Metrics (if enabled)
+```bash
+curl -X GET "$API_URL/metrics"
+```
+
+## 🌍 Translation Endpoints
+
+### Basic Translation (Auto-detect source language)
+```bash
+curl -X POST "$API_URL/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Habari ya asubuhi",
+    "target_language": "eng_Latn"
+  }'
+```
+
+### Translation with Specified Source Language
+```bash
+curl -X POST "$API_URL/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Good morning",
+    "source_language": "eng_Latn",
+    "target_language": "swh_Latn"
+  }'
+```
+
+### Translation with Versioned Endpoint
+```bash
+curl -X POST "$API_URL/api/v1/translate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "text": "Wĩ mwega?",
+    "source_language": "kik_Latn",
+    "target_language": "eng_Latn"
+  }'
+```
+
+## 🗣️ Language Information Endpoints
+
+### Get All Supported Languages
+```bash
+curl -X GET "$API_URL/languages"
+```
+
+### Get Popular Languages
+```bash
+curl -X GET "$API_URL/languages/popular"
+```
+
+### Get African Languages
+```bash
+curl -X GET "$API_URL/languages/african"
+```
+
+### Get Languages by Region
+```bash
+# European languages
+curl -X GET "$API_URL/languages/region/Europe"
+
+# Asian languages
+curl -X GET "$API_URL/languages/region/Asia"
+
+# African languages
+curl -X GET "$API_URL/languages/region/Africa"
+```
+
+### Search Languages
+```bash
+# Search for Swahili
+curl -X GET "$API_URL/languages/search?q=Swahili"
+
+# Search for Chinese
+curl -X GET "$API_URL/languages/search?q=Chinese"
+
+# Search by language code
+curl -X GET "$API_URL/languages/search?q=eng"
+```
+
+### Get Language Statistics
+```bash
+curl -X GET "$API_URL/languages/stats"
+```
+
+### Get Specific Language Information
+```bash
+# Swahili
+curl -X GET "$API_URL/languages/swh_Latn"
+
+# English
+curl -X GET "$API_URL/languages/eng_Latn"
+
+# Chinese (Simplified)
+curl -X GET "$API_URL/languages/cmn_Hans"
+```
+
+## 📚 Documentation Endpoints
+
+### Swagger UI (Open in browser)
+```bash
+open "$API_URL/"
+# or
+curl -X GET "$API_URL/"
+```
+
+### ReDoc Documentation (Open in browser)
+```bash
+open "$API_URL/redoc"
+# or
+curl -X GET "$API_URL/redoc"
+```
+
+### OpenAPI JSON Schema
+```bash
+curl -X GET "$API_URL/openapi.json"
+```
+
+## 🧪 Test Scenarios
+
+### Complete Translation Workflow
+```bash
+# 1. Check API health
+echo "1. Health Check:"
+curl -s "$API_URL/status" | jq '.status'
+
+# 2. Get popular languages
+echo "2. Popular Languages:"
+curl -s "$API_URL/languages/popular" | jq '.total_count'
+
+# 3. Validate language code
+echo "3. Validate Swahili:"
+curl -s "$API_URL/languages/swh_Latn" | jq '.name'
+
+# 4. Perform translation
+echo "4. Translation:"
+curl -s -X POST "$API_URL/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Habari ya asubuhi", "target_language": "eng_Latn"}' \
+  | jq '.translated_text'
+```
+
+### Error Testing
+```bash
+# Test invalid language code
+curl -X GET "$API_URL/languages/invalid_code"
+
+# Test empty translation text
+curl -X POST "$API_URL/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "", "target_language": "eng_Latn"}'
+
+# Test invalid search query
+curl -X GET "$API_URL/languages/search?q=x"
+```
+
+## 🔧 Advanced Usage
+
+### Pretty Print JSON Response
+```bash
+curl -s "$API_URL/languages/popular" | jq '.'
+```
+
+### Save Response to File
+```bash
+curl -s "$API_URL/languages" > all_languages.json
+```
+
+### Check Response Headers
+```bash
+curl -I "$API_URL/health"
+```
+
+### Measure Response Time
+```bash
+curl -w "@curl-format.txt" -s -o /dev/null "$API_URL/translate" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hello", "target_language": "swh_Latn"}'
+```
+
+### Multiple Translations (Batch Testing)
+```bash
+# Test multiple translations
+for text in "Hello" "Good morning" "Thank you" "Goodbye"; do
+  echo "Translating: $text"
+  curl -s -X POST "$API_URL/translate" \
+    -H "Content-Type: application/json" \
+    -d "{\"text\": \"$text\", \"target_language\": \"swh_Latn\"}" \
+    | jq -r '.translated_text'
+  echo "---"
+done
+```
+
+## 📊 Performance Testing
+
+### Simple Load Test
+```bash
+# Run 10 concurrent requests
+for i in {1..10}; do
+  curl -s -X POST "$API_URL/translate" \
+    -H "Content-Type: application/json" \
+    -d '{"text": "Hello world", "target_language": "swh_Latn"}' &
+done
+wait
+```
+
+### Rate Limit Testing
+```bash
+# Test rate limiting (should hit 60 req/min limit)
+for i in {1..65}; do
+  echo "Request $i:"
+  curl -s -X POST "$API_URL/translate" \
+    -H "Content-Type: application/json" \
+    -d '{"text": "Test", "target_language": "swh_Latn"}' \
+    | jq -r '.translated_text // .detail'
+  sleep 0.5
+done
+```
+
+## 💡 Tips
+
+### Create curl-format.txt for timing
+```bash
+cat > curl-format.txt << 'EOF'
+     time_namelookup:  %{time_namelookup}\n
+        time_connect:  %{time_connect}\n
+     time_appconnect:  %{time_appconnect}\n
+    time_pretransfer:  %{time_pretransfer}\n
+       time_redirect:  %{time_redirect}\n
+  time_starttransfer:  %{time_starttransfer}\n
+                     ----------\n
+          time_total:  %{time_total}\n
+EOF
+```
+
+### Set API URL as environment variable
+```bash
+export API_URL="https://sematech-sema-api.hf.space"
+# Now you can use $API_URL in all commands
+```

docs/CURL-Test.md

@@ -0,0 +1,39 @@
+# Sema Translation API - Curl Commands
+
+```bash
+# ✅ Basic Health Check
+curl https://sematech-sema-api.hf.space/health
+```
+
+```bash
+# ✅ Simple Translation
+curl -X POST "https://sematech-sema-api.hf.space/translate" \
+     -H "Content-Type: application/json" \
+     -d '{"text": "Habari ya asubuhi", "target_language": "eng_Latn"}'
+```
+
+```bash
+# ✅ Get All Supported Languages
+curl https://sematech-sema-api.hf.space/languages
+```
+
+```bash
+# ✅ Search for a Specific Language (e.g., Swahili)
+curl "https://sematech-sema-api.hf.space/languages/search?q=Swahili"
+```
+
+```bash
+# ✅ Basic Translation with Auto-Detection (relative path)
+curl -X POST "/translate" \
+     -H "Content-Type: application/json" \
+     -d '{"text": "Habari ya asubuhi", "target_language": "eng_Latn"}'
+```
+
+```bash
+# ✅ Translation with Specified Source Language
+curl -X POST "/translate" \
+     -H "Content-Type: application/json" \
+     -d '{"text": "Hello world", "source_language": "eng_Latn", "target_language": "swh_Latn"}'
+```
+
+---

tests/simple_test.py

@@ -0,0 +1,124 @@
+"""
+Simple API test script using requests
+"""
+
+import requests
+import json
+
+# API base URL - change this to test different environments
+API_URL = "https://sematech-sema-api.hf.space"
+# API_URL = "http://localhost:8000"  # For local testing
+
+def test_health():
+    """Test basic health check"""
+    print("🏥 Testing health check...")
+
+    response = requests.get(f"{API_URL}/status")
+    print(f"Status: {response.status_code}")
+
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ API is healthy")
+        print(f"Version: {data['version']}")
+        print(f"Models loaded: {data['models_loaded']}")
+    else:
+        print(f"❌ Health check failed")
+
+    print("-" * 50)
+
+def test_translation():
+    """Test basic translation"""
+    print("🌍 Testing translation...")
+
+    # Test data
+    data = {
+        "text": "Habari ya asubuhi",
+        "target_language": "eng_Latn"
+    }
+
+    response = requests.post(
+        f"{API_URL}/translate",
+        headers={"Content-Type": "application/json"},
+        json=data
+    )
+
+    print(f"Status: {response.status_code}")
+
+    if response.status_code == 200:
+        result = response.json()
+        print(f"✅ Translation successful")
+        print(f"Original: {data['text']}")
+        print(f"Translation: {result['translated_text']}")
+        print(f"Source language: {result['source_language']}")
+        print(f"Inference time: {result['inference_time']:.3f}s")
+    else:
+        print(f"❌ Translation failed")
+        print(f"Status code: {response.status_code}")
+        try:
+            error_data = response.json()
+            print(f"Error details: {error_data}")
+        except:
+            print(f"Error text: {response.text}")
+
+    print("-" * 50)
+
+def test_languages():
+    """Test language endpoints"""
+    print("🗣️ Testing language endpoints...")
+
+    # Test all languages
+    response = requests.get(f"{API_URL}/languages")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ Found {data['total_count']} supported languages")
+    else:
+        print(f"❌ Failed to get languages")
+
+    # Test popular languages
+    response = requests.get(f"{API_URL}/languages/popular")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ Found {data['total_count']} popular languages")
+    else:
+        print(f"❌ Failed to get popular languages")
+
+    # Test specific language
+    response = requests.get(f"{API_URL}/languages/swh_Latn")
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ Swahili info: {data['name']} ({data['native_name']})")
+    else:
+        print(f"❌ Failed to get Swahili info")
+
+    print("-" * 50)
+
+def test_search():
+    """Test language search"""
+    print("🔍 Testing language search...")
+
+    response = requests.get(f"{API_URL}/languages/search?q=Swahili")
+
+    if response.status_code == 200:
+        data = response.json()
+        print(f"✅ Search found {data['total_count']} results")
+        for code, info in data['languages'].items():
+            print(f"  {code}: {info['name']} ({info['native_name']})")
+    else:
+        print(f"❌ Search failed")
+
+    print("-" * 50)
+
+def run_all_tests():
+    """Run all tests"""
+    print(f"🧪 Testing API at: {API_URL}")
+    print("=" * 50)
+
+    test_health()
+    test_translation()
+    test_languages()
+    test_search()
+
+    print("🎉 All tests completed!")
+
+if __name__ == "__main__":
+    run_all_tests()