converters.go

Overview

The converters.go file provides utility functions to convert responses from the genai API format into the internal model package's format, specifically converting genai.GenerateContentResponse objects into model.LLMResponse objects. This conversion abstracts the differences between the external LLM response representation and the internal application model, enabling seamless integration of generative AI responses into the broader system's workflows and data structures.

Function Details

Genai2LLMResponse

func Genai2LLMResponse(res *genai.GenerateContentResponse) *model.LLMResponse

Purpose

Transforms a pointer to a genai.GenerateContentResponse into a pointer to a model.LLMResponse. This function extracts relevant fields from the external response and populates the internal response structure accordingly, including handling error conditions and usage metadata.

Parameters

• res *genai.GenerateContentResponse: The raw response received from the genai API, which includes candidate content, usage metadata, grounding information, and potential error or feedback messages.

Returns

• *model.LLMResponse: A pointer to the internal LLMResponse struct populated with the extracted and mapped data from the input response.

Behavior and Usage

• Checks if the Candidates slice in the genai response contains at least one candidate and that it is non-nil.

• If the first candidate contains valid content with non-empty parts:

  • Populates an LLMResponse with the content parts, grounding metadata, finish reason, citation metadata, average log probabilities, log probabilities result, and usage metadata.

• If the candidate has no content but includes a finish reason and message:

  • Returns an LLMResponse with error codes derived from the finish reason and message.

• If no candidates are present but prompt feedback exists (indicating a block or error reason):

  • Returns an error response populated with the block reason and message from the prompt feedback.

• If none of the above conditions are met:

  • Returns a generic error response with the error code "UNKNOWN_ERROR" and message "Unknown error."

This function ensures that all relevant metadata and error information is preserved and translated into the internal format expected by the rest of the system.

Example Usage

genaiResponse := &genai.GenerateContentResponse{
    // populated from genai API call
}

llmResponse := Genai2LLMResponse(genaiResponse)
// llmResponse can now be used within the internal system's LLM handling components

Implementation Details

• The function uses defensive programming to handle multiple edge cases, such as missing candidates or absent content.

• It preserves detailed metadata including grounding information and log probabilities, which can be useful for downstream components that require provenance or probabilistic scoring.

• Error handling uses string conversion of enum-like finish reasons and explicit error messages to ensure clarity.

• The usage metadata is passed through unaltered, maintaining tracking of API usage for telemetry or billing.

Interaction with Other System Components

• This file depends on the external genai package, which provides the original LLM content generation responses.

• It converts these responses into the internal model.LLMResponse struct defined in the model package.

• The converted responses are then compatible with the larger LLM integration framework described in the LLM Integration and Agents topic, enabling agents and other components to process LLM results uniformly.

• By providing a clean conversion layer, this file decouples external API response formats from internal data models, simplifying maintenance and upgrades of the generative AI backend.

Visual Diagram

flowchart TD
A[genai.GenerateContentResponse] -->|Genai2LLMResponse| B[model.LLMResponse]
B --> C{Content Present?}
C -- Yes --> D[Populate Content, Metadata, Logprobs]
C -- No --> E{PromptFeedback Present?}
E -- Yes --> F[Populate Error from PromptFeedback]
E -- No --> G[Return Unknown Error Response]

This flowchart illustrates the decision-making process inside the Genai2LLMResponse function, showing how different branches of the input response lead to different forms of the output LLMResponse.