docs/API_REFERENCE.md

📡 API Reference & Schema Specification

Base URL

• Local: http://localhost:7860
• Hugging Face Space: https://ansh123456789-ragingoa.hf.space

---

🚀 Endpoints

1. POST /query

Execute end-to-end Voice RAG query. Supports multipart audio file upload or JSON/form text bypass.

Request Form / JSON Parameters:

• file (optional, UploadFile): Audio file (.wav, .mp3, .ogg, .webm, .m4a).
• text (optional, string): Text query string for fast-path processing.
• language_hint (optional, string): ISO language code (e.g. en, hi, ta, mr) or auto.
• cross_lingual (optional, boolean, default: false): Enable cross-lingual retrieval across all indexed languages.
• bypass_cache (optional, boolean, default: false): Force cold retrieval by skipping semantic cache.

Sample Request (curl):

curl -X POST http://localhost:7860/query \
  -H "Content-Type: application/json" \
  -d '{"text": "What is the capital of France?", "language_hint": "en"}'

Sample Response (JSON):

{
  "query": "What is the capital of France?",
  "transcript": "What is the capital of France?",
  "language_detected": "en",
  "answer": "Paris is the capital and most populous city of France.",
  "answer_source": "extractive",
  "retrieved_chunks": [
    {
      "chunk_id": "en_passage_4821",
      "text": "Paris is the capital and most populous city of France...",
      "source_lang": "en",
      "chunk_strategy": "passage_native",
      "dense_score": 0.8841,
      "bm25_score": 12.45,
      "final_score": 0.8912,
      "contributing_strategies": ["passage_native", "sentence_window"],
      "metadata": {}
    }
  ],
  "guardrail_flags": {
    "unsafe_detected": false,
    "unsafe_reason": null,
    "intent_detected": false,
    "intent_type": null,
    "intent_reason": null,
    "off_topic_detected": false,
    "off_topic_distance": 0.1245,
    "off_topic_reason": null,
    "safety_model_failed": false,
    "model_failed": false,
    "grounding_passed": true,
    "grounding_score": 0.9421,
    "grounding_reason": "Grounded with high lexical and semantic overlap.",
    "decline_reason_code": null
  },
  "stage_timings": [
    {"stage": "stt_transcription", "ms": 0.0, "success": true, "fallback_used": false, "details": "Text bypass"},
    {"stage": "language_routing", "ms": 0.12, "success": true, "fallback_used": false, "details": "Routed to 'en'"},
    {"stage": "pre_retrieval_safety_guardrail", "ms": 0.84, "success": true, "fallback_used": false, "details": "Passed regex and prompt-guard"},
    {"stage": "query_intent_guardrail", "ms": 0.21, "success": true, "fallback_used": false, "details": "Factual intent"},
    {"stage": "query_embedding", "ms": 6.18, "success": true, "fallback_used": false, "details": "ONNX INT8 E5"},
    {"stage": "pre_retrieval_topic_guardrail", "ms": 0.41, "success": true, "fallback_used": false, "details": "On-topic (dist: 0.1245)"},
    {"stage": "vector_retrieval_and_merge", "ms": 0.89, "success": true, "fallback_used": false, "details": "FAISS HNSW + RRF"},
    {"stage": "generation", "ms": 8.42, "success": true, "fallback_used": false, "details": "TextRank + SVD Energy Synthesis"},
    {"stage": "post_generation_grounding_guardrail", "ms": 0.31, "success": true, "fallback_used": false, "details": "Grounded"}
  ],
  "retrieval_ms": 7.89,
  "total_ms": 17.38
}

---

2. POST /tts

Synthesize spoken audio from text using Sarvam AI Bulbul TTS.

Request Body (JSON):

{
  "text": "नमस्ते, मैं आपकी सहायता कैसे कर सकता हूँ?",
  "target_language": "hi",
  "speaker": "anushka",
  "pace": 1.0
}

Response (JSON):

{
  "audio_base64": "<base64_encoded_wav_audio>",
  "format": "audio/wav",
  "sarvam": true,
  "language": "hi-IN",
  "speaker": "anushka"
}

---

3. GET /health

System health check reporting loaded indexes, centroids, active languages, and guardrail statuses.

Response (JSON):

{
  "status": "healthy",
  "configured_languages": ["en", "hi", "ta", "mr"],
  "embedding_model": "intfloat/multilingual-e5-small",
  "indexes_loaded": {
    "passage_native": 148545,
    "semantic_longdoc": 309
  },
  "centroids_available": ["en", "hi", "mr", "global"],
  "allow_network_calls": false,
  "sarvam_stt_configured": true,
  "sarvam_tts_configured": true,
  "semantic_answer_cache_configured": true,
  "request_timeout_seconds": 15.0,
  "query_intent_filter_enabled": true
}

---

4. GET /languages

Returns metadata, scripts, and MS MARCO source mappings for active languages.