new-api/relaykit/relayconvert/reasoning/intent.go

package reasoning

import (
	"errors"
	"fmt"
	"strings"

	"github.com/QuantumNous/new-api/relaykit/dto"
	kitutil "github.com/QuantumNous/new-api/relaykit/relayconvert/kitutil"
)

type Effort string

const (
	EffortNone    Effort = "none"
	EffortMinimal Effort = "minimal"
	EffortLow     Effort = "low"
	EffortMedium  Effort = "medium"
	EffortHigh    Effort = "high"
	EffortXHigh   Effort = "xhigh"
	EffortMax     Effort = "max"
)

type Mode string

type Source string

// ClientError marks invalid user-supplied reasoning controls so host handlers
// can return a 4xx without classifying unrelated adapter failures as client
// errors.
type ClientError struct {
	err error
}

func (e *ClientError) Error() string { return e.err.Error() }
func (e *ClientError) Unwrap() error { return e.err }

func AsClientError(err error) error {
	if err == nil {
		return nil
	}
	var clientErr *ClientError
	if errors.As(err, &clientErr) {
		return err
	}
	return &ClientError{err: err}
}

func IsClientError(err error) bool {
	var clientErr *ClientError
	return errors.As(err, &clientErr)
}

const (
	ModeUnset    Mode = ""
	ModeEnabled  Mode = "enabled"
	ModeAdaptive Mode = "adaptive"
	ModeDisabled Mode = "disabled"
)

const (
	SourceExplicit Source = "explicit"
	SourceNative   Source = "native"
	SourceSuffix   Source = "suffix"
	SourcePivot    Source = "pivot"
)

var (
	ErrEffortConflict      = errors.New("reasoning settings conflict")
	ErrUnsupportedEffort   = errors.New("unsupported reasoning effort")
	ErrThinkingNotDisabled = errors.New("thinking cannot be disabled")
)

// Intent is the protocol-independent part of a request's reasoning controls.
// Summary visibility is intentionally independent from reasoning strength.
type Intent struct {
	Mode            Mode
	Effort          Effort
	BudgetTokens    *int
	IncludeThoughts *bool
	Source          Source
	BudgetSource    Source
}

func (i Intent) HasStrength() bool {
	return i.Mode != ModeUnset || i.Effort != "" || i.BudgetTokens != nil
}

func (i Intent) IsEmpty() bool {
	return !i.HasStrength() && i.IncludeThoughts == nil
}

// IntentFromState reconstructs a portable intent from host- or pivot-carried
// conversion state. A nil state is an empty intent.
func IntentFromState(state *dto.ReasoningConversionState) Intent {
	if state == nil {
		return Intent{}
	}
	return Intent{
		Mode:            Mode(state.Mode),
		Effort:          Effort(state.Effort),
		BudgetTokens:    state.BudgetTokens,
		IncludeThoughts: state.IncludeThoughts,
		Source:          SourceSuffix,
		BudgetSource:    SourceSuffix,
	}
}

// StateFromIntent copies the portable fields of an intent into conversion
// state. Empty intents produce nil so callers can omit the field.
func StateFromIntent(intent Intent) *dto.ReasoningConversionState {
	if intent.IsEmpty() {
		return nil
	}
	return &dto.ReasoningConversionState{
		Mode:            string(intent.Mode),
		Effort:          string(intent.Effort),
		BudgetTokens:    intent.BudgetTokens,
		IncludeThoughts: intent.IncludeThoughts,
	}
}

func ParseEffort(value string) (Effort, error) {
	effort := Effort(strings.ToLower(strings.TrimSpace(value)))
	if effort == "" {
		return "", nil
	}
	switch effort {
	case EffortNone, EffortMinimal, EffortLow, EffortMedium, EffortHigh, EffortXHigh, EffortMax:
		return effort, nil
	default:
		return "", fmt.Errorf("%w: %q", ErrUnsupportedEffort, value)
	}
}

