openai.go

package llm

import (
	"encoding/base64"
	"encoding/json"
	"fmt"
	"strings"
)

// OpenAI chat-completions format: the canonical passthrough. DeepSeek, Z.ai
// (GLM) and Kimi ride this format; quirk flags on ProviderConfig decide the
// thinking-field shape (reasoning_effort vs thinking object vs neither).

// ── request ──────────────────────────────────────────────────────────────

type oaThinking struct {
	Type string `json:"type"` // "enabled" | "disabled"
}

type oaFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type oaToolCall struct {
	ID       string     `json:"id"`
	Type     string     `json:"type"`
	Function oaFunction `json:"function"`
}

type oaMessage struct {
	Role string `json:"role"`
	// Content and ReasoningContent are pointers so the key can be present and
	// empty: nil omits it, a pointer to "" keeps it on the wire.
	Content          *string         `json:"content"` // nil keeps JSON null for tool calls
	ContentParts     []oaContentPart `json:"-"`
	ReasoningContent *string         `json:"reasoning_content,omitempty"`
	ToolCalls        []oaToolCall    `json:"tool_calls,omitempty"`
	ToolCallID       string          `json:"tool_call_id,omitempty"`
}

func (m oaMessage) MarshalJSON() ([]byte, error) {
	type alias oaMessage
	if len(m.ContentParts) == 0 {
		return json.Marshal(alias(m))
	}
	return json.Marshal(struct {
		Role             string          `json:"role"`
		Content          []oaContentPart `json:"content"`
		ReasoningContent *string         `json:"reasoning_content,omitempty"`
		ToolCalls        []oaToolCall    `json:"tool_calls,omitempty"`
		ToolCallID       string          `json:"tool_call_id,omitempty"`
	}{m.Role, m.ContentParts, m.ReasoningContent, m.ToolCalls, m.ToolCallID})
}

type oaImageURL struct {
	URL string `json:"url"`
}
type oaContentPart struct {
	Type     string      `json:"type"`
	Text     string      `json:"text,omitempty"`
	ImageURL *oaImageURL `json:"image_url,omitempty"`
	File     *oaFile     `json:"file,omitempty"`
}

type oaFile struct {
	Filename string `json:"filename"`
	FileData string `json:"file_data"`
}

// openAIContent renders ordered content parts as chat-completions parts.
func openAIContent(m Message) []oaContentPart {
	parts := make([]oaContentPart, 0, len(m.Parts))
	for _, p := range m.Parts {
		switch p.Type {
		case ContentPartImage:
			parts = append(parts, oaContentPart{Type: "image_url", ImageURL: &oaImageURL{URL: "data:" + wireMIME(p.MIMEType) + ";base64," + base64.StdEncoding.EncodeToString(p.Image)}})
		case ContentPartImageURL:
			parts = append(parts, oaContentPart{Type: "image_url", ImageURL: &oaImageURL{URL: p.URL}})
		case ContentPartDocument:
			parts = append(parts, oaContentPart{Type: "file", File: &oaFile{Filename: documentName(p), FileData: "data:application/pdf;base64," + base64.StdEncoding.EncodeToString(p.Data)}})
		default:
			parts = append(parts, oaContentPart{Type: "text", Text: p.Text})
		}
	}
	return parts
}

func openAIText(m Message) *string { return &m.Content }

type oaToolDef struct {
	Type     string          `json:"type"` // "function"
	Function json.RawMessage `json:"function"`
}

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

type oaStreamOptions struct {
	IncludeUsage bool `json:"include_usage"`
}

