Add Deepgram Voice Agent framework support

[weiz9]

Summary

Adds a new deepgram assistant-server framework backed by Deepgram's Voice Agent API (unified STT→LLM→TTS over a single WebSocket), so the Deepgram agent can be benchmarked like the existing S2S frameworks. Modeled on the Gemini Live server and the docs/assistant_server_contract.md contract.

Changes

• New server src/eva/assistant/deepgram_server.py (DeepgramAssistantServer): bridges the Twilio-framed user-simulator WebSocket ↔ client.agent.v1.connect(), with the standard audit-log / framework-log / metrics-log / audio-buffer handling.
• Registration: deepgram added to worker._get_server_class() and the framework Literal in models/config.py.
• Tests: tests/unit/assistant/test_deepgram_server.py (settings + tool-conversion) and a dispatch case in test_framework_dispatch.py.
• Docs: Deepgram reference section in assistant_server_contract.md; deepgram added to the framework enum in .env.example.
• Version: simulation_version 2.0.0 → 2.1.0 (affects benchmark outputs).

Implementation notes (found via live testing)

• SDK workaround: deepgram-sdk 6.1.x mis-deserializes every agent event to the same model via its typed iterator, dropping transcripts and tool-call requests. The server iterates the raw WebSocket and dispatches on the JSON type instead (audio still arrives as binary frames).
• KeepAlive: a periodic KeepAlive task prevents Deepgram's ~10s input-audio timeout from closing the session while the half-duplex agent is speaking.
• Latency: model_response latency is measured from the server-side receipt time of the simulator's user_speech_stop event.

Testing

• ruff, mypy (new file clean), and pre-commit run --all-files all pass (version-bump + metric-signature hooks included).
• 351 unit tests pass across assistant/orchestrator/models suites.
• Live end-to-end runs across airline, itsm, and medical_hr (5 records each): ~104/105 conversations reached a valid end (conversation_valid_end = 1.0), 500+ tool calls executed with scenario-DB mutations, and zero framework-level errors (no disconnects, audio timeouts, or event-processing failures).

Config example

EVA_FRAMEWORK=deepgram
EVA_MODEL__S2S=deepgram
EVA_MODEL__S2S_PARAMS='{"api_key":"<deepgram-key>","model":"gpt-4o-mini"}'

Optional s2s_params (defaults): think_provider (open_ai), listen_model (nova-3), speak_model (aura-2-thalia-en), language (en).

[JosephMarinier]

Considering this version, does this comment from the PR description still apply?

SDK workaround: deepgram-sdk 6.1.x mis-deserializes every agent event to the same model via its typed iterator, dropping transcripts and tool-call requests. The server iterates the raw WebSocket and dispatches on the JSON type instead (audio still arrives as binary frames).

[JosephMarinier]

The PR description says this 🤔

Version: simulation_version 2.0.0 → 2.1.0 (affects benchmark outputs).

Anyway, I'm not sure we need to bump the version. We don't need to rerun any old simulations, right? This addition doesn't really "affect" existing results; it just adds new possibilities. Does that make sense?

Suggested change

	simulation_version = "2.0.5"
	simulation_version = "2.0.1"

[JosephMarinier]

I'd like to double-check, maybe with @fanny-riols, whether it makes sense to have default models, which will certainly go out of fashion, or if it would be better to require the user to specify the models.

If the default models are OK, we should at least reuse the constants here:

Suggested change

	"stt": p.get("listen_model", "nova-3"),
	"llm": p.get("think_label") or p.get("model") or p.get("think_model", ""),
	"tts": p.get("speak_model", "aura-2-thalia-en"),
	"stt": p.get("listen_model", _DEFAULT_LISTEN_MODEL),
	"llm": p.get("think_label") or p.get("model") or p.get("think_model", ""),
	"tts": p.get("speak_model", _DEFAULT_SPEAK_MODEL),

[fanny-riols]

Yeah I think it's fine to have defaults for the deepgram framework. But let's use the DEFAULT vars though.

[JosephMarinier]

This "think_model" is not used anywhere else. Was that a confusion between "think_label" and "think_model"? Or am I missing something?

Also, is there a reason to use that instead of "alias" like in regular S2S models? If we can go with "alias", then we can reuse this function:

Suggested change

	"llm": p.get("think_label") or p.get("model") or p.get("think_model", ""),
	"llm": _param_alias(p),

And adapt DeepgramAssistantServer.__init__() accordingly.

[JosephMarinier]

Thanks to the _check_companion_services() model validator, we can assume that self.s2s_params is a dict (not None), so self.s2s_params or {} is not necessary.

Combining that with the two suggestions above, we get this. Do all these make sense?

Suggested change

	p = self.s2s_params or {}
	return {
	"stt": p.get("listen_model", "nova-3"),
	"llm": p.get("think_label") or p.get("model") or p.get("think_model", ""),
	"tts": p.get("speak_model", "aura-2-thalia-en"),
	}
	return {
	"stt": self.s2s_params.get("listen_model", _DEFAULT_LISTEN_MODEL),
	"llm": _param_alias(self.s2s_params),
	"tts": self.s2s_params.get("speak_model", _DEFAULT_SPEAK_MODEL),
	}