[Enhancement] Add connection pre-warming with warm() for reduced first-call streaming latency

[deepgram-robot]

Summary

Add a warm() method to the streaming client that pre-establishes the WebSocket connection and completes the handshake before the first audio data is sent. This eliminates cold-start latency on the first transcription request, which is critical for latency-sensitive voice agent and real-time transcription applications.

Problem it solves

Developers building real-time voice applications experience a noticeable latency spike on the first streaming request because the WebSocket connection (DNS resolution, TCP handshake, TLS negotiation, Deepgram handshake) happens synchronously when the first audio frame is sent. In voice agent scenarios, this adds 200-500ms to the first response. A pre-warming method lets developers establish the connection during application startup or idle time, so the first audio frame flows immediately without connection overhead.

This is especially important for:

• Voice agents that need sub-second time-to-first-transcript
• Applications that create streaming sessions in response to user actions (button press, wake word)
• Serverless/container environments where connections are established per-request

Proposed API

from deepgram import DeepgramClient

client = DeepgramClient(api_key)

# Pre-warm a streaming connection during app startup
live_client = client.listen.live.v("1")
await live_client.warm(options={
    "model": "nova-3",
    "language": "en",
    "smart_format": True
})

# Later, when audio is ready — connection is already established
# First audio frame flows immediately with zero connection overhead
await live_client.send(audio_data)

# warm() could also accept a timeout parameter
await live_client.warm(options=options, timeout=5.0)

The warm() method should:

1. Establish the WebSocket connection with the specified options
2. Complete the Deepgram handshake (receive MetadataResponse)
3. Keep the connection alive with keepalive messages until audio is sent
4. Be idempotent — calling warm() on an already-warm connection is a no-op
5. Raise a clear error if the connection cannot be established within the timeout

Acceptance criteria

• warm() method available on both sync and async streaming clients
• Connection is fully established and ready to receive audio after warm() returns
• Keepalive messages maintain the pre-warmed connection
• Idempotent — safe to call multiple times
• Configurable timeout with sensible default
• Documented with usage example in README
• Compatible with existing streaming API — no breaking changes

---

Raised by the DX intelligence system.