Release v0.11.1: Normalize Live API usage metadata and improve Vertex AI compatibility

- Implement canonical `candidates_*` fields in `UsageMetadata` to unify
  Gemini Live (`response_*`) and Vertex Live (`candidates_*`) schemas.
- Add `output_token_count/1` and `output_tokens_details/1` helpers for
  backend-agnostic usage tracking.
- Capture and expose Vertex Live `turnCompleteReason` via `ServerContent`.
- Update `RateLimiter.Manager` to reconcile usage against canonical
  fields, preferring `candidatesTokenCount` where available.
- Refine Vertex Live model resolution to exclude native-audio-only models
  from text-only session candidates.
- Improve test stability:
  - Add retry/skip logic for transient upstream 1011 errors.
  - Dynamically skip Vertex text-only tests if no compatible model is
    detected in the user's project.
- Document backend schema differences and provide updated testing
  instructions in README and guides.
- Bump version to 0.11.1.

Author: nshkrdotcom

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-03-27
+
+### Added
+
+#### Live API Schema Compatibility Helpers
+- **`Gemini.Types.Live.Enums.TurnCompleteReason`**: typed enum for Vertex Live `turnCompleteReason`
+- **`Gemini.Types.Live.ServerContent.turn_complete_reason`**: captures the server-provided turn completion reason when present
+- **`Gemini.Types.Live.UsageMetadata.output_token_count/1`** and **`output_tokens_details/1`**: backend-agnostic helpers for normalized Live output usage
+
+### Changed
+- **Live usage metadata normalization**: Gemini Live `responseTokenCount` / `responseTokensDetails` and Vertex Live `candidatesTokenCount` / `candidatesTokensDetails` now populate the same canonical `candidates_*` fields in `Gemini.Types.Live.UsageMetadata`
+- **Backwards compatibility preserved**: `response_token_count` and `response_tokens_details` remain available as aliases for existing caller code
+- **Vertex text live model filtering**: native-audio-only models are no longer treated as text candidates during Vertex Live text model resolution
+- **Live docs and test instructions**: README and Live API guide now document the Gemini-vs-Vertex schema split and the targeted manual test commands
+
+### Fixed
+- **Rate limiter output token accounting**: usage reconciliation now falls back to Gemini-style Live `responseTokenCount` metadata instead of assuming only `candidatesTokenCount`
+- **Vertex Live server content parsing**: `turnCompleteReason` is now captured and exposed through the Live type layer
+- **Live type coverage**: unit tests now cover Gemini-style and Vertex-style usage metadata parsing plus Vertex turn completion reasons
+- **Live integration test stability**: Gemini raw WebSocket setup retries/skips transient upstream `1011` internal errors, and Vertex text-only live session tests skip cleanly when the project has no text-capable Live model
+
 ## [0.11.0] - 2026-03-05
 
 ### Added
@@ -2035,7 +2056,8 @@ config :gemini_ex,
 - Minimal latency overhead
 - Concurrent request processing
 
-[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.1...HEAD
+[0.11.1]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.9.0...v0.9.1

README.md

@@ -59,7 +59,7 @@ Add `gemini` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:gemini_ex, "~> 0.11.0"}
+    {:gemini_ex, "~> 0.11.1"}
   ]
 end
 ```
@@ -208,6 +208,8 @@ See `guides/interactions.md` for CRUD, resumption (`last_event_id`), and backgro
 
 Real-time bidirectional streaming for voice, video, and text interactions. For Gemini Live connections, `v1beta` is the default API version, while `v1alpha` is available for advanced native-audio features. Vertex Live connections use the Vertex `v1` WebSocket endpoint.
 
+Gemini Live and Vertex Live do not emit identical usage metadata fields. `gemini_ex` normalizes both backends into `Gemini.Types.Live.UsageMetadata.candidates_token_count` / `candidates_tokens_details`, keeps `response_*` aliases for backwards compatibility, and exposes `Gemini.Types.Live.UsageMetadata.output_token_count/1` and `output_tokens_details/1` as backend-agnostic helpers. Vertex Live may also populate `server_content.turn_complete_reason`.
+
 #### Model Resolution
 
 Live API model availability varies by API key and regional rollout. `Gemini.Live.Models.resolve/1` uses the model registry plus runtime `list_models` results to select a compatible model:
@@ -1856,8 +1858,19 @@ mix test --cover
 
 # Run integration tests (requires API key)
 GEMINI_API_KEY="your_key" mix test --only integration
+
+# Run Gemini Live session tests when GEMINI_API_KEY is already exported
+mix test --only live_gemini test/gemini/live/session_live_test.exs
+
+# Run Gemini Live feature tests when GEMINI_API_KEY is already exported
+mix test --only live_gemini test/gemini/live/features_live_test.exs
+
+# Run billed Vertex Live tests when Vertex credentials are already exported
+RUN_BILLED_VERTEX_LIVE_TESTS=1 mix test --only live_vertex_ai test/gemini/live/session_vertex_live_test.exs
 ```
 
