From eab5b25d942b6b592d5f6bee5a10677a0262b8f5 Mon Sep 17 00:00:00 2001 From: lucas Date: Sat, 30 May 2026 19:10:37 +0900 Subject: [PATCH] Add Fireworks Sapat Daytona guide Signed-off-by: lucas --- authors/lucas_chinook.md | 5 + ...0530_definition_serverless_asr_endpoint.md | 31 ++ ...fireworks_whisper_with_sapat_in_daytona.md | 343 ++++++++++++++++++ ...whisper_with_sapat_in_daytona_workflow.svg | 50 +++ 4 files changed, 429 insertions(+) create mode 100644 authors/lucas_chinook.md create mode 100644 definitions/20260530_definition_serverless_asr_endpoint.md create mode 100644 guides/20260530_run_fireworks_whisper_with_sapat_in_daytona.md create mode 100644 guides/assets/20260530_run_fireworks_whisper_with_sapat_in_daytona_workflow.svg diff --git a/authors/lucas_chinook.md b/authors/lucas_chinook.md new file mode 100644 index 00000000..3a3d95fa --- /dev/null +++ b/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) diff --git a/definitions/20260530_definition_serverless_asr_endpoint.md b/definitions/20260530_definition_serverless_asr_endpoint.md new file mode 100644 index 00000000..795ea17e --- /dev/null +++ b/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. diff --git a/guides/20260530_run_fireworks_whisper_with_sapat_in_daytona.md b/guides/20260530_run_fireworks_whisper_with_sapat_in_daytona.md new file mode 100644 index 00000000..659fc9d5 --- /dev/null +++ b/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) diff --git a/guides/assets/20260530_run_fireworks_whisper_with_sapat_in_daytona_workflow.svg b/guides/assets/20260530_run_fireworks_whisper_with_sapat_in_daytona_workflow.svg new file mode 100644 index 00000000..8c11ab1a --- /dev/null +++ b/guides/assets/20260530_run_fireworks_whisper_with_sapat_in_daytona_workflow.svg @@ -0,0 +1,50 @@ + + Sapat Fireworks transcription workflow in Daytona + A Daytona workspace prepares local media with Sapat, sends audio to Fireworks AI, and stores reviewed transcript artifacts. + + + + + + + + + + + Fireworks Whisper transcription in Daytona + Secrets stay local, media is prepared reproducibly, and transcript output is reviewed before reuse. + + + + + + + + + Daytona + Open a clean + workspace with + private .env config + + Sapat + Convert media to + Fireworks-ready + WAV input + + Fireworks AI + Call Whisper V3 + or Turbo audio + transcription API + + Review + Save transcript, + check terms, then + publish downstream + + + + + + + No API keys, wallet data, source media, or generated transcripts are committed to Git. +