type oaRequest struct {
	Model               string            `json:"model"`
	Messages            []oaMessage       `json:"messages"`
	Tools               []oaToolDef       `json:"tools,omitempty"`
	MaxTokens           int               `json:"max_tokens,omitempty"`
	MaxCompletionTokens int               `json:"max_completion_tokens,omitempty"`
	Temperature         *float64          `json:"temperature,omitempty"`
	TopP                *float64          `json:"top_p,omitempty"`
	Stop                []string          `json:"stop,omitempty"`
	Stream              bool              `json:"stream,omitempty"`
	StreamOptions       *oaStreamOptions  `json:"stream_options,omitempty"`
	ReasoningEffort     string            `json:"reasoning_effort,omitempty"`
	IncludeReasoning    *bool             `json:"include_reasoning,omitempty"`
	Thinking            *oaThinking       `json:"thinking,omitempty"`
	ToolChoice          any               `json:"tool_choice,omitempty"`
	ParallelToolCalls   *bool             `json:"parallel_tool_calls,omitempty"`
	ResponseFormat      *oaResponseFormat `json:"response_format,omitempty"`
	Seed                *int              `json:"seed,omitempty"`
}

// buildOpenAIRequest renders the canonical request in OpenAI format.
func buildOpenAIRequest(cfg ProviderConfig, req *ChatRequest, model string, stream, includeStreamOptions bool) oaRequest {
	q := cfg.Quirks
	out := oaRequest{
		Model:             model,
		Stop:              req.Stop,
		Stream:            stream,
		ToolChoice:        openAIToolChoice(req.ToolChoice),
		ParallelToolCalls: parallelToolCalls(req),
		ResponseFormat:    openAIResponseFormat(req.ResponseFormat),
		Seed:              req.Seed,
	}
	// OpenAI o-series/gpt-5 models reject max_tokens in favor of
	// max_completion_tokens; everyone else keeps the classic parameter.
	if modelUsesCompletionTokens(model) {
		out.MaxCompletionTokens = req.MaxTokens
	} else {
		out.MaxTokens = req.MaxTokens
	}

	// One OpenAI system message per SystemBlock and per in-band system
	// role. Concatenating would collapse prompt-tiering (stable base +
	// volatile memory) and bust prefix cache on every memory refresh.
	msgs := make([]oaMessage, 0, len(req.Messages)+len(req.System)+1)
	appendSystem := func(text string) {
		if t := strings.TrimRight(text, "\n"); t != "" {
			s := t
			msgs = append(msgs, oaMessage{Role: "system", Content: &s})
		}
	}
	for _, b := range req.System {
		appendSystem(b.Text)
	}
	for _, m := range req.Messages {
		if m.Role == RoleSystem {
			appendSystem(m.Content)
		}
	}
	var toolImages []ContentPart // pending images from the current run of tool results
	for i, m := range req.Messages {
		switch m.Role {
		case RoleSystem:
			// already folded into the system message
			continue
		case RoleTool:
			// Chat-completions tool messages carry text only: the text parts
			// stay on the tool message and images ride a user message right
			// after the run of tool results. IsError has no wire field here.
			c := partsText(m)
			if c == "" && len(m.Parts) > 0 {
				c = "(image result attached below)" // some providers reject empty tool content
			}
			msgs = append(msgs, oaMessage{Role: "tool", Content: &c, ToolCallID: m.ToolCallID})
			if imgs := imageLikeParts(m); len(imgs) > 0 {
				toolImages = append(toolImages, TextPart("Images returned by tool call "+m.ToolCallID+":"))
				toolImages = append(toolImages, imgs...)
			}
			if i+1 < len(req.Messages) && req.Messages[i+1].Role == RoleTool {
				continue
			}
			if len(toolImages) > 0 {
				msgs = append(msgs, oaMessage{Role: "user", ContentParts: openAIContent(Message{Parts: toolImages})})
				toolImages = nil
			}
		case RoleAssistant:
			om := oaMessage{Role: "assistant", Content: openAIText(m)} // Parts are user/tool only
			// DeepSeek thinking mode requires the reasoning_content key on every
			// replayed assistant turn once the request carries tools — including
			// turns where the provider returned no reasoning of its own. Omitting
			// the key there is a 400 that poisons every later request in the tool
			// loop, so the empty echo is deliberate.
			//
			// Scope: this follows the quirk, so it applies to every assistant turn
			// of a chat-completions request that carries tools on a flagged
			// provider — including turns that made no tool call themselves, and
			// not to zai/GLM, where no documentation confirms the same requirement.
			// (A request diverted to /responses never reaches this builder: that
			// format replays reasoning as an encrypted item instead.) Whether
			// DeepSeek accepts a present-but-empty value is measured by
			// TestE2EDeepSeekEmptyReasoningEcho, not assumed here.
			if m.ReasoningContent != "" || (q.EchoReasoningWithTools && len(req.Tools) > 0) {
				rc := m.ReasoningContent
				om.ReasoningContent = &rc
			}
			for _, tc := range m.ToolCalls {
				om.ToolCalls = append(om.ToolCalls, oaToolCall{
					ID:   tc.ID,
					Type: "function",
					Function: oaFunction{
						Name:      tc.Name,
						Arguments: tc.Arguments,
					},
				})
			}
			msgs = append(msgs, om)
		default: // user
			om := oaMessage{Role: "user"}
			if len(m.Parts) == 0 {
				om.Content = openAIText(m)
			} else {
				om.ContentParts = openAIContent(m)
			}
			msgs = append(msgs, om)
		}
	}
	out.Messages = msgs

	for _, t := range req.Tools {
		fn, _ := json.Marshal(oaToolFn{Name: t.Name, Description: t.Description, Parameters: t.Parameters})
		out.Tools = append(out.Tools, oaToolDef{Type: "function", Function: fn})
	}

	// Temperature: 0 → omit (provider default); negative → explicit 0.
	// Models that only accept the default temperature never get the field.
	if req.Temperature != 0 && !modelForbidsTemperature(model) {
		t := req.Temperature
		if t < 0 {
			t = 0
		}
		out.Temperature = &t
	}
	if req.TopP != 0 && !modelForbidsTemperature(model) {
		p := req.TopP
		if p < 0 {
			p = 0
		}
		out.TopP = &p
	}

	if stream && includeStreamOptions {
		out.StreamOptions = &oaStreamOptions{IncludeUsage: true}
	}

	switch {
	case q.ThinkingObject:
		// Anthropic-style thinking object (DeepSeek, GLM).
		switch req.Thinking {
		case "enabled":
			out.Thinking = &oaThinking{Type: "enabled"}
		case "disabled":
			if q.forceThinkingModel(model) {
				// GLM-5.3+ rejects disabled outright; the documented
				// migration is enabled + reasoning_effort low.
				out.Thinking = &oaThinking{Type: "enabled"}
				if q.ReasoningEffort {
					out.ReasoningEffort = "low"
				}
			} else {
				out.Thinking = &oaThinking{Type: "disabled"}
			}
		case "low", "medium", "high", "max":
			out.Thinking = &oaThinking{Type: "enabled"}
			if q.ReasoningEffort {
				// GLM has no "medium" effort level; odek's medium maps to high.
				if req.Thinking == "medium" {
					out.ReasoningEffort = "high"
				} else {
					out.ReasoningEffort = req.Thinking
				}
			}
		}
	case q.ReasoningEffort:
		switch req.Thinking {
		case "enabled":
			out.ReasoningEffort = "medium"
		case "low", "medium", "high":
			out.ReasoningEffort = req.Thinking
		case "max":
			// "max" is the canonical highest level. OpenAI's portable
			// reasoning_effort vocabulary tops out at "high".
			out.ReasoningEffort = "high"
		case "disabled":
			// GPT-5.6 defaults to medium when the field is omitted, which
			// 400s when function tools are present. Pin none so "disabled"
			// is actually off on Chat Completions.
			if chatCompletionsRejectsReasoningWithTools(model) {
				out.ReasoningEffort = "none"
			}
			// "" → omit (provider default)
		}
	default:
		// Provider accepts neither field (Kimi, plain gateways).
	}
	if q.IncludeReasoning {
		// Gateway reasoning opt-in (OpenRouter legacy form of `reasoning: {}`).
		// Pointer so the key is absent entirely without the quirk.
		yes := true
		out.IncludeReasoning = &yes
	}

	return out
}