+If your Vertex project exposes only native-audio Live models, the text-only Vertex session tests will skip instead of failing.
+
 ## Contributing
 
 1. Fork the repository

guides/live_api.md

@@ -102,6 +102,39 @@ For Vertex AI (`auth: :vertex_ai`) connections, `gemini_ex` uses the Vertex Live
 
 This library abstracts the WebSocket connection details. You interact through the `Gemini.Live.Session` module.
 
+### Backend Schema Differences
+
+Gemini Live and Vertex Live use slightly different wire fields for response usage metadata:
+
+- Gemini Live sends `responseTokenCount` and `responseTokensDetails`
+- Vertex Live `v1` sends `candidatesTokenCount` and `candidatesTokensDetails`
+- Vertex Live may also include `turnCompleteReason` on `serverContent`
+
+`gemini_ex` normalizes both backends into the same Live types:
+
+- `Gemini.Types.Live.UsageMetadata.candidates_token_count` and `candidates_tokens_details` are the canonical output-token fields
+- `response_token_count` and `response_tokens_details` are retained as backwards-compatible aliases
+- `Gemini.Types.Live.UsageMetadata.output_token_count/1` and `output_tokens_details/1` return the normalized output view
+- `Gemini.Types.Live.ServerContent.turn_complete_reason` is parsed as a `Gemini.Types.Live.Enums.TurnCompleteReason` value when present
+
+Example callback code that works across both backends:
+
+```elixir
+on_message: fn
+  %{server_content: content, usage_metadata: usage} ->
+    output_tokens = Gemini.Types.Live.UsageMetadata.output_token_count(usage)
+    reason = if content, do: content.turn_complete_reason
+
+    IO.inspect(%{
+      output_tokens: output_tokens,
+      turn_complete_reason: reason
+    })
+
+  _ ->
+    :ok
+end
+```
+
 ### Session Configuration
 
 The initial message after establishing the WebSocket connection sets the session configuration:
@@ -1051,6 +1084,25 @@ Session.close(session)
 
 See `examples/13_live_session_resumption.exs` for a complete example.
 
+## Testing Live Sessions
+
+When your environment variables are already exported, run the Live integration tests directly:
+
+```bash
+# Gemini Live session coverage
+mix test --only live_gemini test/gemini/live/session_live_test.exs
+
+# Gemini Live advanced features
+mix test --only live_gemini test/gemini/live/features_live_test.exs
+
+# Vertex Live coverage (billed; requires explicit opt-in)
+RUN_BILLED_VERTEX_LIVE_TESTS=1 mix test --only live_vertex_ai test/gemini/live/session_vertex_live_test.exs
+```
+
+The default test suite excludes `:live_gemini` and `:live_vertex_ai`, so these targeted commands are the intended manual verification path for real credentials.
+
+If your Vertex project exposes only native-audio Live models, the text-only Vertex session tests will skip instead of failing. This is expected: native-audio-only Vertex models cannot satisfy `response_modalities: ["TEXT"]`.
+
 ## Further Reading
 
 - [Example Files](https://github.com/nshkrdotcom/gemini_ex/tree/main/examples)

lib/gemini/live/models.ex

@@ -22,7 +22,7 @@ defmodule Gemini.Live.Models do
       image: :flash_2_0_exp_image_generation
     },
     vertex_ai: %{
-      text: :flash_2_5_native_audio_preview_12_2025,
+      text: :flash_2_0_live_001,
       audio: :flash_2_5_native_audio_preview_12_2025,
       image: :flash_2_0_preview_image_generation
     }
