translator

package
v8.0.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package translator provides types and functions for converting chat requests and responses between different schemas.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HasNonStreamResponseTransformer

func HasNonStreamResponseTransformer(from, to Format) bool

HasNonStreamResponseTransformer inspects the default registry for a non-streaming response translator.

func HasNonStreamResponseTransformerByFormatName

func HasNonStreamResponseTransformerByFormatName(from, to Format) bool

HasNonStreamResponseTransformerByFormatName reports whether a non-stream response translator exists between two schemas.

func HasPluginHooks

func HasPluginHooks() bool

HasPluginHooks reports whether hooks are installed on the default registry.

func HasRequestTransformer

func HasRequestTransformer(from, to Format) bool

HasRequestTransformer inspects the default registry.

func HasRequestTransformerByFormatName

func HasRequestTransformerByFormatName(from, to Format) bool

HasRequestTransformerByFormatName reports whether a request translator exists between two schemas.

func HasResponseTransformer

func HasResponseTransformer(from, to Format) bool

HasResponseTransformer inspects the default registry.

func HasResponseTransformerByFormatName

func HasResponseTransformerByFormatName(from, to Format) bool

HasResponseTransformerByFormatName reports whether a response translator exists between two schemas.

func HasStreamResponseTransformer

func HasStreamResponseTransformer(from, to Format) bool

HasStreamResponseTransformer inspects the default registry for a streaming response translator.

func HasStreamResponseTransformerByFormatName

func HasStreamResponseTransformerByFormatName(from, to Format) bool

HasStreamResponseTransformerByFormatName reports whether a stream response translator exists between two schemas.

func NormalizeRequest

func NormalizeRequest(ctx context.Context, from, to Format, model string, body []byte, stream bool) []byte

NormalizeRequest executes registered plugin request normalizer hooks on the default registry.

func Register

func Register(from, to Format, request RequestTransform, response ResponseTransform)

Register attaches transforms to the default registry.

func RegisterRequestEnvelope

func RegisterRequestEnvelope(from, to Format, request RequestEnvelopeTransform)

RegisterRequestEnvelope stores an envelope-aware transform on the default registry.

func SetPluginHooks

func SetPluginHooks(hooks PluginHooks)

SetPluginHooks stores plugin hooks on the default registry.

func TranslateNonStream

