feat(telnyx): Telnyx assistant server framework (Media Streaming default)

[lucasassisrosa]

Adds Telnyx hosted AI Assistant as a first-class EVA framework (EVA_FRAMEWORK=telnyx), bridging the EVA user simulator to a Telnyx assistant and enriching the audit log from the Conversations API.

Two transports are implemented; Media Streaming is the default and recommended path.

Media Streaming (default) — verified working end-to-end

Reaches the assistant via Call Control + a bidirectional PCMU Media Streaming WebSocket — no WebRTC, no ICE/DTLS/SRTP. In a live EVA CLI run the assistant heard the caller and responded to what they said:

[assistant] Thank you for calling Summit Health Plan Prior Authorization Support. This is Chloe.
[user]      Hi, I need help requesting a temporary extension for my medical license.
[assistant] I understand you're looking for help with a medical license extension, but I'm the Prior Auth...

audio_user_clean.wav = 15.7s of real speech; EVA extracted 2 user turns (the WebRTC path gets 0).

Turnkey — just two keys. eva.assistant.telnyx_provisioning takes only a TELNYX_API_KEY and discovers/creates everything else (Call Control connection, caller-ID number, outbound profile) — reuse-first, idempotent. Set "webhook_base_url":"auto" and EVA launches a Cloudflare quick tunnel itself for the one-shot run (no account, no manual tunnel), so Telnyx can reach EVA's media WebSocket + call webhooks. Then python main.py.

docs/telnyx_media_streaming.md covers the flow and public-ingress options (tunnel, in-cluster ingress). A ready-to-run deploy image lives at team-telnyx/eva-media-streaming.

Direct WebRTC (alternate) — known limitation

TelnyxWebRTCClient reaches the assistant with only a public assistant_id (no API key, no ingress) via anonymous Verto/WebRTC. Currently blocked by a Telnyx b2bua-rtc inbound-media issue (VSDK-277): the assistant does not receive the caller's audio. ICE (aiortc + Pion both fail), signaling, and SDP have all been excluded; a fix ships here already (SSL_OP_NO_TICKET restores inbound audio). Kept for the id-only use case; use Media Streaming for a reliable graded run.

Contract

Subclasses AbstractAssistantServer, registered in _get_server_class(); serves the Twilio-framed ws://localhost:{port}/ws; routes tools through ToolExecutor; writes the audit log, transcript, audio, and scenario DBs.

Unit tests for the server, provisioner, and tunnel. Full suite green; ruff clean.

🤖 Generated with Claude Code

[JosephMarinier]

Hey Lucas! 👋

Thank you for your PR! We'll take a look soon.

When you get a chance, can you please run this?

uv run pre-commit run --all-files
git commit --message "Run pre-commit" --no-verify
git push

This will

1. Lock the new dependencies in uv.lock;
2. Apply pre-commit linting and formatting; and
3. Unblock the CI tests.

[lucasassisrosa]

Done — ran uv run --extra dev pre-commit run --all-files (pre-commit is in the dev extra) and pushed 567f1a1: ruff-format reformatted 4 files, metric signatures regenerated, and uv.lock updated with the new deps. CI should be unblocked now. 🙏

[muh7788]

hi @JosephMarinier

I’m Ahmed, TPM on the Telnyx side working with Lucas on this. I wanted to introduce myself and see whether there’s anything we can do to help make review of this PR easier.

If there are specific blockers or concerns, I’d really appreciate the guidance so we can help move it forward efficiently.

[katstankiewicz]

Review: feat(telnyx): Telnyx assistant server framework

Thanks @lucasassisrosa — this is a clean, well-documented addition. The code matches the surrounding style, the base-server contract is respected, and the unit tests cover the meaningful branching (provisioning idempotency, transport selection, validation per-mode, payload helpers). A few things worth addressing before merge:

Worth discussing before merge

1. aiohttp / aiortc / soxr are added as hard top-level dependencies.
aiohttp is imported unconditionally at the top of telnyx_server.py (line 43), and all three land in pyproject.toml core dependencies. Since telnyx is one of six frameworks and most runs won't use it, consider whether these should be optional extras rather than forced on every install. aiohttp in particular pulls a heavy transitive footprint into every environment for a single framework. (If the project intentionally keeps all framework deps in core for simplicity, that's fine — just flag it.)

