feat(openai): add LLM.with_cloudflare() for Cloudflare AI Gateway

[mcdgavin]

Summary

Closes #6101. Adds openai.LLM.with_cloudflare(...), a convenience constructor that routes
LLM traffic through the Cloudflare AI Gateway
unified OpenAI-compatible endpoint — mirroring the existing with_openrouter / with_azure
helpers.

from livekit.plugins import openai

# Minimal: account_id from CLOUDFLARE_ACCOUNT_ID, gateway token from CLOUDFLARE_AI_GATEWAY_TOKEN
llm = openai.LLM.with_cloudflare(model="openai/gpt-4o")

# Explicit, with bring-your-own provider key and per-request gateway options
llm = openai.LLM.with_cloudflare(
    model="workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast",
    account_id="<account_id>",
    gateway_id="default",
    cf_aig_token="<gateway_token>",
    api_key="<provider_key>",
    gateway_options={"cache_ttl": 3600, "max_attempts": 3, "backoff": "exponential"},
)

Design notes

• Dual auth. Cloudflare supports two layers: cf-aig-authorization (gateway token) and
  Authorization (BYO downstream provider key); at least one is required. In gateway-stored-keys
  mode the OpenAI SDK still needs a non-empty Authorization, so a "cloudflare" placeholder is
  used — the same pattern as with_ollama.
• Per-request options are headers, not body. Unlike OpenRouter (JSON body fields),
  Cloudflare's controls are cf-aig-* HTTP headers. gateway_options is a
  CloudflareGatewayOptions TypedDict covering caching, retries, timeout, metadata, and custom
  cost; set fields map to the corresponding headers (metadata/custom_cost JSON-encoded). A
  grouped TypedDict (over loose kwargs) keeps the signature to one extra param while typing the
  structured values. Validation is type-level only; numeric ranges pass through to Cloudflare.
• Convenience. The gateway URL is built from account_id (env CLOUDFLARE_ACCOUNT_ID) and
  gateway_id (default "default"), with a base_url override.

Testing

tests/test_openai_with_cloudflare.py (hermetic, --unit): URL building from
account_id/gateway_id, CLOUDFLARE_ACCOUNT_ID env fallback, base_url override, BYOK vs
gateway-stored-keys auth, the full gateway_options → cf-aig-* header mapping (incl. JSON
encoding and the skip_cache-only-when-true rule), and all ValueError paths. make check
passes (ruff format + lint, strict mypy).

Out of scope

STT/TTS via Cloudflare Workers AI (#3163), tracked separately.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[CLAassistant]

All committers have signed the CLA.

[chenghao-mou]

The Unified API (OpenAI compat) endpoint is being deprecated, we should use the rest-api instead.

[mcdgavin]

Switched to the REST API (https://api.cloudflare.com/client/v4/accounts/<id>/ai/v1) in 3a9f400. It's OpenAI-SDK compatible — Cloudflare's own example uses new OpenAI({ baseURL: ".../ai/v1" }) — so the wrapper is unchanged apart from the base URL, and streaming is supported on that endpoint. Gateway selection moved to the cf-aig-gateway-id header (no gateway path segment; defaults to the account's default gateway).

One caveat I want to call out: the REST-API docs don't explicitly mention tool/function calling. It's the OpenAI schema so tools/tool_calls pass through at the protocol level, but whether the gateway+model honors them is model-dependent and I haven't verified it against a live gateway.