Release v0.8.4: Comprehensive examples suite and fixes

Release v0.8.3: Interactions API parity with CRUD, streaming, and res…

…umption

Release v0.8.2: Model path normalization, function response contract

fixes, and image config extensions

This release fixes silent model fallback bugs, prevents double endpoint
suffixing, corrects function response serialization to match API
contracts, and extends image configuration for Vertex AI feature parity.

Critical bug fixes:

Model normalization prevents silent fallback when callers pass model
strings containing endpoint suffixes like "gemini-3-pro-image-preview:
generateContent". Previously extract_model_from_path/1 could not parse
paths with multiple colons and fell back to Config.default_model(),
causing requests to hit the default model instead of the user-specified
one. Now normalize_model_option/1 strips endpoint suffixes before path
composition, validates against invalid characters (dotdot, query params),
and preserves fully qualified resource names (models/, tunedModels/,
projects/, publishers/) without double-prefixing.

Path construction robustness improved in extract_model_from_path/1 and
extract_endpoint_from_path/1 by parsing leftmost segment as model and
last segment as endpoint instead of defaulting on ambiguity, eliminating
silent fallbacks that masked configuration errors.

Vertex AI path building now handles fully qualified project paths and
publisher paths correctly, preventing double-prefixing when models
already contain "projects/" or "publishers/" prefixes. VertexStrategy
build_path/3 branches on prefix type to construct proper paths.

Function response serialization corrected by removing "id" field from
to_api/1 output. The Gemini API contract does not accept "id" in
function response payloads (only in function calls), causing
INVALID_ARGUMENT errors when present. Updated to_api/1 now emits only
name, response, willContinue, and scheduling fields.

Streaming URL construction now uses auth-aware path building via
Gemini.Auth.build_path/4 instead of manual string concatenation,
ensuring consistency with non-streaming requests and preventing endpoint
double-suffixing in UnifiedManager.

Feature additions:

Image config extended with Vertex AI specific fields output_mime_type
and output_compression_quality in GenerationConfig.ImageConfig struct.
These fields documented as Vertex-only in Python SDK, now available for
Elixir callers to express JPEG compression quality and output MIME type
preferences. Updated convert_image_config_to_api/1 to serialize these
fields with camelCase keys (outputMimeType, outputCompressionQuality).

Test improvements:

Added CoordinatorModelPathBuildingTest with Bypass mocks verifying that
Gemini API and Vertex AI preserve user-specified models when endpoint
suffixes present, confirming double-suffixing prevention.

Added CoordinatorModelWithEndpointTest reproducing reported issue where
"gemini-3-pro-image-preview:generateContent" fell back to default model,
now fixed by normalization layer.

Added Gemini3ImagePreviewLiveTest as smoke test for image generation,
writes output to gitignored generated/ directory, skips gracefully when
GEMINI_API_KEY not present.

Extended CoordinatorGenerationConfigNewFieldsTest to verify image_config
serialization includes output_mime_type and output_compression_quality
in both keyword and struct forms.

Files live tests now guard with detect_auth() and skip gracefully when
Gemini API credentials not present, since Files API is Gemini-only and
fails under Vertex AI authentication.

Tunings live tests now return skip: true in setup when Vertex AI not
configured, with per-test guards to skip gracefully instead of failing.

System instruction live tests timeout increased to 120_000ms to reduce
flakiness under Vertex rate limiting.

AFC live test assertions improved to report final_response content when
errors occur instead of opaque refute failures.

Infrastructure improvements:

TokenCache.init/0 now serializes table creation with :global.trans to
prevent race conditions when multiple test processes initialize
concurrently, catching ArgumentError when table already exists.

test_helper.exs now calls Gemini.Auth.TokenCache.init() before ExUnit
starts to ensure table exists before async tests run.

Gap analysis documentation added in docs/20251207/gap_analysis_01/
gemini3_image_preview.md analyzing why model suffix handling dropped
caller models and documenting Python SDK parity gaps for model
normalization, request path construction, image config completeness,
and transport-level controls.

