llm_test.go

Overview

The llm_test.go file contains unit tests for verifying the correctness of the conversion function Genai2LLMResponse in the converters package. This function translates a genai.GenerateContentResponse—which represents a raw response generated by a language model API—into a model.LLMResponse, a more application-specific structured format used internally.

The tests ensure that various scenarios involving generation outputs, error states, log probabilities, and citation metadata are handled correctly. This validation is critical for reliable integration between the language model responses and the internal model layer, which is a foundational aspect of the LLM Integration and Agents topic.

Detailed Explanation of Components

Package

• model_test: This package is dedicated to testing the model package functionalities, particularly focusing on model data structures and conversions.

Constants

• FinishReasonStop, FinishReasonSafety, FinishReasonRecitation (type genai.FinishReason): Enumerate possible reasons why the language model finished generating content (normal stop, safety filter triggered, and recitation triggered).

• BlockedReasonSafety (type genai.BlockedReason): Enumerates a safety-related blocking reason for prompt rejection.

These constants simulate typical generation finish and blocking reasons returned by the language model API.

Test Function: TestCreateResponse

This function performs table-driven testing of the Genai2LLMResponse conversion function with multiple test cases.

Parameters

• t *testing.T: The testing framework object used to report failures.

Purpose

• To verify that Genai2LLMResponse correctly converts genai.GenerateContentResponse inputs into model.LLMResponse outputs under various conditions.

Test Setup

Several predefined reusable complex structs simulate typical and edge cases:

• emptyLogprobs: An empty log probability result.

• concreteLogprobs: A populated log probabilities result with token-level details.

• partialLogprobs: Partial log probabilities with fewer top candidates.

• citationMeta: Citation metadata with example citations.

Test Cases

Each test case contains:

• name: Test description.

• input: The input genai.GenerateContentResponse struct to be converted.

• want: The expected model.LLMResponse output struct after conversion.

The test cases cover scenarios such as:

• Responses with and without log probabilities.

• Responses indicating errors (e.g., safety triggered, recitation triggered).

• Responses with no candidates but prompt feedback blocking.

• Responses containing citation metadata.

• Normal responses with varied content and logprobs.

Test Execution

For each test case:

1. Calls converters.Genai2LLMResponse to convert the input.

2. Asserts equality on key fields:

   • AvgLogprobs (average log probabilities)

   • ErrorCode and ErrorMessage

   • FinishReason

   • Deep equality for nested complex fields:

     • Content

     • LogprobsResult

     • CitationMetadata

Failure Reporting

If any field does not match the expected value, the test logs a descriptive error specifying the mismatch.

Usage Example

t.Run("CreateWithLogprobs", func(t *testing.T) {
    got := converters.Genai2LLMResponse(&genai.GenerateContentResponse{/*...*/})
    if got.AvgLogprobs != expected {
        t.Errorf("AvgLogprobs mismatch")
    }
    // Additional assertions...
})

Important Implementation Details

• The tests rely heavily on reflect.DeepEqual for comparing nested structs such as Content, LogprobsResult, and CitationMetadata to verify comprehensive structural equality.

• The conversion function under test (Genai2LLMResponse) is expected to translate fields like Candidates, FinishReason, FinishMessage, AvgLogprobs, and optional metadata accurately.

• Error cases are distinguished by presence of FinishReason values indicating safety or recitation triggers or prompt blocking metadata.

• The test structure uses table-driven tests, a Go idiomatic pattern to concisely cover multiple scenarios with minimal code duplication.

Interaction with Other System Components

• genai package: Provides the source data structures representing raw responses from the language model API.

• model package: Defines the internal application model representation (LLMResponse) used downstream by components such as agents or session management ([80562], [80559]) for interpreting and reacting to model outputs.

• converters package: Contains the conversion logic bridging genai and model data formats. This file tests that package’s main conversion function.

This file ensures that the interface between external LLM API responses and internal application logic is robust, which is foundational for the entire LLM Integration and Agents flow.

Visual Diagram

flowchart TD
A[Input: genai.GenerateContentResponse] --> B[converters.Genai2LLMResponse]
B --> C[model.LLMResponse]
subgraph Test Verification
C --> D[Check AvgLogprobs]
C --> E[Check ErrorCode & ErrorMessage]
C --> F[Check FinishReason]
C --> G["Check Content (DeepEqual)"]
C --> H["Check LogprobsResult (DeepEqual)"]
C --> I["Check CitationMetadata (DeepEqual)"]
end
style A fill:none,stroke:none
style B fill:none,stroke:none
style C fill:none,stroke:none
style D fill:none,stroke:none
style E fill:none,stroke:none
style F fill:none,stroke:none
style G fill:none,stroke:none
style H fill:none,stroke:none
style I fill:none,stroke:none

Summary of Key Functions and Data Structures

References to Related Topics

• LLM Integration and Agents: This file is part of the integration layer that handles LLM interaction and agent coordination.

• Agent Lifecycle and Callbacks: The error and finish reason handling tested here can influence agent lifecycle events.

• Session Management: The converted LLMResponse feeds into session management workflows that track user-agent interactions.

• Instruction Template Processing and Instruction Injection: Processed LLM outputs like those tested here may be used downstream when injecting data into instruction templates or agent prompts.

This documentation provides a comprehensive understanding of llm_test.go, detailing its purpose, test cases, and role within the broader system architecture.