Gemini Wrappers API

Purpose

This page documents the Gemini provider wrapper module used by Jeni.

Responsibilities

The Gemini wrapper module is responsible for provider-facing workflows, including text generation, image generation and analysis, image editing, embeddings, audio transcription, audio translation, text-to-speech, Gemini Files API operations, file-search stores, and Google Cloud bucket workflows.

Import Requirements

This API page imports gemini.py. Build the documentation from the repository root after installing both application and documentation dependencies:

pip install -r requirements.txt
pip install -r requirements-docs.txt
mkdocs build --strict

API Reference

gemini

Gemini provider wrappers for the Jeni Streamlit application.

Purpose

Provides application-facing wrapper classes for Gemini text generation, image generation and analysis, embeddings, transcription, translation, text-to-speech, Gemini file operations, file-search stores, and Google Cloud Storage bucket workflows.

The module centralizes provider request construction, option lists, response extraction, and error logging so the Streamlit application can call stable Python interfaces instead of provider-specific SDK objects directly.

Classes:

Name	Description
Gemini	Shared base class for Gemini wrapper configuration and runtime state.
Chat	Text-generation wrapper for Gemini chat and grounding workflows.
Images	Image generation, analysis, and editing wrapper.
Embeddings	Text embedding wrapper.
TTS	Text-to-speech wrapper.
Transcription	Audio transcription wrapper.
Translation	Audio translation wrapper.
Files	Gemini file and document workflow wrapper.
FileSearch	Gemini file-search store wrapper.
CloudBuckets	Google Cloud Storage bucket wrapper.

Copyright

Copyright © 2026 Terry Eppler.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, subject to inclusion of the copyright notice and permission notice in substantial portions of the software.

Contact

Terry Eppler, terryeppler@gmail.com or eppler.terry@epa.gov.

Gemini

Shared configuration state for Gemini provider wrappers.

Purpose

Initializes the API credentials, model parameters, generation settings, response configuration, and tool selections shared by the specialized Gemini wrapper classes. The base class performs no provider requests and contains no workflow-specific processing.

Attributes:

Name	Type	Description
google_api_key	Optional[str]	Google API key loaded from application configuration.
gemini_api_key	Optional[str]	Gemini API key loaded from application configuration.
model	Optional[str]	Active Gemini model identifier.
api_version	Optional[str]	API version selected by a specialized wrapper.
temperature	Optional[float]	Sampling temperature.
top_p	Optional[float]	Top-p sampling value.
top_k	Optional[int]	Top-k sampling value.
candidate_count	Optional[int]	Requested candidate count.
frequency_penalty	Optional[float]	Frequency-penalty value.
presence_penalty	Optional[float]	Presence-penalty value.
max_tokens	Optional[int]	Maximum output-token count.
instructions	Optional[str]	System instruction text.
prompt	Optional[str]	Active user prompt.
response_format	Optional[str]	Requested response format.
number	Optional[int]	Requested number of generated results.
response_modalities	List[str]	Requested response modalities.
stops	List[str]	Stop sequences.
domains	List[str]	Domain restrictions used by supported search workflows.
tools	List[str]	Selected provider tools.
tool_choice	Optional[str]	Tool-selection behavior.
content_response	Optional[GenerateContentResponse]	Latest content response.
image_response	Optional[GenerateImagesResponse]	Latest image-generation response.
content_config	Optional[GenerateContentConfig]	Content-generation configuration.
function_config	Optional[FunctionCallingConfig]	Function-calling configuration.
thought_config	Optional[ThinkingConfig]	Thinking configuration.
genimg_config	Optional[GenerateImagesConfig]	Image-generation configuration.
image_config	Optional[ImageConfig]	Image-output configuration.
tool_config	Optional[List[Tool]]	Provider tool configuration.

Chat

Bases: Gemini

Gemini text-generation wrapper.

Purpose

Executes text-generation, grounding, structured-output, streaming, URL Context, File Search, Google Search, Google Maps, and Code Execution workflows through the Gemini Interactions API. The class preserves the application-facing contract used by Jeni while maintaining conversation history through the existing client-managed application state.

Attributes:

Name	Type	Description
use_vertex	bool	Whether Vertex AI configuration is enabled.
http_options	HttpOptions	Gemini client HTTP configuration.
client	Optional[Client]	Gemini SDK client.
storage_client	Optional[Client]	Optional Google Cloud Storage client.
contents	Optional[List[Dict[str, Any]]]	Complete Interactions input timeline.
input_steps	List[Dict[str, Any]]	Interactions input steps submitted to Gemini.
image_uri	Optional[str]	Optional image URI retained for interface compatibility.
audio_uri	Optional[str]	Optional audio URI retained for interface compatibility.
file_path	Optional[str]	Optional local file path retained for compatibility.
files	List[str]	File identifiers retained for interface compatibility.
content_block	str	Additional content prepended to the active prompt.
context	List[Dict[str, Any]]	Existing application-managed conversation history.
urls	List[str]	URL-context values.
max_urls	int	Maximum URL values included in the prompt.
response_schema	Optional[Dict[str, Any]]	Parsed structured-output schema.
safety_profile	str	Safety-profile value retained for UI compatibility.
safety_settings	Optional[List[SafetySetting]]	Optional Gemini safety settings.
file_search_store_names	List[str]	File Search Store resource names.
interaction	Optional[Any]	Most recent Gemini Interaction.
interaction_id	Optional[str]	Identifier of the most recent Interaction.
steps	List[Any]	Steps returned by the most recent Interaction.
response	Optional[Any]	Raw response used by application token accounting.
output_text	str	Generated response text.
grounding_sources	List[Dict[str, Any]]	Normalized grounding citations.
generation_config	Dict[str, Any]	Interactions generation configuration.
interaction_response_format	Optional[Any]	Interactions response-format value.
tool_objects	List[Dict[str, Any]]	Interactions server-side tool definitions.
stream	bool	Whether streaming is enabled.
stream_handler	Optional[Callable[[str], None]]	Text-delta callback.

model_options property

Return supported Gemini text-generation models.

Purpose

Provides the text-generation model identifiers exposed by the Jeni Text, Document Q&A, File Search Stores, and Google Cloud Buckets interfaces.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini text-generation model identifiers.

tool_options property

Return supported Interactions server-side tools.

Purpose

Provides the server-side tools exposed by the Jeni Text interface.

Returns:

Type	Description
List[str]	List[str]: Supported Interactions tool identifiers.

reasoning_options property

Return supported thinking levels.

Purpose

Provides the thinking-level values exposed by the Jeni model controls.

Returns:

Type	Description
List[str]	List[str]: Supported thinking-level values.

media_options property

Return supported media-resolution values.

Purpose

Preserves the media-resolution option contract used by the Jeni interface.

Returns:

Type	Description
List[str]	List[str]: Supported media-resolution values.

choice_options property

Return supported tool-choice values.

Purpose

Provides the tool-selection values accepted by the Interactions API.

Returns:

Type	Description
List[str]	List[str]: Supported tool-choice values.

include_options property

Return compatibility include options.

Purpose

Preserves the option values consumed by existing Jeni controls while citations and tool execution are retrieved from typed Interaction steps.

Returns:

Type	Description
List[str]	List[str]: Existing Jeni include-option values.

modality_options property

Return supported response modalities.

Purpose

Provides response-modality values used by the Jeni Text interface.

Returns:

Type	Description
List[str]	List[str]: Supported response modalities.