All quality gates pass: zero compilation warnings, complete test
coverage for new normalization logic, all existing tests updated to
handle auth detection and graceful skipping, comprehensive regression
coverage for model path building edge cases.

Release v0.8.0: API parity with Python SDK

This major release implements all remaining critical features to match the
Python `google-genai` SDK capabilities, bringing the Elixir client to ~95%
parity.

Key additions:
- **Tunings API**: Full support for supervised model fine-tuning jobs.
- **FileSearchStores**: Semantic search and RAG knowledge base management.
- **Live API**: Real-time bidirectional WebSocket communication (via `:gun`).
- **ADC Support**: Application Default Credentials for seamless GCP auth.
- **Media Generation**: APIs for Image (Imagen) and Video (Veo) generation.

Technical details:
- Added `:gun` dependency for WebSocket support.
- Implemented ETS-based token caching for ADC credentials.
- Updated Vertex strategy to automatically fall back to ADC.
- Added comprehensive types and structs for all new domains.
- Included 200+ new tests and detailed gap analysis documentation.
- Added new guides for Tunings, Live API, ADC, and Media Generation.

Release v0.7.3: System instructions, complete function calling framew…

…ork, and comprehensive gap analysis

This release adds critical function calling infrastructure, system
instruction support, and comprehensive gap analysis documentation
comparing the Elixir implementation to the Python genai SDK.

Major additions:

System instruction support allows persistent system prompts that guide
model behavior across conversations. Accepts multiple formats: string,
Content struct, or map with parts. More token-efficient than inline
instructions in conversation history.

Complete function calling framework with three new modules:
Gemini.Types.Schema provides JSON Schema definitions for function
parameters, supporting all standard types with enum, format, minimum,
maximum, pattern constraints, nested schemas, and API format conversion.

Gemini.Tools.Executor executes function calls from Gemini responses
against function registries, providing sequential and parallel execution
with automatic response building and comprehensive error handling.

Gemini.Tools.AutomaticFunctionCalling implements the complete AFC loop
for autonomous multi-step execution with configurable max_calls,
ignore_call_history, parallel_execution options, call history tracking,
and automatic execute-and-continue cycles.

Coordinator helpers: extract_function_calls/1 and has_function_calls?/1
convenience functions for detecting and extracting function calls from
responses.

Documentation:

New guides: function_calling.md covers complete function calling usage
with examples, patterns, and best practices. system_instructions.md
covers system instruction usage, formats, and integration with other
features.

Comprehensive gap analysis in docs/20251206/gap_analysis/ comparing
Python genai SDK v1.53.0 to Elixir gemini_ex implementation based on
21 parallel subagent deep-dive reports.

Gap analysis includes: executive summary with severity classifications,
critical gaps document analyzing 8 blocking features (Live API, tools,
AFC, system instruction, model tuning, grounding, code execution, image
generation), feature parity matrix with 55% current coverage score,
implementation priorities with tiered roadmap, and detailed TDD-based
implementation prompt.

Quantitative findings show Python SDK has 18,205 lines in types alone
versus approximately 3,000 in Elixir (16% coverage), 12 API modules
versus 7 (58% coverage), 200+ type definitions versus approximately 50
(25% coverage), with overall parity at 55%.

Critical gaps identified: Live/Real-time API (WebSocket) not
implemented, tools/function calling types only without execution (now
addressed in 0.7.3), automatic function calling not implemented (now
addressed), system instruction missing from request building (now
addressed), model tuning API not implemented, grounding/retrieval not
implemented.

Recommended priority actions: system instruction (2-4 hours, now
complete), function calling types (1 week, now complete), function
execution (1 week, now complete), automatic FC loop (1 week, now
complete), Live API (3 weeks, future work).

Technical implementation:

System instruction added to GenerateContentRequest with
format_system_instruction helper supporting string, Content struct, and
map formats. Properly serialized to systemInstruction key in API
requests with camelCase formatting.

