1package provider
2
3import (
4 "encoding/json"
5 "fmt"
6 "maps"
7 "os"
8 "strings"
9)
10
11// UserModelsFile is the JSON format for user-defined models.
12// Place a models.json in $ZOT_HOME to add models that aren't in the
13// baked-in catalog or to override catalog entries. Custom providers
14// (not in the built-in set) may specify a baseUrl and api format at
15// the provider level:
16//
17// {
18// "providers": {
19// "my-company": {
20// "baseUrl": "https://llm.mycompany.com/v1",
21// "api": "openai",
22// "models": [
23// {
24// "id": "company-llm-v2",
25// "name": "Company LLM v2",
26// "contextWindow": 128000,
27// "maxTokens": 32000
28// }
29// ]
30// }
31// }
32// }
33type UserModelsFile struct {
34 Providers map[string]UserProvider `json:"providers"`
35}
36
37// UserProvider groups models under a provider key.
38type UserProvider struct {
39 BaseURL string `json:"baseUrl,omitempty"`
40 API string `json:"api,omitempty"` // "openai" (default), "openai-responses", or "anthropic"
41 Models []UserModel `json:"models"`
42}
43
44// CustomProviderConfig holds runtime config for a user-defined provider
45// that isn't part of the built-in catalog.
46type CustomProviderConfig struct {
47 BaseURL string
48 API string // "openai", "openai-responses", or "anthropic"
49}
50
51var customProviders = map[string]CustomProviderConfig{}
52
53// CustomProviders returns the set of user-defined providers loaded from
54// models.json. Keys are provider names; values carry the base URL and
55// wire-format hint.
56func CustomProviders() map[string]CustomProviderConfig { return customProviders }
57
58// UserModel is a single model entry in the user's models.json.
59type UserModel struct {
60 ID string `json:"id"`
61 Name string `json:"name"`
62 Reasoning bool `json:"reasoning"`
63 ReasoningLevelMap map[string]string `json:"reasoningLevelMap,omitempty"`
64 ContextWindow int `json:"contextWindow"`
65 MaxTokens int `json:"maxTokens"`
66 PriceInput float64 `json:"priceInput"`
67 PriceOutput float64 `json:"priceOutput"`
68 PriceCacheRead float64 `json:"priceCacheRead"`
69 PriceCacheWrite float64 `json:"priceCacheWrite"`
70 BaseURL string `json:"baseUrl,omitempty"`
71 Input []string `json:"input"` // informational only
72 API string `json:"api"` // informational only
73}
74
75func normalizeReasoningLevelMap(levelMap map[string]string, modelRef string) (map[string]string, []string) {
76 if levelMap == nil {
77 return nil, nil
78 }
79 normalized := make(map[string]string, len(levelMap))
80 var warnings []string
81 for rawLevel, rawTarget := range levelMap {
82 level := NormalizeReasoning(rawLevel)
83 if reasoningLevelRank(level) == 0 {
84 warnings = append(warnings, fmt.Sprintf("models.json: %s reasoningLevelMap has unknown level %q; entry ignored", modelRef, rawLevel))
85 continue
86 }
87 target := NormalizeReasoning(rawTarget)
88 if rawTarget != "" && target == "" {
89 // Explicit off aliases remove the level just like an empty value.
90 normalized[level] = ""
91 continue
92 }
93 if target != "" && reasoningLevelRank(target) == 0 {
94 warnings = append(warnings, fmt.Sprintf("models.json: %s reasoningLevelMap has unknown target %q; entry ignored", modelRef, rawTarget))
95 continue
96 }
97 normalized[level] = target
98 }
99 return normalized, warnings
100}
101
102// LoadUserModels reads a models.json file and returns the models
103// converted to the internal Model type. Returns nil on any error
104// (missing file, bad JSON, etc.) so the caller can treat it as
105// optional without error handling.
106func LoadUserModels(path string) []Model {
107 models, _ := LoadUserModelsWithWarnings(path)
108 return models
109}
110
111// LoadUserModelsWithWarnings is like LoadUserModels but also returns
112// human-readable warnings about every recoverable issue it found in
113// the file (unknown provider id, empty model id, malformed JSON for a
114// single provider block, etc.). The caller is responsible for
115// surfacing the warnings; the file is never rejected wholesale unless
116// the top-level JSON itself fails to parse.
117func LoadUserModelsWithWarnings(path string) ([]Model, []string) {
118 var warnings []string
119 data, err := os.ReadFile(path)
120 if err != nil {
121 return nil, nil
122 }
123 var file UserModelsFile
124 if err := json.Unmarshal(data, &file); err != nil {
125 warnings = append(warnings, fmt.Sprintf("models.json: parse error: %v (file ignored)", err))
126 return nil, warnings
127 }
128
129 var out []Model
130 // Reset custom providers on each load so removed entries don't linger.
131 customProviders = map[string]CustomProviderConfig{}
132 for providerName, prov := range file.Providers {
133 if providerName == "" {
134 warnings = append(warnings, "models.json: empty provider key skipped")
135 continue
136 }
137 // Normalize legacy transport aliases to their provider names.
138 normalized := providerName
139 switch providerName {
140 case "openai-responses":
141 normalized = "openai"
142 case "anthropic-messages":
143 normalized = "anthropic"
144 case "moonshot", "moonshot-ai", "kimi-code":
145 normalized = "kimi"
146 case "deepseek-chat", "deepseek-ai":
147 normalized = "deepseek"
148 }
149
150 // Register custom providers that carry endpoint metadata either at
151 // the provider level or on any model. Model-level baseUrl-only
152 // configs still need a custom provider entry so Resolve/NewClient
153 // accept the provider name and choose a wire format.
154 hasModelBaseURL := false
155 for _, um := range prov.Models {
156 if um.BaseURL != "" {
157 hasModelBaseURL = true
158 break
159 }
160 }
161 if prov.BaseURL != "" || prov.API != "" || hasModelBaseURL {
162 api := strings.ToLower(strings.TrimSpace(prov.API))
163 if api == "" {
164 api = "openai"
165 }
166 // Normalize common aliases for the wire format.
167 switch api {
168 case "openai-completions", "openai-chat", "chat", "openai":
169 api = "openai"
170 case "openai-responses", "responses":
171 api = APIResponses
172 case "anthropic-messages", "messages", "anthropic":
173 api = "anthropic"
174 default:
175 warnings = append(warnings, fmt.Sprintf("models.json: provider %q has unknown api %q; defaulting to openai", providerName, prov.API))
176 api = "openai"
177 }
178 customProviders[normalized] = CustomProviderConfig{
179 BaseURL: prov.BaseURL,
180 API: api,
181 }
182 }
183
184 for i, um := range prov.Models {
185 if um.ID == "" {
186 warnings = append(warnings, fmt.Sprintf("models.json: provider %q entry #%d has empty id; skipped", providerName, i))
187 continue
188 }
189 if um.ContextWindow < 0 || um.MaxTokens < 0 {
190 warnings = append(warnings, fmt.Sprintf("models.json: %s/%s has negative contextWindow/maxTokens; clamped to 0", normalized, um.ID))
191 if um.ContextWindow < 0 {
192 um.ContextWindow = 0
193 }
194 if um.MaxTokens < 0 {
195 um.MaxTokens = 0
196 }
197 }
198 levelMap, levelWarnings := normalizeReasoningLevelMap(um.ReasoningLevelMap, normalized+"/"+um.ID)
199 warnings = append(warnings, levelWarnings...)
200 if !um.Reasoning && len(levelMap) > 0 {
201 warnings = append(warnings, fmt.Sprintf("models.json: %s reasoningLevelMap ignored because reasoning is false", normalized+"/"+um.ID))
202 levelMap = nil
203 }
204
205 // Propagate provider-level BaseURL to models without their own.
206 modelBaseURL := um.BaseURL
207 if modelBaseURL == "" {
208 modelBaseURL = prov.BaseURL
209 }
210 modelAPI := ""
211 if cfg, ok := customProviders[normalized]; ok {
212 modelAPI = cfg.API
213 }
214 m := Model{
215 Provider: normalized,
216 ID: um.ID,
217 DisplayName: um.Name,
218 API: modelAPI,
219 ContextWindow: um.ContextWindow,
220 MaxOutput: um.MaxTokens,
221 Reasoning: um.Reasoning,
222 ReasoningLevelMap: levelMap,
223 PriceInput: um.PriceInput,
224 PriceOutput: um.PriceOutput,
225 PriceCacheRead: um.PriceCacheRead,
226 PriceCacheWrite: um.PriceCacheWrite,
227 BaseURL: modelBaseURL,
228 Source: "user",
229 }
230 if m.DisplayName == "" {
231 m.DisplayName = m.ID
232 }
233 out = append(out, m)
234 }
235 }
236 return out, warnings
237}
238
239// SetUserModels merges user-defined models into the active catalog.
240// User models take precedence over both the baked-in catalog and
241// live-discovered models.
242func SetUserModels(models []Model) {
243 if len(models) == 0 {
244 return
245 }
246 activeMu.Lock()
247 defer activeMu.Unlock()
248
249 // Ensure the active overlay starts from the full built-in catalog
250 // when no live/cache overlay has been applied. Otherwise a fresh
251 // install with only models.json would hide every built-in model.
252 if !activeSet || active == nil {
253 active = append([]Model(nil), Catalog...)
254 activeSet = true
255 }
256
257 // Build index of current active models.
258 byKey := func(p, id string) string { return p + "/" + id }
259 index := make(map[string]int, len(active))
260 for i, m := range active {
261 index[byKey(m.Provider, m.ID)] = i
262 }
263
264 for _, um := range models {
265 k := byKey(um.Provider, um.ID)
266 if idx, ok := index[k]; ok {
267 // Override existing entry but keep prices from user if
268 // they provided them, otherwise keep catalog prices.
269 existing := active[idx]
270 if um.PriceInput > 0 {
271 existing.PriceInput = um.PriceInput
272 }
273 if um.PriceOutput > 0 {
274 existing.PriceOutput = um.PriceOutput
275 }
276 if um.PriceCacheRead > 0 {
277 existing.PriceCacheRead = um.PriceCacheRead
278 }
279 if um.PriceCacheWrite > 0 {
280 existing.PriceCacheWrite = um.PriceCacheWrite
281 }
282 if um.DisplayName != "" {
283 existing.DisplayName = um.DisplayName
284 }
285 if um.ContextWindow > 0 {
286 existing.ContextWindow = um.ContextWindow
287 }
288 if um.MaxOutput > 0 {
289 existing.MaxOutput = um.MaxOutput
290 }
291 existing.Reasoning = um.Reasoning
292 if um.ReasoningLevelMap != nil {
293 existing.ReasoningLevelMap = maps.Clone(um.ReasoningLevelMap)
294 }
295 if um.API != "" {
296 existing.API = um.API
297 }
298 if um.BaseURL != "" {
299 existing.BaseURL = um.BaseURL
300 }
301 existing.Source = "user"
302 existing.Speculative = false
303 active[idx] = existing
304 } else {
305 // New model not in catalog.
306 active = append(active, um)
307 }
308 }
309}