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

@@ -90,6 +90,26 @@ jobs:
       - name: Build Voice Agent SDK
         run: make build-voice
 
+  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
+      - 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-tts:
     name: Test TTS SDK
     runs-on: ubuntu-latest

Makefile

@@ -1,12 +1,12 @@
 # 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: test-all test-rt test-batch test-flow test-tts test-voice test-agent-stt
+.PHONY: format-all format-rt format-batch format-flow format-tts format-voice format-agent-stt
+.PHONY: lint-all lint-rt lint-batch lint-flow lint-tts lint-voice lint-agent-stt
+.PHONY: type-check-all type-check-rt type-check-batch type-check-flow type-check-tts type-check-voice type-check-agent-stt
+.PHONY: build-all build-rt build-batch build-flow build-tts build-voice build-agent-stt
+.PHONY: clean-all clean-rt clean-batch clean-flow clean-tts clean-voice clean-agent-stt
 
 
 help:
@@ -19,6 +19,7 @@ help:
 	@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"
+	@echo "  test-agent-stt    Run tests for Agent STT SDK"
 	@echo ""
 	@echo "Code formatting:"
 	@echo "  format-all        Auto-fix formatting for all SDKs"
@@ -27,6 +28,7 @@ help:
 	@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"
+	@echo "  format-agent-stt  Auto-fix formatting for Agent STT SDK"
 	@echo ""
 	@echo "Linting:"
 	@echo "  lint-all          Run linting for all SDKs"
@@ -35,6 +37,7 @@ help:
 	@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"
+	@echo "  lint-agent-stt    Run linting for Agent STT SDK"
 	@echo ""
 	@echo "Type checking:"
 	@echo "  type-check-all    Run type checking for all SDKs"
@@ -43,6 +46,7 @@ help:
 	@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"
+	@echo "  type-check-agent-stt Run type checking for Agent STT SDK"
 	@echo ""
 	@echo "Building:"
 	@echo "  build-all         Build all SDKs"
@@ -51,6 +55,7 @@ help:
 	@echo "  build-flow        Build Flow SDK"
 	@echo "  build-tts         Build TTS SDK"
 	@echo "  build-voice       Build Voice Agent SDK"
+	@echo "  build-agent-stt   Build Agent STT SDK"
 	@echo ""
 	@echo "Cleaning:"
 	@echo "  clean-all         Clean all SDKs"
@@ -59,10 +64,11 @@ help:
 	@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 "  clean-agent-stt   Clean Agent STT 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-flow test-tts test-voice test-agent-stt
 test-rt:
 	pytest tests/rt/ -v -s
 
@@ -78,8 +84,11 @@ test-tts:
 test-voice:
 	pytest tests/voice/ -v -s
 
+test-agent-stt:
+	pytest tests/agent_stt/ -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-flow format-tts format-voice format-agent-stt format-tests format-examples
 
 format-rt:
 	cd sdk/rt/speechmatics && black .
@@ -101,6 +110,10 @@ format-voice:
 	cd sdk/voice/speechmatics && black .
 	cd sdk/voice/speechmatics && ruff check --fix .
 
+format-agent-stt:
+	cd sdk/agent_stt/speechmatics && black .
+	cd sdk/agent_stt/speechmatics && ruff check --fix .
+
 format-tests:
 	cd tests && black .
 	cd tests && ruff check --fix .
@@ -110,7 +123,7 @@ 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-flow lint-tts lint-voice lint-agent-stt
 
 lint-rt:
 	cd sdk/rt/speechmatics && ruff check .
@@ -127,8 +140,11 @@ lint-tts:
 lint-voice:
 	cd sdk/voice/speechmatics && ruff check .
 
+lint-agent-stt:
+	cd sdk/agent_stt/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-flow type-check-tts type-check-voice type-check-agent-stt
 type-check-rt:
 	cd sdk/rt/speechmatics && mypy .
 
@@ -144,6 +160,9 @@ type-check-tts:
 type-check-voice:
 	cd sdk/voice/speechmatics && mypy .
 
+type-check-agent-stt:
+	cd sdk/agent_stt/speechmatics && mypy .
+
 # Installation targets
 install-dev:
 	python -m pip install --upgrade pip
@@ -152,12 +171,13 @@ install-dev:
 	python -m pip install -e sdk/flow[dev]
 	python -m pip install -e sdk/tts[dev]
 	python -m pip install -e sdk/voice[dev]
+	python -m pip install -e sdk/agent_stt[dev]
 
 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-flow build-tts build-voice build-agent-stt
 
 build-rt: install-build
 	cd sdk/rt && python -m build
@@ -174,8 +194,11 @@ build-tts: install-build
 build-voice: install-build
 	cd sdk/voice && python -m build
 
+build-agent-stt: install-build
+	cd sdk/agent_stt && 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-flow clean-tts clean-voice clean-agent-stt 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
@@ -196,6 +219,10 @@ clean-voice:
 	rm -rf sdk/voice/dist sdk/voice/build sdk/voice/*.egg-info
 	find sdk/voice -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-test:
 	find tests -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
 	rm -rf .pytest_cache

README.md

@@ -13,6 +13,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 - voice](https://img.shields.io/pypi/v/speechmatics-voice?label=voice)](https://pypi.org/project/speechmatics-voice/)
+[![PyPI - agent-stt](https://img.shields.io/pypi/v/speechmatics-agent-stt?label=agent-stt)](https://pypi.org/project/speechmatics-agent-stt/)
 [![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)
 [![Build Status](https://github.com/speechmatics/speechmatics-python-sdk/actions/workflows/test.yaml/badge.svg)](https://github.com/speechmatics/speechmatics-python-sdk/actions/workflows/test.yaml)
@@ -57,6 +58,9 @@ pip install speechmatics-rt
 # Voice agents
 pip install speechmatics-voice
 
+# Voice agents on the Agent STT service
+pip install speechmatics-agent-stt
+
 # Text-to-speech
 pip install speechmatics-tts
 ```
@@ -84,6 +88,12 @@ pip install speechmatics-tts
 - Speaker diarization and turn detection
 - Optional ML-based smart turn: `pip install speechmatics-voice[smart]`
 
+**[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)
+- Runs no models locally
+
 **[speechmatics-tts](./sdk/tts/README.md)** - Text-to-speech
 
 - Convert text to natural-sounding speech
@@ -937,6 +947,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-voice** | [README](./sdk/voice/README.md)                                               | Voice agent SDK           |
+| **speechmatics-agent-stt** | [README](./sdk/agent_stt/README.md) • [Plan](./sdk/agent_stt/PLAN.md)     | Agent STT SDK             |
 | **speechmatics-tts**   | [README](./sdk/tts/README.md)                                                 | Text-to-speech            |
 
 ### Speechmatics Academy

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
+```