Schema type provides complete JSON Schema implementation with helper
functions for string, integer, number, boolean, array, object types.
Converts to Gemini API format with UPPERCASE type names and camelCase
field names via to_api_map/1 and from_api_map/1.

Executor module provides execute/2 for single call execution,
execute_all/2 for sequential batch execution, execute_all_parallel/3
for concurrent execution of I/O-bound functions, build_responses/2 for
automatic FunctionResponse building, and create_registry/1 helper for
registry creation from keyword lists or maps.

AutomaticFunctionCalling module implements config/1 for AFC
configuration, extract_function_calls/1 for call extraction from
responses, has_function_calls?/1 for detection, should_continue?/3 for
loop control, build_function_response_content/2 for API format
responses, track_history/2 for call tracking, and loop/8 for complete
AFC execution with generate function callback.

Test coverage:

Unit tests for all new modules: CoordinatorSystemInstructionTest,
SchemaTest, ExecutorTest, AutomaticFunctionCallingTest with
comprehensive test coverage for all public functions.

Live API tests: SystemInstructionLiveTest verifies behavior changes,
format enforcement, persona consistency, JSON output, and tool
integration. FunctionCallingLiveTest verifies function call generation,
multi-turn conversations, AFC loop execution, multiple tool selection,
and error handling.

Documentation updates:

README.md updated to version 0.7.3 with new features listed.
CHANGELOG.md updated with complete 0.7.3 entry including gap analysis
summary, system instruction support, function calling framework, and
implementation roadmap.

mix.exs updated to include new guides in extras and groups_for_extras,
added docs/guides to package files for Hex distribution.

Gap analysis documents added to repository structure with navigation
index, executive summary, critical gaps analysis, feature parity
matrix, and implementation priorities.

All quality gates pass: zero compilation warnings, complete @SPEC
annotations, comprehensive test coverage, follows CODE_QUALITY.md
standards throughout.

Release v0.7.2: ETS-based locking fixes for rate limiter race conditions

Release v0.7.1: Atomic budget reservations, jittered retry windows, a…

…nd streaming rate limiter integration

Release v0.7.0: Complete API Parity with Files, Batches, Operations, …

…and Documents APIs

Release v0.6.4: Comprehensive response and request type enhancements

Added complete support for token usage breakdown by modality. UsageMetadata now
includes thoughts_token_count for thinking models, tool_use_prompt_token_count
for function calling overhead, and per-modality token details fields for prompt,
cache, response, and tool use tokens. Traffic type field added to distinguish
between on-demand and provisioned throughput billing.

GenerateContentResponse gains response_id for tracking, model_version to show
actual model used, and create_time timestamp. Candidate includes finish_message
for human-readable completion explanations and avg_logprobs for confidence
scoring. PromptFeedback adds block_reason_message for clearer blocking context.

Part type expanded with file_data for URI-based file references, function_response
for tool result handling, and thought boolean flag for thinking model output
identification. SafetyRating enhanced with probability_score, severity, and
severity_score numeric fields for finer-grained safety analysis.

GenerationConfig adds seed for deterministic generation, response_modalities to
control output types (text, image, audio), speech_config for audio synthesis
with voice selection, and media_resolution to optimize multimodal input token
usage. Complete speech configuration stack implemented with SpeechConfig,
VoiceConfig, and PrebuiltVoiceConfig supporting single and multi-speaker setups.

Created new types: ModalityTokenCount for per-modality breakdowns, TrafficType
enum for billing classification, FileData for file URI references, FunctionResponse
for tool results, Modality enum for output types, MediaResolution enum for input
optimization. All types include bidirectional API conversion with proper camelCase
handling.

Response parsing updated to handle all new fields from API payloads. Coordinator
properly serializes new GenerationConfig fields. All changes maintain backward
compatibility with nil defaults. Comprehensive test coverage added for new types
and conversions.