format_options property

Return supported text response MIME types.

Purpose

Provides text and structured-output MIME types used by the Text interface.

Returns:

Type	Description
List[str]	List[str]: Supported response MIME types.

get_supported_tools

Return tools supported by the selected model.

Purpose

Builds the tool list consumed by the Jeni Text controls and conditionally includes Google Maps for models that expose that capability.

Parameters:

Name	Type	Description	Default
model	str	Gemini model identifier.	required

Returns:

Type	Description
List[str]	List[str]: Tool identifiers supported by the selected model.

Raises:

Type	Description
Error	Raised when validation or tool-list construction fails.
ValueError	Raised when model is missing.

supports_google_maps

Return whether a model supports Google Maps grounding.

Purpose

Centralizes Google Maps feature gating for the Jeni Text controls.

Parameters:

Name	Type	Description	Default
model	str	Gemini model identifier.	required

Returns:

Name	Type	Description
bool	bool	True when Google Maps may be exposed; otherwise False.

Raises:

Type	Description
Error	Raised when validation or model comparison fails.
ValueError	Raised when model is missing.

normalize_value

Convert an SDK value into standard Python data.

Purpose

Recursively converts SDK response models, dictionaries, and sequences into ordinary Python values used by history and citation processing.

Parameters:

Name	Type	Description	Default
value	Any	SDK or Python value to normalize.	required

Returns:

Name	Type	Description
Any	Any	Equivalent standard Python value.

Raises:

Type	Description
Error	Raised when value normalization fails.

normalize_context

Convert application history into Interactions steps.

Purpose

Preserves existing Interactions steps and converts Jeni role/content dictionaries into user_input and model_output steps for stateless conversation history.

Parameters:

Name	Type	Description	Default
context	Optional[List[Dict[str, Any]]]	Existing conversation history.	None

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Interactions-compatible history steps.

Raises:

Type	Description
Error	Raised when conversation history cannot be normalized.

build_urls

Build the normalized URL list.

Purpose

Removes blank and duplicate URL values while preserving order and applies the configured maximum before URL values are supplied to the active request.

Parameters:

Name	Type	Description	Default
urls	Optional[List[str]]	Candidate URL values.	None
max_urls	int	Maximum URLs to retain; zero retains all values.	0

Returns:

Type	Description
List[str]	List[str]: Normalized URL values.

Raises:

Type	Description
Error	Raised when URL normalization fails.

build_input

Build the complete Interactions input timeline.

Purpose

Combines existing client-managed conversation history with optional content, reference URLs, and the current user prompt.

Parameters:

Name	Type	Description	Default
prompt	str	Current user prompt.	required
content	str	Optional content prepended to the prompt.	''
context	Optional[List[Dict[str, Any]]]	Existing conversation history.	None
urls	Optional[List[str]]	URL-context values.	None
max_urls	int	Maximum number of URLs.	0

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Complete Interactions input timeline.

Raises:

Type	Description
Error	Raised when validation or input construction fails.
ValueError	Raised when prompt is missing.

build_generation_config

Build the Interactions generation configuration.

Purpose

Converts supported Jeni inference controls into the Interactions generation configuration without submitting blank or zero-valued optional controls.

Parameters:

Name	Type	Description	Default
temperature	float	Sampling temperature.	0.0
top_p	float	Top-p sampling value.	0.0
top_k	int	Top-k sampling value.	0
max_tokens	int	Maximum output-token count.	0
stops	Optional[List[str]]	Stop sequences.	None
reasoning	str	Thinking-level value.	''
tool_choice	Optional[str]	Tool-selection behavior.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

Raises:

Type	Description
Error	Raised when generation configuration construction fails.

parse_response_schema

Parse an optional structured-output schema.

Purpose

Accepts a dictionary or JSON string and converts it into the JSON Schema mapping required by the Interactions API.

Parameters:

Name	Type	Description	Default
response_schema	Any	Optional JSON Schema dictionary or JSON string.	None

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: Parsed JSON Schema, or None when absent.

Raises:

Type	Description
Error	Raised when a nonblank schema cannot be parsed.

build_response_format

Build the Interactions response format.

Purpose

Converts the Jeni MIME type, response modalities, and optional JSON Schema into the polymorphic response-format structure used by the current Interactions API.

Parameters:

Name	Type	Description	Default
response_format	str	Requested text MIME type.	''
response_schema	Any	Optional JSON Schema mapping or JSON string.	None
modalities	Optional[List[str]]	Requested response modalities.	None

Returns:

Type	Description
Optional[Any]	Optional[Any]: Interactions response-format value.

Raises:

Type	Description
Error	Raised when response-format construction fails.

build_tools

Build Interactions server-side tools.

Purpose

Translates Jeni tool identifiers into Interactions tool declarations. URL Context is enabled when selected or when URLs are supplied. File Search is enabled when File Search Store resource names are supplied.

Parameters:

Name	Type	Description	Default
tools	Optional[List[str]]	Selected tool identifiers.	None
urls	Optional[List[str]]	Normalized URL-context values.	None
file_search_store_names	Optional[List[str]]	File Search Store names.	None

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Interactions server-side tool declarations.

Raises:

Type	Description
Error	Raised when tool construction fails.

append_source

Append one normalized grounding source.

Purpose

Converts provider citation and tool-result fields into the stable source shape consumed by Jeni and prevents duplicate records.

Parameters:

Name	Type	Description	Default
source	Dict[str, Any]	Provider citation or result mapping.	required
default_type	str	Source type used when omitted by the mapping.	required

Returns:

Name	Type	Description
None	None	This method updates source state through side effects.

Raises:

Type	Description
Error	Raised when validation or source normalization fails.
ValueError	Raised when a required argument is missing.

extract_grounding_sources

Extract grounding citations from an Interaction.

Purpose

Collects model-output annotations and supported server-side tool-result data from the current Interaction steps.

Parameters:

Name	Type	Description	Default
interaction	Any	Completed Gemini Interaction.	required

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Normalized grounding-source records.

Raises:

Type	Description
Error	Raised when validation or citation extraction fails.
ValueError	Raised when interaction is missing.

capture_interaction

Capture a completed Gemini Interaction.

Purpose

Stores the raw response, identifier, output steps, generated text, and grounding sources on the members consumed by the Jeni application.

Parameters:

Name	Type	Description	Default
interaction	Any	Completed Gemini Interaction.	required

Returns:

Name	Type	Description
None	None	This method updates response state through side effects.

Raises:

Type	Description
Error	Raised when validation or response extraction fails.
ValueError	Raised when interaction is missing.

get_grounding_sources

Return sources from the most recent Interaction.

Purpose

Provides normalized grounding-source records consumed by Jeni response renderers.

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Grounding sources from the latest response.

get_structured_history

Return the complete stateless conversation history.

Purpose

Combines the submitted input timeline with the output steps returned by the latest Interaction so Jeni can preserve client-managed conversation state.

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Complete Interactions-compatible history.

Raises:

Type	Description
Error	Raised when output steps cannot be normalized.

generate_text_stream

Execute the prepared streaming Interactions request.

Purpose

Submits the active request, forwards text deltas to the application callback, accumulates the complete generated text, and captures final usage metadata.

Returns:

Name	Type	Description
str	str	Complete generated text.

Raises:

Type	Description
Error	Raised when streaming execution or event handling fails.

generate_text

Generate text through the Gemini Interactions API.

Purpose

