transform

type BaseTransform ¶

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

BaseTransform handles protocol conversion from original format to target API style This is the first transform in the chain, converting the request format before consistency normalization and vendor-specific adjustments.

func NewBaseTransform(targetType protocol.APIType) *BaseTransform

func (t *BaseTransform) Apply(ctx *TransformContext) error

func (t *BaseTransform) Name() string

type ClaudeCodeCompatTransform ¶ added in v0.260604.1

type ClaudeCodeCompatTransform struct{}

ClaudeCodeCompatTransform normalizes "system" roles in the inbound Anthropic messages array so the request is valid for third-party Anthropic-compatible providers. Claude Code sends mid-conversation system-role entries (a non-standard extension over the bare user/assistant message contract); this transform rewrites them before forwarding so providers that reject the role do not error.

Runs as a pre-Base stage; non-Anthropic inbound request types are left untouched. The transform is a thin shell — ops.ApplyClaudeCodeCompatRoleRewrite is the position-aware operation primitive (merge into the preceding user turn, or re-role to user) and this stage only decides when to invoke it based on the inbound request type.

func NewClaudeCodeCompatTransform() *ClaudeCodeCompatTransform

func (t *ClaudeCodeCompatTransform) Apply(ctx *TransformContext) error

func (t *ClaudeCodeCompatTransform) Name() string

type ConsistencyTransform ¶

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

ConsistencyTransform applies cross-provider normalization rules to requests. These rules apply to ALL providers, regardless of vendor.

Consistency Transform handles:

• Tool Schema Normalization - Ensure type: "object", normalize properties
• Scenario Flags - Disable stream usage, thinking mode if needed
• Messages Normalization - Truncate tool_call_id to 40 chars
• Validation - Check max_tokens, temperature ranges

func NewConsistencyTransform(targetAPIStyle protocol.APIType) *ConsistencyTransform

func (t *ConsistencyTransform) Apply(ctx *TransformContext) error

func (t *ConsistencyTransform) Name() string

type OpenAICursorCompatTransform ¶ added in v0.260531.1

type OpenAICursorCompatTransform struct{}

OpenAICursorCompatTransform flattens rich content blocks in OpenAI Chat messages for Cursor-style clients that only accept plain string content.

It runs as a pre-Base stage so it sees the inbound request in its original shape — Cursor IDE always sends OpenAI Chat, so the type-switch matches and flattening happens before BaseTransform converts to the target shape. For non-Chat inbound shapes (Anthropic, Responses, Google) it is a no-op: Cursor compatibility is only meaningful when the source-of-truth message structure is OpenAI Chat.

The transform is a thin shell — ops.ApplyCursorCompatContentNormalization is the operation primitive; this stage only decides when to invoke it based on the inbound request type.

Only added to the chain when the rule's cursor_compat flag is enabled.

func NewOpenAICursorCompatTransform() *OpenAICursorCompatTransform

func (t *OpenAICursorCompatTransform) Apply(ctx *TransformContext) error

func (t *OpenAICursorCompatTransform) Name() string

type OpenAIMaxTokensRewriteTransform ¶ added in v0.260531.1

type OpenAIMaxTokensRewriteTransform struct {
	UseMaxCompletionTokens bool
	UseMaxTokens           bool
}

OpenAIMaxTokensRewriteTransform rewrites the OpenAI Chat `max_tokens` / `max_completion_tokens` field pair based on per-rule flags. It runs as a post-base stage so it sees the request in its target shape — protocol conversion (Anthropic ↔ OpenAI) has already happened by then.

Only added to the chain when at least one of the two flags is set.

func NewOpenAIMaxTokensRewriteTransform(useMaxCompletionTokens, useMaxTokens bool) *OpenAIMaxTokensRewriteTransform

func (t *OpenAIMaxTokensRewriteTransform) Apply(ctx *TransformContext) error

func (t *OpenAIMaxTokensRewriteTransform) Name() string

type RequestUnionConstraint ¶

type RequestUnionConstraint interface {
	*anthropic.MessageNewParams | *anthropic.BetaMessageNewParams |
		*openai.ChatCompletionNewParams | *responses.ResponseNewParams |
		*protocol.GoogleRequest
}

RequestUnionConstraint defines the exact set of request types accepted by the transform chain. This is a compile-time type constraint enforced via generic functions. Any attempt to pass a type not in this union will fail at compile time.

type RuleThinkingTransform ¶ added in v0.260604.1

type RuleThinkingTransform struct {
	Effort string
}

RuleThinkingTransform applies the unified thinking_effort control at the rule level. It runs as a post-base stage so the type-switch sees the upstream-bound request shape after protocol conversion.

Effort semantics are documented on ops.ApplyThinkingEffort. Only added to the chain when Effort is non-default.

func NewRuleThinkingTransform(effort string) *RuleThinkingTransform

func (t *RuleThinkingTransform) Apply(ctx *TransformContext) error

func (t *RuleThinkingTransform) Name() string

type ToolBlockTransform ¶ added in v0.260531.1

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

