Releae v0.11.0: add Gemini 3.1 model support and comprehensive Files API features

- Add `gemini-3.1-flash-lite-preview` and `gemini-3.1-flash-image-preview`
  entries to the model registry.
- Implement generic `Gemini.predict/3` and `predict_long_running/3` endpoints
  for advanced model interactions (Imagen/Veo).
- Add `thinking` boolean to `Gemini.Types.Response.Model` and `supports_thinking?/1`
  helper to identify reasoning capabilities.
- Enhance `generateContent` response parsing with `candidates_tokens_details`,
  `grounding_metadata`, `logprobs_result`, and `url_context_metadata`.
- Add structured parsing for `CitationMetadata` and `CitationSource`.
- Implement `MultiSpeakerVoiceConfig` for advanced text-to-speech workflows.
- Add `enable_enhanced_civic_answers` to `GenerationConfig`.
- Enforce Gemini-only auth for Files API; add `api_key` override support.
- Remove `mimeType` from file upload metadata (output-only field fix).
- Deprecate `gemini-3-pro-preview` in favor of `gemini-3.1-pro-preview`.

Author: nshkrdotcom

CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-03-05
+
+### Added
+
+#### New Model Registry Entries
+- `gemini-3.1-flash-lite-preview` — Gemini 3.1 Flash-Lite Preview, frontier-class performance rivaling larger models at a fraction of the cost
+- `gemini-3.1-flash-image-preview` — Nano Banana 2, high-efficiency image generation and editing optimized for speed and high-volume use cases
+
+#### Config Model Registry
+- `flash_3_1_lite_preview` and `flash_3_1_image_preview` keys added to universal models in `Gemini.Config`
+
+#### Models API: `thinking` field
+- **`thinking` boolean field** added to `Gemini.Types.Response.Model` — reflects whether the model supports thinking/reasoning as returned by the API
+- **`Model.supports_thinking?/1`** helper function for querying thinking capability
+- `thinking` included in `Model.capabilities_summary/1` output
+- Parsed from API responses in both `Gemini.APIs.Models` and `Gemini.APIs.Coordinator`
+
+#### generateContent/streamGenerateContent API completeness
+- **`candidates_tokens_details`** field added to `UsageMetadata` — parses `candidatesTokensDetails` modality token counts from API responses
+- **`grounding_metadata`** field added to `Candidate` — stores `groundingMetadata` (grounding chunks, supports, web search queries) from API responses
+- **`logprobs_result`** field added to `Candidate` — stores `logprobsResult` log probability data from API responses
+- **`url_context_metadata`** field added to `Candidate` — stores `urlContextMetadata` from API responses
+- **`CitationMetadata.from_api/1`** and **`CitationSource.from_api/1`** — proper structured parsing of citation data (previously stored as raw maps)
+- **`safety_settings`** wired into `build_generate_request` — pass `safety_settings: [SafetySetting.harassment(:block_none)]` to set per-request safety thresholds
+- **`enable_enhanced_civic_answers`** field added to `GenerationConfig` and supported in `put_generation_opt`
+- **`MultiSpeakerVoiceConfig`** and **`SpeakerVoiceConfig`** types added with `from_api/1` and `to_api/1`
+- **`multi_speaker_voice_config`** field added to `SpeechConfig` for multi-speaker voice synthesis
+
+#### Models API: `predict` and `predictLongRunning` endpoints
+- **`Gemini.predict/3`** — generic `models.predict` endpoint (`POST /v1beta/{model=models/*}:predict`) for direct prediction requests
+- **`Gemini.predict_long_running/3`** — `models.predictLongRunning` endpoint (`POST /v1beta/{model=models/*}:predictLongRunning`) returning an Operation for async processing
+- Both endpoints support Vertex AI (`projects/.../publishers/google/models/...:predict`) and Gemini API paths
+- For most use cases, prefer the higher-level `Gemini.APIs.Images` or `Gemini.APIs.Videos` modules which use these endpoints internally
+
+### Changed
+- **Gemini 3 Pro deprecation**: `gemini-3-pro-preview` track changed from `:preview` to `:deprecated` — Google is discontinuing the model on March 9, 2026; migrate to `gemini-3.1-pro-preview`
+
 ## [0.10.0] - 2026-02-22
 
 ### Added
@@ -1998,7 +2035,8 @@ config :gemini_ex,
 - Minimal latency overhead
 - Concurrent request processing
 