Preserves Jeni's text-generation method contract while routing model execution through the Interactions API. Existing client-managed history is converted into Interactions steps and returned through get_structured_history() after the call.

Parameters:

Name	Type	Description	Default
prompt	str	Current user prompt.	required
model	str	Gemini model identifier.	required
number	int	Candidate-count value retained for compatibility.	1
temperature	float	Sampling temperature.	0.0
top_p	float	Top-p sampling value.	0.0
top_k	int	Top-k sampling value.	0
frequency	float	Frequency penalty retained for compatibility.	0.0
presence	float	Presence penalty retained for compatibility.	0.0
max_tokens	int	Maximum output-token count.	0
stops	Optional[List[str]]	Stop sequences.	None
instruct	str	System instruction text.	''
response_format	str	Requested response MIME type.	''
tools	Optional[List[str]]	Server-side tool identifiers.	None
tool_choice	Optional[str]	Tool-selection behavior.	None
reasoning	str	Thinking-level value.	''
modalities	Optional[List[str]]	Requested output modalities.	None
media_resolution	str	Media-resolution value retained for compatibility.	''
context	Optional[List[Dict[str, Any]]]	Client-managed conversation history.	None
content	str	Additional application content.	''
urls	Optional[List[str]]	URL-context values.	None
max_urls	int	Maximum number of URLs.	0
response_schema	Any	Optional JSON Schema mapping or JSON string.	''
safety_profile	str	Safety-profile value retained for compatibility.	''
file_search_store_names	Optional[List[str]]	File Search Store names.	None
stream	bool	Whether to stream response text.	False
stream_handler	Optional[Callable[[str], None]]	Text-delta callback.	None

Returns:

Name	Type	Description
str	str	Generated response text.

Raises:

Type	Description
Error	Raised when validation, request construction, or execution fails.
ValueError	Raised when a required prompt, model, or API key is missing.

Images

Bases: Gemini

Gemini image-generation, analysis, and editing wrapper.

Purpose

Executes image generation, image understanding, and image editing through the Gemini Interactions API. The class converts local images into Interactions image-content blocks, builds image and text response formats, configures supported Google Search grounding, captures generated image or text output, and preserves the application-facing method contracts consumed by the Jeni Images mode.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Gemini client.
http_options	HttpOptions	Gemini client HTTP configuration.
aspect_ratio	Optional[str]	Requested output-image aspect ratio.
size	Optional[str]	Requested output-image size.
resolution	Optional[str]	Media-resolution value retained for UI compatibility.
max_output_tokens	Optional[int]	Maximum text-output token count.
output_mime_type	Optional[str]	Requested output-image MIME type.
response_mode	Optional[str]	Requested response-modality selection.
response_format_value	Optional[Any]	Interactions response-format configuration.
generation_config	Dict[str, Any]	Interactions generation configuration.
input_content	List[Dict[str, Any]]	Multimodal Interactions input.
tool_objects	List[Dict[str, Any]]	Interactions Google Search tool declarations.
interaction	Optional[Any]	Most recent Gemini Interaction.
response	Optional[Any]	Raw response used by application token accounting.
output_text	str	Text extracted from the latest Interaction.
output_image_content	Optional[Any]	Image content from the latest Interaction.
grounding_metadata	Optional[Any]	Grounding data retained for UI compatibility.
grounding_sources	List[Dict[str, Any]]	Normalized grounding records.

model_options property

Return supported Gemini image models.

Purpose

Provides image-generation and image-editing model identifiers exposed by the Jeni Images mode.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini image-model identifiers.

include_options property

Return compatibility include options.

Purpose

Preserves the option contract consumed by existing Jeni controls.

Returns:

Type	Description
List[str]	List[str]: Existing include-option values.

aspect_options property

Return supported output-image aspect ratios.

Purpose

Provides aspect-ratio values accepted by Gemini image response formats.

Returns:

Type	Description
List[str]	List[str]: Supported aspect ratios.

media_options property

Return supported media-resolution values.

Purpose

Provides media-resolution values retained by the Jeni image controls.

Returns:

Type	Description
List[str]	List[str]: Supported media-resolution values.

modality_options property

Return supported image response modes.

Purpose

Provides text-only, image-only, and combined text-and-image output selections.

Returns:

Type	Description
List[str]	List[str]: Supported response-mode values.

reasoning_options property

Return supported thinking levels.

Purpose

Provides thinking-level values accepted by supported image models.

Returns:

Type	Description
List[str]	List[str]: Supported thinking-level values.

size_options property

Return supported output-image sizes.

Purpose

Provides output-image sizes accepted through the Interactions response format.

Returns:

Type	Description
List[str]	List[str]: Supported image-size values.

tool_options property

Return supported image grounding tools.

Purpose

Provides Google Web Search and Google Image Search selections used by the Jeni Images mode.

Returns:

Type	Description
List[str]	List[str]: Supported image tool identifiers.

choice_options property

Return supported tool-choice values.

Purpose

Preserves the existing Jeni tool-choice option contract.

Returns:

Type	Description
List[str]	List[str]: Supported tool-choice values.

format_options property

Return supported text-output MIME types.

Purpose

Provides text MIME types retained by the Jeni image controls.

Returns:

Type	Description
List[str]	List[str]: Supported text-output MIME types.

mime_options property

Return supported generated-image MIME types.

Purpose

Provides image MIME types accepted by the Interactions image response format.

Returns:

Type	Description
List[str]	List[str]: Supported generated-image MIME types.

resolution_options property

Return supported output-image resolution options.

Purpose

Provides the output-size values exposed by the Jeni Images mode.

Returns:

Type	Description
List[str]	List[str]: Supported output-image sizes.

supports_image_size

Return whether the selected model supports explicit image size.

Purpose

Centralizes output-image-size feature gating for the Jeni image controls.

Parameters:

Name	Type	Description	Default
model	str	Gemini image-model identifier.	required

Returns:

Name	Type	Description
bool	bool	True when the model supports explicit image size.

Raises:

Type	Description
Error	Raised when validation or model comparison fails.
ValueError	Raised when model is missing.

supports_search_grounding

Return whether the model supports Google Search grounding.

Purpose

Centralizes Google Search grounding feature gating for image generation.

Parameters:

Name	Type	Description	Default
model	str	Gemini image-model identifier.	required

Returns:

Name	Type	Description
bool	bool	True when the model supports Google Search grounding.

Raises:

Type	Description
Error	Raised when validation or model comparison fails.
ValueError	Raised when model is missing.

supports_image_search

Return whether the model supports Google Image Search grounding.

Purpose

Restricts Google Image Search grounding to the model documented for that feature.

Parameters:

Name	Type	Description	Default
model	str	Gemini image-model identifier.	required

Returns:

Name	Type	Description
bool	bool	True when Google Image Search is supported.

Raises:

Type	Description
Error	Raised when validation or model comparison fails.
ValueError	Raised when model is missing.

normalize_response_modalities

Normalize the requested response modes.

Purpose

Converts the Jeni response-mode value into text and image modality identifiers used to build the Interactions response format.

Parameters:

Name	Type	Description	Default
response_modalities	Optional[str]	Jeni response-mode value.	required
image_only	bool	Whether image output must be included.	False

Returns:

Type	Description
List[str]	List[str]: Normalized response modes.

Raises:

Type	Description
Error	Raised when response-mode normalization fails.

get_image_mime_type

Return the MIME type for a local image.

Purpose

Uses the local file suffix to produce the image MIME type required by an Interactions image-content block.