@@ -52,9 +52,7 @@ defmodule Gemini.Live.Models do
     },
     vertex_ai: %{
       text: [
-        :flash_2_5_native_audio_latest,
-        :flash_2_5_native_audio_preview_12_2025,
-        :flash_2_5_native_audio_preview_09_2025
+        :flash_2_0_live_001
       ],
       audio: [
         :flash_2_5_native_audio_latest,
@@ -111,6 +109,7 @@ defmodule Gemini.Live.Models do
     (registry_candidates ++ legacy_candidates)
     |> Enum.reject(&is_nil/1)
     |> Enum.uniq()
+    |> Enum.filter(&candidate_for_modality?(&1, modality, auth))
   end
 
   @doc """
@@ -205,7 +204,9 @@ defmodule Gemini.Live.Models do
   end
 
   defp live_candidate_for_modality?(model_name, :text, :vertex_ai) do
-    live_like_model_name?(model_name) and not String.contains?(model_name, "tts")
+    live_like_model_name?(model_name) and
+      not String.contains?(model_name, "tts") and
+      not String.contains?(model_name, "native-audio")
   end
 
   defp live_candidate_for_modality?(model_name, :audio, _auth) do
@@ -236,6 +237,12 @@ defmodule Gemini.Live.Models do
 
   defp prioritize_models(models, _modality), do: models
 
+  defp candidate_for_modality?(model_name, modality, auth) do
+    model_name
+    |> normalize_model_name()
+    |> live_candidate_for_modality?(modality, auth)
+  end
+
   defp filter_models_by_method(models, require_method) do
     models
     |> Enum.filter(&supports_method?(&1, require_method))

lib/gemini/rate_limiter/manager.ex

@@ -685,17 +685,25 @@ defmodule Gemini.RateLimiter.Manager do
       Map.has_key?(response, :usage_metadata) ->
         cached_tokens = Map.get(response.usage_metadata, :cached_content_token_count, 0)
 
+        output_tokens =
+          Map.get(response.usage_metadata, :candidates_token_count) ||
+            Map.get(response.usage_metadata, :response_token_count, 0)
+
         %{
           input_tokens: Map.get(response.usage_metadata, :prompt_token_count, 0) + cached_tokens,
-          output_tokens: Map.get(response.usage_metadata, :candidates_token_count, 0)
+          output_tokens: output_tokens
         }
 
       Map.has_key?(response, "usageMetadata") ->
         cached_tokens = Map.get(response["usageMetadata"], "cachedContentTokenCount", 0)
 
+        output_tokens =
+          Map.get(response["usageMetadata"], "candidatesTokenCount") ||
+            Map.get(response["usageMetadata"], "responseTokenCount", 0)
+
         %{
           input_tokens: Map.get(response["usageMetadata"], "promptTokenCount", 0) + cached_tokens,
-          output_tokens: Map.get(response["usageMetadata"], "candidatesTokenCount", 0)
+          output_tokens: output_tokens
         }
 
       true ->

lib/gemini/types/live/enums.ex

@@ -145,4 +145,39 @@ defmodule Gemini.Types.Live.Enums do
     def from_api(nil), do: nil
     def from_api(_), do: :unspecified
   end
+
+  defmodule TurnCompleteReason do
+    @moduledoc """
+    Reasons why a Live API turn completed.
+
+    ## Values
+
+    - `:unspecified` - Unspecified completion reason
+    - `:malformed_function_call` - The model emitted an invalid function call
+    - `:response_rejected` - The response was rejected by the service
+    - `:need_more_input` - The model requires more user input to continue
+    """
+
+    @type t ::
+            :unspecified
+            | :malformed_function_call
+            | :response_rejected
+            | :need_more_input
+            | String.t()
+
+    @spec to_api(t()) :: String.t()
+    def to_api(:unspecified), do: "TURN_COMPLETE_REASON_UNSPECIFIED"
+    def to_api(:malformed_function_call), do: "MALFORMED_FUNCTION_CALL"
+    def to_api(:response_rejected), do: "RESPONSE_REJECTED"
+    def to_api(:need_more_input), do: "NEED_MORE_INPUT"
+    def to_api(value) when is_binary(value), do: value
+
+    @spec from_api(String.t() | nil) :: t() | nil
+    def from_api("TURN_COMPLETE_REASON_UNSPECIFIED"), do: :unspecified
+    def from_api("MALFORMED_FUNCTION_CALL"), do: :malformed_function_call
+    def from_api("RESPONSE_REJECTED"), do: :response_rejected
+    def from_api("NEED_MORE_INPUT"), do: :need_more_input
+    def from_api(nil), do: nil
+    def from_api(value) when is_binary(value), do: value
+  end
 end

lib/gemini/types/live/server_content.ex

@@ -16,6 +16,7 @@ defmodule Gemini.Types.Live.ServerContent do
   - `input_transcription` - Transcription of input audio
   - `output_transcription` - Transcription of model's audio output
   - `url_context_metadata` - Metadata from URL context retrieval
+  - `turn_complete_reason` - Reason why the turn completed on Vertex Live
 
   ## Example
 
@@ -25,6 +26,7 @@ defmodule Gemini.Types.Live.ServerContent do
       }
   """
 
+  alias Gemini.Types.Live.Enums.TurnCompleteReason
   alias Gemini.Types.Live.{GroundingMetadata, Transcription}
 
   @type content :: %{
@@ -44,7 +46,8 @@ defmodule Gemini.Types.Live.ServerContent do
           grounding_metadata: GroundingMetadata.t() | nil,
           input_transcription: Transcription.t() | nil,
           output_transcription: Transcription.t() | nil,
-          url_context_metadata: url_context_metadata() | nil
+          url_context_metadata: url_context_metadata() | nil,
+          turn_complete_reason: TurnCompleteReason.t() | nil
         }
 
   defstruct [
@@ -55,7 +58,8 @@ defmodule Gemini.Types.Live.ServerContent do
     :grounding_metadata,
     :input_transcription,
     :output_transcription,
-    :url_context_metadata
+    :url_context_metadata,
+    :turn_complete_reason
   ]
 
   @doc """
@@ -71,7 +75,8 @@ defmodule Gemini.Types.Live.ServerContent do
       grounding_metadata: Keyword.get(opts, :grounding_metadata),
       input_transcription: Keyword.get(opts, :input_transcription),
       output_transcription: Keyword.get(opts, :output_transcription),
-      url_context_metadata: Keyword.get(opts, :url_context_metadata)
+      url_context_metadata: Keyword.get(opts, :url_context_metadata),
+      turn_complete_reason: Keyword.get(opts, :turn_complete_reason)
     }
   end
 
@@ -91,6 +96,7 @@ defmodule Gemini.Types.Live.ServerContent do
     |> maybe_put("inputTranscription", Transcription.to_api(value.input_transcription))
     |> maybe_put("outputTranscription", Transcription.to_api(value.output_transcription))
     |> maybe_put("urlContextMetadata", convert_url_context_to_api(value.url_context_metadata))
+    |> maybe_put("turnCompleteReason", normalize_turn_complete_reason(value.turn_complete_reason))
   end
 
   @doc """
@@ -115,7 +121,10 @@ defmodule Gemini.Types.Live.ServerContent do
         (data["outputTranscription"] || data["output_transcription"])
         |> Transcription.from_api(),
       url_context_metadata:
-        parse_url_context(data["urlContextMetadata"] || data["url_context_metadata"])
+        parse_url_context(data["urlContextMetadata"] || data["url_context_metadata"]),
+      turn_complete_reason:
+        (data["turnCompleteReason"] || data["turn_complete_reason"])
+        |> TurnCompleteReason.from_api()
     }
   end
 
@@ -197,6 +206,13 @@ defmodule Gemini.Types.Live.ServerContent do
     }
   end
 
+  defp normalize_turn_complete_reason(nil), do: nil
+
+  defp normalize_turn_complete_reason(value) when is_atom(value),
+    do: TurnCompleteReason.to_api(value)
+
+  defp normalize_turn_complete_reason(value), do: value
+
   defp maybe_put(map, _key, nil), do: map
   defp maybe_put(map, key, value), do: Map.put(map, key, value)
 end