Release v0.8.8: Extract shared utilities and remove dead code

Consolidate duplicated helper functions into dedicated utility modules
and remove unused code paths discovered during codebase audit.

New utility modules:

  lib/gemini/utils/map_helpers.ex
    - maybe_put/3: conditionally add to map if value not nil
    - maybe_put_non_empty/3: skip nil and empty strings
    - maybe_put_non_zero/3: skip nil and zero values
    - build_paginated_path/2: construct paths with pagination params
    - add_query_param/3: conditionally add query parameters

  lib/gemini/utils/polling_helpers.ex
    - timed_out?/2: check if polling operation exceeded timeout
    - maybe_add/3: conditionally add to keyword list

Modules updated to use shared utilities:
  - Gemini.APIs.Batches
  - Gemini.APIs.Documents
  - Gemini.APIs.FileSearchStores
  - Gemini.APIs.Files
  - Gemini.APIs.Interactions
  - Gemini.APIs.Operations
  - Gemini.APIs.RagStores
  - Gemini.APIs.Tunings
  - Gemini.APIs.Videos
  - Gemini.Auth.MultiAuthCoordinator
  - Gemini.Config
  - Gemini.RateLimiter.RetryManager
  - Gemini.Types.Generation.Video
  - Gemini.Types.Interactions.* (content, config, delta, events, etc.)
  - Gemini.Types.Request.* (embed content types)
  - Gemini.Types.Schema
  - Gemini.Types.Tuning

Removed dead code:

  Gemini.Auth
    - authenticate/2 and base_url/2 delegators (unused)

  Gemini.Auth.GeminiStrategy
    - authenticate/1 (headers/1 is the actual interface)

  Gemini.Auth.MultiAuthCoordinator
    - Unused struct definition

  Gemini.Client
    - stream_post/2 and stream_post_with_auth/4
    - Streaming moved to HTTPStreaming module

  Gemini.Client.HTTP
    - All SSE streaming functions (parse_sse_stream, handle_stream_*)
    - Module now focused on regular HTTP requests only

  Gemini.Config
    - models/0, use_case_models/0, use_case_token_minima/0
    - model_for_use_case/2, resolved_use_case_models/1

  Gemini.RateLimiter.ConcurrencyGate
    - reset/1 (reset_all/0 sufficient for testing)

  Gemini.RateLimiter.Config
    - adaptive_enabled?/1, profile_config/1

  Gemini.RateLimiter.State
    - would_exceed_budget?/3

  Gemini.Streaming.ToolOrchestrator
    - subscribe/2, stop/1, cleanup_streams/1

Deleted files:
  - lib/gemini/types/interactions/params.ex (unused parameter structs)
  - lib/gemini/types/live.ex (unused Live API types)
  - test/gemini/auth/vertex_strategy_test_old.exs (stale test file)

Test updates:
  - gemini_strategy_test.exs now tests headers/1 interface
  - auth_test.exs uses build_headers/2 instead of authenticate/2
  - Removed tests for deleted would_exceed_budget?/3 function

Author: nshkrdotcom

CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.8] - 2025-12-29
+
+### Added
+- **Paid Tier 3 Rate Limit Profile**: New `:paid_tier_3` profile for maximum throughput workloads
+  - Qualification: >$1,000 total spend + 30 days since payment
+  - Settings: 30 max concurrency, 4M token budget, 100ms backoff, 50 adaptive ceiling
+  - Added corresponding test coverage in `rate_limiter_test.exs`
+
+- **Use-Case Model Aliases**: Implemented `Gemini.Config.model_for_use_case/2` and related functions
+  - `model_for_use_case/2`: Resolve use-case atoms to model strings with optional API validation
+  - `use_case_token_budget/1`: Get recommended token budget for a use-case
+  - `resolved_use_case_models/0`: Get all use-case to model mappings
+  - `available_use_cases/0`: List available use-case aliases
+  - Use cases: `:cache_context` (gemini-2.5-flash), `:report_section` (gemini-2.5-pro), `:fast_path` (gemini-2.5-flash-lite)
+
+- **Shared Utility Modules**: Consolidated duplicated helpers into dedicated modules
+  - `Gemini.Utils.MapHelpers`: `maybe_put/3`, `maybe_put_non_empty/3`, `maybe_put_non_zero/3`, `build_paginated_path/2`, `add_query_param/3`
+  - `Gemini.Utils.PollingHelpers`: `timed_out?/2`, `maybe_add/3`
+
+### Changed
+- **Rate Limit Documentation**: Updated to reflect current Google API tier structure
+  - Added tier qualifications table (Free, Tier 1-3 with spending thresholds)
+  - Documented that rate limits are per-project (not per-API key)
+  - Added note that RPD quotas reset at midnight Pacific time
+  - Added links to AI Studio for viewing actual model-specific limits
+  - Removed hardcoded RPM/TPM values (vary by model)
+
+- **Unified Streaming Architecture**: Removed redundant streaming managers
+  - `UnifiedManager` is now the canonical implementation
+  - Deleted legacy `Manager` and `ManagerV2` modules
+  - Updated examples and tests to use unified architecture
+
+- **Authentication Interface**: Renamed `strategy/1` to `Gemini.Auth.get_strategy/1`
+
+### Removed
+- **Dead Code Cleanup**: Removed unused functions and modules discovered during codebase audit
+  - `Gemini.Auth`: `authenticate/2`, `base_url/2` delegators
+  - `Gemini.Auth.GeminiStrategy`: `authenticate/1` (headers/1 is the actual interface)
+  - `Gemini.Auth.MultiAuthCoordinator`: Unused struct definition
+  - `Gemini.Client`: `stream_post/2`, `stream_post_with_auth/4` (moved to HTTPStreaming)
+  - `Gemini.Client.HTTP`: All SSE streaming functions (module now focused on regular HTTP)
+  - `Gemini.Config`: `models/0`, `use_case_models/0`, `use_case_token_minima/0`
+  - `Gemini.RateLimiter.ConcurrencyGate`: `reset/1`
+  - `Gemini.RateLimiter.Config`: `adaptive_enabled?/1`, `profile_config/1`
+  - `Gemini.RateLimiter.State`: `would_exceed_budget?/3`
+  - `Gemini.Streaming.ToolOrchestrator`: `subscribe/2`, `stop/1`, `cleanup_streams/1`
+
+- **Deleted Files**:
+  - `lib/gemini/types/interactions/params.ex` (unused parameter structs)
+  - `lib/gemini/types/live.ex` (unused Live API types)
+  - `lib/gemini/apis/generate.ex` (migrated to Coordinator)
+  - `lib/gemini/live/session.ex` and `lib/gemini/live/message.ex` (experimental modules)
+  - `test/gemini/auth/vertex_strategy_test_old.exs` (stale test file)
+  - `oldDocs/` directory (obsolete design specifications)
+
+### Technical
+- 13 modules updated to use shared `MapHelpers` and `PollingHelpers` utilities
+- Removed all `__test_` prefixed helper functions from ContextCache, Coordinator, and Videos modules
+- Tests now focus on public module interfaces instead of internal helpers
+- Function extraction and modularization across API modules
+
+### Notes
+- All changes maintain backward compatibility for public API
+- Zero compilation warnings maintained
+- Documentation generates without warnings
+
 ## [0.8.7] - 2025-12-27
 
 ### Changed

docs/guides/rate_limiting.md

@@ -86,20 +86,35 @@ end
 
 ## Quick Start
 