// reasoningEffortNonePatched returns a copy of the request with
// reasoning_effort pinned to "none" (learn-once: the provider rejected
// reasoning_effort combined with function tools).
func reasoningEffortNonePatched(r oaRequest) oaRequest {
	r.ReasoningEffort = "none"
	if r.Thinking != nil {
		r.Thinking = nil // effort and thinking object never combine here
	}
	return r
}

// ── response ─────────────────────────────────────────────────────────────

type oaRespToolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

// oaFlexString decodes a JSON string tolerantly. Gateways in the wild send
// the reasoning fields as non-string JSON values (e.g. OpenRouter reasoning
// objects); a non-string value is skipped (decodes to "") instead of failing
// the whole response parse. Null decodes to "" as well.
type oaFlexString string

func (s *oaFlexString) UnmarshalJSON(b []byte) error {
	if len(b) > 0 && b[0] == '"' {
		var v string
		if err := json.Unmarshal(b, &v); err != nil {
			return err
		}
		*s = oaFlexString(v)
		return nil
	}
	*s = "" // null, object, array, number, bool: skipped
	return nil
}

type oaRespMessage struct {
	Role             string              `json:"role"`
	Content          string              `json:"content"`
	Refusal          string              `json:"refusal"`
	ReasoningContent oaFlexString        `json:"reasoning_content"`
	Reasoning        oaFlexString        `json:"reasoning"`
	ReasoningDetails []oaReasoningDetail `json:"reasoning_details"`
	ToolCalls        []oaRespToolCall    `json:"tool_calls"`
}