func normalizeIntent(intent Intent) (Intent, error) {
	effort, err := ParseEffort(string(intent.Effort))
	if err != nil {
		return Intent{}, err
	}
	intent.Effort = effort

	switch intent.Mode {
	case ModeUnset, ModeEnabled, ModeAdaptive, ModeDisabled:
	default:
		return Intent{}, fmt.Errorf("unsupported reasoning mode %q", intent.Mode)
	}

	if intent.BudgetTokens != nil {
		budget := *intent.BudgetTokens
		if budget < -1 {
			return Intent{}, fmt.Errorf("thinking budget must be -1 or non-negative, got %d", budget)
		}
		if budget == 0 {
			if intent.Mode == ModeEnabled || intent.Mode == ModeAdaptive || (intent.Effort != "" && intent.Effort != EffortNone) {
				return Intent{}, fmt.Errorf("%w: zero budget disables thinking", ErrEffortConflict)
			}
			intent.Mode = ModeDisabled
			intent.Effort = EffortNone
		} else if intent.Mode == ModeDisabled || intent.Effort == EffortNone {
			return Intent{}, fmt.Errorf("%w: a non-zero budget enables thinking", ErrEffortConflict)
		} else if intent.Mode == ModeUnset {
			intent.Mode = ModeEnabled
		}
	}

	if intent.Effort == EffortNone {
		if intent.Mode == ModeEnabled || intent.Mode == ModeAdaptive {
			return Intent{}, fmt.Errorf("%w: effort none disables thinking", ErrEffortConflict)
		}
		intent.Mode = ModeDisabled
	}

	return intent, nil
}

// MergeExplicitAndSuffix combines structured request fields with a model-name
// alias. Contradictions are rejected because the alias may carry a distinct
// billing identity; silently choosing either side would make request semantics
// and accounting disagree.
func MergeExplicitAndSuffix(explicit Intent, suffix Intent, model string) (Intent, error) {
	var err error
	explicit, err = normalizeIntent(explicit)
	if err != nil {
		return Intent{}, err
	}
	suffix, err = normalizeIntent(suffix)
	if err != nil {
		return Intent{}, err
	}

	if !explicit.HasStrength() {
		if explicit.IncludeThoughts != nil {
			suffix.IncludeThoughts = explicit.IncludeThoughts
		}
		return suffix, nil
	}
	if !suffix.HasStrength() {
		if explicit.IncludeThoughts == nil {
			explicit.IncludeThoughts = suffix.IncludeThoughts
		}
		return explicit, nil
	}

	explicitDisabled := explicit.Mode == ModeDisabled || explicit.Effort == EffortNone
	suffixDisabled := suffix.Mode == ModeDisabled || suffix.Effort == EffortNone
	if explicitDisabled != suffixDisabled {
		return Intent{}, fmt.Errorf("%w for model %q: explicit fields and model suffix disagree about whether thinking is enabled", ErrEffortConflict, model)
	}
	if !explicitDisabled && explicit.Effort != "" && suffix.Effort != "" && explicit.Effort != suffix.Effort {
		return Intent{}, fmt.Errorf("%w for model %q: explicit effort %q differs from suffix effort %q", ErrEffortConflict, model, explicit.Effort, suffix.Effort)
	}
	if explicit.BudgetTokens != nil && suffix.BudgetTokens != nil && *explicit.BudgetTokens != *suffix.BudgetTokens {
		return Intent{}, fmt.Errorf("%w for model %q: explicit budget %d differs from suffix budget %d", ErrEffortConflict, model, *explicit.BudgetTokens, *suffix.BudgetTokens)
	}
	if (explicit.Effort != "" && explicit.Effort != EffortNone && suffix.BudgetTokens != nil) ||
		(explicit.BudgetTokens != nil && suffix.Effort != "" && suffix.Effort != EffortNone) {
		return Intent{}, fmt.Errorf("%w for model %q: effort and an exact suffix budget cannot both select reasoning strength", ErrEffortConflict, model)
	}

	merged := suffix
	if explicit.Mode != ModeUnset {
		merged.Mode = explicit.Mode
	}
	if explicit.Effort != "" {
		merged.Effort = explicit.Effort
	}
	if explicit.BudgetTokens != nil {
		merged.BudgetTokens = explicit.BudgetTokens
		merged.BudgetSource = explicit.BudgetSource
	}
	if explicit.IncludeThoughts != nil {
		merged.IncludeThoughts = explicit.IncludeThoughts
	}
	return normalizeIntent(merged)
}

