first

2026-07-10 09:46:49 +02:00
parent 429cb84461
commit 7a3f61c125
16 changed files with 762 additions and 16 deletions
@@ -0,0 +1,66 @@
+# audio-transcription — přehled
+
+Stateless FastAPI služba v AppFactory. Přijme audio + parametry v POST a vrátí JSON
+s přepisy. Přepis běží dvěma engine paralelně (Deepgram + OpenAI Whisper) a volitelně
+se oba texty sloučí přes OpenAI Chat do jednoho co nejpřesnějšího přepisu.
+
+Vychází z původní .NET implementace `CallCenterController` (dual/combined přepis).
+Napojení na Twilio bylo vynecháno — audio se posílá přímo jako proměnná (upload).
+
+## Architektura
+
+```
+app/
+  main.py              # FastAPI app, root_path, Swagger, exception handlers
+  config.py            # env konfigurace + defaulty (žádné secrets)
+  logging_config.py    # logging (bez secrets)
+  errors.py            # typované výjimky + handlery (žádná tichá selhání)
+  credentials.py       # X- hlavičky → přihlašovací údaje (stateless)
+  prompts.py           # výchozí slučovací prompt (Czech Transcript Merger)
+  clients/
+    deepgram_client.py # Deepgram pre-recorded REST (httpx)
+    openai_client.py   # OpenAI Whisper + Chat Completions (httpx)
+  routers/
+    meta.py            # /health, /version
+    transcribe.py      # /transcribe/dual, /transcribe/combined
+```
+
+Žádné SDK — upstream API se volají přímo přes `httpx`, aby služba nebyla závislá na
+verzích knihoven. Nic se neukládá; služba je multi-tenant a stateless.
+
+## Reverse proxy
+
+Běží za `/apps/audio-transcription`. `root_path` se čte z env `ROOT_PATH`, takže
+OpenAPI `servers` i Swagger „Try it out“ míří na správný prefix.
+
+## Endpointy
+
+| Metoda | Cesta | Popis |
+|--------|-------|-------|
+| GET | `/health` | Health check (200) |
+| GET | `/version` | Verze + root_path |
+| POST | `/transcribe/dual` | Deepgram + Whisper (dva texty) |
+| POST | `/transcribe/combined` | dual + sloučený `merged` |
+
+Detaily viz [transcribe.md](transcribe.md).
+
+## Přihlašovací údaje
+
+Secrets se předávají v hlavičkách u každého requestu (nikdy v těle/URL, nikdy se
+nelogují ani neukládají):
+
+- `X-Deepgram-Api-Key`
+- `X-OpenAI-Api-Key`
+
+## Konfigurace (env)
+
+| Proměnná | Default | Popis |
+|----------|---------|-------|
+| `ROOT_PATH` | `""` | Prefix reverse proxy (`/apps/audio-transcription`) |
+| `DEFAULT_DEEPGRAM_MODEL` | `nova-2` | Výchozí Deepgram model |
+| `DEFAULT_WHISPER_MODEL` | `whisper-1` | Výchozí OpenAI přepisový model |
+| `DEFAULT_CHAT_MODEL` | `gpt-4o` | Výchozí chat model pro sloučení |
+| `DEFAULT_LANGUAGE` | `cs` | Výchozí jazyk |
+| `UPSTREAM_TIMEOUT_SECONDS` | `300` | Timeout upstream volání |
+| `DEEPGRAM_BASE_URL` | `https://api.deepgram.com/v1` | Base URL Deepgram |
+| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Base URL OpenAI |