-[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.10.0...HEAD
+[Unreleased]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.11.0...HEAD
+[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
 [0.9.0]: https://github.com/nshkrdotcom/gemini_ex/compare/v0.8.8...v0.9.0

README.md

@@ -29,7 +29,7 @@ A comprehensive Elixir client for Google's Gemini AI API with dual authenticatio
 - **Batches API**: Submit large numbers of requests with 50% cost savings (NEW in v0.7.0!)
 - **Operations API**: Track long-running operations like video generation (NEW in v0.7.0!)
 - **Tunings (Fine-Tuning)**: Create, monitor, and manage tuned models (NEW in v0.8.x!)
-- **Model Registry**: Centralized model capabilities, modality tracking, and registry-backed Live API model resolution (NEW in v0.10.0!)
+- **Model Registry**: Centralized model capabilities, modality tracking, and registry-backed Live API model resolution (Enhanced in v0.11.0!)
 - **Image & Video Generation**: Imagen/Veo APIs for text-to-image, editing, upscaling, and video generation with Veo 3.1 support
 - **Embeddings with MRL**: Text embeddings with Matryoshka Representation Learning, normalization, and distance metrics
 - **Async Batch Embeddings**: Production-scale embedding generation with 50% cost savings
@@ -59,7 +59,7 @@ Add `gemini` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:gemini_ex, "~> 0.10.0"}
+    {:gemini_ex, "~> 0.11.0"}
   ]
 end
 ```
@@ -431,7 +431,7 @@ alias Gemini.Types.Content
 - `gemini-2.5-pro`
 - `gemini-2.0-flash-001`
 - `gemini-2.0-flash-lite-001`
-- `gemini-3-pro-preview`
+- `gemini-3.1-pro-preview`
 - `gemini-3-flash-preview`
 
 You can list, get, update TTL, and delete caches via the top-level `Gemini.*cache*` helpers or `Gemini.APIs.ContextCache.*`. Vertex AI names are auto-expanded when `auth: :vertex_ai` or configured credentials are present.
@@ -442,25 +442,24 @@ Upload and manage files for use with Gemini models. Perfect for multimodal conte
 
 ```elixir
 alias Gemini.APIs.Files
-alias Gemini.Types.File
 
-# Upload a file
-{:ok, file} = Files.upload("path/to/image.png")
+# Upload a file (Gemini Developer API only)
+{:ok, file} = Files.upload("path/to/image.png", auth: :gemini)
 
-# Wait for processing (videos/large files)
-{:ok, ready} = Files.wait_for_processing(file.name)
+# Use the File struct directly in content generation
+{:ok, response} = Gemini.generate([file, "What's in this image?"])
 
-# Use in content generation
-{:ok, response} = Gemini.generate([
-  "What's in this image?",
-  %{file_uri: ready.uri, mime_type: ready.mime_type}
-])
+# Wait for processing only when the file is still processing
+{:ok, video} = Files.upload("path/to/video.mp4", auth: :gemini)
+{:ok, ready_video} = Files.wait_for_processing(video.name, auth: :gemini)
+{:ok, video_response} = Gemini.generate([ready_video, "Describe this video clip"])
 
 # List all files
-{:ok, files} = Files.list_all()
+{:ok, files} = Files.list_all(auth: :gemini)
 
 # Clean up
-:ok = Files.delete(file.name)
+:ok = Files.delete(file.name, auth: :gemini)
+:ok = Files.delete(video.name, auth: :gemini)
 ```
 
 **Key Features:**
@@ -469,6 +468,8 @@ alias Gemini.Types.File
 - Automatic MIME type detection
 - 48-hour file expiration
 
+**Note:** The Files API is available only on the Gemini Developer API. It is not supported on Vertex AI.
+
 See [Files API Guide](guides/files.md) for complete documentation.
 
 ## File Search Stores (New in v0.8.x!)
@@ -631,18 +632,14 @@ Register existing GCS files with the Gemini API without uploading. Ideal for lar
 ```elixir
 alias Gemini.APIs.Files
 
-# GCS credentials with read access to the bucket
-credentials = %{
-  "type" => "service_account",
-  "client_email" => "...",
-  "private_key" => "...",
-  # ... other service account fields
-}
+# Fetch an OAuth token with read access to the bucket
+{:ok, token} = Goth.fetch(MyApp.Goth)
 
 # Register GCS files
 {:ok, response} = Files.register_files(
   ["gs://my-bucket/documents/report.pdf", "gs://my-bucket/images/photo.jpg"],
-  credentials: credentials
+  credentials: %{token: token.token},
+  auth: :gemini
 )
 
 # Use registered files in generation
@@ -652,12 +649,12 @@ end)
 
 file = hd(response.files)
 {:ok, response} = Gemini.generate([
-  "Summarize this document",
-  %{file_uri: file.uri, mime_type: file.mime_type}
+  file,
+  "Summarize this document"
 ])
 ```
 
-**Note:** This feature is only available in the Gemini Developer API, not Vertex AI. The credentials must have read access to the GCS bucket.
+**Note:** This feature is only available in the Gemini Developer API, not Vertex AI. Pass either `%{token: "..."}` or a `Goth.Token`-style struct, and ensure the token can read the referenced GCS objects.
 
 ## Model Armor (Vertex AI only)
 
@@ -1510,7 +1507,7 @@ config :gemini_ex,
 Or specify per-request:
 
 ```elixir
-Gemini.generate("Hello", model: "gemini-3-pro-preview")
+Gemini.generate("Hello", model: "gemini-3.1-pro-preview")
 Gemini.embed_content("Text", model: "gemini-embedding-001")
 ```
 
@@ -1622,7 +1619,7 @@ All generation config options are fully supported across all API entry points:
 - `gemini-flash-lite-latest` (default; fastest + most cost-efficient)
 - `gemini-2.5-flash` (balanced price/performance for high-volume workloads)
 - `gemini-3-flash-preview` (fast Gemini 3 with full thinking levels + built-in tools)
-- `gemini-3-pro-preview` (most capable multimodal reasoning)
+- `gemini-3.1-pro-preview` (most capable multimodal reasoning and agentic coding)
 
 ### Multimodal Content (New in v0.2.2!)
 

examples/15_files_api.exs

@@ -0,0 +1,139 @@
+# Files API Example
+# Run with: mix run examples/15_files_api.exs
+#
+# Demonstrates:
+# - Uploading a file with the Gemini Files API
+# - Using the File struct directly in generation
+# - Getting metadata and listing files
+# - Cleaning up uploaded files
+
+defmodule FilesAPIExample do
+  alias Gemini.APIs.Files
+
+  @fixture_path Path.expand("../test/fixtures/test_document.txt", __DIR__)
+
+  def run do
+    print_header("FILES API")
+
+    if gemini_api_key_available?() do
+      demo_files_api()
+      print_footer()
+    else
+      IO.puts("[SKIP] Files API examples require GEMINI_API_KEY.")
+      IO.puts("[SKIP] Vertex AI credentials are not enough for Gemini Files uploads.")
+      IO.puts("")
+    end
+  end
+
+  defp demo_files_api do
+    print_section("1. Upload, Generate, Inspect, Delete")
+
+    uploaded_file =
+      case Files.upload(@fixture_path, auth: :gemini) do
+        {:ok, file} ->
+          IO.puts("UPLOADED:")
+          IO.puts("  name: #{file.name}")
+          IO.puts("  mime_type: #{file.mime_type}")
+          IO.puts("")
+          file
+
+        {:error, error} ->
+          IO.puts("[ERROR] Upload failed: #{inspect(error)}")
+          System.halt(1)
+      end
+
+    try do
+      demo_generate(uploaded_file)
+      demo_get(uploaded_file)
+      demo_list(uploaded_file)
+    after
+      case Files.delete(uploaded_file.name, auth: :gemini) do
+        :ok ->
+          IO.puts("CLEANUP:")
+          IO.puts("  deleted #{uploaded_file.name}")
+          IO.puts("")
+
+        {:error, error} ->
+          IO.puts("[ERROR] Cleanup failed: #{inspect(error)}")
+          IO.puts("")
+      end
+    end
+  end
+
+  defp demo_generate(file) do
+    IO.puts("GENERATE:")
+
+    case Gemini.generate([file, "\n\n", "Summarize this file in one sentence."]) do
+      {:ok, response} ->
+        {:ok, text} = Gemini.extract_text(response)
+        IO.puts("  #{text}")
+        IO.puts("")
+
+      {:error, error} ->
+        IO.puts("  [ERROR] #{inspect(error)}")
+        IO.puts("")
+    end
+  end
+
+  defp demo_get(file) do
+    IO.puts("GET:")
+
+    case Files.get(file.name, auth: :gemini) do
+      {:ok, fetched} ->
+        IO.puts("  state: #{inspect(fetched.state)}")
+        IO.puts("  uri: #{fetched.uri}")
+        IO.puts("")
+
+      {:error, error} ->
+        IO.puts("  [ERROR] #{inspect(error)}")
+        IO.puts("")
+    end
+  end
+
+  defp demo_list(file) do
+    IO.puts("LIST:")
+
+    case Files.list(page_size: 5, auth: :gemini) do
+      {:ok, page} ->
+        present? = Enum.any?(page.files, &(&1.name == file.name))
+        IO.puts("  returned #{length(page.files)} files")
+        IO.puts("  uploaded file present?: #{present?}")
+        IO.puts("")
+
+      {:error, error} ->
+        IO.puts("  [ERROR] #{inspect(error)}")
+        IO.puts("")
+    end
+  end
+
+  defp gemini_api_key_available? do
+    case System.get_env("GEMINI_API_KEY") do
+      value when is_binary(value) and value != "" -> true
+      _ -> false
+    end
+  end
+
+  defp print_header(title) do
+    IO.puts("")
+    IO.puts(String.duplicate("=", 70))
+    IO.puts("  #{title}")
+    IO.puts(String.duplicate("=", 70))
+    IO.puts("")
+  end
+
+  defp print_section(title) do
+    IO.puts(String.duplicate("-", 70))
+    IO.puts(title)
+    IO.puts(String.duplicate("-", 70))
+    IO.puts("")
+  end
+
+  defp print_footer do
+    IO.puts(String.duplicate("=", 70))
+    IO.puts("  EXAMPLE COMPLETE")
+    IO.puts(String.duplicate("=", 70))
+    IO.puts("")
+  end
+end
+
+FilesAPIExample.run()

examples/README.md

@@ -50,9 +50,10 @@ mix run examples/01_basic_generation.exs
 | 09 | `09_safety_settings.exs` | Content safety filters, harm categories, thresholds |
 | 10 | `10_system_instructions.exs` | Persona setup, formatting rules, domain experts |
 | 11 | `11_live_text_chat.exs` | Live API multi-turn text conversations |
-| 12 | `12_live_audio_streaming.exs` | Live API audio input/output streaming |
-| 13 | `13_live_session_resumption.exs` | Session resume across disconnections |
-| 14 | `14_live_function_calling.exs` | Tool/function calling with telemetry |
+| 12 | `12_live_audio_streaming.exs` | Live API audio input/output streaming |
+| 13 | `13_live_session_resumption.exs` | Session resume across disconnections |
+| 14 | `14_live_function_calling.exs` | Tool/function calling with telemetry |
+| 15 | `15_files_api.exs` | Gemini Files upload/get/list/delete workflow with generation |
 
 ## Example Details
 
@@ -190,8 +191,8 @@ SafetySetting.permissive()  # Block only high risk
 Gemini.generate(prompt, safety_settings: safety_settings)
 ```
 