// MergeExplicit combines two structured representations of the same request.
// A numeric budget and an effort may coexist: Claude and OpenRouter expose both
// controls, and keeping both is what lets an in-memory OpenAI pivot preserve an
// exact budget for budget-based targets while retaining an effort for
// level-based targets.
func MergeExplicit(primary Intent, secondary Intent, model string) (Intent, error) {
	var err error
	primary, err = normalizeIntent(primary)
	if err != nil {
		return Intent{}, err
	}
	secondary, err = normalizeIntent(secondary)
	if err != nil {
		return Intent{}, err
	}

	if primary.IsEmpty() {
		return secondary, nil
	}
	if secondary.IsEmpty() {
		return primary, nil
	}

	primaryDisabled := primary.Mode == ModeDisabled || primary.Effort == EffortNone
	secondaryDisabled := secondary.Mode == ModeDisabled || secondary.Effort == EffortNone
	if primary.HasStrength() && secondary.HasStrength() && primaryDisabled != secondaryDisabled {
		return Intent{}, fmt.Errorf("%w for model %q: explicit fields disagree about whether thinking is enabled", ErrEffortConflict, model)
	}
	if primary.Effort != "" && secondary.Effort != "" && primary.Effort != secondary.Effort {
		return Intent{}, fmt.Errorf("%w for model %q: explicit efforts %q and %q differ", ErrEffortConflict, model, primary.Effort, secondary.Effort)
	}
	if primary.BudgetTokens != nil && secondary.BudgetTokens != nil && *primary.BudgetTokens != *secondary.BudgetTokens {
		return Intent{}, fmt.Errorf("%w for model %q: explicit budgets %d and %d differ", ErrEffortConflict, model, *primary.BudgetTokens, *secondary.BudgetTokens)
	}

	merged := secondary
	if primary.Mode != ModeUnset {
		merged.Mode = primary.Mode
	}
	if primary.Effort != "" {
		merged.Effort = primary.Effort
	}
	if primary.BudgetTokens != nil {
		merged.BudgetTokens = primary.BudgetTokens
		merged.BudgetSource = primary.BudgetSource
	}
	if primary.IncludeThoughts != nil {
		merged.IncludeThoughts = primary.IncludeThoughts
	}
	return normalizeIntent(merged)
}

type openRouterReasoning struct {
	Enabled   *bool  `json:"enabled,omitempty"`
	Effort    string `json:"effort,omitempty"`
	MaxTokens *int   `json:"max_tokens,omitempty"`
	Exclude   *bool  `json:"exclude,omitempty"`
}

func FromOpenAIChat(req *dto.GeneralOpenAIRequest) (Intent, error) {
	if req == nil {
		return Intent{}, nil
	}

	var intent Intent
	intent.Source = SourceExplicit
	if req.ReasoningEffort != "" {
		effort, err := ParseEffort(req.ReasoningEffort)
		if err != nil {
			return Intent{}, err
		}
		intent.Effort = effort
		if effort == EffortNone {
			intent.Mode = ModeDisabled
		} else {
			intent.Mode = ModeEnabled
		}
	}

	if len(req.Reasoning) > 0 {
		var raw openRouterReasoning
		if err := kitutil.Unmarshal(req.Reasoning, &raw); err != nil {
			return Intent{}, fmt.Errorf("invalid reasoning config: %w", err)
		}
		nested := Intent{BudgetTokens: raw.MaxTokens, Source: SourceExplicit, BudgetSource: SourceExplicit}
		if raw.Enabled != nil {
			if *raw.Enabled {
				nested.Mode = ModeEnabled
			} else {
				nested.Mode = ModeDisabled
				nested.Effort = EffortNone
			}
		}
		if raw.Effort != "" {
			effort, err := ParseEffort(raw.Effort)
			if err != nil {
				return Intent{}, err
			}
			nested.Effort = effort
			if effort == EffortNone {
				nested.Mode = ModeDisabled
			} else if nested.Mode == ModeUnset {
				nested.Mode = ModeEnabled
			}
		}
		if raw.Exclude != nil {
			include := !*raw.Exclude
			nested.IncludeThoughts = &include
		}
		var err error
		intent, err = MergeExplicit(intent, nested, req.Model)
		if err != nil {
			return Intent{}, err
		}
	}

	if req.ReasoningConversion == nil {
		return normalizeIntent(intent)
	}
	pivot := Intent{
		Mode:            Mode(req.ReasoningConversion.Mode),
		Effort:          Effort(req.ReasoningConversion.Effort),
		BudgetTokens:    req.ReasoningConversion.BudgetTokens,
		IncludeThoughts: req.ReasoningConversion.IncludeThoughts,
		Source:          SourcePivot,
		BudgetSource:    SourcePivot,
	}
	if req.ReasoningEffort != "" {
		projectedEffort := OpenAIEffort(EffectiveEffort(pivot))
		if Effort(req.ReasoningEffort) == projectedEffort {
			intent.Effort = ""
			intent.Mode = ModeUnset
		}
	}
	return MergeExplicit(intent, pivot, req.Model)
}

