llm

type AuthMode string

type Capabilities struct {
	Vision                interface{} `json:"vision,omitempty" yaml:"vision,omitempty"`                                 // Supports vision/image input: bool or VisionFormat string ("openai", "claude"/"base64", "default")
	Audio                 bool        `json:"audio,omitempty" yaml:"audio,omitempty"`                                   // Supports audio input/output (multimodal audio understanding)
	STT                   bool        `json:"stt,omitempty" yaml:"stt,omitempty"`                                       // Speech-to-Text / audio transcription model (e.g. Whisper)
	ToolCalls             bool        `json:"tool_calls,omitempty" yaml:"tool_calls,omitempty"`                         // Supports tool/function calling
	Reasoning             bool        `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`                           // Supports reasoning/thinking mode (o1, DeepSeek R1)
	Streaming             bool        `json:"streaming,omitempty" yaml:"streaming,omitempty"`                           // Supports streaming responses
	JSON                  bool        `json:"json,omitempty" yaml:"json,omitempty"`                                     // Supports JSON mode
	Multimodal            bool        `json:"multimodal,omitempty" yaml:"multimodal,omitempty"`                         // Supports multimodal input
	Embedding             bool        `json:"embedding,omitempty" yaml:"embedding,omitempty"`                           // Text embedding model (e.g. text-embedding-3-large)
	ImageGeneration       bool        `json:"image_generation,omitempty" yaml:"image_generation,omitempty"`             // Image generation model (e.g. DALL-E, Seedream)
	ImageEditing          interface{} `json:"image_editing,omitempty" yaml:"image_editing,omitempty"`                   // Image editing: bool or protocol string ("multipart" = form-data /images/edits, "json" = JSON /images/generations + image field)
	OCR                   bool        `json:"ocr,omitempty" yaml:"ocr,omitempty"`                                       // OCR text extraction model (e.g. Qwen3.5-OCR, Qwen-VL-OCR)
	Decision              bool        `json:"decision,omitempty" yaml:"decision,omitempty"`                             // TypeSafe Jev: typed decision (choice/score/noul)
	TemperatureAdjustable bool        `json:"temperature_adjustable,omitempty" yaml:"temperature_adjustable,omitempty"` // Supports temperature adjustment (reasoning models typically don't)
	MaxInputTokens        int         `json:"max_input_tokens,omitempty" yaml:"max_input_tokens,omitempty"`             // Maximum input context window size (aligned with Anthropic Models API)
	MaxOutputTokens       int         `json:"max_output_tokens,omitempty" yaml:"max_output_tokens,omitempty"`           // Maximum output tokens the model can generate
}

type DecisionAnswer struct {
	Type          string             `json:"type"`
	Choice        string             `json:"choice,omitempty"`
	Score         *float64           `json:"score,omitempty"` // expected level, may be fractional (e.g. 1.28)
	Noul          *float64           `json:"noul,omitempty"`  // 0–1 probability
	Probabilities map[string]float64 `json:"probabilities,omitempty"`
	Confidence    *float64           `json:"confidence,omitempty"` // nil for noul; calibrated value for choice/score
	Legend        map[string]string  `json:"legend,omitempty"`     // score level descriptions (e.g. {"0":"Calm","1":"Frustrated"})
}

type DecisionConnector interface {
	LLMConnector
	// Decide sends a typed decision request and returns structured answers.
	Decide(req *DecisionRequest) (*DecisionResponse, error)
}

type DecisionQuestion struct {
	Type         string      `json:"type"`               // "choice" | "score" | "noul"
	Instructions string      `json:"instructions"`       // natural-language instructions for the model
	Criteria     interface{} `json:"criteria,omitempty"` // choice: map[string]string, score: []string
}

type DecisionRequest struct {
	Model     string                      `json:"model"`
	State     interface{}                 `json:"state"` // string, object, or array — required
	Questions map[string]DecisionQuestion `json:"questions"`
}

type DecisionResponse struct {
	Model   string                    `json:"model"`
	Answers map[string]DecisionAnswer `json:"answers"`
	Usage   *DecisionUsage            `json:"usage,omitempty"`
}

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

type LLMConnector interface {
	GetAuthMode() AuthMode
	GetURL() string // API base URL (host > proxy > provider default). Does NOT include endpoint paths.
	GetKey() string
	GetModel() string
	GetSupportedParams() map[string]*ParamSpec // nil → use provider-type defaults
	GetCapabilities() *Capabilities
}

type ParamSpec struct {
	Min           *float64      `json:"min,omitempty"`
	Max           *float64      `json:"max,omitempty"`
	AllowedValues []interface{} `json:"allowed_values,omitempty"`
}