Add agent stt sdk

.github/workflows/release-agent-stt.yaml

@@ -0,0 +1,90 @@
+name: Release Agent STT SDK
+
+on:
+  push:
+    tags:
+      - "agent-stt/v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  extract-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.extract.outputs.version }}
+    steps:
+      - name: Extract version from tag
+        id: extract
+        run: |
+          # Extract version from tag (agent-stt/v1.0.0 -> 1.0.0)
+          VERSION=${GITHUB_REF#refs/tags/agent-stt/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION"
+
+  test-agent-stt:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Test Agent STT SDK
+        run: |
+          make install-dev
+          make lint-agent-stt
+          make test-agent-stt
+
+  release-build:
+    runs-on: ubuntu-latest
+    needs: [extract-version, test-agent-stt]
+    outputs:
+      version: ${{ needs.extract-version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Update package version in sdk/agent_stt/speechmatics/agent_stt/__init__.py
+        run: |
+          VERSION="${{ needs.extract-version.outputs.version }}"
+          sed -i "s/0\.0\.0/$VERSION/g" ./sdk/agent_stt/speechmatics/agent_stt/__init__.py
+          echo "Updated version to: $VERSION"
+          cat ./sdk/agent_stt/speechmatics/agent_stt/__init__.py | grep __version__
+
+      - name: Build Agent STT SDK
+        run: |
+          make install-dev
+          make build-agent-stt
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: agent-stt-release-dist
+          path: sdk/agent_stt/dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs: [release-build]
+    environment:
+      name: pypi-agent-stt
+      url: https://pypi.org/project/speechmatics-agent-stt/${{ needs.release-build.outputs.version }}
+
+    steps:
+      - name: Retrieve release dist
+        uses: actions/download-artifact@v4
+        with:
+          name: agent-stt-release-dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          password: ${{ secrets.PYPI_ORG_TOKEN }}

.github/workflows/test.yaml

@@ -50,6 +50,26 @@ jobs:
       - name: Build Batch SDK
         run: make build-batch
 
+  test-agent-stt:
+    name: Test Agent STT SDK
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: make install-dev-agent-stt
+      - name: Lint Agent STT SDK
+        run: make lint-agent-stt
+      - name: Test Agent STT SDK
+        run: make test-agent-stt
+      - name: Build Agent STT SDK
+        run: make build-agent-stt
+
   test-flow:
     name: Test Flow SDK
     runs-on: ubuntu-latest

Makefile

@@ -1,13 +1,13 @@
 # Makefile for Speechmatics Python SDKs
 
 .PHONY: help
-.PHONY: test-all test-rt test-batch test-flow test-tts test-voice
-.PHONY: format-all format-rt format-batch format-flow format-tts format-voice
-.PHONY: lint-all lint-rt lint-batch lint-flow lint-tts lint-voice
-.PHONY: type-check-all type-check-rt type-check-batch type-check-flow type-check-tts type-check-voice
-.PHONY: build-all build-rt build-batch build-flow build-tts build-voice
-.PHONY: clean-all clean-rt clean-batch clean-flow clean-tts clean-voice
-.PHONY: install-dev install-dev-rt install-dev-batch install-dev-flow install-dev-tts install-dev-voice
+.PHONY: test-all test-rt test-batch test-agent-stt test-flow test-tts test-voice
+.PHONY: format-all format-rt format-batch format-agent-stt format-flow format-tts format-voice
+.PHONY: lint-all lint-rt lint-batch lint-agent-stt lint-flow lint-tts lint-voice
+.PHONY: type-check-all type-check-rt type-check-batch type-check-agent-stt type-check-flow type-check-tts type-check-voice
+.PHONY: build-all build-rt build-batch build-agent-stt build-flow build-tts build-voice
+.PHONY: clean-all clean-rt clean-batch clean-agent-stt clean-flow clean-tts clean-voice
+.PHONY: install-dev install-dev-rt install-dev-batch install-dev-agent-stt install-dev-flow install-dev-tts install-dev-voice
 
 
 help:
@@ -17,6 +17,7 @@ help:
 	@echo "  test-all          Run tests for all SDKs"
 	@echo "  test-rt           Run tests for RT SDK"
 	@echo "  test-batch        Run tests for Batch SDK"
+	@echo "  test-agent-stt    Run tests for Agent STT SDK"
 	@echo "  test-flow         Run tests for Flow SDK"
 	@echo "  test-tts          Run tests for TTS SDK"
 	@echo "  test-voice        Run tests for Voice Agent SDK"
@@ -25,6 +26,7 @@ help:
 	@echo "  format-all        Auto-fix formatting for all SDKs"
 	@echo "  format-rt         Auto-fix formatting for RT SDK"
 	@echo "  format-batch      Auto-fix formatting for Batch SDK"
+	@echo "  format-agent-stt  Auto-fix formatting for Agent STT SDK"
 	@echo "  format-flow       Auto-fix formatting for Flow SDK"
 	@echo "  format-tts        Auto-fix formatting for TTS SDK"
 	@echo "  format-voice      Auto-fix formatting for Voice Agent SDK"
@@ -33,6 +35,7 @@ help:
 	@echo "  lint-all          Run linting for all SDKs"
 	@echo "  lint-rt           Run linting for RT SDK"
 	@echo "  lint-batch        Run linting for Batch SDK"
+	@echo "  lint-agent-stt    Run linting for Agent STT SDK"
 	@echo "  lint-flow         Run linting for Flow SDK"
 	@echo "  lint-tts          Run linting for TTS SDK"
 	@echo "  lint-voice        Run linting for Voice Agent SDK"
@@ -41,6 +44,7 @@ help:
 	@echo "  type-check-all    Run type checking for all SDKs"
 	@echo "  type-check-rt     Run type checking for RT SDK"
 	@echo "  type-check-batch  Run type checking for Batch SDK"
+	@echo "  type-check-agent-stt Run type checking for Agent STT SDK"
 	@echo "  type-check-flow   Run type checking for Flow SDK"
 	@echo "  type-check-tts    Run type checking for TTS SDK"
 	@echo "  type-check-voice  Run type checking for Voice Agent SDK"
@@ -49,6 +53,7 @@ help:
 	@echo "  build-all         Build all SDKs"
 	@echo "  build-rt          Build RT SDK"
 	@echo "  build-batch       Build Batch SDK"
+	@echo "  build-agent-stt   Build Agent STT SDK"
 	@echo "  build-flow        Build Flow SDK"
 	@echo "  build-tts         Build TTS SDK"
 	@echo "  build-voice       Build Voice Agent SDK"
@@ -57,19 +62,23 @@ help:
 	@echo "  clean-all         Clean all SDKs"
 	@echo "  clean-rt          Clean RT SDK build artifacts"
 	@echo "  clean-batch       Clean Batch SDK build artifacts"
+	@echo "  clean-agent-stt   Clean Agent STT SDK build artifacts"
 	@echo "  clean-flow        Clean Flow SDK build artifacts"
 	@echo "  clean-tts         Clean TTS SDK build artifacts"
 	@echo "  clean-voice       Clean Voice Agent SDK build artifacts"
 	@echo ""
 
 # Testing targets
-test-all: test-rt test-batch test-flow test-tts test-voice
+test-all: test-rt test-batch test-agent-stt test-flow test-tts test-voice
 test-rt:
 	pytest tests/rt/ -v -s
 
 test-batch:
 	pytest tests/batch/ -v -s
 
+test-agent-stt:
+	pytest tests/agent_stt/ -v -s
+
 test-flow:
 	pytest tests/flow/ -v -s
 
@@ -80,7 +89,7 @@ test-voice:
 	pytest tests/voice/ -v -s
 
 # Formatting targets
-format-all: format-rt format-batch format-flow format-tts format-voice format-tests format-examples
+format-all: format-rt format-batch format-agent-stt format-flow format-tts format-voice format-tests format-examples
 
 format-rt:
 	cd sdk/rt/speechmatics && black .
@@ -90,6 +99,10 @@ format-batch:
 	cd sdk/batch/speechmatics && black .
 	cd sdk/batch/speechmatics && ruff check --fix .
 
+format-agent-stt:
+	cd sdk/agent_stt/speechmatics && black .
+	cd sdk/agent_stt/speechmatics && ruff check --fix .
+
 format-flow:
 	cd sdk/flow/speechmatics && black .
 	cd sdk/flow/speechmatics && ruff check --fix .
@@ -111,14 +124,17 @@ format-examples:
 	cd examples && ruff check --fix .
 
 # Linting targets
-lint-all: lint-rt lint-batch lint-flow lint-tts lint-voice
+lint-all: lint-rt lint-batch lint-agent-stt lint-flow lint-tts lint-voice
 
 lint-rt:
 	cd sdk/rt/speechmatics && ruff check .
 
 lint-batch:
 	cd sdk/batch/speechmatics && ruff check .
 
+lint-agent-stt:
+	cd sdk/agent_stt/speechmatics && ruff check .
+
 lint-flow:
 	cd sdk/flow/speechmatics && ruff check .
 
@@ -129,13 +145,16 @@ lint-voice:
 	cd sdk/voice/speechmatics && ruff check .
 
 # Type checking targets
-type-check-all: type-check-rt type-check-batch type-check-flow type-check-tts type-check-voice
+type-check-all: type-check-rt type-check-batch type-check-agent-stt type-check-flow type-check-tts type-check-voice
 type-check-rt:
 	cd sdk/rt/speechmatics && mypy .
 
 type-check-batch:
 	cd sdk/batch/speechmatics && mypy .
 
+type-check-agent-stt:
+	cd sdk/agent_stt/speechmatics && mypy .
+
 type-check-flow:
 	cd sdk/flow/speechmatics && mypy .
 
@@ -151,7 +170,7 @@ type-check-voice:
 # never satisfies that, so pip silently replaces the editable rt install with a published
 # PyPI wheel the moment voice[dev] installs after it. rt must always be the LAST install
 # in any sequence that also installs voice, so the local editable copy is what's left active.
-install-dev: install-dev-batch install-dev-flow install-dev-tts install-dev-voice install-dev-rt
+install-dev: install-dev-batch install-dev-agent-stt install-dev-flow install-dev-tts install-dev-voice install-dev-rt
 
 install-dev-rt:
 	python -m pip install --upgrade pip
@@ -161,6 +180,11 @@ install-dev-batch:
 	python -m pip install --upgrade pip
 	python -m pip install -e sdk/batch[dev]
 
+install-dev-agent-stt:
+	python -m pip install --upgrade pip
+	python -m pip install -e sdk/agent_stt[dev]
+	python -m pip install -e sdk/rt
+
 install-dev-flow:
 	python -m pip install --upgrade pip
 	python -m pip install -e sdk/flow[dev]
@@ -178,14 +202,17 @@ install-build:
 	python -m pip install --upgrade build
 
 # Building targets
-build-all: build-rt build-batch build-flow build-tts build-voice
+build-all: build-rt build-batch build-agent-stt build-flow build-tts build-voice
 
 build-rt: install-build
 	cd sdk/rt && python -m build
 
 build-batch: install-build
 	cd sdk/batch && python -m build
 
+build-agent-stt: install-build
+	cd sdk/agent_stt && python -m build
+
 build-flow: install-build
 	cd sdk/flow && python -m build
 
@@ -196,7 +223,7 @@ build-voice: install-build
 	cd sdk/voice && python -m build
 
 # Cleaning targets
-clean-all: clean-rt clean-batch clean-flow clean-tts clean-voice clean-test clean-examples
+clean-all: clean-rt clean-batch clean-agent-stt clean-flow clean-tts clean-voice clean-test clean-examples
 clean-rt:
 	rm -rf sdk/rt/dist sdk/rt/build sdk/rt/*.egg-info
 	find sdk/rt -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
@@ -205,6 +232,10 @@ clean-batch:
 	rm -rf sdk/batch/dist sdk/batch/build sdk/batch/*.egg-info
 	find sdk/batch -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
 
+clean-agent-stt:
+	rm -rf sdk/agent_stt/dist sdk/agent_stt/build sdk/agent_stt/*.egg-info
+	find sdk/agent_stt -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
 clean-flow:
 	rm -rf sdk/flow/dist sdk/flow/build sdk/flow/*.egg-info
 	find sdk/flow -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

README.md

@@ -12,6 +12,7 @@
 
 [![PyPI - batch](https://img.shields.io/pypi/v/speechmatics-batch?label=batch)](https://pypi.org/project/speechmatics-batch/)
 [![PyPI - rt](https://img.shields.io/pypi/v/speechmatics-rt?label=rt)](https://pypi.org/project/speechmatics-rt/)
+[![PyPI - agent-stt](https://img.shields.io/pypi/v/speechmatics-agent-stt?label=agent-stt)](https://pypi.org/project/speechmatics-agent-stt/)
 [![PyPI - voice](https://img.shields.io/pypi/v/speechmatics-voice?label=voice)](https://pypi.org/project/speechmatics-voice/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/speechmatics-batch.svg)](https://pypi.org/project/speechmatics-batch/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/speechmatics/speechmatics-python-sdk/blob/main/LICENSE)
@@ -54,6 +55,9 @@ pip install speechmatics-batch
 # Realtime streaming
 pip install speechmatics-rt
 
+# Voice agents on the Agent STT service
+pip install speechmatics-agent-stt
+
 # Voice agents
 pip install speechmatics-voice
 
@@ -78,6 +82,12 @@ pip install speechmatics-tts
 - Ultra-low latency (150ms p95)
 - Partial and final transcripts
 
+**[speechmatics-agent-stt](./sdk/agent_stt/README.md)** - Agent STT SDK
+
+- Segment-level transcription for voice agents
+- Server-side VAD and turn detection, or bring your own (Pipecat, LiveKit)
+- Lightweight install: pure Python, no ML runtime or GPU required, all heavy lifting is done in the service itself
+
 **[speechmatics-voice](./sdk/voice/README.md)** - Voice agent SDK
 
 - Build conversational AI applications
@@ -936,6 +946,7 @@ Each SDK package includes detailed documentation:
 | ---------------------- | ----------------------------------------------------------------------------- | ------------------------- |
 | **speechmatics-batch** | [README](./sdk/batch/README.md) • [Migration Guide](./sdk/batch/MIGRATION.md) | Async batch transcription |
 | **speechmatics-rt**    | [README](./sdk/rt/README.md) • [Migration Guide](./sdk/rt/MIGRATION.md)       | Realtime Streaming        |
+| **speechmatics-agent-stt** | [README](./sdk/agent_stt/README.md) • [Plan](./sdk/agent_stt/PLAN.md)     | Agent STT SDK             |
 | **speechmatics-voice** | [README](./sdk/voice/README.md)                                               | Voice agent SDK           |
 | **speechmatics-tts**   | [README](./sdk/tts/README.md)                                                 | Text-to-speech            |
 

examples/agent_stt/README.md

@@ -0,0 +1,24 @@
+# Agent STT examples
+
+Set `SPEECHMATICS_API_KEY` first. To point at a local Voice Agent Service, set
+`SPEECHMATICS_RT_URL` (for example `ws://localhost:8000/v2`); the `/agent` segment is appended
+when it is missing.
+
+The service needs 16 kHz raw PCM, so the file examples take a 16 kHz WAV and default to
+`tests/voice/assets/audio_01_16kHz.wav`.
+
+| Example | What it shows |
+| --- | --- |
+| [file/main.py](file/main.py) | File transcription with the service's VAD; segments, turn events, transcript at the end |
+| [realtime_file/main.py](realtime_file/main.py) | The same file paced at wall-clock speed, with the lag of each message behind the audio |
+| [client_vad/main.py](client_vad/main.py) | `TurnDetectionMode.EXTERNAL`: the application owns turn boundaries and calls `finalize()`, as Pipecat and LiveKit do |
+| [microphone/main.py](microphone/main.py) | Live microphone with diarization and speaker-labelled transcript (needs `pyaudio`) |
+| [microphone_windows/main.py](microphone_windows/main.py) | The same, set up for Windows: device selection, in-place partials, Ctrl+C shutdown |
+
+```bash
+python examples/agent_stt/file/main.py
+python examples/agent_stt/realtime_file/main.py
+python examples/agent_stt/client_vad/main.py
+python examples/agent_stt/microphone/main.py
+py examples\agent_stt\microphone_windows\main.py
+```