// oaReasoningDetail is one entry of OpenRouter's reasoning_details array
// (docs: Reasoning Details API Shape). Only text and summary carry usable
// prose; encrypted entries are intentionally skipped.
type oaReasoningDetail struct {
	Type    string `json:"type"`
	Text    string `json:"text"`
	Summary string `json:"summary"`
}

// foldReasoning reconciles the documented OpenAI-format reasoning response
// shapes into one string: reasoning_content (LiteLLM standardized) wins, then
// the reasoning string alias, then the reasoning_details fold in array order
// (reasoning.text → text, reasoning.summary → summary, encrypted skipped).
func foldReasoning(content, reasoning string, details []oaReasoningDetail) string {
	if content != "" {
		return content
	}
	if reasoning != "" {
		return reasoning
	}
	var b strings.Builder
	for _, d := range details {
		part := d.Text
		if part == "" {
			part = d.Summary
		}
		if part == "" {
			continue
		}
		if b.Len() > 0 {
			b.WriteString("\n")
		}
		b.WriteString(part)
	}
	return b.String()
}

type oaRespChoice struct {
	Message      oaRespMessage `json:"message"`
	FinishReason string        `json:"finish_reason"`
}

type oaUsageDetails struct {
	ReasoningTokens int `json:"reasoning_tokens"`
}

type oaPromptDetails struct {
	CachedTokens int `json:"cached_tokens"`
}

type oaRespUsage struct {
	PromptTokens            int              `json:"prompt_tokens"`
	CompletionTokens        int              `json:"completion_tokens"`
	CompletionTokensDetails oaUsageDetails   `json:"completion_tokens_details"`
	CacheCreationTokens     int              `json:"cache_creation_input_tokens"`
	CacheReadTokens         int              `json:"cache_read_input_tokens"`
	PromptTokensDetails     *oaPromptDetails `json:"prompt_tokens_details"`
	PromptCacheHitTokens    int              `json:"prompt_cache_hit_tokens"`
	PromptCacheMissTokens   int              `json:"prompt_cache_miss_tokens"`
	TopCachedTokens         int              `json:"cached_tokens"` // Moonshot/Kimi: top-level, subset of prompt_tokens
}