// ApplyToOpenAIChat writes the portable portion of an intent to the OpenAI
// pivot. reasoning_effort carries level-based strength; a JSON-excluded DTO
// state retains exact budgets and summary visibility across in-process steps.
func ApplyToOpenAIChat(req *dto.GeneralOpenAIRequest, intent Intent) error {
	if req == nil {
		return nil
	}
	intent, err := normalizeIntent(intent)
	if err != nil {
		return err
	}

	if effort := OpenAIEffort(EffectiveEffort(intent)); effort != "" {
		req.ReasoningEffort = string(effort)
	}

	if intent.IsEmpty() {
		return nil
	}
	req.ReasoningConversion = &dto.ReasoningConversionState{
		Mode:            string(intent.Mode),
		Effort:          string(intent.Effort),
		BudgetTokens:    intent.BudgetTokens,
		IncludeThoughts: intent.IncludeThoughts,
	}
	return nil
}

// ApplyToOpenAIResponses writes the portable portion of an intent directly to
// a Responses request. The JSON-excluded state retains exact provider-native
// controls for any later in-process conversion.
func ApplyToOpenAIResponses(req *dto.OpenAIResponsesRequest, intent Intent) error {
	if req == nil {
		return nil
	}
	intent, err := normalizeIntent(intent)
	if err != nil {
		return err
	}

	if effort := OpenAIEffort(EffectiveEffort(intent)); effort != "" {
		summary := "detailed"
		if effort == EffortNone || (intent.IncludeThoughts != nil && !*intent.IncludeThoughts) {
			summary = ""
		}
		req.Reasoning = &dto.Reasoning{
			Effort:  string(effort),
			Summary: summary,
		}
	}

	if intent.IsEmpty() {
		return nil
	}
	state := &dto.ReasoningConversionState{
		Mode:            string(intent.Mode),
		Effort:          string(intent.Effort),
		BudgetTokens:    intent.BudgetTokens,
		IncludeThoughts: intent.IncludeThoughts,
	}
	req.ReasoningConversion = state
	return nil
}

// OpenAIEffort maps the canonical cross-provider vocabulary to the public
// OpenAI reasoning_effort vocabulary. Claude/OpenRouter "max" has no direct
// OpenAI equivalent and is represented by xhigh at that wire boundary.
func OpenAIEffort(effort Effort) Effort {
	if effort == EffortMax {
		return EffortXHigh
	}
	return effort
}

func FromOpenAIResponses(req *dto.OpenAIResponsesRequest) (Intent, error) {
	if req == nil {
		return Intent{}, nil
	}
	var intent Intent
	if req.Reasoning != nil {
		intent.Source = SourceExplicit
		if req.Reasoning.Effort != "" {
			effort, err := ParseEffort(req.Reasoning.Effort)
			if err != nil {
				return Intent{}, err
			}
			intent.Effort = effort
			intent.Mode = ModeEnabled
			if effort == EffortNone {
				intent.Mode = ModeDisabled
			}
		}
		if req.Reasoning.Summary != "" {
			include := true
			intent.IncludeThoughts = &include
		}
	}
	if req.ReasoningConversion == nil {
		return normalizeIntent(intent)
	}
	pivot := Intent{
		Mode:            Mode(req.ReasoningConversion.Mode),
		Effort:          Effort(req.ReasoningConversion.Effort),
		BudgetTokens:    req.ReasoningConversion.BudgetTokens,
		IncludeThoughts: req.ReasoningConversion.IncludeThoughts,
		Source:          SourcePivot,
		BudgetSource:    SourcePivot,
	}
	if req.Reasoning != nil && req.Reasoning.Effort != "" {
		projectedEffort := OpenAIEffort(EffectiveEffort(pivot))
		if Effort(req.Reasoning.Effort) == projectedEffort {
			intent.Effort = ""
			intent.Mode = ModeUnset
		}
	}
	return MergeExplicit(intent, pivot, req.Model)
}