func TranslateNonStream(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []byte

TranslateNonStream is a helper on the default registry.

func TranslateNonStreamByFormatName

func TranslateNonStreamByFormatName(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []byte

TranslateNonStreamByFormatName converts non-streaming responses between schemas by their string identifiers.

func TranslateRequest

func TranslateRequest(from, to Format, model string, rawJSON []byte, stream bool) []byte

TranslateRequest is a helper on the default registry.

func TranslateRequestByFormatName

func TranslateRequestByFormatName(from, to Format, model string, rawJSON []byte, stream bool) []byte

TranslateRequestByFormatName converts a request payload between schemas by their string identifiers.

func TranslateStream

func TranslateStream(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) [][]byte

TranslateStream is a helper on the default registry.

func TranslateStreamByFormatName

func TranslateStreamByFormatName(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) [][]byte

TranslateStreamByFormatName converts streaming responses between schemas by their string identifiers.

func TranslateTokenCount

func TranslateTokenCount(ctx context.Context, from, to Format, count int64, rawJSON []byte) []byte

TranslateTokenCount is a helper on the default registry.

func TranslateTokenCountByFormatName

func TranslateTokenCountByFormatName(ctx context.Context, from, to Format, count int64, rawJSON []byte) []byte

TranslateTokenCountByFormatName converts token counts between schemas by their string identifiers.

func Unregister

func Unregister(from, to Format)

Unregister removes transforms for one format pair from the default registry.

Types

type Format

type Format string

Format identifies a request/response schema used inside the proxy.

const (
	FormatOpenAI         Format = "openai"
	FormatOpenAIResponse Format = "openai-response"
	FormatClaude         Format = "claude"
	FormatGemini         Format = "gemini"
	FormatCodex          Format = "codex"
	FormatAntigravity    Format = "antigravity"
	FormatInteractions   Format = "interactions"
)

Common format identifiers exposed for SDK users.

func FromString

func FromString(v string) Format

FromString converts an arbitrary identifier to a translator format.

func (Format) String

func (f Format) String() string

String returns the raw schema identifier.

type Pipeline

type Pipeline struct {
	// contains filtered or unexported fields
}

Pipeline orchestrates request/response transformation with middleware support.

func NewPipeline

func NewPipeline(registry *Registry) *Pipeline

NewPipeline constructs a pipeline bound to the provided registry.

func (*Pipeline) TranslateRequest

func (p *Pipeline) TranslateRequest(ctx context.Context, from, to Format, req RequestEnvelope) (RequestEnvelope, error)

TranslateRequest applies middleware and registry transformations.

func (*Pipeline) TranslateResponse

func (p *Pipeline) TranslateResponse(ctx context.Context, from, to Format, resp ResponseEnvelope, originalReq, translatedReq []byte, param *any) (ResponseEnvelope, error)

TranslateResponse applies middleware and registry transformations.

func (*Pipeline) UseRequest

func (p *Pipeline) UseRequest(mw RequestMiddleware)

UseRequest adds request middleware executed in registration order.

func (*Pipeline) UseResponse

func (p *Pipeline) UseResponse(mw ResponseMiddleware)

UseResponse adds response middleware executed in registration order.

type PluginHooks

type PluginHooks interface {
	NormalizeRequest(ctx context.Context, from, to Format, model string, body []byte, stream bool) []byte
	TranslateRequest(ctx context.Context, from, to Format, model string, body []byte, stream bool) ([]byte, bool)
	NormalizeResponseBefore(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, body []byte, stream bool) []byte
	TranslateResponse(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, body []byte, stream bool) ([]byte, bool)
	NormalizeResponseAfter(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, body []byte, stream bool) []byte
}

PluginHooks defines optional translator extension hooks provided by plugins.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages translation functions across schemas.

func Default

func Default() *Registry

Default exposes the package-level registry for shared use.

func NewRegistry

func NewRegistry() *Registry

NewRegistry constructs an empty translator registry.

func (*Registry) HasNonStreamResponseTransformer

func (r *Registry) HasNonStreamResponseTransformer(from, to Format) bool

HasNonStreamResponseTransformer indicates whether a non-streaming response translator exists.

func (*Registry) HasPluginHooks

func (r *Registry) HasPluginHooks() bool

HasPluginHooks reports whether request or response translation hooks are installed.

func (*Registry) HasRequestTransformer

func (r *Registry) HasRequestTransformer(from, to Format) bool

HasRequestTransformer indicates whether a request translator exists.

func (*Registry) HasResponseTransformer

func (r *Registry) HasResponseTransformer(from, to Format) bool

HasResponseTransformer indicates whether a response translator exists.

func (*Registry) HasStreamResponseTransformer

func (r *Registry) HasStreamResponseTransformer(from, to Format) bool

HasStreamResponseTransformer indicates whether a streaming response translator exists.

func (*Registry) NormalizeRequest

func (r *Registry) NormalizeRequest(ctx context.Context, from, to Format, model string, body []byte, stream bool) []byte

NormalizeRequest executes registered plugin request normalizer hooks, returning the payload unmodified if no hooks are registered.

func (*Registry) Register

func (r *Registry) Register(from, to Format, request RequestTransform, response ResponseTransform)

Register stores request/response transforms between two formats.

func (*Registry) RegisterRequestEnvelope

func (r *Registry) RegisterRequestEnvelope(from, to Format, request RequestEnvelopeTransform)

RegisterRequestEnvelope stores a request transform that consumes the complete request envelope, including request-scoped model metadata.

func (*Registry) SetPluginHooks

func (r *Registry) SetPluginHooks(hooks PluginHooks)

SetPluginHooks stores translator plugin hooks for this registry.

func (*Registry) TranslateNonStream

func (r *Registry) TranslateNonStream(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []byte

TranslateNonStream applies the registered non-stream response translator.

func (*Registry) TranslateRequest

func (r *Registry) TranslateRequest(from, to Format, model string, rawJSON []byte, stream bool) []byte

TranslateRequest converts a payload between schemas, returning the original payload if no translator is registered. When falling back to the original payload, the "model" field is still updated to match the resolved model name so that client-side prefixes (e.g. "copilot/gpt-5-mini") are not leaked upstream.

func (*Registry) TranslateRequestEnvelope

func (r *Registry) TranslateRequestEnvelope(ctx context.Context, from, to Format, req RequestEnvelope) RequestEnvelope

TranslateRequestEnvelope translates a complete request envelope while preserving request-scoped metadata for the selected transform.

func (*Registry) TranslateStream

func (r *Registry) TranslateStream(ctx context.Context, from, to Format, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) [][]byte

TranslateStream applies the registered streaming response translator.

func (*Registry) TranslateTokenCount

func (r *Registry) TranslateTokenCount(ctx context.Context, from, to Format, count int64, rawJSON []byte) []byte

TranslateTokenCount applies the registered token count response translator.

func (*Registry) Unregister

func (r *Registry) Unregister(from, to Format)

Unregister removes the request and response transforms for one format pair. Empty parent maps are dropped so a temporary registration can be restored.

type RequestEnvelope

type RequestEnvelope struct {
	Format    Format
	Model     string
	Stream    bool
	Body      []byte
	ModelInfo *registry.ModelInfo
	// ConfigurationUpdatesChanged reports that a plugin normalizer modified Responses updates.
	ConfigurationUpdatesChanged bool
	// Err is a request-scoped translation failure. Callers must not send Body upstream when it is set.
	Err error
}

RequestEnvelope represents a request in the translation pipeline.

func TranslateRequestEnvelope

func TranslateRequestEnvelope(ctx context.Context, from, to Format, req RequestEnvelope) RequestEnvelope

TranslateRequestEnvelope translates a complete request envelope using the default registry.

type RequestEnvelopeTransform

type RequestEnvelopeTransform func(ctx context.Context, req RequestEnvelope) RequestEnvelope

RequestEnvelopeTransform translates a request while preserving request-scoped metadata.

type RequestHandler

type RequestHandler func(ctx context.Context, req RequestEnvelope) (RequestEnvelope, error)

RequestHandler performs request translation between formats.

type RequestMiddleware

type RequestMiddleware func(ctx context.Context, req RequestEnvelope, next RequestHandler) (RequestEnvelope, error)

RequestMiddleware decorates request translation.

type RequestTransform

type RequestTransform func(model string, rawJSON []byte, stream bool) ([]byte, error)

RequestTransform converts a request payload from a source schema to a target schema. A non-nil error is a request-scoped refusal. Registry.Register stores it on RequestEnvelope.Err so executors can reject the request before calling upstream. TranslateRequest still returns only the body for legacy callers.

type ResponseEnvelope

type ResponseEnvelope struct {
	Format Format
	Model  string
	Stream bool
	Body   []byte
	Chunks [][]byte
}

ResponseEnvelope represents a response in the translation pipeline.

type ResponseHandler

type ResponseHandler func(ctx context.Context, resp ResponseEnvelope) (ResponseEnvelope, error)

ResponseHandler performs response translation between formats.

type ResponseMiddleware

type ResponseMiddleware func(ctx context.Context, resp ResponseEnvelope, next ResponseHandler) (ResponseEnvelope, error)

ResponseMiddleware decorates response translation.

type ResponseNonStreamTransform

type ResponseNonStreamTransform func(ctx context.Context, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []byte

ResponseNonStreamTransform is a function type that converts a non-streaming response from a source schema to a target schema. It takes a context, the model name, the raw JSON of the original and converted requests, the raw JSON of the response, and an optional parameter. It returns the converted response as a single byte slice.

type ResponseStreamTransform

type ResponseStreamTransform func(ctx context.Context, model string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) [][]byte

ResponseStreamTransform is a function type that converts a streaming response from a source schema to a target schema. It takes a context, the model name, the raw JSON of the original and converted requests, the raw JSON of the current response chunk, and an optional parameter. It returns a slice of byte chunks containing the converted streaming response.

type ResponseTokenCountTransform

type ResponseTokenCountTransform func(ctx context.Context, count int64) []byte

ResponseTokenCountTransform is a function type that transforms a token count from a source format to a target format. It takes a context and the token count as an int64, and returns the transformed token count as bytes.

type ResponseTransform

type ResponseTransform struct {
	// Stream is the function for transforming streaming responses.
	Stream ResponseStreamTransform
	// NonStream is the function for transforming non-streaming responses.
	NonStream ResponseNonStreamTransform
	// TokenCount is the function for transforming token counts.
	TokenCount ResponseTokenCountTransform
}

ResponseTransform is a struct that groups together the functions for transforming streaming and non-streaming responses, as well as token counts.

Directories

Path Synopsis
Package builtin exposes the built-in translator registrations for SDK users.
Package builtin exposes the built-in translator registrations for SDK users.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL