Implementation:Arize ai Phoenix Google Adapter

Overview

The GoogleGenAIAdapter is a concrete implementation of the BaseLLMAdapter abstract class that integrates the Google GenAI (Gemini) API into the Phoenix evaluator framework. It resides in the phoenix-evals sub-package and provides both synchronous and asynchronous methods for text generation and structured object extraction. The adapter supports both structured output (via response_mime_type="application/json") and tool calling (via function declarations), with an automatic fallback strategy when the AUTO generation method is selected.

Description

The module defines the GoogleGenAIAdapter class, a GoogleGenAIRateLimitError custom exception, and two supporting functions: identify_google_genai_client() and get_google_genai_rate_limit_errors(). Together they enable the Phoenix evaluator framework to:

• Identify whether a given client object is a Google GenAI client (by checking for GoogleGenAIClientWrapper, or the presence of models and chats attributes).
• Translate Google-specific HTTP 429 / RESOURCE_EXHAUSTED errors into a custom GoogleGenAIRateLimitError for integration with the rate limiting subsystem.
• Adapt the Google GenAI generate_content API to the four core adapter methods.

Key adapter behaviors:

• System instruction handling: Google GenAI passes system instructions via the GenerateContentConfig.system_instruction parameter rather than as part of the content array. The adapter extracts system messages and merges them into the config.
• Config object merging: When a config kwarg is already provided, the adapter safely extracts its parameters (trying Pydantic v2 model_dump(), v1 dict(), to_dict(), or filtered __dict__) to merge system instructions.
• Role mapping: Google uses "model" instead of "assistant" for AI responses, and expects a parts structure. The adapter performs this translation.
• Dual structured output strategies: For generate_object(), the AUTO method first attempts structured output via response_schema, then falls back to tool calling via FunctionDeclaration with FunctionCallingConfigMode("ANY").
• Rate limit error translation: The _handle_api_error() method catches Google APIError instances with code 429 or status RESOURCE_EXHAUSTED and re-raises them as GoogleGenAIRateLimitError.

Usage

from google import genai
from phoenix.evals.llm.adapters.google.adapter import GoogleGenAIAdapter

# Synchronous usage
client = genai.Client(api_key="...")
adapter = GoogleGenAIAdapter(client=client, model="gemini-2.0-flash")

# Text generation
response = adapter.generate_text("Explain quantum computing in simple terms.")

# Structured output (tries structured output first, then tool calling)
schema = {
    "type": "object",
    "properties": {
        "label": {"type": "string"},
        "confidence": {"type": "number"}
    },
    "required": ["label", "confidence"]
}
result = adapter.generate_object("Classify this.", schema=schema)

# Forcing a specific generation method
from phoenix.evals.llm.types import ObjectGenerationMethod

# Use structured output only
result = adapter.generate_object(
    prompt, schema=schema, method=ObjectGenerationMethod.STRUCTURED_OUTPUT
)

# Use tool calling only
result = adapter.generate_object(
    prompt, schema=schema, method=ObjectGenerationMethod.TOOL_CALLING
)

Code Reference

Symbol	Kind	Location	Lines
GoogleGenAIRateLimitError	Exception	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	15-16
identify_google_genai_client()	Function	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	19-24
get_google_genai_rate_limit_errors()	Function	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	27-28
GoogleGenAIAdapter	Class	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	41-578
GoogleGenAIAdapter.generate_text()	Method	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	104-139
GoogleGenAIAdapter.async_generate_text()	Method	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	141-178
GoogleGenAIAdapter.generate_object()	Method	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	180-217
GoogleGenAIAdapter.async_generate_object()	Method	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	219-255
GoogleGenAIAdapter._handle_api_error()	Method	packages/phoenix-evals/src/phoenix/evals/llm/adapters/google/adapter.py	567-578

I/O Contract

generate_text / async_generate_text

Direction	Type	Description
Input	Union[PromptLike, MultimodalPrompt]	A string prompt, list of message dicts, list of Message TypedDicts, or legacy MultimodalPrompt
Input	**kwargs	Additional keyword arguments forwarded to client.models.generate_content() (including optional config)
Output	str	The .text attribute from the Google GenAI response object
Raises	ValueError	If sync method is called on async client (or vice versa), or if response has no text attribute
Raises	GoogleGenAIRateLimitError	If the API returns HTTP 429 or RESOURCE_EXHAUSTED

generate_object / async_generate_object

Direction	Type	Description
Input	Union[PromptLike, MultimodalPrompt]	A prompt in any supported format
Input	Dict[str, Any]	A JSON schema defining the expected output structure
Input	ObjectGenerationMethod	AUTO (default: tries structured output, falls back to tool calling), STRUCTURED_OUTPUT, or TOOL_CALLING
Output	Dict[str, Any]	Parsed JSON dict from structured output, or function call args from tool calling
Raises	ValueError	If schema validation fails, no function call in response, or both methods fail under AUTO

Usage Examples

Automatic Object Generation Fallback

# AUTO mode tries structured output first, falls back to tool calling
adapter = GoogleGenAIAdapter(client=client, model="gemini-2.0-flash")

schema = {
    "type": "object",
    "properties": {"label": {"type": "string"}},
    "required": ["label"],
    "description": "Classification result"
}

# If structured output fails, the adapter will transparently retry with tool calling
result = adapter.generate_object("Classify this text.", schema=schema)
print(result)  # {"label": "positive"}

System Instruction Handling

from phoenix.evals.llm.prompts import Message, MessageRole

messages = [
    Message(role=MessageRole.SYSTEM, content="You are a classification expert."),
    Message(role=MessageRole.USER, content="Is this text positive or negative?"),
]

# System message is extracted and passed as system_instruction config parameter
response = adapter.generate_text(messages)

Related Pages

• Arize_ai_Phoenix_LLM_Base_Types - Abstract base class BaseLLMAdapter and core type definitions
• Arize_ai_Phoenix_Anthropic_Adapter - Anthropic adapter following the same interface
• Arize_ai_Phoenix_OpenAI_Adapter - OpenAI adapter following the same interface
• Arize_ai_Phoenix_LLM_Prompts - Prompt template and message abstraction layer
• Arize_ai_Phoenix_Evals_Rate_Limiters - Rate limiting subsystem consuming GoogleGenAIRateLimitError
• Arize_ai_Phoenix_Evals_Executors - Task execution framework that orchestrates adapter calls