ToolBlockTransform strips a configured set of tools from the request's tool list. It runs as a pre-Base stage so it sees the request in its inbound shape — the names it matches are the ones the client actually sent, before any protocol conversion or vendor-specific tool renaming.

When no names are configured it is never added to the chain (see rulePreBaseTransforms).

func NewToolBlockTransform(names []string) *ToolBlockTransform

func (t *ToolBlockTransform) Apply(ctx *TransformContext) error

func (t *ToolBlockTransform) Name() string

type Transform ¶

type Transform interface {
	// Name returns the unique identifier for this transform
	Name() string

	// Apply applies the transformation to the context
	// Returns an error if the transformation fails
	Apply(ctx *TransformContext) error
}

Transform defines the interface for a single transformation step

type TransformChain ¶

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

TransformChain manages an ordered sequence of transforms

func NewTransformChain(transforms []Transform) *TransformChain

func (c *TransformChain) Add(transform Transform)

func (c *TransformChain) Execute(ctx *TransformContext) (*TransformContext, error)

func (c *TransformChain) GetTransforms() []Transform

func (c *TransformChain) Length() int

func (c *TransformChain) SetTransforms(ts []Transform)

type TransformConfig ¶ added in v0.260402.2330

type TransformConfig struct {
	// MaxTokens is the maximum output tokens allowed for the request.
	// Used by base transform when converting between protocols.
	MaxTokens int64

	// UserID is the OAuth user ID for authenticated requests.
	UserID string

	// Device is the device identifier (e.g., Claude Code device ID).
	Device string

	// OpenAIConfig holds OpenAI-specific configuration populated during transforms.
	OpenAIConfig *protocol.OpenAIConfig

	// ResponsesConfig holds Responses API-specific configuration populated during transforms.
	ResponsesConfig *protocol.OpenAIConfig
}

TransformConfig holds structured, type-safe configuration for the transform chain. Use With* option constructors to set these values.

type TransformContext ¶

type TransformContext struct {
	// Context carries the request-scoped context for cancellation and deadlines.
	// Transforms should use this instead of context.Background().
	Context context.Context

	SourceAPI protocol.APIType
	TargetAPI protocol.APIType

	RequestModel  string
	ResponseModel string

	// Request is the request being transformed.
	// Use SetRequest[T]() to update — only types satisfying RequestUnionConstraint are accepted.
	Request interface{}

	// ScenarioFlags contains configuration flags for the scenario
	ScenarioFlags *typ.ScenarioFlags

	// IsStreaming indicates if this is a streaming request
	IsStreaming bool

	// IsAdvisorRequest indicates if this is an advisor loopback request
	// Used to prevent recursive MCP tool injection
	IsAdvisorRequest bool

	// HasNativeAdvisor indicates Claude Code native advisor semantics are already
	// present in the request, so tingly-box must not inject or bridge a second advisor.
	HasNativeAdvisor bool

	// OriginalRequest stores the original request before any transformations
	OriginalRequest interface{}

	// TransformSteps records the names of transforms that have been applied
	TransformSteps []string

	// Config holds structured, type-safe configuration for the transform chain.
	Config TransformConfig

	// Provider is the canonical provider configuration for transforms that need
	// provider-aware behavior.
	Provider *typ.Provider

	// Extra allows transforms to pass arbitrary data through the chain
	Extra map[string]interface{}
}

TransformContext carries state through the transform chain

func NewTransformContext[T RequestUnionConstraint](request T, opts ...TransformOption) *TransformContext

ctx := transform.NewTransformContext(&anthropicReq,
    transform.WithProvider(provider),
    transform.WithStreaming(true),
)

func (ctx *TransformContext) Release()

type TransformOption ¶

type TransformOption func(*TransformContext)

TransformOption configures a TransformContext

func WithContext(c context.Context) TransformOption

func WithDevice(device string) TransformOption

func WithExtra(extra map[string]interface{}) TransformOption

func WithIsAdvisorRequest(isAdvisor bool) TransformOption

func WithMaxTokens(maxTokens int64) TransformOption

func WithProvider(provider *typ.Provider) TransformOption

func WithScenarioFlags(flags *typ.ScenarioFlags) TransformOption

func WithStreaming(isStreaming bool) TransformOption

func WithUserID(userID string) TransformOption

type ValidationError ¶

type ValidationError struct {
	Field   string      `json:"field"`
	Message string      `json:"message"`
	Value   interface{} `json:"value,omitempty"`
}

ValidationError represents a validation error for request parameters.

func (e *ValidationError) Error() string

type VendorTransform ¶

type VendorTransform struct{}

VendorTransform applies provider-specific request adjustments. Per-shape dispatch is a flat strings.Contains chain — uniform across all request shapes so new vendors land in one place per shape. Provider data is read from TransformContext so this transform remains stateless and reusable.

func NewVendorTransform() *VendorTransform

func (t *VendorTransform) Apply(ctx *TransformContext) error

func (t *VendorTransform) Name() string