translate

type AnthropicBlock struct {
	Type string `json:"type"`

	// type: "text"
	Text string `json:"text,omitempty"`

	// type: "image"
	Source *AnthropicImageSource `json:"source,omitempty"`

	// type: "tool_use"
	ID    string          `json:"id,omitempty"`
	Name  string          `json:"name,omitempty"`
	Input json.RawMessage `json:"input,omitempty"`

	// type: "tool_result"
	ToolUseID string `json:"tool_use_id,omitempty"`
	// Content on tool_result is either a string or a content[] of text/image
	// blocks. We keep RawMessage for the boundary.
	ToolContent json.RawMessage `json:"content,omitempty"`
	IsError     bool            `json:"is_error,omitempty"`

	// type: "thinking" (Stage 2.6c). Thinking carries the model's reasoning
	// text; Signature is constant "shim-passthrough-v1" — shim doesn't
	// verify on roundtrip and DeepSeek discards it. See README "Errors and
	// debugging" for the no-verification posture rationale.
	Thinking  string `json:"thinking,omitempty"`
	Signature string `json:"signature,omitempty"`
}

type AnthropicImageSource struct {
	Type      string `json:"type"`       // "base64" | "url"
	MediaType string `json:"media_type"` // e.g. "image/png"
	Data      string `json:"data,omitempty"`
	URL       string `json:"url,omitempty"`
}

type AnthropicMessage struct {
	Role    string          `json:"role"`
	Content json.RawMessage `json:"content"`
}

type AnthropicRequest struct {
	Model         string             `json:"model"`
	Messages      []AnthropicMessage `json:"messages"`
	System        json.RawMessage    `json:"system,omitempty"` // string | content[]
	MaxTokens     int                `json:"max_tokens"`
	Stream        bool               `json:"stream,omitempty"`
	Temperature   *float64           `json:"temperature,omitempty"`
	TopP          *float64           `json:"top_p,omitempty"`
	StopSequences []string           `json:"stop_sequences,omitempty"`
	Tools         []AnthropicTool    `json:"tools,omitempty"`
	ToolChoice    json.RawMessage    `json:"tool_choice,omitempty"`
	Thinking      *ThinkingConfig    `json:"thinking,omitempty"`
}

type AnthropicResponse struct {
	ID           string           `json:"id"`
	Type         string           `json:"type"` // always "message"
	Role         string           `json:"role"` // always "assistant"
	Model        string           `json:"model"`
	Content      []AnthropicBlock `json:"content"`
	StopReason   string           `json:"stop_reason"`
	StopSequence *string          `json:"stop_sequence,omitempty"`
	Usage        AnthropicUsage   `json:"usage"`
}

type AnthropicTool struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema"`
}

type AnthropicUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
}

type OpenAIChoice struct {
	Index        int           `json:"index"`
	Message      OpenAIMessage `json:"message"`
	FinishReason string        `json:"finish_reason"`
}

type OpenAIContentPart struct {
	Type     string          `json:"type"` // "text" | "image_url"
	Text     string          `json:"text,omitempty"`
	ImageURL *OpenAIImageURL `json:"image_url,omitempty"`
}

type OpenAIImageURL struct {
	URL string `json:"url"`
}

type OpenAIMessage struct {
	Role             string           `json:"role"`
	Content          json.RawMessage  `json:"content,omitempty"`
	ToolCalls        []OpenAIToolCall `json:"tool_calls,omitempty"`
	ToolCallID       string           `json:"tool_call_id,omitempty"`
	ReasoningContent string           `json:"reasoning_content,omitempty"`
}

type OpenAIRequest struct {
	Model       string          `json:"model"`
	Messages    []OpenAIMessage `json:"messages"`
	MaxTokens   int             `json:"max_tokens,omitempty"`
	Temperature *float64        `json:"temperature,omitempty"`
	TopP        *float64        `json:"top_p,omitempty"`
	Stop        []string        `json:"stop,omitempty"`
	Tools       []OpenAITool    `json:"tools,omitempty"`
	ToolChoice  json.RawMessage `json:"tool_choice,omitempty"`
	Stream      bool            `json:"stream,omitempty"`
	Thinking    *ThinkingConfig `json:"thinking,omitempty"`
}

type OpenAIResponse struct {
	ID      string         `json:"id"`
	Model   string         `json:"model"`
	Choices []OpenAIChoice `json:"choices"`
	Usage   OpenAIUsage    `json:"usage"`
}

type OpenAITool struct {
	Type     string             `json:"type"` // always "function"
	Function OpenAIToolFunction `json:"function"`
}

type OpenAIToolCall struct {
	ID       string             `json:"id"`
	Type     string             `json:"type"` // always "function"
	Function OpenAIToolCallBody `json:"function"`
}

type OpenAIToolCallBody struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON-encoded string per spec
}

type OpenAIToolFunction struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters"`
}

type OpenAIUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type SSEEvent struct {
	Name string
	Data any
}

type ThinkingConfig struct {
	Type string `json:"type"`
}

type Translator interface {
	// ToUpstream builds the upstream request body. req is the parsed request;
	// raw is the original inbound bytes (the identity translator forwards them
	// verbatim, so client fields shim doesn't model survive). mappedModel is
	// the upstream model name (from Adapter.MapModel). stopCapped reports how
	// many stop sequences the dialect dropped, so the server emits the
	// loud-fail metric/log (thesis-2) while the translator stays pure. The
	// implementation owns the upstream `stream` flag for its dialect.
	ToUpstream(req *AnthropicRequest, raw []byte, mappedModel string) (body []byte, stopCapped int, err error)

	// FromUpstream converts a buffered (non-streaming) upstream response body
	// into the Anthropic-shaped response BYTES the client should receive, plus
	// normalized usage so the caller records the token delta without knowing
	// the dialect. Returning bytes (not a struct) lets the identity translator
	// forward the upstream body verbatim — lossless passthrough, no field-drop
	// from re-encoding through shim's response struct.
	FromUpstream(body []byte, originalModel string) (respBody []byte, usage AnthropicUsage, err error)

	// StreamChunks returns a pull iterator over wire-ready Anthropic SSE event
	// bytes (`event: <name>\ndata: <json>\n\n`). The caller writes + flushes
	// each chunk. usage is populated by the time next reports ok=false. The
	// implementation owns reading resp.Body; the caller has already gated on a
	// 2xx upstream status.
	StreamChunks(resp *http.Response, originalModel string) (next func() ([]byte, bool, error), usage *AnthropicUsage, err error)

	// FromUpstreamError renders a NON-2xx upstream response for the client,
	// returning the client-facing status and body. It is the error-path analog
	// of FromUpstream: the dialect — not the handler — owns how an upstream
	// failure surfaces. The OpenAI dialect re-classifies the status and emits a
	// fresh Anthropic-shaped error envelope (the OpenAI body is OpenAI-shaped,
	// may carry prompt content, and must not leak to an Anthropic client);
	// identity forwards the upstream status + body verbatim (the upstream IS
	// native Anthropic — its error is already correctly shaped, so re-wrapping
	// would only lose fidelity). The server owns logging, measurement, and the
	// write; this method owns only the dialect render.
	FromUpstreamError(upstreamStatus int, upstreamBody []byte) (clientStatus int, clientBody []byte)
}