openai_client

OpenAI ModelClient integration.

Functions

estimate_token_count(text)	Estimate the token count of a given text.
get_all_messages_content(completion)	When the n > 1, get all the messages content.
get_first_message_content(completion)	When we only need the content of the first message.
get_probabilities(completion)	Get the probabilities of each token in the completion.
handle_streaming_response(generator)	Handle the streaming response.
parse_stream_response(completion)	Parse the response of the stream API.

Classes

OpenAIClient([api_key, ...])

A component wrapper for the OpenAI API client.

get_first_message_content(completion: ChatCompletion) → str

When we only need the content of the first message. It is the default parser for chat completion.

estimate_token_count(text: str) → int

Estimate the token count of a given text.

Parameters:

text (str) – The text to estimate token count for.

Returns:

Estimated token count.

Return type:

int

parse_stream_response(completion: ChatCompletionChunk) → str

Parse the response of the stream API.

handle_streaming_response(generator: Stream[ChatCompletionChunk])

Handle the streaming response.

get_all_messages_content(completion: ChatCompletion) → List[str]

When the n > 1, get all the messages content.

get_probabilities(completion: ChatCompletion) → List[List[TokenLogProb]]

Get the probabilities of each token in the completion.

class OpenAIClient(api_key: str | None = None, chat_completion_parser: Callable[[Completion], Any] = None, input_type: Literal['text', 'messages'] = 'text', base_url: str = 'https://api.openai.com/v1/', env_api_key_name: str = 'OPENAI_API_KEY')

Bases: ModelClient

A component wrapper for the OpenAI API client.

Supports both embedding and chat completion APIs, including multimodal capabilities.

Users can: 1. Simplify use of Embedder and Generator components by passing OpenAIClient() as the model_client. 2. Use this as a reference to create their own API client or extend this class by copying and modifying the code.

Note

We recommend avoiding response_format to enforce output data type or tools and tool_choice in model_kwargs when calling the API. OpenAI’s internal formatting and added prompts are unknown. Instead: - Use OutputParser for response parsing and formatting.

For multimodal inputs, provide images in model_kwargs[“images”] as a path, URL, or list of them. The model must support vision capabilities (e.g., gpt-4o, gpt-4o-mini, o1, o1-mini).

For image generation, use model_type=ModelType.IMAGE_GENERATION and provide: - model: “dall-e-3” or “dall-e-2” - prompt: Text description of the image to generate - size: “1024x1024”, “1024x1792”, or “1792x1024” for DALL-E 3; “256x256”, “512x512”, or “1024x1024” for DALL-E 2 - quality: “standard” or “hd” (DALL-E 3 only) - n: Number of images to generate (1 for DALL-E 3, 1-10 for DALL-E 2) - response_format: “url” or “b64_json”

Parameters:

• api_key (Optional[str], optional) – OpenAI API key. Defaults to None.

• chat_completion_parser (Callable[[Completion], Any], optional) – A function to parse the chat completion into a str. Defaults to None. The default parser is get_first_message_content.

• base_url (str) – The API base URL to use when initializing the client. Defaults to “https://api.openai.com”, but can be customized for third-party API providers or self-hosted models.

• env_api_key_name (str) – The environment variable name for the API key. Defaults to “OPENAI_API_KEY”.

References

• OpenAI API Overview: https://platform.openai.com/docs/introduction

• Embeddings Guide: https://platform.openai.com/docs/guides/embeddings

• Chat Completion Models: https://platform.openai.com/docs/guides/text-generation

• Vision Models: https://platform.openai.com/docs/guides/vision

• Image Generation: https://platform.openai.com/docs/guides/images

init_sync_client()

init_async_client()

parse_chat_completion(completion: ChatCompletion | Generator[ChatCompletionChunk, None, None]) → GeneratorOutput

Parse the completion, and put it into the raw_response.

track_completion_usage(completion: ChatCompletion | Generator[ChatCompletionChunk, None, None]) → CompletionUsage

Track the chat completion usage. Use OpenAI standard API for tracking.

parse_embedding_response(response: CreateEmbeddingResponse) → EmbedderOutput

Parse the embedding response to a structure Adalflow components can understand.

Should be called in Embedder.

convert_inputs_to_api_kwargs(input: Any | None = None, model_kwargs: Dict = {}, model_type: ModelType = ModelType.UNDEFINED) → Dict

Specify the API input type and output api_kwargs that will be used in _call and _acall methods. Convert the Component’s standard input, and system_input(chat model) and model_kwargs into API-specific format. For multimodal inputs, images can be provided in model_kwargs[“images”] as a string path, URL, or list of them. The model specified in model_kwargs[“model”] must support multimodal capabilities when using images.

Parameters:

• input – The input text or messages to process

• model_kwargs – Additional parameters including: - images: Optional image source(s) as path, URL, or list of them - detail: Image detail level (‘auto’, ‘low’, or ‘high’), defaults to ‘auto’ - model: The model to use (must support multimodal inputs if images are provided)

• model_type – The type of model (EMBEDDER or LLM)

Returns:

API-specific kwargs for the model call

Return type:

Dict

parse_image_generation_response(response: List[Image]) → GeneratorOutput

Parse the image generation response into a GeneratorOutput.

call(api_kwargs: Dict = {}, model_type: ModelType = ModelType.UNDEFINED)

kwargs is the combined input and model_kwargs. Support streaming call.

async acall(api_kwargs: Dict = {}, model_type: ModelType = ModelType.UNDEFINED)

kwargs is the combined input and model_kwargs

classmethod from_dict(data: Dict[str, Any]) → T

Create an instance from previously serialized data using to_dict() method.

to_dict() → Dict[str, Any]

Convert the component to a dictionary.