2. The speech_fidelity_base.py change ships a behavior change to the Gemini audio judge for all runs, not just Telnyx.
The PR is titled around adding the Telnyx framework, but speech_fidelity_base.py:184-195 changes the judge path: when GEMINI_API_KEY is set, it always uploads the audio and calls google.genai directly, bypassing the LiteLLM router entirely. That's a real behavior change affecting every speech-fidelity / user-speech-fidelity / TTS-fidelity run. The metric-signature source_hash bumps in tests/fixtures/metric_signatures.json reflect this. Two asks:

• Split this into its own commit/PR, or at minimum call it out explicitly in the PR body — a reviewer scanning "Telnyx framework" would otherwise miss that the shared audio-judge path changed for everyone.
• Confirm the always-upload behavior is intended. Previously upload happened only as a fallback on "no audio"; now it's the primary path whenever a Gemini key is present, which changes cost/latency characteristics for every metrics run.

Correctness / robustness

3. The direct-Gemini path no longer logs token usage.
On the file-upload path, _generate_with_file is called but _log_token_usage is not (line 200 vs the router path at lines 202-205). The genai response's usage_metadata is also discarded inside _generate_with_file. If token accounting matters for these runs (it does elsewhere in the repo for cost tracking), the direct path silently drops it.

4. Auto-provision can silently reassign a number that's attached to another connection.
provision.py:117-131 — pick_from_number prefers unattached numbers, but falls back to any active number (including ones attached to other connections) when none are unattached, and provision.py:195-202 then PATCHes that number's connection_id to the managed connection. For a benchmarking tool that may run against a shared Telnyx account, silently re-pointing a number that's in production use elsewhere is risky. Consider refusing to reassign an already-attached number unless --from-number explicitly names it, or at least emitting a loud warning.

5. Created assistants leak on crash.
create_assistant defaults to True (telnyx_server.py:1281-1282), so every run that doesn't supply an explicit assistant_id creates a Telnyx assistant and relies on _shutdown to delete it (line 1472). If the run crashes before _shutdown reaches the delete (KeyboardInterrupt, OOM, exception during transport teardown), the assistant leaks on the Telnyx account. The provisioner reconciles connections/numbers idempotently, but there's no equivalent reaping of orphaned created assistants on the next run. Consider either persisting the created id for reaping next run, or documenting that crash-recovery of created assistants is manual.

6. _point_connection_webhook re-points a (potentially shared) connection's webhook to the per-run tunnel URL.
This is correct during a run with an ephemeral tunnel, but the call-control application is reuse-first/idempotent and may be shared across runs. If two runs ever overlap on the same account/connection they'll race on the webhook URL. A one-line caveat in docs/telnyx_media_streaming.md (auto-tunnel + shared connection assumes non-overlapping runs) would cover it.

Minor / nits

7. TelnyxAssistantManager.DEFAULT_MODEL = "moonshotai/Kimi-K2.5" — the created assistant falls back to this model unless model is set in s2s_params, and start() passes self._model which itself defaults to DEFAULT_MODEL. So unless the caller explicitly sets model, every created assistant uses Kimi-K2.5. Worth confirming this is the intended benchmark default rather than just a last-resort fallback (the PR body's Summit Health example suggests the agent config should drive the model).

8. The worker.py error message and config.py Literal are both updated consistently. ✓

9. _disable_dtls_session_tickets monkeypatches RTCCertificate._create_ssl_context globally (guarded by a module-level flag so idempotent). The comment explains the rationale well; the global patch is acceptable for a single-process CLI. ✓

Summary

The Telnyx framework integration itself is solid and well-tested. The main asks before merge:

• Split or explicitly justify the speech_fidelity_base.py audio-judge behavior change (it affects all runs, not just Telnyx), and confirm the always-upload-to-Gemini path is intended.
• Decide whether aiohttp/aiortc/soxr belong in core deps or as an optional extra.
• Address the assistant-leak-on-crash risk (or document it), and the silent-number-reassignment risk in the provisioner.

Happy to dig deeper into any of these.