Skip to content

docs: improve TTS extension guide with WebSocket patterns and config passthrough#314

Open
BenWeekes wants to merge 2 commits intomainfrom
improve/tts-extension-guide
Open

docs: improve TTS extension guide with WebSocket patterns and config passthrough#314
BenWeekes wants to merge 2 commits intomainfrom
improve/tts-extension-guide

Conversation

@BenWeekes
Copy link
Copy Markdown

Summary

  • Add complete serial WebSocket client and extension examples based on production deepgram_tts implementation
  • Add critical WebSocket patterns section: finish_request(), _finalize_request(), TTFB measurement, invalid text handling, cancel/reconnect, audio_start ordering
  • Add params passthrough pattern (update_params() convention used by all TTS extensions)
  • Add voice-assistant graph wiring section (manifest dependency, property.json graph variant, live testing)

Fixes

  • Replace mutable params = {} defaults with Field(default_factory=dict)
  • Widen typing from Dict[str, Optional[str]] to dict[str, Any]
  • Replace fictional test config filenames with real property_*.json layout
  • Add InvalidStatus handling to WebSocket _connect() example
  • Fix graph schema to use "graph": {"nodes": ..., "connections": ...}
  • Replace misleading "no explicit TTS connections needed" with "copy a known-good graph"

Context

These gaps were identified while building the deepgram_tts extension (TEN-framework/ten-framework#2131). The existing guide covered HTTP mode well but left significant blind spots for WebSocket implementations — particularly around finish_request() (forgetting it hangs the queue), TTFB measurement, invalid text handling for guarder tests, and config params forwarding.

Test plan

  • Review rendered MDX for formatting correctness
  • Verify code examples compile conceptually against current ten_ai_base API

…sthrough, graph wiring

add complete serial WebSocket client and extension examples based on
production deepgram_tts implementation. add critical patterns section
covering finish_request(), _finalize_request(), TTFB measurement,
invalid text handling, cancel/reconnect, and audio_start ordering.

add params passthrough pattern showing update_params() convention used
by all TTS extensions. add voice-assistant graph wiring section.

fix config examples to use Field(default_factory=dict) and dict[str, Any].
replace fictional test config filenames with real property_*.json layout.
add InvalidStatus handling to WebSocket _connect() example.
fix graph schema to use "graph": {"nodes": ..., "connections": ...}.
replace generic RuntimeError with VendorTTSConnectionException that
preserves HTTP status code, enabling the extension to distinguish
401 (FATAL_ERROR) from transient failures (NON_FATAL_ERROR). add
connection error handling in request_tts() showing the mapping.

remove fictional property.json from test configs tree — the guarder
tests use property_basic_audio_setting1.json as their default config.
add inline descriptions showing which guarder tests use each file.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant