""" Voice API endpoints for Phase 2 of ScamShield AI. Provides voice-based scam interaction endpoints that wrap the existing Phase 1 text pipeline with ASR (speech-to-text) on input and TTS (text-to-speech) on output. Phase 1 code is imported and reused without modification. Endpoints: POST /api/v1/voice/engage - Voice-based honeypot engagement GET /api/v1/voice/audio/{filename} - Serve generated audio files GET /api/v1/voice/health - Voice subsystem health check """ import os import tempfile import time import uuid from pathlib import Path from typing import Optional from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile from fastapi.responses import FileResponse from app.api.auth import verify_api_key from app.api.schemas import ExtractedIntelligence from app.api.voice_schemas import ( TranscriptionMetadata, VoiceEngageResponse, VoiceHealthResponse, ) from app.config import settings from app.utils.logger import get_logger logger = get_logger(__name__) # --------------------------------------------------------------------------- # Constants # --------------------------------------------------------------------------- AUDIO_OUTPUT_DIR: Path = Path(tempfile.gettempdir()) / "scamshield_audio" AUDIO_OUTPUT_DIR.mkdir(parents=True, exist_ok=True) ALLOWED_AUDIO_CONTENT_TYPES = frozenset({ "audio/mpeg", "audio/mp3", "audio/wav", "audio/x-wav", "audio/wave", "audio/ogg", "audio/flac", "audio/webm", "audio/mp4", "audio/x-m4a", }) # TTS-supported language codes (subset of ISO 639-1 supported by gTTS) _TTS_SUPPORTED_CODES = frozenset({"en", "hi", "gu", "ta", "te", "bn", "mr"}) # --------------------------------------------------------------------------- # Router # --------------------------------------------------------------------------- voice_router = APIRouter(prefix="/api/v1/voice", tags=["voice"]) # --------------------------------------------------------------------------- # POST /engage # --------------------------------------------------------------------------- @voice_router.post( "/engage", response_model=VoiceEngageResponse, dependencies=[Depends(verify_api_key)], summary="Voice-based honeypot engagement", ) async def voice_engage( audio_file: UploadFile = File( ..., description="Audio file (mp3, wav, ogg, flac, webm)" ), session_id: Optional[str] = Form( None, description="Session ID for multi-turn conversations" ), language: Optional[str] = Form( None, description="Language hint (ISO 639-1 code, e.g. 'en', 'hi')", ), ) -> VoiceEngageResponse: """Process voice input through the scam detection and honeypot pipeline. Complete flow: 1. Save uploaded audio to a temporary file. 2. Transcribe audio to text via ASR (Whisper). 3. Run Phase 1 scam detection on the transcribed text. 4. If scam detected (or ongoing session), engage honeypot agent. 5. Extract financial intelligence from the conversation. 6. Convert the agent's text reply to speech via TTS (gTTS). 7. Return structured response with transcription, detection results, agent reply text, audio URL, and intelligence. Args: audio_file: Uploaded audio in a supported format. session_id: Optional session identifier for continuing a multi-turn conversation. language: Optional ISO 639-1 language hint for ASR and TTS. Returns: VoiceEngageResponse containing the full processing result. Raises: HTTPException: 400 for invalid input, 500 for internal errors. """ start_time: float = time.time() temp_audio_path: Optional[str] = None try: # Lazy imports -- avoids loading heavy models at module import time # and mirrors the Phase 1 import pattern inside endpoint handlers. from app.models.detector import get_detector from app.models.extractor import extract_intelligence from app.agent.honeypot import HoneypotAgent from app.database.redis_client import ( get_session_state_with_fallback, save_session_state_with_fallback, ) from app.voice.asr import get_asr_engine from app.voice.tts import get_tts_engine # ---- 1. Validate and persist upload -------------------------------- _validate_audio_upload(audio_file) temp_audio_path = await _save_upload_to_temp(audio_file) # ---- 2. ASR: speech-to-text ---------------------------------------- asr_engine = get_asr_engine() transcription = asr_engine.transcribe( temp_audio_path, language=language if language and language != "auto" else None, ) transcribed_text: str = transcription.get("text", "") asr_language: str = transcription.get("language", "unknown") asr_confidence: float = transcription.get("confidence", 0.0) if not transcribed_text.strip(): raise HTTPException( status_code=400, detail={ "code": "EMPTY_TRANSCRIPTION", "message": ( "No speech detected in the uploaded audio file." ), }, ) logger.info( "ASR complete: language=%s, confidence=%.3f, text_length=%d", asr_language, asr_confidence, len(transcribed_text), ) # ---- 3. Determine processing language ------------------------------ process_language: str = ( language if language and language != "auto" else asr_language ) # ---- 4. Session management ----------------------------------------- if not session_id: session_id = str(uuid.uuid4()) session_state = None is_ongoing_session: bool = False existing_state = get_session_state_with_fallback(session_id) if existing_state and existing_state.get("turn_count", 0) > 0: session_state = existing_state is_ongoing_session = True logger.info( "Continuing voice session %s, turn=%d", session_id, session_state.get("turn_count", 0), ) # ---- 5. Scam detection (Phase 1 detector) -------------------------- detector = get_detector() detection = detector.detect(transcribed_text, process_language) scam_detected: bool = detection.get("scam_detected", False) confidence: float = detection.get("confidence", 0.0) indicators: list = detection.get("indicators", []) scam_type: Optional[str] = indicators[0] if indicators else None # ---- 6. Non-scam, non-ongoing -> early return ---------------------- if not scam_detected and not is_ongoing_session: processing_time_ms = int((time.time() - start_time) * 1000) logger.info( "No scam detected in voice session %s (confidence=%.2f)", session_id, confidence, ) return VoiceEngageResponse( session_id=session_id, scam_detected=False, scam_confidence=confidence, scam_type=None, turn_count=0, ai_reply_text="No scam detected. Message appears legitimate.", ai_reply_audio_url=None, transcription=TranscriptionMetadata( text=transcribed_text, language=asr_language, confidence=asr_confidence, ), voice_fraud=None, extracted_intelligence=None, processing_time_ms=processing_time_ms, ) # ---- 7. Scam or ongoing -> honeypot engagement --------------------- if is_ongoing_session: existing_confidence = session_state.get("scam_confidence", 0.0) confidence = max(confidence, existing_confidence) scam_detected = True agent = HoneypotAgent() result = agent.engage(transcribed_text, session_state) # ---- 8. Intelligence extraction (Phase 1 extractor) ---------------- full_text: str = " ".join( msg.get("message", "") for msg in result.get("messages", []) ) intel, extraction_confidence = extract_intelligence(full_text) result["extracted_intel"] = intel result["extraction_confidence"] = extraction_confidence result["scam_confidence"] = confidence # ---- 9. Persist session to Redis ----------------------------------- save_session_state_with_fallback(session_id, result) # ---- 10. Extract agent reply text ---------------------------------- agent_messages = [ m for m in result.get("messages", []) if m.get("sender") == "agent" ] agent_reply: str = ( agent_messages[-1]["message"] if agent_messages else "Engaged with scammer." ) # ---- 11. TTS: text-to-speech --------------------------------------- tts_language: str = _resolve_tts_language(asr_language, language) audio_url: Optional[str] = None try: tts_engine = get_tts_engine() audio_filename: str = f"reply_{uuid.uuid4().hex}.mp3" audio_output_path: str = str(AUDIO_OUTPUT_DIR / audio_filename) tts_engine.synthesize( text=agent_reply, language=tts_language, output_path=audio_output_path, ) audio_url = f"/api/v1/voice/audio/{audio_filename}" logger.info("TTS complete: %s", audio_url) except Exception as tts_exc: # TTS is non-critical; the text reply is still usable. logger.warning( "TTS synthesis failed, returning text-only response: %s", tts_exc, ) # ---- 12. Build response -------------------------------------------- turn_count: int = result.get("turn_count", 1) processing_time_ms = int((time.time() - start_time) * 1000) extracted_intelligence = ExtractedIntelligence( upi_ids=intel.get("upi_ids", []), bank_accounts=intel.get("bank_accounts", []), ifsc_codes=intel.get("ifsc_codes", []), phone_numbers=intel.get("phone_numbers", []), phishing_links=intel.get("phishing_links", []), extraction_confidence=extraction_confidence, ) logger.info( "Voice engagement complete: session=%s, turn=%d, " "confidence=%.2f, processing_time=%dms", session_id, turn_count, confidence, processing_time_ms, ) return VoiceEngageResponse( session_id=session_id, scam_detected=True, scam_confidence=confidence, scam_type=scam_type, turn_count=turn_count, ai_reply_text=agent_reply, ai_reply_audio_url=audio_url, transcription=TranscriptionMetadata( text=transcribed_text, language=asr_language, confidence=asr_confidence, ), voice_fraud=None, extracted_intelligence=extracted_intelligence, processing_time_ms=processing_time_ms, ) except HTTPException: raise except ValueError as exc: logger.warning("Validation error in voice engage: %s", exc) raise HTTPException( status_code=400, detail={ "code": "INVALID_REQUEST", "message": str(exc), }, ) except Exception as exc: logger.error("Voice engage failed: %s", exc, exc_info=True) raise HTTPException( status_code=500, detail={ "code": "VOICE_PROCESSING_ERROR", "message": "An error occurred during voice processing.", "details": str(exc) if settings.DEBUG else None, }, ) finally: if temp_audio_path: _cleanup_file(temp_audio_path) # --------------------------------------------------------------------------- # GET /audio/{filename} # --------------------------------------------------------------------------- @voice_router.get( "/audio/{filename}", summary="Serve generated audio response", ) async def serve_audio(filename: str) -> FileResponse: """Serve a previously generated TTS audio file. Args: filename: Name of the audio file (e.g. ``reply_.mp3``). Returns: FileResponse streaming the MP3 audio content. Raises: HTTPException: 400 if the filename contains path-traversal characters, 404 if the file does not exist. """ if ".." in filename or "/" in filename or "\\" in filename: raise HTTPException( status_code=400, detail={ "code": "INVALID_FILENAME", "message": "Invalid audio filename.", }, ) file_path: Path = AUDIO_OUTPUT_DIR / filename if not file_path.exists() or not file_path.is_file(): raise HTTPException( status_code=404, detail={ "code": "AUDIO_NOT_FOUND", "message": f"Audio file '{filename}' not found.", }, ) return FileResponse( path=str(file_path), media_type="audio/mpeg", filename=filename, ) # --------------------------------------------------------------------------- # GET /health # --------------------------------------------------------------------------- @voice_router.get( "/health", response_model=VoiceHealthResponse, summary="Voice subsystem health check", ) async def voice_health() -> VoiceHealthResponse: """Check the operational status of ASR and TTS engines. Returns: VoiceHealthResponse reporting the status of each voice engine. """ asr_info = None tts_info = None overall_status = "healthy" # ASR health try: from app.voice.asr import get_asr_engine asr = get_asr_engine() asr_info = { "model": asr.model_size, "device": asr.device, "loaded": asr.model is not None, } except Exception as exc: logger.warning("ASR health check failed: %s", exc) asr_info = {"loaded": False, "error": str(exc)} overall_status = "degraded" # TTS health try: from app.voice.tts import get_tts_engine tts = get_tts_engine() tts_info = { "engine": tts.engine, "loaded": True, } except Exception as exc: logger.warning("TTS health check failed: %s", exc) tts_info = {"loaded": False, "error": str(exc)} overall_status = "degraded" # Both engines down => unhealthy if ( asr_info and not asr_info.get("loaded") and tts_info and not tts_info.get("loaded") ): overall_status = "unhealthy" return VoiceHealthResponse( status=overall_status, asr=asr_info, tts=tts_info, ) # --------------------------------------------------------------------------- # Helper functions # --------------------------------------------------------------------------- def _validate_audio_upload(audio_file: UploadFile) -> None: """Validate that the uploaded file is a usable audio file. Args: audio_file: FastAPI UploadFile instance. Raises: HTTPException: 400 if the file is missing or has an unsupported content type. """ if not audio_file or not audio_file.filename: raise HTTPException( status_code=400, detail={ "code": "MISSING_AUDIO_FILE", "message": "An audio file is required.", }, ) content_type: str = (audio_file.content_type or "").lower() # Only reject when the content type is explicitly non-audio. # Allow unknown/octet-stream through so that clients without proper # MIME detection still work. if ( content_type and content_type not in ALLOWED_AUDIO_CONTENT_TYPES and not content_type.startswith("audio/") and content_type != "application/octet-stream" ): raise HTTPException( status_code=400, detail={ "code": "INVALID_AUDIO_FORMAT", "message": ( f"Unsupported content type '{content_type}'. " f"Accepted: {', '.join(sorted(ALLOWED_AUDIO_CONTENT_TYPES))}" ), }, ) async def _save_upload_to_temp(audio_file: UploadFile) -> str: """Persist an uploaded audio file to a temporary path on disk. Args: audio_file: FastAPI UploadFile instance. Returns: Absolute path to the saved temporary file. Raises: HTTPException: 400 if the file body is empty, 500 if the file cannot be written. """ suffix: str = Path(audio_file.filename or "audio.wav").suffix or ".wav" try: fd, temp_path = tempfile.mkstemp(suffix=suffix, prefix="voice_in_") with os.fdopen(fd, "wb") as tmp: content: bytes = await audio_file.read() if not content: os.unlink(temp_path) raise HTTPException( status_code=400, detail={ "code": "EMPTY_AUDIO_FILE", "message": "The uploaded audio file is empty.", }, ) tmp.write(content) logger.debug( "Saved upload to temp file: %s (%d bytes)", temp_path, len(content), ) return temp_path except HTTPException: raise except Exception as exc: logger.error("Failed to save uploaded audio: %s", exc) raise HTTPException( status_code=500, detail={ "code": "FILE_SAVE_ERROR", "message": "Failed to process the uploaded audio file.", }, ) from exc def _resolve_tts_language( asr_language: str, language_hint: Optional[str], ) -> str: """Determine the best language code for TTS synthesis. Priority order: 1. Explicit client hint (if TTS-supported). 2. ASR-detected language (if TTS-supported). 3. English (``'en'``) as fallback. Args: asr_language: Language code detected by the ASR engine. language_hint: Optional language hint from the client form data. Returns: ISO 639-1 code supported by the TTS engine. """ if language_hint: normalized: str = language_hint.strip().lower() if normalized in _TTS_SUPPORTED_CODES: return normalized if asr_language: normalized = asr_language.strip().lower() if normalized in _TTS_SUPPORTED_CODES: return normalized return "en" def _cleanup_file(path: str) -> None: """Remove a temporary file, suppressing errors. Args: path: Absolute path to the file to remove. """ try: if os.path.exists(path): os.remove(path) except OSError as exc: logger.debug("Failed to clean up temp file %s: %s", path, exc)