Parameters:

Name	Type	Description	Default
path	str	Local image path.	required

Returns:

Name	Type	Description
str	str	Image MIME type.

Raises:

Type	Description
Error	Raised when validation or MIME-type resolution fails.
ValueError	Raised when path is missing.

build_image_input

Build Interactions text and image input.

Purpose

Creates a text content block and, when supplied, a base64-encoded local image content block for image analysis or editing.

Parameters:

Name	Type	Description	Default
prompt	str	Image-generation, analysis, or editing instruction.	required
path	Optional[str]	Optional local image path.	None

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Interactions-compatible input content.

Raises:

Type	Description
Error	Raised when validation, file reading, or input construction fails.
ValueError	Raised when prompt is missing.

build_generation_config

Build the Interactions image generation configuration.

Purpose

Converts supported Jeni inference values into the Interactions generation configuration.

Parameters:

Name	Type	Description	Default
temperature	Optional[float]	Sampling temperature.	None
top_p	Optional[float]	Top-p sampling value.	None
max_tokens	Optional[int]	Maximum output-token count.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

Raises:

Type	Description
Error	Raised when generation configuration construction fails.

build_response_format

Build the Interactions image response format.

Purpose

Constructs text, image, or combined response formats and applies supported image MIME type, aspect ratio, and output-size settings to the image format.

Parameters:

Name	Type	Description	Default
response_modalities	Optional[str]	Jeni response-mode value.	required
image_only	bool	Whether image output must be included.	False
aspect	Optional[str]	Requested output-image aspect ratio.	None
resolution	Optional[str]	Requested output-image size.	None
output_mime_type	Optional[str]	Requested generated-image MIME type.	None

Returns:

Name	Type	Description
Any	Any	Interactions response-format object or list.

Raises:

Type	Description
Error	Raised when response-format construction fails.

build_grounding_tools

Build image grounding tool declarations.

Purpose

Creates the Interactions Google Search tool declaration for web grounding and optionally enables Google Image Search when supported by the selected model.

Parameters:

Name	Type	Description	Default
grounded	bool	Whether Google Web Search grounding is enabled.	False
image_search	bool	Whether Google Image Search grounding is enabled.	False

Returns:

Type	Description
List[Dict[str, Any]]	List[Dict[str, Any]]: Interactions tool declarations.

Raises:

Type	Description
Error	Raised when grounding-tool construction fails.

extract_image

Extract a generated image from an Interaction.

Purpose

Reads the SDK output_image convenience property, decodes its base64 content, and returns an independent Pillow image object.

Parameters:

Name	Type	Description	Default
interaction	Any	Completed Gemini Interaction.	required

Returns:

Type	Description
Optional[Image]	Optional[PIL.Image.Image]: Generated image, or None when no image was returned.

Raises:

Type	Description
Error	Raised when validation or image extraction fails.
ValueError	Raised when interaction is missing.

extract_text

Extract generated text from an Interaction.

Purpose

Reads the Interactions SDK output_text convenience property and returns the normalized text expected by the Jeni image-analysis workflow.

Parameters:

Name	Type	Description	Default
interaction	Any	Completed Gemini Interaction.	required

Returns:

Type	Description
Optional[str]	Optional[str]: Generated text, or None when no text was returned.

Raises:

Type	Description
Error	Raised when validation or text extraction fails.
ValueError	Raised when interaction is missing.

capture_metadata

Capture grounding information from the latest Interaction.

Purpose

Retains the latest Interaction steps and Google Search result metadata for application display and diagnostics.

Returns:

Name	Type	Description
None	None	This method updates response state through side effects.

Raises:

Type	Description
Error	Raised when grounding metadata cannot be captured.

execute_interaction

Execute an image Interaction.

Purpose

Validates required inputs, creates the Gemini client, builds multimodal input, generation settings, output formats, and grounding tools, submits the request, and captures the response state shared by generation, analysis, and editing workflows.

Parameters:

Name	Type	Description	Default
prompt	str	Image-generation, analysis, or editing instruction.	required
model	str	Gemini image-model identifier.	required
path	Optional[str]	Optional local image path.	None
aspect	Optional[str]	Requested output-image aspect ratio.	None
number	Optional[int]	Requested result count retained for compatibility.	None
temperature	Optional[float]	Sampling temperature.	None
top_p	Optional[float]	Top-p sampling value.	None
frequency	Optional[float]	Frequency penalty retained for compatibility.	None
presence	Optional[float]	Presence penalty retained for compatibility.	None
max_tokens	Optional[int]	Maximum output-token count.	None
resolution	Optional[str]	Requested generated-image size.	None
instruct	Optional[str]	System instruction text.	None
output_mime_type	Optional[str]	Requested generated-image MIME type.	None
response_modalities	Optional[str]	Requested response-mode value.	None
image_only	bool	Whether image output must be included.	False
grounded	bool	Whether Google Search grounding is enabled.	False
image_search	bool	Whether Google Image Search grounding is enabled.	False

Returns:

Name	Type	Description
Any	Any	Completed Gemini Interaction.

Raises:

Type	Description
Error	Raised when validation, request construction, or provider execution fails.
ValueError	Raised when prompt, model, or the API key is missing.

get_first_image

Return the image from the most recent Interaction.

Purpose

Preserves the existing Jeni helper contract by extracting the generated image from the latest Interaction.

Returns:

Type	Description
Optional[Image]	Optional[PIL.Image.Image]: Generated image, or None when unavailable.

Raises:

Type	Description
Error	Raised when image extraction fails.

get_output_text

Return text from the most recent Interaction.

Purpose

Preserves the existing Jeni helper contract by extracting generated text from the latest Interaction.

Returns:

Type	Description
Optional[str]	Optional[str]: Generated text, or None when unavailable.

Raises:

Type	Description
Error	Raised when text extraction fails.

generate

Generate an image through the Gemini Interactions API.

Purpose

Submits a text-to-image Interaction and returns the generated Pillow image expected by the Jeni Image Generation workflow.

Parameters:

Name	Type	Description	Default
prompt	str	Image-generation instruction.	required
model	str	Gemini image-model identifier.	'gemini-3.1-flash-image'
aspect	str	Requested output-image aspect ratio.	None
number	int	Requested result count retained for compatibility.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None
frequency	float	Frequency penalty retained for compatibility.	None
presence	float	Presence penalty retained for compatibility.	None
max_tokens	int	Maximum output-token count.	None
resolution	str	Requested generated-image size.	None
instruct	str	System instruction text.	None
output_mime_type	str	Requested generated-image MIME type.	None
response_modalities	str	Requested response-mode value.	None
grounded	bool	Whether Google Search grounding is enabled.	False
image_search	bool	Whether Google Image Search grounding is enabled.	False

Returns:

Type	Description
Optional[Image]	Optional[PIL.Image.Image]: Generated image, or None when no image is returned.

Raises:

Type	Description
Error	Raised when request execution or image extraction fails.
ValueError	Raised when a required argument is missing.

analyze

Analyze an image through the Gemini Interactions API.

Purpose

Submits text and a local image as multimodal Interaction input and returns the generated text expected by the Jeni Image Analysis workflow.

Parameters:

Name	Type	Description	Default
prompt	str	Image-analysis instruction.	required
path	str	Local image path.	required
model	str	Gemini image-model identifier.	'gemini-3.1-flash-image'
aspect	str	Aspect-ratio value retained for compatibility.	None
number	int	Requested result count retained for compatibility.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None
frequency	float	Frequency penalty retained for compatibility.	None
presence	float	Presence penalty retained for compatibility.	None
max_tokens	int	Maximum output-token count.	None
resolution	str	Media-resolution value retained for compatibility.	None
instruct	str	System instruction text.	None
output_mime_type	str	Output MIME type retained for compatibility.	None
response_modalities	str	Requested response-mode value.	None
grounded	bool	Whether Google Search grounding is enabled.	False
image_search	bool	Whether Google Image Search grounding is enabled.	False

Returns:

Type	Description
Optional[str]	Optional[str]: Generated image analysis, or None when no text is returned.

Raises:

Type	Description
Error	Raised when request execution or text extraction fails.
ValueError	Raised when a required argument is missing.

edit

Edit an image through the Gemini Interactions API.

Purpose

Submits an editing instruction and local image as multimodal Interaction input and returns the generated Pillow image expected by the Jeni Image Editing workflow.

Parameters:

Name	Type	Description	Default
prompt	str	Image-editing instruction.	required
path	str	Local source-image path.	required
model	str	Gemini image-model identifier.	'gemini-3.1-flash-image'
aspect	str	Requested output-image aspect ratio.	None
number	int	Requested result count retained for compatibility.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None
frequency	float	Frequency penalty retained for compatibility.	None
presence	float	Presence penalty retained for compatibility.	None
max_tokens	int	Maximum output-token count.	None
resolution	str	Requested generated-image size.	None
instruct	str	System instruction text.	None
output_mime_type	str	Requested generated-image MIME type.	None
response_modalities	str	Requested response-mode value.	None
grounded	bool	Whether Google Search grounding is enabled.	False
image_search	bool	Whether Google Image Search grounding is enabled.	False

Returns:

Type	Description
Optional[Image]	Optional[PIL.Image.Image]: Edited image, or None when no image is returned.

Raises:

Type	Description
Error	Raised when request execution or image extraction fails.
ValueError	Raised when a required argument is missing.

Embeddings

Bases: Gemini

Gemini embedding wrapper.

Purpose

Creates numerical vector representations of text through the Gemini embeddings API. The class validates and normalizes text input, builds provider-supported embedding configuration, executes the specialized models.embed_content() operation, and extracts vectors from the returned embedding response.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Google Gen AI client.
response	Optional[EmbedContentResponse]	Most recent embedding response.
embedding	Optional[List[float] | List[List[float]]]	Extracted embedding result.
embeddings	Optional[List[List[float]]]	Extracted embedding vectors.
encoding_format	str	Application-facing embedding encoding selection.
dimensions	Optional[int]	Requested output dimensionality.
task_type	Optional[str]	Embedding task type.
title	Optional[str]	Retrieval-document title.
embedding_config	Optional[EmbedContentConfig]	Embedding request configuration.
contents	Optional[str | List[str]]	Normalized provider input.
input_text	Optional[str | List[str]]	Original normalized text input.

model_options property

Return supported Gemini embedding models.

Purpose

Provides the active embedding model identifiers exposed by the Jeni Embeddings mode.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini embedding model identifiers.

encoding_options property

Return supported embedding encodings.

Purpose

Provides the native numerical encoding returned by the Gemini embeddings API.

Returns:

Type	Description
List[str]	List[str]: Supported embedding encoding values.

task_options property

Return supported embedding task types.

Purpose

Provides the embedding task types accepted for text embedding requests.

Returns:

Type	Description
List[str]	List[str]: Supported embedding task types.

normalize_dimensions

Normalize the requested output dimensionality.

Purpose

Converts a zero-valued UI selection into an omitted provider setting and validates positive dimensionality values against the range exposed by the application.

Parameters:

Name	Type	Description	Default
dimensions	int	Requested output dimensionality.	0

Returns:

Type	Description
Optional[int]	Optional[int]: Positive output dimensionality, or None when omitted.

Raises:

Type	Description
Error	Raised when dimensionality validation fails.
ValueError	Raised when dimensionality exceeds the supported application range.

normalize_contents

Normalize embedding input.

Purpose

Removes blank values while preserving whether the caller supplied one string or a list of independent strings.

Parameters:

Name	Type	Description	Default
text	str | List[str]	Text or text values to embed.	required

Returns:

Type	Description
str | List[str]	str | List[str]: Normalized embedding input.

Raises:

Type	Description
Error	Raised when input validation or normalization fails.
ValueError	Raised when no usable text remains.

build_embedding_config

Build the embedding request configuration.

Purpose

Constructs the provider configuration from output dimensionality, task type, and retrieval-document title settings supported by the selected embedding model.

Parameters:

Name	Type	Description	Default
model	str	Gemini embedding model identifier.	required
dimensions	int	Requested output dimensionality.	0
task_type	str	Optional embedding task type.	''
title	str	Optional retrieval-document title.	''

Returns:

Name	Type	Description
EmbedContentConfig	EmbedContentConfig	Provider embedding configuration.

Raises:

Type	Description
Error	Raised when validation or configuration construction fails.
ValueError	Raised when model is missing.

extract_embeddings

Extract vectors from the embedding response.

Purpose

Converts SDK embedding objects into ordinary lists of floating-point values and preserves the single-vector return shape for a single string input.

Returns:

Type	Description
Optional[List[float] | List[List[float]]]	Optional[List[float] | List[List[float]]]: Extracted embedding vector or vectors.

Raises:

Type	Description
Error	Raised when response extraction fails.

create

Create text embeddings.

Purpose

Validates and normalizes text input, constructs the provider configuration, executes the specialized Gemini embeddings operation, and returns the extracted vector data.

Parameters:

Name	Type	Description	Default
text	str | List[str]	Text or independent text values to embed.	required
model	str	Gemini embedding model identifier.	'gemini-embedding-2'
dimensions	int	Requested output dimensionality.	0
task_type	str	Optional embedding task type.	''
title	str	Optional retrieval-document title.	''
encoding_format	str	Application-facing encoding selection.	'float'

Returns:

Type	Description
Optional[List[float] | List[List[float]]]	Optional[List[float] | List[List[float]]]: Generated embedding vector or vectors.

Raises:

Type	Description
Error	Raised when validation, provider execution, or extraction fails.
ValueError	Raised when required input, model, API key, or encoding is invalid.

TTS

Bases: Gemini

Gemini text-to-speech wrapper.

Purpose

Converts text into single-speaker audio through the Gemini Interactions API. The class builds controllable speech prompts, applies the selected prebuilt voice, retrieves PCM audio from the completed Interaction, wraps the PCM data in a WAV container, and optionally writes the generated audio to disk.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Gemini SDK client.
http_options	HttpOptions	Gemini client HTTP configuration.
speed	Optional[float]	Requested speech-rate control.
voice	Optional[str]	Selected prebuilt Gemini voice.
response	Optional[Any]	Most recent Gemini Interaction.
interaction	Optional[Any]	Most recent Gemini Interaction.
audio_path	Optional[str]	Optional output WAV path.
response_format	Optional[str]	Application-facing audio format.
input_text	Optional[str]	Complete text and performance instruction sent to Gemini.
audio_bytes	Optional[bytes]	Generated WAV audio.
pcm_bytes	Optional[bytes]	Raw PCM audio returned by Gemini.
generation_config	Dict[str, Any]	Interactions speech-generation configuration.

model_options property

Return supported Gemini text-to-speech models.

Purpose

