Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Dispatch and error translation for the two speech nodes.
Reads the registries to route a call to the right provider, and normalizes
every provider failure into ``NodeUserError`` at one catch site. The nodes
never touch a provider class.
**No client cache here, deliberately.** ``ChatUnifier`` caches SDK clients
because an agent loop makes many model calls inside one node execution, so
connection reuse is worth a lease-counted LRU. Speech is the opposite shape:
a node execution issues exactly one HTTP request, and the client setup cost
is invisible next to a multi-second synthesis. Caching would buy nothing and
cost a process-wide singleton plus a shutdown hook wired into ``main.py`` --
core coupling this plugin has no reason to need. A client is built per call
and closed in ``finally``.
That also settles the question left open when the generic registry was
extracted: there is no second consumer for a shared client cache, so none
was built.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, TypeVar
from core.logging import get_logger
from services.plugin import NodeUserError
from services.provider_registry import ProviderSpec
if TYPE_CHECKING:
from services.gateway.routing import GatewayRoute
from ._protocol import (
SpeechError,
SpeechErrorCategory,
SttRequest,
SttResult,
TtsRequest,
TtsResult,
Voice,
)
from ._registry import get_stt_provider, get_tts_provider
logger = get_logger(__name__)
T = TypeVar("T")
async def synthesize(
*,
provider: str,
api_key: str,
request: TtsRequest,
translate_errors: bool = True,
route: Optional[GatewayRoute] = None,
) -> TtsResult:
"""Synthesize speech via the named provider (through the OpenCompany
Gateway when ``route`` is set)."""
spec = get_tts_provider(provider)
return await _dispatch(
spec,
provider,
api_key,
lambda client: client.synthesize(request),
operation="synthesis",
translate_errors=translate_errors,
route=route,
)
async def transcribe(
*,
provider: str,
api_key: str,
request: SttRequest,
translate_errors: bool = True,
route: Optional[GatewayRoute] = None,
) -> SttResult:
"""Transcribe audio via the named provider (through the OpenCompany
Gateway when ``route`` is set)."""
spec = get_stt_provider(provider)
return await _dispatch(
spec,
provider,
api_key,
lambda client: client.transcribe(request),
operation="transcription",
translate_errors=translate_errors,
route=route,
)
async def list_voices(*, provider: str, api_key: str) -> List[Voice]:
"""List selectable voices for a synthesis provider.
Providers without a live catalogue return their configured static list,
so the dropdown loader never branches on whether an endpoint exists.
"""
spec = get_tts_provider(provider)
return await _dispatch(
spec,
provider,
api_key,
lambda client: client.list_voices(),
operation="voice listing",
translate_errors=True,
)
async def _dispatch(
spec: ProviderSpec,
provider: str,
api_key: str,
call: Callable[[object], Awaitable[T]],
*,
operation: str,
translate_errors: bool,
route: Optional[GatewayRoute] = None,
) -> T:
"""Build a client, run ``call``, normalize failures, always close.
One catch site for all three entry points. ``translate_errors=False``
re-raises the structured :class:`SpeechError` instead of a flattened
user message, which is what a Temporal retry policy needs to read
``retryable``.
A ``route`` points the client at the OpenCompany Gateway: its URL, the
LiteLLM model prefix and the run's attribution headers. Only providers
on :class:`OpenAISpeechProvider` get one (``"gateway": true`` in
speech_defaults.json).
"""
client: Optional[object] = None
try:
client = spec.factory(api_key=api_key, **_client_kwargs(spec, route))
return await call(client)
except spec.sdk_exception_types as exc:
error = SpeechError.from_exception(provider, exc)
if not translate_errors:
raise error from exc
logger.warning(
"speech provider request failed",
provider=error.provider,
operation=operation,
category=error.category.value,
retryable=error.retryable,
status_code=error.status_code,
provider_code=error.provider_code,
request_id=error.request_id,
gateway=route is not None,
)
raise NodeUserError(_gateway_message(route, exc) or error.user_message) from error
except SpeechError as exc:
# A provider classified a failure itself -- typically a documented
# vendor error that arrived with HTTP 200, which both Deepgram and
# Sarvam can do. Already structured, so just surface it.
if not translate_errors:
raise
logger.warning(
"speech provider returned a failure payload",
provider=exc.provider,
operation=operation,
category=exc.category.value,
)
raise NodeUserError(exc.user_message) from exc
except (ValueError, TypeError, OSError) as exc:
# Only normalize failures raised while *constructing* the client.
# Once one exists, an unexpected exception from provider logic is a
# programming error and keeps its traceback.
if client is not None:
raise
category = (
SpeechErrorCategory.CONNECTION
if isinstance(exc, OSError)
else SpeechErrorCategory.INVALID_REQUEST
)
error = SpeechError(
message=str(exc),
provider=provider,
category=category,
retryable=category == SpeechErrorCategory.CONNECTION,
)
if not translate_errors:
raise error from exc
logger.warning(
"speech client construction failed",
provider=error.provider,
operation=operation,
category=error.category.value,
)
raise NodeUserError(error.user_message) from error
finally:
if client is not None:
await _close(client)
def _client_kwargs(spec: ProviderSpec, route: Optional[GatewayRoute]) -> Dict[str, Any]:
if route is None:
return dict(spec.client_kwargs)
from services.gateway.attribution import request_headers
return {
**spec.client_kwargs,
"base_url": route.base_url,
"model_prefix": route.model_prefix,
"extra_headers": request_headers(),
}
def _gateway_message(route: Optional[GatewayRoute], exc: BaseException) -> Optional[str]:
"""Gateway wording for a failed gateway call: the vendor's texts point
at the wrong key and billing account."""
if route is None:
return None
from services.gateway.errors import describe
return describe(exc)
async def _close(client: object) -> None:
"""Close a provider if it holds anything. Probed, not required."""
close = getattr(client, "aclose", None)
if close is None:
return
try:
result = close()
if hasattr(result, "__await__"):
await result
except Exception as exc:
logger.warning("failed to close speech client", error=str(exc))
__all__ = ["list_voices", "synthesize", "transcribe"]