-### 10 - System Instructions
-Control model behavior and persona:
+### 10 - System Instructions
+Control model behavior and persona:
 - Create custom personas
 - Enforce response formatting
 - Define domain expertise
@@ -204,10 +205,22 @@ You are a helpful coding assistant. Always:
 - Suggest best practices
 """
 
-Gemini.generate(prompt, system_instruction: system_instruction)
-```
-
-## Output Format
+Gemini.generate(prompt, system_instruction: system_instruction)
+```
+
+### 15 - Files API
+Upload a file with Gemini, use the returned `Gemini.Types.File` directly in generation, inspect it, and delete it:
+
+```elixir
+{:ok, file} = Gemini.APIs.Files.upload("test/fixtures/test_document.txt", auth: :gemini)
+{:ok, response} = Gemini.generate([file, "Summarize this file in one sentence."])
+{:ok, fetched} = Gemini.APIs.Files.get(file.name, auth: :gemini)
+:ok = Gemini.APIs.Files.delete(file.name, auth: :gemini)
+```
+
+This example skips itself unless `GEMINI_API_KEY` is present, because the Files API is Gemini-only.
+
+## Output Format
 
 All examples follow a consistent output format:
 - Clear section headers with `===` or `---`

guides/file_search_stores.md

@@ -189,8 +189,8 @@ Stores are created asynchronously. Always wait for activation before adding docu
 If you've already uploaded a file using the Files API:
 
 ```elixir
-# Upload a file first
-{:ok, file} = Gemini.upload_file("/path/to/document.pdf")
+# Upload a file first with the Gemini Files API
+{:ok, file} = Gemini.APIs.Files.upload("/path/to/document.pdf", auth: :gemini)
 
 # Import it into the store
 {:ok, doc} = FileSearchStores.import_file(
@@ -200,7 +200,7 @@ If you've already uploaded a file using the Files API:
 )
 
 # Wait for processing
-{:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name)
+{:ok, ready_doc} = FileSearchStores.wait_for_document(doc.name, auth: :vertex_ai)
 IO.puts("Document ready with #{ready_doc.chunk_count} chunks")
 ```