Principle:BerriAI Litellm Request Construction
| Knowledge Sources | BerriAI/litellm repository |
|---|---|
| Domains | LLM Integration, Request Formatting, API Design |
| Last Updated | 2026-02-15 |
Overview
Request construction is the practice of assembling a standardized, provider-agnostic request payload that can be translated to any LLM provider's native format.
Description
Each LLM provider has its own API contract for chat completions, including different message formats, parameter names, and validation rules. Request construction addresses this by defining a single, canonical request schema -- modeled after the OpenAI Chat Completions API -- that serves as the lingua franca for all providers. The caller composes messages using typed dictionaries with well-defined roles (system, user, assistant, tool, function) and content structures (text, images, tool calls), and these are later transformed into the format required by the specific target provider.
This principle ensures that switching providers does not require rewriting message construction logic, and it provides compile-time (or static analysis) safety through typed message parameters.
Usage
Apply request construction patterns whenever:
- Building chat completion requests that must work across multiple providers.
- Constructing multi-turn conversations with mixed message roles.
- Including multimodal content (text and images) in messages.
- Using function calling or tool-use features across different providers.
- Validating request payloads before dispatching them to provider APIs.
Theoretical Basis
Request construction implements the Canonical Data Model enterprise integration pattern. The core principles are:
1. Typed Message Schema
Each message role is represented by a distinct typed structure with required and optional fields. This provides both documentation and validation.
# Pseudocode: message type hierarchy
MessageParam = Union[SystemMessage, UserMessage, AssistantMessage, ToolMessage, FunctionMessage]
SystemMessage:
role: "system" (required)
content: string (required)
name: string (optional)
UserMessage:
role: "user" (required)
content: string | List[ContentPart] (required)
name: string (optional)
AssistantMessage:
role: "assistant" (required)
content: string (optional, required if no tool_calls)
tool_calls: List[ToolCall] (optional)
function_call: FunctionCall (optional, deprecated)
ToolMessage:
role: "tool" (required)
content: string (required)
tool_call_id: string (required)
2. Content Part Composition
User messages support polymorphic content: either a plain string or a list of typed content parts (text, image URL). This enables multimodal requests within the same schema.
# Pseudocode: content part types
ContentPart = Union[TextPart, ImagePart]
TextPart:
type: "text"
text: string
ImagePart:
type: "image_url"
image_url:
url: string (URL or base64 data)
detail: "auto" | "low" | "high"
3. Request Model Aggregation
A complete request bundles the message list with generation parameters (temperature, top_p, max_tokens, etc.) into a single validated structure. The request model enforces type constraints and provides sensible defaults.
4. Forward Compatibility
The request schema uses extensible structures (extra fields are allowed) so that new provider-specific or OpenAI-specific parameters can be passed through without breaking existing code.