"""Orquestra a transcrição: validação → idempotência → job em memória → fila → motor STT. Modelo híbrido (ver README, "Transcrição"): o POST espera o job até `stt_sync_wait_s`; se terminar, responde `ready`, senão `pending` + `jobRef`, consultado em `GET /v1/transcribe/jobs/{jobRef}`. Privacidade: o áudio só vive em memória até o job rodar; o texto só vive em memória até o job expirar (`stt_job_ttl_s`). No disco fica apenas (keyId, idempotencyKey) → hash. Nada de texto em log. Isolamento por chave de serviço: o job pertence ao `keyId` que o criou. Consultar o `jobRef` com outra chave dá o mesmo 410 `job_not_found` de um job inexistente (não revela que ele existe), e o mesmo áudio enviado por duas chaves vira dois jobs. """ from __future__ import annotations import asyncio import hashlib import json import logging import secrets import time from dataclasses import dataclass, field from .config import Settings from .errors import ( AudioTooLarge, AudioTooLong, IdempotencyConflict, InvalidRequest, JobNotFound, LanguageNotSupported, QueueFull, ServiceError, SynthesisTimeout, TranscriptionFailed, TranscriptionTimeout, ) from .store import Store from .stt import DETAILS, WHISPER_LANGUAGES, SttEngine, Transcript from .work_queue import WorkQueue log = logging.getLogger("cenaforge_voice") STT_SCHEMA = 2 # suba quando mudar o pipeline (muda a chave de conteúdo) # Folga sobre o teto de duração: o backend mede em ms e o container OGG arredonda. DURATION_TOLERANCE_S = 0.5 MIN_RETRY_AFTER_MS = 500 MAX_RETRY_AFTER_MS = 10_000 @dataclass class TranscriptionJob: ref: str key_id: str content_key: str audio_s: float detail: str = "text" created_at: float = field(default_factory=time.monotonic) finished_at: float | None = None result: Transcript | None = None error: ServiceError | None = None task: asyncio.Task | None = None @property def done(self) -> bool: return self.finished_at is not None def content_key_for(audio: bytes, language: str, engine_name: str, detail: str = "text") -> str: payload = { "schema": STT_SCHEMA, "engine": engine_name, "language": language, "detail": detail, "audio": hashlib.sha256(audio).hexdigest(), } return hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest() class TranscriptionService: def __init__(self, settings: Settings, engine: SttEngine, store: Store, queue: WorkQueue): self.settings = settings self.engine = engine self.store = store self.queue = queue self._by_content: dict[tuple[str, str], TranscriptionJob] = {} # (keyId, chave de conteúdo) self._by_ref: dict[str, TranscriptionJob] = {} # Segundos de relógio por segundo de áudio, medido (média móvel). Só estima o retryAfterMs. self._wall_per_audio_s = 0.5 def validate(self, size: int, duration_ms: int, language: str, detail: str = "text") -> str: whisper_language = WHISPER_LANGUAGES.get(language) if whisper_language is None: raise LanguageNotSupported() if detail not in DETAILS: raise InvalidRequest(f"X-Detail precisa ser um de {', '.join(DETAILS)}.") if size > self.settings.stt_max_bytes: raise AudioTooLarge() if duration_ms > self.settings.stt_max_audio_s * 1000: raise AudioTooLong() return whisper_language async def submit( self, audio: bytes, duration_ms: int, language: str, idempotency_key: str, key_id: str, detail: str = "text" ) -> tuple[TranscriptionJob, bool]: """Cria (ou reaproveita) o job. Devolve (job, é_replay).""" whisper_language = self.validate(len(audio), duration_ms, language, detail) key = content_key_for(audio, whisper_language, self.engine.name, detail) is_new, bound = self.store.bind_transcription(key_id, idempotency_key, key) if bound != key: raise IdempotencyConflict("Esta idempotencyKey já foi usada com outro áudio.") self._purge() job = self._by_content.get((key_id, key)) if job is not None and job.error is None: return job, not is_new # em andamento ou pronto: mesmo resultado if job is not None: # falhou antes: o retry com a mesma chave tenta de novo self._forget(job) if self.queue.is_full(key_id): raise QueueFull() job = TranscriptionJob( ref=secrets.token_urlsafe(18), key_id=key_id, content_key=key, audio_s=duration_ms / 1000, detail=detail ) self._by_content[(key_id, key)] = job self._by_ref[job.ref] = job job.task = asyncio.create_task(self._run(job, audio, whisper_language, detail)) return job, not is_new async def wait(self, job: TranscriptionJob, timeout_s: float) -> None: if job.task is not None and not job.done and timeout_s > 0: await asyncio.wait({job.task}, timeout=timeout_s) def get(self, ref: str, key_id: str) -> TranscriptionJob: self._purge() job = self._by_ref.get(ref) # Job de outra chave responde igual a job inexistente: nem 403, nem pista de que existe. if job is None or job.key_id != key_id: raise JobNotFound() return job def retry_after_ms(self, job: TranscriptionJob) -> int: elapsed = time.monotonic() - job.created_at remaining = job.audio_s * self._wall_per_audio_s - elapsed return int(min(MAX_RETRY_AFTER_MS, max(MIN_RETRY_AFTER_MS, remaining * 1000))) async def _run(self, job: TranscriptionJob, audio: bytes, language: str, detail: str) -> None: started = time.perf_counter() try: job.result = await self.queue.run(lambda: self._work(audio, language, detail), owner=job.key_id) except SynthesisTimeout: job.error = TranscriptionTimeout() except ServiceError as exc: job.error = exc except Exception as exc: # noqa: BLE001 - qualquer falha do motor vira erro estável # Mensagem da biblioteca (DLL, memória da GPU), nunca o texto transcrito. log.error("transcribe job=%s erro=%s: %s", job.ref, type(exc).__name__, str(exc)[:200]) job.error = TranscriptionFailed() finally: job.finished_at = time.monotonic() wall = time.perf_counter() - started if job.result is not None: if job.audio_s > 0: self._wall_per_audio_s = 0.7 * self._wall_per_audio_s + 0.3 * (wall / job.audio_s) # Só métricas: nunca o texto. log.info( "transcribe job=%s audio_ms=%d wall_ms=%d cpu_ms=%d cpu_per_audio_s=%.3f segments=%d no_speech=%.2f", job.ref, int(job.audio_s * 1000), int(wall * 1000), int(job.result.cpu_s * 1000), job.result.cpu_s / job.audio_s if job.audio_s else 0.0, job.result.segment_count, job.result.no_speech_prob, ) else: log.info("transcribe job=%s falhou code=%s wall_ms=%d", job.ref, job.error.code, int(wall * 1000)) def _work(self, audio: bytes, language: str, detail: str) -> Transcript: # A duração declarada pelo cliente é conferida contra a real: o teto vale para o que foi # decodificado, e a decodificação para ao passar dele. samples = self.engine.decode(audio, self.settings.stt_max_audio_s + DURATION_TOLERANCE_S) return self.engine.transcribe(samples, language, detail) def _forget(self, job: TranscriptionJob) -> None: self._by_content.pop((job.key_id, job.content_key), None) self._by_ref.pop(job.ref, None) def _purge(self) -> None: now = time.monotonic() for job in [j for j in self._by_ref.values() if j.done and now - j.finished_at > self.settings.stt_job_ttl_s]: self._forget(job)