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_service_instance_transcription.md b/definitions/20260530_definition_service_instance_transcription.md new file mode 100644 index 00000000..d6d28c55 --- /dev/null +++ b/definitions/20260530_definition_service_instance_transcription.md @@ -0,0 +1,30 @@ +--- +title: "Service Instance Transcription" +description: "Service instance transcription sends prepared audio to a cloud speech-to-text endpoint that is scoped to one provider account or deployment." +date: 2026-05-30 +author: "Lucas Chinook" +--- + +# Service Instance Transcription + +## Definition + +Service instance transcription is a speech-to-text workflow where audio is sent +to a cloud service URL that belongs to a specific provider instance, region, or +deployment. Instead of calling a single global endpoint, the client combines an +account-specific service URL with an API key or access token, then requests a +transcript for a prepared audio file. + +## Context and Usage + +This pattern is common for enterprise speech platforms because credentials, +region, data handling rules, and available models are often tied to a service +instance. IBM Watson Speech to Text is one example: a project stores an API key +and a service URL, then calls the instance's `/v1/recognize` endpoint with a +content type such as `audio/wav`. + +Inside a reproducible development environment, service instance transcription +is easier to operate safely. The workspace can keep secrets in `.env`, convert +audio into a provider-supported format, run the same transcription command +across test clips, and document which model was used. This makes transcripts +more auditable than a one-off upload from a developer laptop. diff --git a/guides/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona.md b/guides/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona.md new file mode 100644 index 00000000..92d37de8 --- /dev/null +++ b/guides/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona.md @@ -0,0 +1,332 @@ +--- +title: 'Run IBM Watson Speech to Text With Sapat in Daytona' +description: + 'Create a reproducible Daytona workspace for transcribing media with Sapat + and IBM Watson Speech to Text.' +date: 2026-05-30 +author: 'Lucas Chinook' +tags: ['AI', 'transcription', 'python', 'daytona'] +--- + +# Run IBM Watson Speech to Text With Sapat in Daytona + +Speech-to-text work gets messy when the service URL, API key, audio conversion, +and model choice all live on a single developer machine. A Daytona workspace +turns that setup into a repeatable project. Sapat handles media conversion and +provider routing. IBM Watson Speech to Text handles the transcript request +through a service-instance endpoint. + +This guide shows how to run Sapat with IBM Watson Speech to Text inside a +Daytona workspace. The workflow uses a companion Sapat provider implementation +in [nibzard/sapat#62](https://github.com/nibzard/sapat/pull/62). It is designed +for AI engineers who need a predictable [service instance transcription](../definitions/20260530_definition_service_instance_transcription.md) +workflow without committing keys, private recordings, or generated transcripts. + +![Sapat IBM Watson workflow](./assets/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona_workflow.svg) + +## What You Will Build + +You will create a small transcription workspace with: + +- A Daytona workspace cloned from Sapat. +- A local `.env` file for IBM Watson Speech to Text credentials. +- An input folder for short test recordings. +- A repeatable Sapat command that converts media to WAV and calls IBM's + synchronous `POST /v1/recognize` endpoint. +- A review checklist for validating transcript output before using it in a + downstream AI workflow. + +The result is not a magic upload button. It is a developer-friendly runbook: +clone, configure, transcribe, inspect, and repeat. + +## 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 source media before sending audio to a + provider. +- A Sapat branch or release that includes the `ibm_watson` provider. +- An IBM Watson Speech to Text service instance, API key, and service URL. + +IBM documents the synchronous HTTP interface as a single `POST /v1/recognize` +method for speech recognition requests. The API reference also lists supported +audio content types and notes that synchronous recognize requests accept audio +data and return final transcription results. The Sapat provider in this guide +uses that synchronous flow with basic API key authentication. + +## Step 1: Create the Workspace Project + +Create a small project folder for the IBM Watson transcription workflow: + +```bash +mkdir sapat-ibm-watson-daytona +cd sapat-ibm-watson-daytona +``` + +Add a minimal README so future runs explain what the folder is for: + +```bash +cat > README.md <<'EOF' +# Sapat IBM Watson Transcription + +This workspace runs Sapat with IBM Watson Speech to Text. +Secrets stay in .env. Source media stays in input/. Transcript outputs are +reviewed before being used in downstream AI workflows. +EOF +``` + +Create the folder layout: + +```bash +mkdir -p input transcripts notes +touch .gitignore +printf ".env\ninput/*\ntranscripts/*\n" >> .gitignore +``` + +Keep sample files short while validating the provider. IBM's synchronous API is +best for direct request-response checks, so start with a short WAV or MP4 clip +before moving to longer recordings. + +## Step 2: Open the Project in Daytona + +Initialize Git and create the workspace: + +```bash +git init +git add README.md .gitignore +git commit -m "Initialize IBM Watson transcription workspace" +daytona create . --code +``` + +Inside the Daytona workspace 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/ibm-watson-provider" +``` + +After the provider lands upstream, switch the install URL back to the main Sapat +repository: + +```bash +python -m pip install "git+https://github.com/nibzard/sapat.git" +``` + +## Step 3: Configure IBM Watson Credentials + +Create `.env` locally in the workspace. Do not commit this file. + +```bash +cat > .env <<'EOF' +IBM_WATSON_STT_API_KEY=replace-with-your-api-key +IBM_WATSON_STT_URL=https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/replace-with-instance-id +IBM_WATSON_STT_TIMEOUT=120 +EOF +``` + +Load the variables for the current shell: + +```bash +set -a +. ./.env +set +a +``` + +Confirm the variables are present without printing the secret: + +```bash +test -n "$IBM_WATSON_STT_API_KEY" && echo "IBM Watson key loaded" +test -n "$IBM_WATSON_STT_URL" && echo "IBM Watson service URL loaded" +``` + +IBM service URLs are instance-specific. Keep the exact URL from the IBM Cloud +resource page, including its region and instance path. Sapat appends +`/v1/recognize` when it sends the transcription request. + +## Step 4: Prepare a Safe Test Clip + +Copy a short, non-sensitive recording into `input/`: + +```bash +cp ~/Downloads/product-demo-short.mp4 input/product-demo-short.mp4 +``` + +If you already have a WAV file, that is fine too. The IBM provider prefers WAV, +so Sapat will ask `ffmpeg` to convert video or compressed audio into a 16 kHz +mono WAV file before upload. That keeps the content type explicit and avoids +guessing at the provider boundary. + +For the first validation run, use a clip under one minute with known wording. +Write the expected names, product terms, or acronyms in `notes/expected.md`: + +```bash +cat > notes/expected.md <<'EOF' +# Expected Terms + +- Daytona +- Sapat +- IBM Watson Speech to Text +- service instance transcription +EOF +``` + +## Step 5: Run Sapat With IBM Watson + +Run Sapat with the provider name and a model: + +```bash +sapat input/product-demo-short.mp4 \ + --provider ibm_watson \ + --model en-US_BroadbandModel \ + --language en \ + --quality H +``` + +The command prints the selected provider and model, converts the source file to +WAV, sends the WAV bytes to IBM Watson Speech to Text, writes the transcript as +`input/product-demo-short.txt`, and removes the temporary WAV file. + +Move the transcript into the review folder: + +```bash +mv input/product-demo-short.txt transcripts/product-demo-short.ibm-watson.txt +``` + +Then create a compact run note: + +```bash +cat > notes/product-demo-short.ibm-watson.md <<'EOF' +# IBM Watson Transcription Run + +- Provider: ibm_watson +- Model: en-US_BroadbandModel +- Source: input/product-demo-short.mp4 +- Output: transcripts/product-demo-short.ibm-watson.txt +- Reviewer: +- Issues: +EOF +``` + +## Step 6: Review the Transcript + +Before sending the transcript into an AI summarizer or retrieval pipeline, check +the basics: + +- Does the transcript include the expected product names? +- Are acronyms readable enough to search? +- Are speaker turns or topic transitions obvious from the text? +- Did the command use the intended IBM service instance URL? +- Was the audio safe to send to the provider? + +For a repeatable comparison, keep a small shell helper: + +```bash +cat > run-ibm-watson.sh <<'EOF' +#!/usr/bin/env bash +set -euo pipefail + +input="${1:?usage: ./run-ibm-watson.sh input/file.mp4}" +base="$(basename "${input%.*}")" + +sapat "$input" \ + --provider ibm_watson \ + --model "${IBM_WATSON_STT_MODEL:-en-US_BroadbandModel}" \ + --language "${IBM_WATSON_STT_LANGUAGE:-en}" \ + --quality "${SAPAT_QUALITY:-H}" + +mkdir -p transcripts +mv "${input%.*}.txt" "transcripts/${base}.ibm-watson.txt" +EOF +chmod +x run-ibm-watson.sh +``` + +Now each new recording uses the same provider settings: + +```bash +./run-ibm-watson.sh input/standup-demo.mp4 +``` + +## Step 7: Validate the Provider Path + +The companion Sapat PR includes mocked tests for the provider. You can run the +same focused checks in the workspace: + +```bash +git clone https://github.com/chinook1001/sapat.git +cd sapat +git checkout codex/ibm-watson-provider +python -m venv .venv +. .venv/bin/activate +python -m pip install -e ".[dev]" +python -m pytest tests/providers/test_ibm_watson.py tests/test_registry.py -q +python -m black --check sapat/providers/ibm_watson.py tests/providers/test_ibm_watson.py +python -m compileall sapat/providers/ibm_watson.py tests/providers/test_ibm_watson.py +git diff --check +``` + +The tests verify that the provider: + +- Registers only when `IBM_WATSON_STT_API_KEY` and `IBM_WATSON_STT_URL` are set. +- Calls the service instance's `/v1/recognize` endpoint. +- Sends binary audio with the correct `Content-Type`. +- Uses API key authentication. +- Extracts transcript text from IBM Watson recognition results. +- Raises useful errors when the API fails or returns no transcript text. + +## Troubleshooting + +**Problem:** Sapat says no providers are available. + +**Solution:** Confirm the `.env` file is loaded and both IBM Watson variables +are set. The provider registry skips providers when required environment +variables are missing. + +**Problem:** IBM returns an authentication error. + +**Solution:** Check that the API key belongs to the Speech to Text instance +whose service URL you are using. A key from a different IBM service or region +will not authenticate the same request. + +**Problem:** IBM returns an unsupported content type error. + +**Solution:** Let Sapat convert to WAV instead of uploading the original file +directly. The provider maps `.wav` files to `audio/wav`, which IBM lists as a +supported recognition content type. + +**Problem:** The transcript is empty. + +**Solution:** Try a clearer audio sample, verify that the file is longer than a +short silence-only clip, and review whether the selected model matches the +recording language. The provider raises an error when IBM returns no transcript +text so the run is not mistaken for a successful blank transcript. + +## Conclusion + +You now have a reproducible Daytona workflow for running Sapat with IBM Watson +Speech to Text. Daytona keeps the development environment consistent, Sapat +handles conversion and provider routing, and IBM Watson processes the prepared +audio through a service-instance endpoint. + +The important habit is to treat the transcript as a build artifact. Keep the +raw media private, load secrets from `.env`, write down the provider and model, +and review the text before sending it to another AI system. + +## References + +- [IBM Speech to Text getting started documentation](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-gettingStarted) +- [IBM Speech to Text API reference](https://cloud.ibm.com/apidocs/speech-to-text) +- [IBM synchronous HTTP interface documentation](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-http) +- [Sapat IBM Watson provider PR](https://github.com/nibzard/sapat/pull/62) +- [Sapat repository](https://github.com/nibzard/sapat) diff --git a/guides/assets/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona_workflow.svg b/guides/assets/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona_workflow.svg new file mode 100644 index 00000000..f9a39718 --- /dev/null +++ b/guides/assets/20260530_run_ibm_watson_speech_to_text_with_sapat_in_daytona_workflow.svg @@ -0,0 +1,31 @@ + + Sapat IBM Watson Speech to Text workflow in Daytona + A Daytona workspace converts source media to WAV, routes it through Sapat, sends it to IBM Watson Speech to Text, and stores reviewed transcript output. + + + Daytona + workspace + .env + media + + Sapat + convert to WAV + provider registry + + IBM Watson + Speech to Text + POST /v1/recognize + + Reviewed Transcript + plain text output + run notes + + + + + repeatable + workspace runs + + + + + +