Adapters

Polyglot drivers are composed from small, focused adapter classes. Each adapter handles one aspect of the translation between Polyglot’s unified data model and a provider’s native HTTP format. This composition makes it straightforward to add new providers — most of the logic is shared, and only the provider-specific differences need new code.

Adapter Responsibilities

Every inference driver is built from two main translators, each of which may use additional formatters internally:

Request Translation

The request adapter converts a Polyglot InferenceRequest into an HttpRequest. It is responsible for:

Message formatting — mapping Polyglot’s typed Messages (with roles, content parts, tool calls, and tool results) into the provider’s expected structure
Body formatting — assembling the full request body including model, tools, response format, and mode-specific adjustments
HTTP request assembly — setting the URL, headers (including authentication), and body

These responsibilities are typically split across three classes:

Class Pattern	Contract	Purpose
`*MessageFormat`	`CanMapMessages`	Maps `Messages` to provider format
`*BodyFormat`	`CanMapRequestBody`	Assembles the full request body
`*RequestAdapter`	`CanTranslateInferenceRequest`	Builds the final `HttpRequest`

Response Translation

The response adapter converts raw HTTP responses back into Polyglot data objects:

Class Pattern	Contract	Purpose
`*ResponseAdapter`	`CanTranslateInferenceResponse`	Parses responses and stream deltas
`*UsageFormat`	`CanMapUsage`	Extracts token usage from response data

How They Compose

Each driver wires its adapters together in its constructor. Here is the OpenAI driver as an example:

class OpenAIDriver extends BaseInferenceRequestDriver
{
    public function __construct(
        LLMConfig $config,
        CanSendHttpRequests $httpClient,
        EventDispatcherInterface $events,
    ) {
        parent::__construct(
            config: $config,
            httpClient: $httpClient,
            events: $events,
            requestTranslator: new OpenAIRequestAdapter(
                $config,
                new OpenAIBodyFormat($config, new OpenAIMessageFormat()),
            ),
            responseTranslator: new OpenAIResponseAdapter(
                new OpenAIUsageFormat(),
            ),
        );
    }
}
// @doctest id="744b"

The BaseInferenceRequestDriver handles the shared execution logic — sending HTTP requests, reading responses, and parsing event streams. The adapters only need to handle format translation.

The Contracts

Request Side

The CanTranslateInferenceRequest contract defines a single method:

interface CanTranslateInferenceRequest
{
    public function toHttpRequest(InferenceRequest $request): HttpRequest;
}
// @doctest id="cd51"

Request adapters typically delegate body construction to a CanMapRequestBody implementation:

interface CanMapRequestBody
{
    public function toRequestBody(InferenceRequest $request): array;
}
// @doctest id="ef0b"

Message formatting is handled by CanMapMessages, which receives typed Messages and returns a provider-native array. Implementations compose a MessageMapper utility for typed iteration instead of duplicating the loop:

interface CanMapMessages
{
    public function map(Messages $messages): array;
}
// @doctest id="d193"

A typical request adapter composes these together. For example, OpenAIRequestAdapter receives a CanMapRequestBody (which itself wraps a CanMapMessages), then builds the final HTTP request with URL, headers, and the formatted body:

class OpenAIRequestAdapter implements CanTranslateInferenceRequest
{
    public function __construct(
        protected LLMConfig $config,
        protected CanMapRequestBody $bodyFormat,
    ) {}

    public function toHttpRequest(InferenceRequest $request): HttpRequest
    {
        return new HttpRequest(
            url: "{$this->config->apiUrl}{$this->config->endpoint}",
            method: 'POST',
            headers: [
                'Authorization' => "Bearer {$this->config->apiKey}",
                'Content-Type' => 'application/json; charset=utf-8',
                'Accept' => 'application/json',
            ],
            body: $this->bodyFormat->toRequestBody($request),
            options: ['stream' => $request->isStreamed()],
        );
    }
}
// @doctest id="beb6"

Response Side

The CanTranslateInferenceResponse contract handles both synchronous and streaming responses:

interface CanTranslateInferenceResponse
{
    public function fromResponse(HttpResponse $response): ?InferenceResponse;

    /** @return iterable<PartialInferenceDelta> */
    public function fromStreamDeltas(
        iterable $eventBodies,
        ?HttpResponse $responseData = null,
    ): iterable;

    public function toEventBody(string $data): string|bool;
}
// @doctest id="c91e"

The toEventBody() method extracts the payload from an SSE line (stripping the data: prefix, detecting [DONE] markers). The fromStreamDeltas() method parses a sequence of those payloads into PartialInferenceDelta objects carrying incremental content, tool call fragments, and usage snapshots. Usage extraction is handled by CanMapUsage:

interface CanMapUsage
{
    public function fromData(array $data): InferenceUsage;
}
// @doctest id="148b"

Different providers report token usage under different keys and with different granularity. Some include cache tokens or reasoning tokens, others do not. Each provider’s usage formatter encapsulates these differences into the normalized InferenceUsage object.

Embeddings Adapters

Embeddings drivers follow the same pattern with their own set of contracts:

Contract	Purpose
`EmbedRequestAdapter`	Converts `EmbeddingsRequest` to `HttpRequest`
`EmbedResponseAdapter`	Converts `HttpResponse` to `EmbeddingsResponse`
`CanMapRequestBody`	Assembles the embeddings request body
`CanMapUsage`	Extracts usage from embeddings response data

Adding a New Provider

To add support for a new provider, you typically need to create:

A message format class if the provider uses a non-OpenAI message structure
A body format class to assemble requests with any provider-specific fields
A request adapter to set the URL, headers, and authentication scheme
A response adapter to parse responses and streaming events
A usage format class if token usage is reported differently
A driver class that wires these adapters together and extends BaseInferenceRequestDriver

Many providers use OpenAI-compatible formats. In those cases, you can often reuse the OpenAI adapters directly or extend them with minimal overrides. The OpenAICompatibleDriver is designed exactly for this purpose — drivers like ollama, together, and moonshot all map to it in the bundled driver registry.

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Adapter Responsibilities

Request Translation

Response Translation

How They Compose

The Contracts

Request Side

Response Side

Embeddings Adapters

Adding a New Provider

​Adapter Responsibilities

​Request Translation

​Response Translation

​How They Compose

​The Contracts

​Request Side

​Response Side

​Embeddings Adapters

​Adding a New Provider

Adapter Responsibilities

Request Translation

Response Translation

How They Compose

The Contracts

Request Side

Response Side

Embeddings Adapters

Adding a New Provider