// usageFromOpenAI maps a chat-completions usage object onto canonical
// Usage with odek applyUsage exclusive normalization: OpenAI
// cached_tokens and DeepSeek hit/miss are subsets of prompt_tokens and
// are subtracted so PromptTokens is uncached-only; Anthropic-named
// cache fields are exclusive and are not subtracted. Guards keep
// hostile payloads from driving PromptTokens negative.
func usageFromOpenAI(u *oaRespUsage) Usage {
	if u == nil {
		return Usage{}
	}
	out := Usage{
		PromptTokens:        u.PromptTokens,
		CompletionTokens:    u.CompletionTokens,
		ReasoningTokens:     u.CompletionTokensDetails.ReasoningTokens,
		CacheCreationTokens: u.CacheCreationTokens,
		CacheReadTokens:     u.CacheReadTokens,
	}
	if u.PromptTokensDetails != nil {
		out.CachedTokens = u.PromptTokensDetails.CachedTokens
		out.CacheReported = true
	}
	if u.CacheCreationTokens > 0 || u.CacheReadTokens > 0 {
		out.CacheReported = true
	}
	switch {
	case u.PromptCacheHitTokens > 0 || u.PromptCacheMissTokens > 0:
		// DeepSeek native fields (authoritative when present; DeepSeek may
		// echo the hit count as cached_tokens too). A hit is prompt content
		// read from cache; a miss is ordinary uncached input and stays in
		// PromptTokens. Guarded so hostile payloads never go negative.
		out.CacheReported = true
		if hit := u.PromptCacheHitTokens; hit <= out.PromptTokens {
			out.PromptTokens -= hit
			out.CacheReadTokens += hit
		}
	case u.CacheReadTokens > 0:
		// Anthropic-named field from a gateway, already in CacheReadTokens.
		// When the OpenAI-shaped cached_tokens rides along, prompt_tokens
		// follows OpenAI (inclusive) semantics and both fields describe the
		// same read: subtract it from the prompt once, never add it twice.
		if d := u.PromptTokensDetails; d != nil && d.CachedTokens > 0 && d.CachedTokens <= out.PromptTokens {
			out.PromptTokens -= d.CachedTokens
		}
	case u.PromptTokensDetails != nil && u.PromptTokensDetails.CachedTokens > 0 &&
		u.PromptTokensDetails.CachedTokens <= out.PromptTokens:
		out.PromptTokens -= u.PromptTokensDetails.CachedTokens
		out.CacheReadTokens += u.PromptTokensDetails.CachedTokens
	case u.TopCachedTokens > 0 && u.TopCachedTokens <= out.PromptTokens:
		// Moonshot/Kimi report the cached subset top-level.
		out.CacheReported = true
		out.CachedTokens = u.TopCachedTokens
		out.PromptTokens -= u.TopCachedTokens
		out.CacheReadTokens += u.TopCachedTokens
	}
	return out
}

type oaResponse struct {
	ID      string         `json:"id"`
	Model   string         `json:"model"`
	Choices []oaRespChoice `json:"choices"`
	Usage   *oaRespUsage   `json:"usage"`
	Error   *oaErrorBody   `json:"error"`
}

type oaErrorBody struct {
	Message string `json:"message"`
	Type    string `json:"type"`
	Code    any    `json:"code"`
}

// mapOpenAIFinishReason maps OpenAI finish_reason to canonical values.
func mapOpenAIFinishReason(s string) string {
	switch s {
	case "stop":
		return FinishStop
	case "length":
		return FinishLength
	case "tool_calls", "function_call":
		return FinishToolCalls
	case "content_filter":
		return FinishContentFilter
	case "":
		return ""
	default:
		// Non-canonical reasons never leak into the public vocabulary.
		return ""
	}
}

// parseOpenAIResponse parses a buffered chat-completions response body.
func parseOpenAIResponse(body []byte) (*ChatResult, error) {
	var r oaResponse
	if err := json.Unmarshal(body, &r); err != nil {
		return nil, fmt.Errorf("llm: parse response: %w", err)
	}
	if r.Error != nil && r.Error.Message != "" {
		return nil, fmt.Errorf("llm: provider error: %s", r.Error.Message)
	}
	if len(r.Choices) == 0 {
		return nil, fmt.Errorf("llm: response has no choices")
	}
	ch := r.Choices[0]
	res := &ChatResult{
		Content:          ch.Message.Content,
		ReasoningContent: foldReasoning(string(ch.Message.ReasoningContent), string(ch.Message.Reasoning), ch.Message.ReasoningDetails),
		FinishReason:     mapOpenAIFinishReason(ch.FinishReason),
		Refusal:          ch.Message.Refusal,
		Meta:             ResponseMeta{ID: r.ID, Model: r.Model},
	}
	for _, tc := range ch.Message.ToolCalls {
		args := tc.Function.Arguments
		if args == "" {
			args = "{}"
		}
		res.ToolCalls = append(res.ToolCalls, ToolCall{
			ID:        tc.ID,
			Name:      tc.Function.Name,
			Arguments: args,
		})
	}
	// Named tool_choice (and many gateways) report "stop" for a tool turn.
	if res.FinishReason == FinishStop && len(res.ToolCalls) > 0 {
		res.FinishReason = FinishToolCalls
	}
	res.FinishReason = refusalFinish(res.FinishReason, res.Refusal)
	if r.Usage != nil {
		res.Usage = usageFromOpenAI(r.Usage)
	}
	return res, nil
}