func FromClaude(req *dto.ClaudeRequest) (Intent, error) {
	if req == nil {
		return Intent{}, nil
	}
	var intent Intent
	intent.Source = SourceNative
	if req.Thinking != nil {
		switch req.Thinking.Type {
		case "", "enabled":
			intent.Mode = ModeEnabled
		case "adaptive":
			intent.Mode = ModeAdaptive
		case "disabled":
			intent.Mode = ModeDisabled
			intent.Effort = EffortNone
		default:
			return Intent{}, fmt.Errorf("unsupported Claude thinking type %q", req.Thinking.Type)
		}
		intent.BudgetTokens = req.Thinking.BudgetTokens
		if req.Thinking.BudgetTokens != nil {
			budget := *req.Thinking.BudgetTokens
			if budget < 1024 {
				return Intent{}, fmt.Errorf("Claude thinking budget_tokens must be at least 1024, got %d", budget)
			}
			if req.MaxTokens != nil && uint(budget) >= *req.MaxTokens {
				return Intent{}, fmt.Errorf("Claude thinking budget_tokens must be less than max_tokens")
			}
			intent.BudgetSource = SourceNative
		}
		switch req.Thinking.Display {
		case "summarized":
			include := true
			intent.IncludeThoughts = &include
		case "omitted":
			include := false
			intent.IncludeThoughts = &include
		}
	}
	if len(req.OutputConfig) > 0 {
		var output dto.OutputConfigForEffort
		if err := kitutil.Unmarshal(req.OutputConfig, &output); err != nil {
			return Intent{}, fmt.Errorf("invalid Claude output_config: %w", err)
		}
		if output.Effort != "" {
			effort, err := ParseEffort(output.Effort)
			if err != nil {
				return Intent{}, err
			}
			intent.Effort = effort
		}
	}
	if intent.Mode == ModeDisabled && intent.Effort != "" && intent.Effort != EffortNone {
		return intent, nil
	}
	return normalizeIntent(intent)
}

func FromGemini(req *dto.GeminiChatRequest) (Intent, error) {
	if req == nil || req.GenerationConfig.ThinkingConfig == nil {
		return Intent{}, nil
	}
	config := req.GenerationConfig.ThinkingConfig
	if config.ThinkingBudget != nil && config.ThinkingLevel != "" {
		return Intent{}, fmt.Errorf("%w: Gemini thinkingBudget and thinkingLevel cannot both be set", ErrEffortConflict)
	}
	intent := Intent{
		BudgetTokens:    config.ThinkingBudget,
		IncludeThoughts: config.IncludeThoughts,
		Source:          SourceNative,
		BudgetSource:    SourceNative,
	}
	if config.ThinkingLevel != "" {
		effort, err := ParseEffort(config.ThinkingLevel)
		if err != nil {
			return Intent{}, err
		}
		intent.Effort = effort
		intent.Mode = ModeEnabled
	}
	return normalizeIntent(intent)
}

func EffectiveEffort(intent Intent) Effort {
	intent, err := normalizeIntent(intent)
	if err != nil {
		return ""
	}
	if intent.Mode == ModeDisabled {
		return EffortNone
	}
	if intent.Effort != "" {
		return intent.Effort
	}
	if intent.BudgetTokens != nil {
		return EffortFromBudget(*intent.BudgetTokens)
	}
	if intent.Mode == ModeEnabled || intent.Mode == ModeAdaptive {
		return EffortHigh
	}
	return ""
}

func EffortFromBudget(budget int) Effort {
	if budget == 0 {
		return EffortNone
	}
	if budget < 0 {
		return EffortHigh
	}
	if budget <= 1024 {
		return EffortLow
	}
	if budget <= 8192 {
		return EffortMedium
	}
	return EffortHigh
}