Run Fireworks Whisper with Sapat in Daytona

authors/lucas_chinook.md

@@ -0,0 +1,5 @@
+Author: Lucas Chinook Title: AI Engineer Description: Lucas Chinook builds
+developer automation, AI-assisted coding workflows, and reproducible cloud
+development guides. Lucas focuses on practical systems that engineers can
+verify locally before they rely on them in production. Author GitHub:
+[GitHub](https://github.com/chinook1001)

definitions/20260530_definition_serverless_asr_endpoint.md

@@ -0,0 +1,31 @@
+---
+title: "Serverless ASR Endpoint"
+description: "A serverless ASR endpoint accepts prepared audio, runs speech recognition on provider-managed infrastructure, and returns transcript text without requiring users to operate model servers."
+date: 2026-05-30
+author: "Lucas Chinook"
+---
+
+# Serverless ASR Endpoint
+
+## Definition
+
+A serverless ASR endpoint is a managed automatic speech recognition interface
+that accepts an audio file or audio URL, runs the speech-to-text model on
+provider-managed infrastructure, and returns a transcript. Developers call the
+endpoint with an API key and a model name instead of provisioning GPU workers,
+model files, queue consumers, or custom transcription services.
+
+## Context and Usage
+
+Serverless ASR endpoints are useful when a team wants repeatable transcription
+without maintaining inference infrastructure. A workspace can prepare audio,
+load credentials from local environment variables, choose a provider model, and
+send the prepared file to the endpoint. The provider handles model hosting,
+scaling, and response formatting.
+
+This pattern works well inside Daytona because the workspace can make the input
+and validation steps reproducible. The API key stays in `.env`, the source media
+stays out of Git, and the transcript can be reviewed as a generated artifact.
+Fireworks AI's pre-recorded transcription API is one example of this pattern:
+Sapat prepares the audio locally, then sends it to the Fireworks audio
+transcription endpoint for Whisper-based recognition.

guides/20260530_run_fireworks_whisper_with_sapat_in_daytona.md

@@ -0,0 +1,343 @@
+---
+title: 'Run Fireworks Whisper With Sapat in Daytona'
+description:
+  'Create a reproducible Daytona workspace for transcribing media with Sapat
+  and Fireworks AI serverless Whisper endpoints.'
+date: 2026-05-30
+author: 'Lucas Chinook'
+tags: ['AI', 'transcription', 'python', 'daytona']
+---
+
+# Run Fireworks Whisper With Sapat in Daytona
+
+Fireworks AI hosts Whisper V3 speech recognition behind managed audio
+endpoints. That is useful when you want cloud-hosted ASR without operating a
+GPU server, but the developer workflow still needs discipline: credentials
+should stay private, media should stay out of Git, and transcript output should
+be reviewed before it feeds another AI system.
+
+This guide shows how to run Sapat with Fireworks AI inside a Daytona workspace.
+Sapat handles repeatable audio conversion and provider routing. Fireworks
+handles the serverless ASR request. Daytona gives the whole workflow a clean,
+reproducible workspace that another engineer can open without inheriting your
+local laptop state.
+
+The workflow uses the companion Sapat provider implementation in
+[nibzard/sapat#63](https://github.com/nibzard/sapat/pull/63). It calls the
+Fireworks audio transcription API directly, without a Fireworks SDK dependency,
+and keeps the API key in local environment variables.
+
+![Sapat Fireworks workflow](./assets/20260530_run_fireworks_whisper_with_sapat_in_daytona_workflow.svg)
+
+## What You Will Build
+
+You will create a Daytona transcription workspace that can:
+
+- Install Sapat from a branch that includes the `fireworks` provider.
+- Store `FIREWORKS_API_KEY` in `.env` without committing it.
+- Convert source media to a Fireworks-friendly audio file.
+- Run `whisper-v3` for accuracy or `whisper-v3-turbo` for lower latency.
+- Save generated transcripts as reviewable build artifacts.
+- Keep validation notes beside each transcription run.
+
+This is intentionally a developer workflow, not a black-box upload page. The
+goal is to make transcription repeatable enough that a teammate can inspect the
+command, model, input file, and review notes later.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- [Daytona](https://github.com/daytonaio/daytona) installed and authenticated.
+- Python 3.9 or newer available in the workspace.
+- `ffmpeg`, because Sapat converts input media before provider upload.
+- A Fireworks AI API key with access to audio transcription.
+- A Sapat branch or release that includes the `fireworks` provider.
+
+Fireworks documents pre-recorded transcription as a multipart audio request.
+The provider supports files such as MP3, FLAC, and WAV, with `whisper-v3` served
+from the production audio endpoint and `whisper-v3-turbo` served from the turbo
+audio endpoint. The Sapat provider uses those model names to choose the right
+endpoint automatically.
+
+## Step 1: Create the Project Folder
+
+Create a folder for the workflow:
+
+```bash
+mkdir sapat-fireworks-daytona
+cd sapat-fireworks-daytona
+```
+
+Add a small README so the workspace describes its purpose:
+
+```bash
+cat > README.md <<'EOF'
+# Sapat Fireworks Transcription
+
+This workspace transcribes private test media with Sapat and Fireworks AI.
+Secrets stay in .env. Media stays in input/. Reviewed transcripts live in
+transcripts/.
+EOF
+```
+
+Create folders for input files, transcripts, and review notes:
+
+```bash
+mkdir -p input transcripts notes
+cat > .gitignore <<'EOF'
+.env
+input/*
+transcripts/*
+*.wav
+*.mp3
+EOF
+```
+
+The `.gitignore` is part of the workflow, not just housekeeping. It prevents a
+quick test clip or generated transcript from becoming an accidental repository
+artifact.
+
+## Step 2: Open the Workspace in Daytona
+
+Initialize Git and create the Daytona workspace:
+
+```bash
+git init
+git add README.md .gitignore
+git commit -m "Initialize Fireworks transcription workspace"
+daytona create . --code
+```
+
+Inside the Daytona terminal, install system and Python dependencies:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y ffmpeg
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+```
+
+Install Sapat from the companion branch while the provider PR is under review:
+
+```bash
+python -m pip install \
+  "git+https://github.com/chinook1001/sapat.git@codex/fireworks-provider"
+```
+
+After the provider lands upstream, switch back to the main repository:
+
+```bash
+python -m pip install "git+https://github.com/nibzard/sapat.git"
+```
+
+## Step 3: Configure Fireworks
+
+Create `.env` in the workspace:
+
+```bash
+cat > .env <<'EOF'
+FIREWORKS_API_KEY=replace-with-your-fireworks-api-key
+FIREWORKS_MODEL=whisper-v3
+EOF
+```
+
+Load the file for the current shell:
+
+```bash
+set -a
+. ./.env
+set +a
+```
+
+Confirm the key is present without printing it:
+
+```bash
+test -n "$FIREWORKS_API_KEY" && echo "Fireworks key loaded"
+```
+
+Use `whisper-v3` when accuracy is more important than speed. Use
+`whisper-v3-turbo` when turnaround time matters more. Sapat maps the short
+alias `turbo` to `whisper-v3-turbo`, so both of these are valid:
+
+```bash
+sapat input/demo.mp4 --provider fireworks --model whisper-v3 --language en
+sapat input/demo.mp4 --provider fireworks --model turbo --language en
+```
+
+## Step 4: Prepare a Test Clip
+
+Start with a short, non-sensitive recording. A one-minute product demo, internal
+standup excerpt, or synthetic sample is enough to validate the provider path.
+
+```bash
+cp ~/Downloads/standup-short.mp4 input/standup-short.mp4
+```
+
+Write down the expected vocabulary before running the transcription. This gives
+you a simple quality check that does not depend on memory after the fact.
+
+```bash
+cat > notes/standup-short.expected.md <<'EOF'
+# Expected Terms
+
+- Daytona
+- Sapat
+- Fireworks AI
+- Whisper V3
+- transcript review
+EOF
+```
+
+Sapat converts source media to the provider's preferred format before upload.
+For Fireworks, the provider prefers WAV because Fireworks notes that
+pre-converting audio to its processing format can improve runtime performance.
+
+## Step 5: Run the Transcription
+
+Run Sapat against the sample file:
+
+```bash
+sapat input/standup-short.mp4 \
+  --provider fireworks \
+  --model "${FIREWORKS_MODEL:-whisper-v3}" \
+  --language en \
+  --quality H
+```
+
+The command selects the Fireworks provider, converts the source media, sends a
+multipart transcription request, writes a `.txt` file next to the input, and
+removes the temporary converted audio.
+
+Move the transcript into the review folder:
+
+```bash
+mv input/standup-short.txt transcripts/standup-short.fireworks.txt
+```
+
+Then record the run details:
+
+```bash
+cat > notes/standup-short.fireworks.md <<'EOF'
+# Fireworks Transcription Run
+
+- Provider: fireworks
+- Model: whisper-v3
+- Source: input/standup-short.mp4
+- Output: transcripts/standup-short.fireworks.txt
+- Reviewer:
+- Expected terms checked:
+- Follow-up edits:
+EOF
+```
+
+## Step 6: Add a Repeatable Runner
+
+A small runner keeps later transcription jobs consistent:
+
+```bash
+cat > run-fireworks.sh <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="${1:?usage: ./run-fireworks.sh input/file.mp4}"
+model="${FIREWORKS_MODEL:-whisper-v3}"
+base="$(basename "${input%.*}")"
+
+sapat "$input" \
+  --provider fireworks \
+  --model "$model" \
+  --language "${FIREWORKS_LANGUAGE:-en}" \
+  --quality "${SAPAT_QUALITY:-H}"
+
+mkdir -p transcripts
+mv "${input%.*}.txt" "transcripts/${base}.fireworks.txt"
+EOF
+chmod +x run-fireworks.sh
+```
+
+Now each file uses the same provider, model, language, quality setting, and
+artifact naming pattern:
+
+```bash
+FIREWORKS_MODEL=whisper-v3-turbo ./run-fireworks.sh input/customer-call.mp4
+```
+
+## Step 7: Validate the Provider Path
+
+The companion Sapat PR includes mocked tests, so validation does not require a
+real Fireworks key or private recording. In a clean workspace, run:
+
+```bash
+git clone https://github.com/chinook1001/sapat.git
+cd sapat
+git checkout codex/fireworks-provider
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest tests/providers/test_fireworks.py tests/test_registry.py -q
+python -m black --check sapat/providers/fireworks.py tests/providers/test_fireworks.py
+python -m compileall sapat/providers/fireworks.py tests/providers/test_fireworks.py
+git diff --check
+```
+
+Those checks verify that the provider:
+
+- Registers only when `FIREWORKS_API_KEY` is set.
+- Sends multipart audio with Fireworks authorization.
+- Routes `whisper-v3` to the production audio endpoint.
+- Routes `whisper-v3-turbo` to the turbo audio endpoint.
+- Extracts transcript text from a JSON response.
+- Raises clear errors when the API fails or returns no transcript text.
+
+## Troubleshooting
+
+**Problem:** Sapat says the `fireworks` provider is not available.
+
+**Solution:** Load `.env` again and confirm that `FIREWORKS_API_KEY` is set in
+the current shell. Sapat discovers providers from environment variables at
+runtime.
+
+**Problem:** Fireworks returns an authentication error.
+
+**Solution:** Check that the API key is copied from Fireworks and that the
+header value is not prefixed or quoted inside `.env`.
+
+**Problem:** The transcription is slower than expected.
+
+**Solution:** Try `whisper-v3-turbo`, keep clips reasonably short for the first
+run, and let Sapat convert the file before upload. If you need to process many
+hours of audio, split the work into smaller source files and store run notes per
+file.
+
+**Problem:** The transcript misses product names or acronyms.
+
+**Solution:** Add a short prompt with the important vocabulary. For example:
+
+```bash
+sapat input/standup-short.mp4 \
+  --provider fireworks \
+  --model whisper-v3 \
+  --language en \
+  --transcription-prompt "Vocabulary: Daytona, Sapat, Fireworks AI, Whisper V3"
+```
+
+## Conclusion
+
+You now have a Daytona workspace that can run Fireworks Whisper transcription
+through Sapat without leaking secrets or relying on a one-off local setup.
+Daytona keeps the workspace repeatable, Sapat standardizes conversion and
+provider selection, and Fireworks supplies the managed ASR endpoint.
+
+Treat each transcript as a build artifact. Keep the raw media private, record
+the provider and model, review expected terms, and only then use the transcript
+in summarization, search, or documentation workflows.
+
+## References
+
+- [Fireworks Speech to Text guide](https://fireworks.ai/docs/guides/querying-asr-models)
+- [Fireworks audio transcription API reference](https://fireworksai-docs.mintlify.app/api-reference/audio-transcriptions)
+- [Fireworks Whisper V3 model page](https://fireworks.ai/models/fireworks/whisper-v3)
+- [Sapat Fireworks provider PR](https://github.com/nibzard/sapat/pull/63)
+- [Sapat repository](https://github.com/nibzard/sapat)