Provides the Gemini TTS model identifiers exposed by the Jeni Audio mode.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini text-to-speech model identifiers.

format_options property

Return supported application audio formats.

Purpose

Provides the local WAV output format supported by the Jeni Audio mode.

Returns:

Type	Description
List[str]	List[str]: Supported application audio formats.

voice_options property

Return supported prebuilt Gemini voices.

Purpose

Provides the prebuilt single-speaker voices exposed by the Jeni Audio controls.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini prebuilt voice names.

to_wave_bytes

Wrap PCM audio in a WAV container.

Purpose

Writes raw Gemini PCM output into an in-memory WAV file using the channel count, sampling rate, and sample width documented for Gemini TTS output.

Parameters:

Name	Type	Description	Default
pcm_data	bytes	Raw PCM audio.	required
rate	int	Audio sample rate in hertz.	24000
channels	int	Audio channel count.	1
sample_width	int	Sample width in bytes.	2

Returns:

Name	Type	Description
bytes	bytes	Complete WAV file bytes.

Raises:

Type	Description
Error	Raised when validation or WAV encoding fails.
ValueError	Raised when pcm_data is missing.

normalize_voice

Normalize the selected Gemini voice.

Purpose

Returns the selected prebuilt voice when supported and otherwise uses Kore as the stable default voice.

Parameters:

Name	Type	Description	Default
voice	Optional[str]	Candidate Gemini voice name.	None

Returns:

Name	Type	Description
str	str	Supported Gemini voice name.

Raises:

Type	Description
Error	Raised when voice normalization fails.

normalize_tts_prompt

Build the controllable TTS prompt.

Purpose

Combines optional system-style performance instructions, speech-rate guidance, and the exact source text into the single text input accepted by Gemini TTS models.

Parameters:

Name	Type	Description	Default
text	str	Text to synthesize.	required
speed	Optional[float]	Relative speech-rate control.	None
instruct	Optional[str]	Optional performance instruction.	None

Returns:

Name	Type	Description
str	str	Complete Gemini TTS prompt.

Raises:

Type	Description
Error	Raised when validation or prompt construction fails.
ValueError	Raised when text is missing.

build_generation_config

Build the Interactions speech-generation configuration.

Purpose

Constructs the single-speaker speech configuration and adds supported inference settings without submitting legacy Generate Content configuration objects.

Parameters:

Name	Type	Description	Default
voice	str	Supported Gemini voice name.	required
temperature	Optional[float]	Sampling temperature.	None
top_p	Optional[float]	Top-p sampling value.	None
max_tokens	Optional[int]	Maximum output-token count.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

Raises:

Type	Description
Error	Raised when validation or configuration construction fails.
ValueError	Raised when voice is missing.

create_speech

Generate speech through the Gemini Interactions API.

Purpose

Builds the controllable TTS prompt, submits an audio-only Interaction, decodes the returned base64 PCM audio, wraps it in a WAV container, and returns the WAV bytes or the path written by the method.

Parameters:

Name	Type	Description	Default
text	str	Text to synthesize.	required
filepath	str	Optional output WAV path.	None
model	str	Gemini text-to-speech model.	'gemini-3.1-flash-tts-preview'
format	str	Application-facing audio format.	'audio/wav'
speed	float	Relative speech-rate control.	None
voice	str	Prebuilt Gemini voice.	None
frequency	float	Frequency penalty retained for UI compatibility.	None
presense	float	Presence penalty retained for UI compatibility.	None
max_tokens	int	Maximum output-token count.	None
instruct	str	Optional speech-performance instruction.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None

Returns:

Type	Description
bytes | str | None	bytes | str | None: WAV bytes when no path is supplied, or the written file path.

Raises:

Type	Description
Error	Raised when validation, request execution, decoding, or file writing fails.
ValueError	Raised when required input is missing or no audio is returned.

Transcription

Bases: Gemini

Gemini audio-transcription wrapper.

Purpose

Transcribes local audio files into text through the Gemini Interactions API. The class normalizes audio MIME types, builds transcription instructions with optional language and time-range constraints, uploads the local audio through the Gemini Files API, and submits the uploaded audio as multimodal Interactions input.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Gemini SDK client.
http_options	HttpOptions	Gemini client HTTP configuration.
transcript	Optional[str]	Text returned by the transcription request.
file_path	Optional[str]	Local audio-file path.
mime_type	Optional[str]	Normalized audio MIME type.
uploaded_file	Optional[File]	File resource uploaded to Gemini.
interaction	Optional[Any]	Most recent Gemini Interaction.
response	Optional[Any]	Raw Interaction consumed by application token accounting.
generation_config	Dict[str, Any]	Interactions generation configuration.

model_options property

Return supported audio-transcription models.

Purpose

Provides the Gemini audio-understanding model identifiers exposed by the Jeni Audio mode.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini transcription-model identifiers.

language_options property

Return supported transcription language hints.

Purpose

Provides optional spoken-language hints consumed by the Jeni Audio controls.

Returns:

Type	Description
List[str]	List[str]: Supported language-hint values.

mime_options property

Return supported audio MIME types.

Purpose

Provides audio MIME-type values accepted by the Jeni Audio mode.

Returns:

Type	Description
List[str]	List[str]: Supported audio MIME types.

normalize_mime_type

Normalize an audio MIME type.

Purpose

Uses an explicitly supplied MIME type when available and otherwise derives the MIME type from the local file extension.

Parameters:

Name	Type	Description	Default
path	str	Local audio-file path.	required
mime_type	str	Optional explicit audio MIME type.	None

Returns:

Name	Type	Description
str	str	Normalized audio MIME type.

Raises:

Type	Description
Error	Raised when validation or MIME-type normalization fails.
ValueError	Raised when path is missing.

build_prompt

Build the transcription prompt.

Purpose

Constructs the transcription instruction and adds optional spoken-language and time-range constraints without altering the source audio.

Parameters:

Name	Type	Description	Default
language	str	Optional spoken-language hint.	None
start_time	float	Optional starting timestamp in seconds.	0.0
end_time	float	Optional ending timestamp in seconds.	0.0

Returns:

Name	Type	Description
str	str	Complete transcription prompt.

Raises:

Type	Description
Error	Raised when prompt construction fails.

build_generation_config

Build the transcription generation configuration.

Purpose

Converts supported Jeni inference controls into the Interactions generation configuration.

Parameters:

Name	Type	Description	Default
temperature	float	Sampling temperature.	required
top_p	float	Top-p sampling value.	required
max_tokens	int	Maximum output-token count.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

Raises:

Type	Description
Error	Raised when configuration construction fails.

transcribe

Transcribe audio through the Gemini Interactions API.

Purpose

Uploads the local audio file, constructs a multimodal Interactions request using the uploaded file URI and MIME type, and returns the generated transcript.

Parameters:

Name	Type	Description	Default
path	str	Local audio-file path.	required
model	str	Gemini audio-understanding model.	'gemini-3.6-flash'
language	str	Optional spoken-language hint.	None
mime_type	str	Optional explicit audio MIME type.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None
frequency	float	Frequency penalty retained for UI compatibility.	None
presence	float	Presence penalty retained for UI compatibility.	None
max_tokens	int	Maximum output-token count.	None
start_time	float	Optional starting timestamp in seconds.	0.0
end_time	float	Optional ending timestamp in seconds.	0.0
instruct	str	Optional system instruction text.	None

Returns:

Name	Type	Description
str	str	Generated transcript.

Raises:

Type	Description
Error	Raised when validation, upload, request execution, or response extraction fails.
ValueError	Raised when required input is missing or the transcript is empty.

Translation

Bases: Gemini

Gemini audio-translation wrapper.

Purpose

Translates spoken audio into target-language text through the Gemini Interactions API. The class normalizes audio MIME types, builds translation instructions with source and target language hints, uploads the local audio through the Gemini Files API, and submits the uploaded audio as multimodal Interactions input.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Gemini SDK client.
http_options	HttpOptions	Gemini client HTTP configuration.
target_language	Optional[str]	Requested translation target language.
source_language	Optional[str]	Optional spoken source-language hint.
file_path	Optional[str]	Local audio-file path.
mime_type	Optional[str]	Normalized audio MIME type.
translation	Optional[str]	Text returned by the translation request.
uploaded_file	Optional[File]	File resource uploaded to Gemini.
interaction	Optional[Any]	Most recent Gemini Interaction.
response	Optional[Any]	Raw Interaction consumed by application token accounting.
generation_config	Dict[str, Any]	Interactions generation configuration.

model_options property

Return supported audio-translation models.

Purpose

Provides the Gemini audio-understanding model identifiers exposed by the Jeni Audio mode.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini translation-model identifiers.

language_options property

Return supported translation languages.

Purpose

Provides source and target language values consumed by the Jeni Audio controls.

Returns:

Type	Description
List[str]	List[str]: Supported translation language values.

normalize_mime_type

Normalize an audio MIME type.

Purpose

Uses an explicitly supplied MIME type when available and otherwise derives the MIME type from the local file extension.

Parameters:

Name	Type	Description	Default
path	str	Local audio-file path.	required
mime_type	str	Optional explicit audio MIME type.	None

Returns:

Name	Type	Description
str	str	Normalized audio MIME type.

Raises:

Type	Description
Error	Raised when validation or MIME-type normalization fails.
ValueError	Raised when path is missing.

build_prompt

Build the audio-translation prompt.

Purpose

Constructs a target-language translation instruction and adds optional source-language and time-range constraints.

Parameters:

Name	Type	Description	Default
target_language	str	Requested translation target language.	required
source_language	str	Optional spoken source-language hint.	None
start_time	float	Optional starting timestamp in seconds.	0.0
end_time	float	Optional ending timestamp in seconds.	0.0

Returns:

Name	Type	Description
str	str	Complete translation prompt.

Raises:

Type	Description
Error	Raised when validation or prompt construction fails.
ValueError	Raised when target_language is missing.

build_generation_config

Build the translation generation configuration.

Purpose

Converts supported Jeni inference controls into the Interactions generation configuration.

Parameters:

Name	Type	Description	Default
temperature	float	Sampling temperature.	required
top_p	float	Top-p sampling value.	required
max_tokens	int	Maximum output-token count.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

Raises:

Type	Description
Error	Raised when configuration construction fails.

translate

Translate audio through the Gemini Interactions API.

Purpose

Uploads the local audio file, constructs a multimodal Interactions request using the uploaded file URI and MIME type, and returns the generated target-language text.

Parameters:

Name	Type	Description	Default
path	str	Local audio-file path.	required
target_language	str	Requested translation target language.	required
model	str	Gemini audio-understanding model.	'gemini-3.6-flash'
source_language	str	Optional spoken source-language hint.	None
mime_type	str	Optional explicit audio MIME type.	None
temperature	float	Sampling temperature.	None
top_p	float	Top-p sampling value.	None
frequency	float	Frequency penalty retained for UI compatibility.	None
presence	float	Presence penalty retained for UI compatibility.	None
max_tokens	int	Maximum output-token count.	None
start_time	float	Optional starting timestamp in seconds.	0.0
end_time	float	Optional ending timestamp in seconds.	0.0
instruct	str	Optional system instruction text.	None

Returns:

Name	Type	Description
str	str	Generated target-language translation.

Raises:

Type	Description
Error	Raised when validation, upload, request execution, or response extraction fails.
ValueError	Raised when required input is missing or the translation is empty.

Files

Bases: Gemini

Gemini file and document workflow wrapper.

Purpose

Manages Gemini Files API resources and executes document, web-search, and Google Maps model workflows. File lifecycle operations remain on the specialized Files API, while document reasoning and grounded generation use the Gemini Interactions API.

Attributes:

Name	Type	Description
client	Optional[Client]	Active Google Gen AI client.
storage_client	Optional[Client]	Google Cloud Storage client.
project_id	Optional[str]	Google Cloud project identifier.
project_location	Optional[str]	Google Cloud location.
file_id	Optional[str]	Active Gemini file resource name.
bucket_id	Optional[str]	Active Google Cloud Storage bucket name.
display_name	Optional[str]	Uploaded file display name.
mime_type	Optional[str]	Active file MIME type.
file_path	Optional[str]	Active local file path.
file_list	List[str]	Google Cloud Storage object names returned by the latest list operation.
file_paths	List[str]	Local paths used by a multi-document request.
file_lists	List[File]	Uploaded Gemini file resources used by a multi-document request.
response	Optional[Any]	Most recent Files API or Interactions response.
interaction	Optional[Any]	Most recent Gemini Interaction.
use_vertex	bool	Compatibility flag retained for application configuration.
collections	Dict[str, str]	Compatibility collection mapping.
documents	Dict[str, str]	Compatibility document mapping.

file_options property

Return cached file resource names.

Returns:

Type	Description
List[str]	List[str]: Cached Gemini file resource names.

model_options property

Return supported document models.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini model identifiers.

include_options property

Return compatibility include options.

Returns:

Type	Description
List[str]	List[str]: Existing application include-option values.

reasoning_options property

Return supported thinking levels.

Returns:

Type	Description
List[str]	List[str]: Supported thinking-level values.

choice_options property

Return supported tool-choice values.

Returns:

Type	Description
List[str]	List[str]: Supported tool-choice values.

tool_options property

Return supported Interactions tools.

Returns:

Type	Description
List[str]	List[str]: Supported tool identifiers.

modality_options property

Return supported response modalities.

Returns:

Type	Description
List[str]	List[str]: Supported response modality values.

media_options property

Return supported media-resolution values.

Returns:

Type	Description
List[str]	List[str]: Supported media-resolution values.

create_client

Create the Google Gen AI client.

Returns:

Type	Description
Client	genai.Client: Configured provider client.

Raises:

Type	Description
Error	Raised when API-key validation or client creation fails.

normalize_mime_type

Resolve the MIME type for a local file.

Parameters:

Name	Type	Description	Default
filepath	str	Local file path.	required

Returns:

Name	Type	Description
str	str	Resolved MIME type.

Raises:

Type	Description
Error	Raised when validation or MIME-type resolution fails.

upload

Upload a local file through the Gemini Files API.

Parameters:

Name	Type	Description	Default
filepath	str	Local file path.	required
name	str	Optional display name.	None

Returns:

Name	Type	Description
File	File	Uploaded Gemini file resource.

Raises:

Type	Description
Error	Raised when validation or upload fails.

list

List configured Google Cloud Storage document objects.

Purpose

Preserves the existing Files wrapper contract by listing objects from the jeni-financial bucket under the regulations prefix. The model and generation arguments remain accepted because they are part of the existing application-facing signature, but they are not provider inputs for this storage operation.

Parameters:

Name	Type	Description	Default
model	str	Model value retained by the wrapper.	'gemini-3.6-flash'
top_p	float	Top-P value retained by the wrapper.	0.8
top_k	int	Top-K value retained by the wrapper.	50
temperature	float	Temperature value retained by the wrapper.	0.5
frequency	float	Frequency-penalty value retained by the wrapper.	0.0
presence	float	Presence-penalty value retained by the wrapper.	0.0
max_tokens	int	Maximum-token value retained by the wrapper.	8192
tool_choice	str	Tool-choice value retained by the wrapper.	'auto'
stops	List[str]	Stop sequences retained by the wrapper.	None
tools	List[str]	Tool identifiers retained by the wrapper.	None
domains	List[str]	Domain values retained by the wrapper.	None
modalities	List[str]	Response modalities retained by the wrapper.	None
media_resolution	str	Media-resolution value retained by the wrapper.	'media_resolution_medium'

Returns:

Type	Description
List[str]	List[str]: Object names under the configured regulations prefix.

Raises:

Type	Description
Error	Raised when the Google Cloud Storage listing fails.

retrieve

Retrieve a Gemini file resource.

Parameters:

Name	Type	Description	Default
file_id	str	Gemini file resource name.	required

Returns:

Name	Type	Description
File	File	Retrieved Gemini file resource.

Raises:

Type	Description
Error	Raised when validation or retrieval fails.

build_generation_config

Build an Interactions generation configuration.

Parameters:

Name	Type	Description	Default
temperature	float	Sampling temperature.	None
top_p	float	Top-P sampling value.	None
max_tokens	int	Maximum output-token count.	None
stops	List[str]	Stop sequences.	None

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions generation configuration.

build_document_block

Build an inline Interactions document block.

Parameters:

Name	Type	Description	Default
filepath	str	Local document path.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Interactions document content block.

Raises:

Type	Description
Error	Raised when validation or file encoding fails.

execute_document_interaction

Execute a document Interaction.

Parameters:

Name	Type	Description	Default
prompt	str	Document instruction or question.	required
filepaths	List[str]	Local document paths.	required
model	str	Gemini model identifier.	required
temperature	float	Sampling temperature.	None
top_p	float	Top-P sampling value.	None
frequency	float	Compatibility frequency-penalty value.	None
presence	float	Compatibility presence-penalty value.	None
max_tokens	int	Maximum output-token count.	None
stops	List[str]	Stop sequences.	None
instruct	str	Optional system instruction.	None

Returns:

Name	Type	Description
str	str	Generated document response.

Raises:

Type	Description
Error	Raised when validation, request construction, or execution fails.

summarize

Summarize a local document through Interactions.

search

Answer a question about a local document through Interactions.

survey

Analyze multiple local documents through Interactions.

execute_grounded_interaction

Execute a Google Search or Google Maps Interaction.

web_search

Generate a Google Search-grounded response.

search_maps

Generate a Google Maps-grounded response.

delete

Delete a Gemini file resource.

Parameters:

Name	Type	Description	Default
file_id	str	Gemini file resource name.	required

Returns:

Name	Type	Description
bool	bool	True after successful deletion.

Raises:

Type	Description
Error	Raised when validation or deletion fails.

CloudBuckets

Bases: Gemini

Google Cloud Storage bucket wrapper.

Purpose

Manages Google Cloud Storage objects and executes Google Search and Google Maps grounded model requests through the Gemini Interactions API.

Attributes:

Name	Type	Description
project_id	Optional[str]	Google Cloud project identifier.
bucket_name	Optional[str]	Active bucket name.
object_name	Optional[str]	Active object name.
file_path	Optional[str]	Active local file path.
file_ids	List[str]	Cached file identifiers.
store_ids	List[str]	Cached store identifiers.
client	Optional[Client]	Active Google Cloud Storage client.
bucket	Optional[Bucket]	Active bucket.
response	Optional[Any]	Most recent storage or Interactions response.
interaction	Optional[Any]	Most recent Gemini Interaction.
collections	Dict[str, str]	Named bucket and prefix mappings.
documents	Dict[str, str]	Named document mappings.

model_options property

Return supported grounded-generation models.

Returns:

Type	Description
List[str]	List[str]: Supported Gemini model identifiers.

media_options property

Return supported media-resolution values.

Returns:

Type	Description
List[str]	List[str]: Supported media-resolution values.

create_storage_client

Create the Google Cloud Storage client.

Returns:

Type	Description
Client	storage.Client: Configured storage client.

Raises:

Type	Description
Error	Raised when client creation fails.

create

Create an empty object in a bucket.

Parameters:

Name	Type	Description	Default
bucket	str	Bucket name.	required
name	str	Object name.	required

Returns:

Name	Type	Description
Blob	Blob	Created object reference.

Raises:

Type	Description
Error	Raised when validation or object creation fails.

upload

Upload a local file to a bucket.

Parameters:

Name	Type	Description	Default
path	str	Local file path.	required
bucket	str	Bucket name.	required
name	str	Optional object name.	None

Returns:

Name	Type	Description
Blob	Blob	Uploaded object.

Raises:

Type	Description
Error	Raised when validation or upload fails.

retrieve

Retrieve object metadata.

Parameters:

Name	Type	Description	Default
bucket	str	Bucket name.	required
name	str	Object name.	required

Returns:

Type	Description
Optional[Blob]	Optional[Blob]: Matching object, or None when absent.

Raises:

Type	Description
Error	Raised when validation or retrieval fails.

list

List bucket objects.

Parameters:

Name	Type	Description	Default
bucket	str	Bucket name.	required

Returns:

Type	Description
List[Blob]	List[Blob]: Bucket objects.

Raises:

Type	Description
Error	Raised when validation or listing fails.

execute_grounded_interaction

Execute a grounded Interactions request.

Parameters:

Name	Type	Description	Default
prompt	str	User prompt.	required
model	str	Gemini model identifier.	required
tool_type	str	Grounding tool type.	required
temperature	float	Sampling temperature.	None
top_p	float	Top-P sampling value.	None
frequency	float	Compatibility frequency-penalty value.	None
presence	float	Compatibility presence-penalty value.	None
max_tokens	int	Maximum output-token count.	None
stops	List[str]	Stop sequences.	None
instruct	str	Optional system instruction.	None

Returns:

Name	Type	Description
str	str	Generated grounded response.

Raises:

Type	Description
Error	Raised when validation or execution fails.

web_search

Generate a Google Search-grounded response.

search_maps

Generate a Google Maps-grounded response.

delete

Delete a bucket object.

Parameters:

Name	Type	Description	Default
bucket	str	Bucket name.	required
name	str	Object name.	required

Returns:

Name	Type	Description
bool	bool	True after successful deletion.

Raises:

Type	Description
Error	Raised when validation or deletion fails.

throw_if

Validate that a required argument has a usable value.

Purpose

Provides a shared argument guard for provider calls, file operations, and configuration builders. The helper raises a clear ValueError when a required value is missing, blank, or an empty collection.

Parameters:

Name	Type	Description	Default
name	str	Name of the argument being validated.	required
value	object	Runtime value to validate.	required

Raises:

Type	Description
ValueError	Raised when value is None, blank, or an empty collection.

encode_image

Encode a local image file as base64 text.

Purpose

Reads a local image file and converts its binary content into a base64-encoded string. This supports workflows that need inline image data instead of a file handle or URI.

Parameters:

Name	Type	Description	Default
image_path	str	Path to the local image file.	required

Returns:

Type	Description
str	Base64-encoded image content.