// ── streaming ────────────────────────────────────────────────────────────

type oaStreamDelta struct {
	Content          string              `json:"content"`
	Refusal          string              `json:"refusal"`
	ReasoningContent oaFlexString        `json:"reasoning_content"`
	Reasoning        oaFlexString        `json:"reasoning"`
	ReasoningDetails []oaReasoningDetail `json:"reasoning_details"`
	ToolCalls        []oaStreamToolCall  `json:"tool_calls"`
}

type oaStreamToolCall struct {
	Index    *int   `json:"index"` // OpenAI sends it; default 0 when absent
	ID       string `json:"id"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type oaStreamChoice struct {
	Delta        oaStreamDelta `json:"delta"`
	FinishReason string        `json:"finish_reason"`
}

type oaStreamChunk struct {
	ID      string           `json:"id"`
	Model   string           `json:"model"`
	Choices []oaStreamChoice `json:"choices"`
	Usage   *oaRespUsage     `json:"usage"`
	Error   json.RawMessage  `json:"error"` // see streamErrorMessage
}

// mapOpenAIStreamEvent folds one SSE data payload into the accumulator and
// returns the canonical deltas to emit. done reports a terminal event.
func mapOpenAIStreamEvent(data []byte, acc *streamAccum) (deltas []Delta, done bool, err error) {
	var c oaStreamChunk
	if err := json.Unmarshal(data, &c); err != nil {
		return nil, false, fmt.Errorf("llm: parse stream chunk: %w", err)
	}
	if msg, ok := streamErrorMessage(c.Error); ok {
		return nil, false, fmt.Errorf("llm: provider error: %s", msg)
	}
	acc.noteMeta(c.ID, c.Model)
	if c.Usage != nil {
		acc.usage = usageFromOpenAI(c.Usage)
	}
	for _, ch := range c.Choices {
		d := ch.Delta
		if r := foldReasoning(string(d.ReasoningContent), string(d.Reasoning), d.ReasoningDetails); r != "" {
			acc.reasoning.WriteString(r)
			deltas = append(deltas, Delta{Kind: DeltaReasoning, Text: r})
		}
		if d.Content != "" {
			acc.content.WriteString(d.Content)
			deltas = append(deltas, Delta{Kind: DeltaContent, Text: d.Content})
		}
		if d.Refusal != "" {
			acc.refusal.WriteString(d.Refusal)
			deltas = append(deltas, Delta{Kind: DeltaRefusal, Text: d.Refusal})
		}
		for _, tc := range d.ToolCalls {
			idx := acc.openAIToolKey(tc.Index, tc.ID)
			call := acc.call(idx)
			if tc.ID != "" {
				call.id = tc.ID
			}
			if tc.Function.Name != "" {
				call.name = tc.Function.Name
			}
			accDelta := Delta{Kind: DeltaToolArgs, Text: tc.Function.Arguments, ToolIndex: call.pos, ToolID: call.id, ToolName: call.name}
			call.args.WriteString(tc.Function.Arguments)
			deltas = append(deltas, accDelta)
		}
		if ch.FinishReason != "" {
			acc.finishReason = mapOpenAIFinishReason(ch.FinishReason)
			if acc.finishReason == FinishStop && len(acc.calls) > 0 {
				acc.finishReason = FinishToolCalls
			}
			acc.sawFinish = true
		}
	}
	return deltas, false, nil
}