basic_processor.go

Overview

basic_processor.go provides core functionality to prepare and populate model.LLMRequest objects with configuration data derived from an LLM agent's internal settings. The primary role of this file is to ensure that the request sent to the Large Language Model (LLM) is properly configured according to the agent's generation parameters and output schema. Additionally, it includes a generic deep cloning utility implemented using Go's reflection capabilities, which supports copying complex nested structures such as structs, slices, maps, and pointers.

This file is an internal component that interacts closely with the agent runtime and model layers, particularly focusing on configuring generation requests before they are dispatched to the underlying LLM services. It references agent context and request models to extract and apply configuration settings.

Functions and Methods

basicRequestProcessor

func basicRequestProcessor(ctx agent.InvocationContext, req *model.LLMRequest) error

• Purpose:
  Populates a given LLMRequest with generation configuration data extracted from the invoking agent's internal settings. This configures how the LLM will generate content based on agent-specific parameters.

• Parameters:

  • ctx agent.InvocationContext: The current invocation context containing the agent instance and runtime state.

  • req *model.LLMRequest: Pointer to the LLM request object that needs to be populated with generation configuration.

• Returns:

  • error: Returns nil if successful or no action is necessary; otherwise, could theoretically return an error for invalid states (though current code never returns an error).

• Behavior:

  • Retrieves the agent instance as an LLM agent via asLLMAgent.

  • If the agent is not an LLM agent, it does nothing and returns.

  • Clones the agent's GenerateContentConfig into the request’s Config field using the clone function.

  • If no config exists, initializes an empty genai.GenerateContentConfig.

  • If the agent has an output schema, it sets the response schema and MIME type to expect JSON.

  • Contains a TODO comment for future implementation of LiveConnectConfig population.

• Usage Example:

var req model.LLMRequest
err := basicRequestProcessor(ctx, &req)
if err != nil {
    // Handle error
}
// req is now populated with LLM generation config

clone

func clone[M any](src M) M

• Purpose:
  Creates a deep copy of the given source object src. This is a generic function that works for any type M but does not support types with unexported fields (will panic if encountered).

• Parameters:

  • src M: The source object to clone.

• Returns:

  • M: A deep copy of the source object.

• Implementation Details:

  • Uses reflection to inspect and copy the underlying structure.

  • Handles nil pointers gracefully by returning a zero-value.

  • Dereferences pointers to copy the underlying value.

  • Creates a new instance of the same type and recursively copies fields via deepCopy.

  • Returns either a pointer or value depending on the input.

• Important Notes:

  • The function panics if it encounters unexported struct fields because they are inaccessible via reflection.

  • Suitable for cloning configuration structs that are fully exported.

deepCopy

func deepCopy(src, dst reflect.Value)

• Purpose:
  Helper function used by clone to recursively copy the contents of src to dst using reflection.

• Parameters:

  • src reflect.Value: The source value to copy from.

  • dst reflect.Value: The destination value to copy to.

• Returns:

  • None. Modifies dst in place.

• Implementation Details:

  • Handles different kinds of values:

    • Struct: Iterates over exported fields, recursively copying each.

    • Slice: Creates a new slice and copies each element recursively.

    • Map: Creates a new map and copies keys and values recursively.

    • Pointer: Creates a new pointer and copies the underlying value recursively.

    • Basic Types: Copies values directly.

  • Panics if an unexported struct field is encountered.

  • Handles nil slices, maps, and pointers by leaving dst zero-valued.

Important Implementation Details

• The cloning approach relies heavily on Go's reflection package, enabling deep copy of arbitrarily nested objects without manually writing copy logic for each type.

• Unexported struct fields cause a panic because Go's reflection cannot access them, which is explicitly checked to avoid silent failures.

• The basicRequestProcessor function depends on an internal method asLLMAgent to cast the generic agent interface to an LLM-specific agent. This is critical for extracting generation configurations.

• The basicRequestProcessor currently does not implement population of LiveConnectConfig, which is noted as a TODO for future enhancement.

• The design assumes that model.LLMRequest is a central data structure for LLM invocation requests and that genai.GenerateContentConfig holds generation parameters and schemas relevant to the LLM response format.

Interaction with Other System Components

• Agent Invocation Context (agent.InvocationContext): Provides the runtime context for the agent invocation, including access to the underlying agent instance. This is important for retrieving agent-specific LLM generation settings.

• LLM Agent (asLLMAgent): An internal interface or adapter that exposes LLM-specific properties such as generation config and output schema. This interface is critical to customize request configuration per agent.

• Model Layer (model.LLMRequest): Represents the request object sent to LLM services. This file populates its Config field, which directly impacts how the LLM generates text.

• Generation Config (genai.GenerateContentConfig): The configuration object that specifies parameters like output schema and MIME type for the LLM generation request.

• This file serves as a foundational piece in the LLM Integration and Agents topic, particularly in preparing requests for LLM calls.

• It is indirectly related to Agent Invocation Context by utilizing the invocation context to access agent information.

Visual Diagram

classDiagram
class basicRequestProcessor {
+InvocationContext ctx
+*LLMRequest req
+error
}
class clone {
+M src
+M
}
class deepCopy {
+reflect.Value src
+reflect.Value dst
+void
}
basicRequestProcessor --> clone : uses
clone --> deepCopy : calls

The diagram illustrates the functional relationships within the file: the main processor function calls clone to copy config data, which in turn calls deepCopy to recursively realize the deep copy operation.

References

• The agent lifecycle and context concepts are detailed in Agent Invocation Context.

• The LLM configuration concepts relate to LLM Agent Configuration.

• Deep cloning of configuration objects is relevant to ensuring immutability and isolation in LLM Integration and Agents.

• The design aligns with the modular agent framework in AI Agent Framework.