-Choose a profile matching your Google Cloud tier:
+Choose a profile matching your Google Cloud tier. Rate limits are **per-project** (not per-API key)
+and vary by model. View your actual limits in [AI Studio](https://aistudio.google.com/usage?timeRange=last-28-days&tab=rate-limit).
 
-| Profile | Best For | RPM | TPM | Token Budget |
-|---------|----------|-----|-----|--------------|
-| `:free_tier` | Development, testing | 15 | 1M | 32,000 |
-| `:paid_tier_1` | Standard production | 500 | 4M | 1,000,000 |
-| `:paid_tier_2` | High throughput | 1000 | 8M | 2,000,000 |
+### Tier Qualifications
+
+| Tier | Qualification |
+|------|---------------|
+| Free | Users in [eligible countries](https://ai.google.dev/gemini-api/docs/available-regions) |
+| Tier 1 | Billing account [linked to project](https://ai.google.dev/gemini-api/docs/billing#enable-cloud-billing) |
+| Tier 2 | >$250 total spend + 30 days since payment |
+| Tier 3 | >$1,000 total spend + 30 days since payment |
+
+### Profile Settings
+
+| Profile | Best For | Token Budget |
+|---------|----------|--------------|
+| `:free_tier` | Development, testing | 32,000 |
+| `:paid_tier_1` | Standard production | 1,000,000 |
+| `:paid_tier_2` | High throughput | 2,000,000 |
+| `:paid_tier_3` | Maximum throughput | 4,000,000 |
 
 ```elixir
 # Select your tier
 config :gemini_ex, :rate_limiter, profile: :paid_tier_1
 ```
 
-> **Default behavior:** If you don’t choose a profile, `:prod` is used (`token_budget_per_window: 500_000`, `window_duration_ms: 60_000`). The base fallback defaults are 32,000/60s and are used by `:custom` unless overridden. Set `token_budget_per_window: nil` if you need the pre-0.6.1 “unlimited” budgeting behavior.
+> **Default behavior:** If you don't choose a profile, `:prod` is used (`token_budget_per_window: 500_000`, `window_duration_ms: 60_000`). The base fallback defaults are 32,000/60s and are used by `:custom` unless overridden. Set `token_budget_per_window: nil` if you need the pre-0.6.1 "unlimited" budgeting behavior.
+
+> **Note:** Requests per day (RPD) quotas reset at midnight Pacific time.
 
 ## Profiles
 
@@ -110,7 +125,7 @@ appropriate limits for your Google Cloud plan.
 
 #### Free Tier (`:free_tier`)
 
-Conservative settings for Google's free tier (15 RPM / 1M TPM):
+Conservative settings for Google's free tier:
 
 ```elixir
 config :gemini_ex, :rate_limiter, profile: :free_tier
@@ -126,7 +141,7 @@ config :gemini_ex, :rate_limiter, profile: :free_tier
 
 #### Paid Tier 1 (`:paid_tier_1`)
 
-Standard production settings for Tier 1 plans (500 RPM / 4M TPM):
+Standard production settings for Tier 1 (billing account linked):
 
 ```elixir
 config :gemini_ex, :rate_limiter, profile: :paid_tier_1
@@ -142,7 +157,7 @@ config :gemini_ex, :rate_limiter, profile: :paid_tier_1
 
 #### Paid Tier 2 (`:paid_tier_2`)
 
-High throughput settings for Tier 2 plans (1000 RPM / 8M TPM):
+High throughput settings for Tier 2 (>$250 total spend):
 
 ```elixir
 config :gemini_ex, :rate_limiter, profile: :paid_tier_2
@@ -156,6 +171,22 @@ config :gemini_ex, :rate_limiter, profile: :paid_tier_2
 # adaptive_ceiling: 30
 ```
 
+#### Paid Tier 3 (`:paid_tier_3`)
+
+Maximum throughput settings for Tier 3 (>$1,000 total spend):
+
+```elixir
+config :gemini_ex, :rate_limiter, profile: :paid_tier_3
+
+# Equivalent to:
+# max_concurrency_per_model: 30
+# max_attempts: 2
+# base_backoff_ms: 100
+# token_budget_per_window: 4_000_000
+# adaptive_concurrency: true
+# adaptive_ceiling: 50
+```
+
 ### Legacy Profiles
 
 #### Development Profile (`:dev`)
@@ -299,9 +330,10 @@ and is used for proactive budget checking.
 
 Each profile includes a default token budget:
 
-- `:free_tier` - 32,000 tokens per minute (~3% of 1M TPM)
-- `:paid_tier_1` - 1,000,000 tokens per minute (25% of 4M TPM)
-- `:paid_tier_2` - 2,000,000 tokens per minute (25% of 8M TPM)
+- `:free_tier` - 32,000 tokens per minute
+- `:paid_tier_1` - 1,000,000 tokens per minute
+- `:paid_tier_2` - 2,000,000 tokens per minute
+- `:paid_tier_3` - 4,000,000 tokens per minute
 - `:prod` - 500,000 tokens per minute
 - `:dev` - 16,000 tokens per minute
 

lib/gemini/apis/batches.ex

@@ -62,6 +62,9 @@ defmodule Gemini.APIs.Batches do
   alias Gemini.Config
   alias Gemini.Types.{BatchJob, ListBatchJobsResponse}
 
+  import Gemini.Utils.PollingHelpers, only: [timed_out?: 2]
+  import Gemini.Utils.MapHelpers, only: [build_paginated_path: 2]
+
   @type create_opts :: [
           {:display_name, String.t()}
           | {:file_name, String.t()}
@@ -461,32 +464,7 @@ defmodule Gemini.APIs.Batches do
   defp normalize_batch_path("batchPredictionJobs/" <> _ = name), do: name
   defp normalize_batch_path(name), do: "batches/#{name}"
 
-  defp build_list_path(opts) do
-    query_params = []
-
-    query_params =
-      case Keyword.get(opts, :page_size) do
-        nil -> query_params
-        size -> [{"pageSize", size} | query_params]
-      end
-
-    query_params =
-      case Keyword.get(opts, :page_token) do
-        nil -> query_params
-        token -> [{"pageToken", token} | query_params]
-      end
-
-    query_params =
-      case Keyword.get(opts, :filter) do
-        nil -> query_params
-        filter -> [{"filter", filter} | query_params]
-      end
-
-    case query_params do
-      [] -> "batches"
-      params -> "batches?" <> URI.encode_query(params)
-    end
-  end
+  defp build_list_path(opts), do: build_paginated_path("batches", opts)
 
   defp collect_all_batches(opts, acc) do
     case list(opts) do
@@ -527,8 +505,4 @@ defmodule Gemini.APIs.Batches do
 
   defp maybe_report_progress(nil, _batch), do: :ok
   defp maybe_report_progress(callback, batch), do: callback.(batch)
-
-  defp timed_out?(start_time, timeout) do
-    System.monotonic_time(:millisecond) - start_time >= timeout
-  end
 end

lib/gemini/apis/documents.ex

@@ -41,6 +41,9 @@ defmodule Gemini.APIs.Documents do
   alias Gemini.Client.HTTP
   alias Gemini.Types.{Document, ListDocumentsResponse}
 
+  import Gemini.Utils.PollingHelpers, only: [timed_out?: 2]
+  import Gemini.Utils.MapHelpers, only: [build_paginated_path: 2, add_query_param: 3]
+
   @type list_opts :: [
           {:page_size, pos_integer()}
           | {:page_token, String.t()}
@@ -225,16 +228,7 @@ defmodule Gemini.APIs.Documents do
         "ragStores/#{store_name}/documents"
       end
 
-    query_params =
-      []
-      |> maybe_add_param("pageSize", Keyword.get(opts, :page_size))
-      |> maybe_add_param("pageToken", Keyword.get(opts, :page_token))
-      |> maybe_add_param("filter", Keyword.get(opts, :filter))
-
-    case query_params do
-      [] -> base
-      params -> base <> "?" <> URI.encode_query(params)
-    end
+    build_paginated_path(base, opts)
   end
 
   defp collect_all_documents(store_name, opts, acc) do
@@ -261,9 +255,6 @@ defmodule Gemini.APIs.Documents do
     end
   end
 
-  defp maybe_add_param(params, _key, nil), do: params
-  defp maybe_add_param(params, key, value), do: [{key, value} | params]
-
   defp maybe_report_status(nil, _doc), do: :ok
   defp maybe_report_status(callback, doc), do: callback.(doc)
 
@@ -316,10 +307,6 @@ defmodule Gemini.APIs.Documents do
 
   defp handle_document_state(%{state: state}, _name, _opts, _poll, _timeout, _start, _cb),
     do: {:error, {:unknown_state, state}}
-
-  defp timed_out?(start_time, timeout) do
-    System.monotonic_time(:millisecond) - start_time >= timeout
-  end
 end
 
 defmodule Gemini.APIs.RagStores do
@@ -355,6 +342,8 @@ defmodule Gemini.APIs.RagStores do
   alias Gemini.Client.HTTP
   alias Gemini.Types.{ListRagStoresResponse, RagStore}
 
+  import Gemini.Utils.MapHelpers, only: [maybe_put: 3, build_paginated_path: 2]
+
   @type list_opts :: [
           {:page_size, pos_integer()}
           | {:page_token, String.t()}
@@ -500,26 +489,7 @@ defmodule Gemini.APIs.RagStores do
   defp normalize_store_path("ragStores/" <> _ = name), do: name
   defp normalize_store_path(name), do: "ragStores/#{name}"
 
-  defp build_list_path(opts) do
-    query_params = []
-
-    query_params =
-      case Keyword.get(opts, :page_size) do
-        nil -> query_params
-        size -> [{"pageSize", size} | query_params]
-      end
-
-    query_params =
-      case Keyword.get(opts, :page_token) do
-        nil -> query_params
-        token -> [{"pageToken", token} | query_params]
-      end
-
-    case query_params do
-      [] -> "ragStores"
-      params -> "ragStores?" <> URI.encode_query(params)
-    end
-  end
+  defp build_list_path(opts), do: build_paginated_path("ragStores", opts)
 
   defp collect_all_stores(opts, acc) do
     case list(opts) do
@@ -533,7 +503,4 @@ defmodule Gemini.APIs.RagStores do
         {:error, reason}
     end
   end
-
-  defp maybe_put(map, _key, nil), do: map
-  defp maybe_put(map, key, value), do: Map.put(map, key, value)
 end

lib/gemini/apis/file_search_stores.ex

@@ -101,6 +101,9 @@ defmodule Gemini.APIs.FileSearchStores do
     ListFileSearchStoresResponse
   }
 
+  import Gemini.Utils.PollingHelpers, only: [timed_out?: 2]
+  import Gemini.Utils.MapHelpers, only: [build_paginated_path: 2]
+
   @type create_opts :: [
           {:auth, :gemini | :vertex_ai}
         ]
@@ -521,35 +524,7 @@ defmodule Gemini.APIs.FileSearchStores do
     end
   end
 
-  defp build_list_path(opts) do
-    base = "fileSearchStores"
-    query_params = []
-
-    query_params =
-      case Keyword.get(opts, :page_size) do
-        nil -> query_params
-        size -> [{"pageSize", size} | query_params]
-      end
-
-    query_params =
-      case Keyword.get(opts, :page_token) do
-        nil -> query_params
-        token -> [{"pageToken", token} | query_params]
-      end
-
-    case query_params do
-      [] ->
-        base
-
-      params ->
-        query_string =
-          Enum.map_join(params, "&", fn {k, v} ->
-            "#{k}=#{URI.encode_www_form(to_string(v))}"
-          end)
-
-        "#{base}?#{query_string}"
-    end
-  end
+  defp build_list_path(opts), do: build_paginated_path("fileSearchStores", opts)
 
   defp collect_all_stores(opts, acc) do
     case list(opts) do
@@ -647,8 +622,4 @@ defmodule Gemini.APIs.FileSearchStores do
 
   defp maybe_report_status(nil, _resource), do: :ok
   defp maybe_report_status(callback, resource), do: callback.(resource)
-
-  defp timed_out?(start_time, timeout) do
-    System.monotonic_time(:millisecond) - start_time >= timeout
-  end
 end