QVAC-18735 feat[api]: add POST /v1/audio/translations to qvac serve OpenAI adapter

[lauripiisang]

🎯 What problem does this PR solve?

• qvac serve openai had no OpenAI-compatible translations endpoint, so consumers that hit POST /v1/audio/translations (Whisper translate-to-English task) had to fall back to a separate transcribe + text-translate pipeline.
• serve.models had no way to declare a Whisper alias whose endpoint category was audio-translation, since the only Whisper type was whispercpp-transcription.

📝 How does it solve it?

• Adds POST /v1/audio/translations to the OpenAI HTTP adapter. Route gates on endpointCategory === 'audio-translation', rejects language (OpenAI translations are English-only), and supports json (default) / text response formats.
• Introduces virtual serve.models type whispercpp-audio-translation. The CLI resolves it to the real engine whispercpp-transcription and forces translate: true at parse time (warns if the operator set translate: false). Nested whisperConfig: { ... } is flattened into the top-level modelConfig so it matches what @qvac/sdk loadModel expects.
• Extends the constant-shorthand serve.models entry with an optional type override, so the recommended config keeps using the same "model": "<SDK_CONSTANT>" shape as every other entry:

"whisper-translate": {
  "model": "WHISPER_EN_TINY_Q8_0",
  "type": "whispercpp-audio-translation",
  "preload": true
}

• Docs: new packages/cli/docs/serve-openai.md, README pointer, and package.json files now includes docs/**/*.md so the doc ships with the published package.

🧪 How was it tested?

• Unit: npm test — adds config.test.ts (constant + type override path, virtual-type flattening, translate-true enforcement) and translations.test.ts (validation branches: missing fields, language rejection, non-translation alias gate, unsupported formats, json/text responses).
• BATS smoke: npm run test:bats — cli.bats smoke cases mirroring the transcriptions set.
• BATS e2e: npm run test:e2e — e2e.bats registers test-whisper-translate via model + type override, hits /v1/audio/translations for both json and text, asserts rejection of a transcription-only alias and of a chat alias, and verifies DELETE unloads both whisper aliases.
• Verified locally end-to-end against WHISPER_EN_TINY_Q8_0.

🔌 API Changes

New endpoint — POST /v1/audio/translations:

curl -s http://127.0.0.1:11434/v1/audio/translations \
  -F model=whisper-translate \
  -F file=@./sample.wav \
  -F response_format=json
# => { "text": "..." }   (always English)

New serve.models shape — Whisper translation alias via constant + type override:

{
  "serve": {
    "models": {
      "whisper-transcribe": { "model": "WHISPER_EN_TINY_Q8_0", "preload": true },
      "whisper-translate": {
        "model": "WHISPER_EN_TINY_Q8_0",
        "type": "whispercpp-audio-translation",
        "preload": true
      }
    }
  }
}

The explicit { "type": "whispercpp-audio-translation", "src": "<weights>" } form is still accepted for non-registry weights (literal URL / path / registry://…); src is passed to the SDK verbatim and is not resolved against SDK model constants.

Ticket

QVAC-18735

[opaninakuffo]

Adds /v1/audio/translations, the whispercpp-audio-translation virtual type (flatten + forced translate), startup/docs/package files, and solid unit + BATS coverage. Mirrors the transcriptions handler cleanly and gates on audio-translation nicely.

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ✅ APPROVED

**Requirements:**
- 1 Team Member approval ✅ (2/1)
- 1 Team Lead OR Management approval ✅ (1/1)



---
*This comment is automatically updated when reviews change.*

[simon-iribarren]

Approve. Verified locally: build ✓, typecheck ✓, 243/243 tests pass. CI green on all technical gates.

Three things worth surfacing:

1. routes/translations.ts is a ~95% duplicate of routes/transcriptions.ts. Only ~12 effective lines differ (endpoint category, language policy, log labels, error code), and validation order is already drifting between the two siblings. Worth factoring a shared handleWhisperAudio(req, res, ctx, { requiredCategory, opLabel, errorCode, languagePolicy }) helper before the third Whisper variant lands.
2. transcribeOverride was added to the public RouteContext interface but only translations.ts consumes it. transcriptions.ts still calls sdkTranscribe directly. Wrong test seam — either flip both routes to read from ctx, or pass sdkTranscribe into a handler factory and drop the RouteContext field.
3. whisperConfig nested→flat flattening is asymmetric. config.ts::resolveExplicitServeModel flattens only for the virtual whispercpp-audio-translation type. Plain whispercpp-transcription entries with nested whisperConfig pass through unchanged, even though the new serve-openai.md tells transcription users to use flat keys. Silent footgun — either flatten symmetrically or document the asymmetry.

Smaller nits:

• response_format allowlist is case-sensitive; OpenAI clients send lowercase, but the divergence will catch someone.
• console.warn in the config parser — prefer the structured logger.
• No client-disconnect propagation (same wart as transcriptions).
• No changelog/0.3.0/api.md update in this PR — easy to add.

[lauripiisang]

/review

[lauripiisang]

/review