cloakapi 1.4.1-x86_64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +160 -0
  3. data/LICENSE +202 -0
  4. data/NOTICE +18 -0
  5. data/README.md +407 -0
  6. data/THIRD-PARTY-NOTICES.md +22 -0
  7. data/TRADEMARKS.md +19 -0
  8. data/examples/fake_gateway.rb +78 -0
  9. data/examples/hello.rb +64 -0
  10. data/lib/cloakapi/_lib/linux-x86_64/libcloak_engine.so +0 -0
  11. data/lib/cloakapi/client.rb +1272 -0
  12. data/lib/cloakapi/degraded.rb +77 -0
  13. data/lib/cloakapi/disclosure.rb +252 -0
  14. data/lib/cloakapi/engine.rb +702 -0
  15. data/lib/cloakapi/errors.rb +65 -0
  16. data/lib/cloakapi/pii/bundled_rules.rb +670 -0
  17. data/lib/cloakapi/pii/card_spans.rb +300 -0
  18. data/lib/cloakapi/pii/detector.rb +1925 -0
  19. data/lib/cloakapi/pii/patterns.json +2238 -0
  20. data/lib/cloakapi/pii/pii_match.rb +7 -0
  21. data/lib/cloakapi/pii/pii_type.rb +7 -0
  22. data/lib/cloakapi/pii/ruleset.rb +65 -0
  23. data/lib/cloakapi/pii/tokenizer.rb +411 -0
  24. data/lib/cloakapi/posture.rb +82 -0
  25. data/lib/cloakapi/receipts.rb +406 -0
  26. data/lib/cloakapi/resources/chat.rb +82 -0
  27. data/lib/cloakapi/resources/messages.rb +90 -0
  28. data/lib/cloakapi/resources/models.rb +25 -0
  29. data/lib/cloakapi/resources/receipts.rb +162 -0
  30. data/lib/cloakapi/resources/reconstruct.rb +120 -0
  31. data/lib/cloakapi/resources/request_strings.rb +485 -0
  32. data/lib/cloakapi/resources/reviewable.rb +163 -0
  33. data/lib/cloakapi/resources/tokens.rb +28 -0
  34. data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
  35. data/lib/cloakapi/routing.rb +500 -0
  36. data/lib/cloakapi/streaming.rb +196 -0
  37. data/lib/cloakapi/surrogate_mode.rb +233 -0
  38. data/lib/cloakapi/version.rb +15 -0
  39. data/lib/cloakapi/warnings.rb +137 -0
  40. data/lib/cloakapi.rb +37 -0
  41. data/licenses/Apache-2.0.txt +202 -0
  42. data/licenses/CC-BY-4.0.txt +104 -0
  43. data/licenses/MIT-Faker.txt +21 -0
  44. data/licenses/MIT.txt +21 -0
  45. metadata +150 -0
@@ -0,0 +1,107 @@
1
+ {
2
+ "catalogue_version": 3,
3
+ "generated_at": "2026-07-08T04:47:06.390Z",
4
+ "source": "gateway config/providers_catalogue.php (ids) + config/billing.php provider_pricing (USD cents/1M → USD/1M) + catalogue/model-catalogue.src.json (pool/latency/benchmark) — runtime source of truth",
5
+ "unit_cost": "usd_per_1m_tokens",
6
+ "candidates": [
7
+ {
8
+ "provider": "anthropic",
9
+ "model": "claude-sonnet-5",
10
+ "cost_per_1m_input": 3,
11
+ "cost_per_1m_output": 15,
12
+ "is_local": false,
13
+ "benchmark_quality": 0.93,
14
+ "p50_latency_ms": 800
15
+ },
16
+ {
17
+ "provider": "anthropic",
18
+ "model": "claude-haiku-4-5",
19
+ "cost_per_1m_input": 1,
20
+ "cost_per_1m_output": 5,
21
+ "is_local": false,
22
+ "benchmark_quality": 0.85,
23
+ "p50_latency_ms": 400
24
+ },
25
+ {
26
+ "provider": "openai",
27
+ "model": "gpt-4o",
28
+ "cost_per_1m_input": 2.5,
29
+ "cost_per_1m_output": 10,
30
+ "is_local": false,
31
+ "benchmark_quality": 0.93,
32
+ "p50_latency_ms": 600
33
+ },
34
+ {
35
+ "provider": "openai",
36
+ "model": "gpt-4o-mini",
37
+ "cost_per_1m_input": 0.15,
38
+ "cost_per_1m_output": 0.6,
39
+ "is_local": false,
40
+ "benchmark_quality": 0.84,
41
+ "p50_latency_ms": 400
42
+ },
43
+ {
44
+ "provider": "ollama",
45
+ "model": "qwen2.5:32b",
46
+ "cost_per_1m_input": 0,
47
+ "cost_per_1m_output": 0,
48
+ "is_local": true,
49
+ "benchmark_quality": 0.86,
50
+ "p50_latency_ms": 2000
51
+ },
52
+ {
53
+ "provider": "ollama",
54
+ "model": "deepseek-v3",
55
+ "cost_per_1m_input": 0,
56
+ "cost_per_1m_output": 0,
57
+ "is_local": true,
58
+ "benchmark_quality": 0.9,
59
+ "p50_latency_ms": 3000
60
+ }
61
+ ],
62
+ "benchmark_scores": {
63
+ "anthropic:claude-opus-4-7": 0.97,
64
+ "anthropic:claude-opus-4-8": 0.97,
65
+ "anthropic:claude-sonnet-4-6": 0.93,
66
+ "anthropic:claude-sonnet-5": 0.93,
67
+ "anthropic:claude-haiku-4-5": 0.85,
68
+ "anthropic:claude-3-5-sonnet": 0.92,
69
+ "anthropic:claude-3-5-haiku": 0.84,
70
+ "openai:gpt-5": 0.96,
71
+ "openai:gpt-5.5": 0.96,
72
+ "openai:gpt-5.4": 0.95,
73
+ "openai:gpt-5-mini": 0.88,
74
+ "openai:gpt-5.4-mini": 0.84,
75
+ "openai:gpt-4o": 0.93,
76
+ "openai:gpt-4o-mini": 0.84,
77
+ "openai:gpt-4": 0.91,
78
+ "openai:o1": 0.94,
79
+ "openai:o3": 0.95,
80
+ "grok:grok-4-pro": 0.94,
81
+ "grok:grok-4": 0.9,
82
+ "grok:grok-4.3": 0.9,
83
+ "grok:grok-4-mini": 0.83,
84
+ "google:gemini-2.5-pro": 0.93,
85
+ "google:gemini-2.5-flash": 0.86,
86
+ "gemini:gemini-2.5-pro": 0.93,
87
+ "gemini:gemini-2.5-flash": 0.86,
88
+ "gemini:gemini-3.5-flash": 0.88,
89
+ "ollama:qwen2.5:72b": 0.89,
90
+ "ollama:qwen2.5:32b": 0.86,
91
+ "ollama:qwen2.5:14b": 0.82,
92
+ "ollama:qwen2.5:7b": 0.76,
93
+ "ollama:deepseek-v3": 0.9,
94
+ "ollama:deepseek-r1": 0.91,
95
+ "ollama:llama3.3:70b": 0.88,
96
+ "ollama:llama3.1:70b": 0.86,
97
+ "ollama:llama3.1:8b": 0.75,
98
+ "ollama:mistral-large": 0.88,
99
+ "ollama:mistral:7b": 0.73,
100
+ "ollama:phi-3.5:3.8b": 0.72,
101
+ "ollama:phi-4:14b": 0.83,
102
+ "ollama:gemma2:27b": 0.87,
103
+ "ollama:gemma2:9b": 0.79,
104
+ "mistral:mistral-large-2": 0.89,
105
+ "mistral:mistral-small-3": 0.78
106
+ }
107
+ }
@@ -0,0 +1,500 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "net/http"
5
+ require "uri"
6
+
7
+ module CloakAPI
8
+ # CLIENT-SIDE ARBITRAGE ROUTING + versioned catalogue (C19).
9
+ #
10
+ # Under literal relay-only the gateway does NOTHING with prompt content, so the
11
+ # arbitrage classification that used to run server-side MOVES to the client,
12
+ # which already holds the raw prompt. This is a faithful port of the TypeScript
13
+ # reference (+src/routing/arbitrage.ts+ + +catalogue.ts+), itself a port of the
14
+ # shared Rust arbitrage-router engine.
15
+ #
16
+ # The client classifies its own prompt locally (task class + vision + token
17
+ # count + quality), PICKS provider+model, and the caller declares that choice to
18
+ # the gateway (+body.provider/model+ + header +X-CloakAPI-Routing: client+).
19
+ #
20
+ # BILLING SAFETY (§31): the client's pick affects ONLY which upstream is
21
+ # relayed to. The gateway meters the ACTUALLY-relayed provider+model ×
22
+ # gateway-counted tokens × the api-key's flat markup — never values chosen here.
23
+ module Routing
24
+ STRATEGIES = %w[passthrough auto local-first cheapest fastest highest-quality].freeze
25
+
26
+ # Default catalogue URL — served same-origin with the PORTAL (app.cloakapi.io),
27
+ # NOT the gateway (api.cloakapi.io).
28
+ DEFAULT_CATALOGUE_URL = "https://app.cloakapi.io/catalogue/v1/models.json"
29
+
30
+ STALE_AFTER_MS = 6 * 60 * 60 * 1000 # 6h
31
+
32
+ # Bundled offline seed catalogue (generated-equivalent to the served one).
33
+ SEED_CATALOGUE = JSON.parse(File.read(File.join(__dir__, "routing", "bundled-catalogue.json"))).freeze
34
+ # Bundled benchmark-score map (offline scoreFor fallback).
35
+ BUNDLED_BENCHMARK_SCORES = (SEED_CATALOGUE["benchmark_scores"] || {}).freeze
36
+
37
+ CLF_BIAS = 0.0
38
+ CLF_WEIGHTS = [0.1, 0.05, 2.5, -0.3].freeze
39
+ CLF_COLD_START_MARGIN = 0.05
40
+ CLF_VERSION = "benchmark-anchor-v1-client"
41
+
42
+ TASK_ENCODING = {
43
+ "general" => 0, "summarisation" => 1, "extraction" => 2, "classification" => 3,
44
+ "translation" => 4, "code_completion" => 5, "code_generation" => 6, "reasoning" => 7,
45
+ "factual_lookup" => 8, "multimodal_vision" => 9, "multimodal_audio" => 10
46
+ }.freeze
47
+
48
+ module_function
49
+
50
+ # strategy.rs::from_header — any unknown value falls back to passthrough.
51
+ def strategy_from_header(val)
52
+ v = val.to_s.downcase
53
+ STRATEGIES.include?(v) && v != "passthrough" ? v : "passthrough"
54
+ end
55
+
56
+ def sigmoid(x) = 1.0 / (1.0 + Math.exp(-x))
57
+ def clamp(x, lo, hi) = [[x, lo].max, hi].min
58
+
59
+ def floor_increment(task)
60
+ case task
61
+ when "factual_lookup" then 0.05
62
+ when "reasoning" then 0.02
63
+ else 0.0
64
+ end
65
+ end
66
+
67
+ def task_class_encoding(task) = (TASK_ENCODING[task] || 0) / 10.0
68
+
69
+ def length_bucket(tokens)
70
+ return 0.0 if tokens <= 256
71
+ return 0.2 if tokens <= 512
72
+ return 0.4 if tokens <= 1024
73
+ return 0.6 if tokens <= 4096
74
+ return 0.8 if tokens <= 32_768
75
+
76
+ 1.0
77
+ end
78
+
79
+ # classifier.rs::logistic — P(quality_ok | features).
80
+ def predict_quality(task, input_tokens, score_delta, cost_ratio)
81
+ f0 = task_class_encoding(task)
82
+ f1 = length_bucket(input_tokens)
83
+ f2 = clamp(score_delta, -1.0, 1.0)
84
+ f3 = clamp(cost_ratio, 0.0, 1.0)
85
+ logit = CLF_BIAS + CLF_WEIGHTS[0] * f0 + CLF_WEIGHTS[1] * f1 +
86
+ CLF_WEIGHTS[2] * f2 + CLF_WEIGHTS[3] * f3
87
+ sigmoid(logit)
88
+ end
89
+
90
+ # benchmark.rs::score_for — exact, then prefix, then conservative 0.75.
91
+ def score_for(provider, model, scores = BUNDLED_BENCHMARK_SCORES)
92
+ key = "#{provider.to_s.downcase}:#{model.to_s.downcase}"
93
+ return scores[key] if scores.key?(key)
94
+
95
+ base = model.to_s.split(":").first || model.to_s
96
+ prefix = "#{provider.to_s.downcase}:#{base.downcase}"
97
+ hit = scores.keys.find { |k| k.start_with?(prefix) }
98
+ hit ? scores[hit] : 0.75
99
+ end
100
+
101
+ # router.rs::composite_score.
102
+ def composite_score(strategy, quality_prob, cost, declared_cost, latency_ms, is_local)
103
+ case strategy
104
+ when "cheapest"
105
+ declared_cost > 0.0 ? 1.0 - cost / [declared_cost, cost].max + quality_prob * 0.01 : quality_prob
106
+ when "fastest"
107
+ (1.0 - [latency_ms / 5000.0, 1.0].min) + quality_prob * 0.01
108
+ when "highest-quality"
109
+ quality_prob
110
+ when "local-first"
111
+ (is_local ? 10.0 : 0.0) + quality_prob
112
+ else
113
+ cost_saving = declared_cost > 0.0 ? 1.0 - cost / [declared_cost, cost].max : 0.0
114
+ latency_factor = 1.0 - [latency_ms / 5000.0, 1.0].min
115
+ quality_prob * 0.5 + cost_saving * 0.35 + latency_factor * 0.15
116
+ end
117
+ end
118
+
119
+ # router.rs::route — score + rank candidates and return the decision Hash.
120
+ # candidates are Hashes with string keys matching the catalogue candidate shape.
121
+ def route(req, candidates, benchmark_scores = BUNDLED_BENCHMARK_SCORES)
122
+ start = now_ms
123
+
124
+ base_decision = lambda do |chosen, scores, floor|
125
+ {
126
+ "strategy" => req["strategy"], "quality_floor" => floor, "candidates" => scores,
127
+ "route_chosen" => chosen, "savings_vs_passthrough_usd" => 0.0,
128
+ "savings_vs_passthrough_pct" => 0.0, "classifier_model_id" => CLF_VERSION,
129
+ "classifier_model_sha256" => "N/A", "decision_latency_ms" => now_ms - start,
130
+ "classifier_degraded" => false, "routed_client_side" => true
131
+ }
132
+ end
133
+
134
+ if req["strategy"] == "passthrough"
135
+ declared = candidates.find do |c|
136
+ c["provider"] == req["declared_provider"] && c["model"] == req["declared_model"]
137
+ end || candidates[0]
138
+ raise "client-arbitrage: no candidates available" if declared.nil?
139
+
140
+ scores = candidates.map do |c|
141
+ {
142
+ "provider" => c["provider"], "model" => c["model"],
143
+ "predicted_quality" => c["benchmark_quality"], "cost_per_1m_output" => c["cost_per_1m_output"],
144
+ "p50_latency_ms" => c["p50_latency_ms"], "composite_score" => 0.0,
145
+ "selected" => c["provider"] == declared["provider"] && c["model"] == declared["model"],
146
+ "disqualified_reason" => nil
147
+ }
148
+ end
149
+ return base_decision.call(declared, scores, req["quality_floor"])
150
+ end
151
+
152
+ effective_floor = clamp(req["quality_floor"] + floor_increment(req["task_class"]), 0.0, 1.0)
153
+ # ⛔ Q34 (KOMITÉ-ORDRE 10, sak 81), 2026-08-11 — DEN DEKLARERTE MODELLEN, IKKJE
154
+ # BERRE LEVERANDØREN. `find` matcha på "provider" åleine og tok fyrste kandidat, so
155
+ # ein deklarert dyr modell fekk grunnlinja til den billegaste modellen hjå same
156
+ # leverandør (målt: deklarert haiku-4-5 $5 -> rapportert $14.4 mot reelle $4.4).
157
+ # `fetch(..., 1.0)` var den andre halvdelen: utan den deklarerte modellen i poolen
158
+ # fanst det inga grunnlinje, og $1.00 gjorde det om til ei sparing mot ein pris som
159
+ # aldri fanst.
160
+ # ⛔ Same verdi går inn i cost_ratio og composite_score, so feilen flytta ÒG
161
+ # MODELLVALET. Saka namngav FEM portar; grunnsanninga viste ÅTTE — dei fem pluss
162
+ # sdk/rust, sdk/dotnet og DENNE. Alle åtte retta i same commit.
163
+ declared_cost = candidates.find do |c|
164
+ c["provider"] == req["declared_provider"] && c["model"] == req["declared_model"]
165
+ end&.fetch("cost_per_1m_output", nil)
166
+ cost_reference = declared_cost ||
167
+ candidates.map { |c| c["cost_per_1m_output"].to_f }.max || 0.0
168
+ declared_score = score_for(req["declared_provider"], req["declared_model"], benchmark_scores)
169
+
170
+ scored = []
171
+ candidates.each do |c|
172
+ allowed = req["allowed_providers"] || []
173
+ if !allowed.empty? && !allowed.include?(c["provider"])
174
+ scored << { composite: 0.0, ok: false, candidate: c, reason: "not in allowed_providers" }
175
+ next
176
+ end
177
+ if c["is_local"] && !req["local_allowed"]
178
+ scored << { composite: 0.0, ok: false, candidate: c, reason: "local not allowed" }
179
+ next
180
+ end
181
+ if !req["max_cost_per_1m"].nil? && c["cost_per_1m_output"] > req["max_cost_per_1m"]
182
+ scored << { composite: 0.0, ok: false, candidate: c,
183
+ reason: "cost #{c['cost_per_1m_output']} > ceiling #{req['max_cost_per_1m']}" }
184
+ next
185
+ end
186
+
187
+ candidate_score = score_for(c["provider"], c["model"], benchmark_scores)
188
+ score_delta = candidate_score - declared_score
189
+
190
+ apply_cold_start = %w[auto highest-quality].include?(req["strategy"])
191
+ if apply_cold_start && score_delta < -CLF_COLD_START_MARGIN
192
+ scored << { composite: 0.0, ok: false, candidate: c,
193
+ reason: "score_delta #{format('%.3f', score_delta)} below cold-start margin" }
194
+ next
195
+ end
196
+
197
+ cost_ratio = cost_reference > 0.0 ? c["cost_per_1m_output"] / cost_reference : 0.0
198
+ quality_prob = predict_quality(req["task_class"], req["input_tokens"], score_delta, cost_ratio)
199
+
200
+ if c["benchmark_quality"] < effective_floor
201
+ scored << { composite: 0.0, ok: false, candidate: c,
202
+ reason: "benchmark_quality #{c['benchmark_quality']} < floor #{format('%.3f', effective_floor)}" }
203
+ next
204
+ end
205
+
206
+ composite = composite_score(req["strategy"], quality_prob, c["cost_per_1m_output"],
207
+ cost_reference, c["p50_latency_ms"], c["is_local"])
208
+ scored << { composite: composite, ok: true, candidate: c, reason: nil }
209
+ end
210
+
211
+ eligible = scored.select { |s| s[:ok] }.sort_by { |s| -s[:composite] }
212
+ if req["strategy"] == "local-first"
213
+ eligible = eligible.sort do |a, b|
214
+ la = a[:candidate]["is_local"] ? 0 : 1
215
+ lb = b[:candidate]["is_local"] ? 0 : 1
216
+ la == lb ? (b[:composite] <=> a[:composite]) : (la <=> lb)
217
+ end
218
+ end
219
+
220
+ chosen = eligible[0]&.dig(:candidate)
221
+ raise "client-arbitrage: no candidate meets floor #{effective_floor} / max_cost #{req['max_cost_per_1m']}" \
222
+ if chosen.nil?
223
+
224
+ candidate_scores = scored.map do |s|
225
+ c = s[:candidate]
226
+ {
227
+ "provider" => c["provider"], "model" => c["model"],
228
+ "predicted_quality" => score_for(c["provider"], c["model"], benchmark_scores),
229
+ "cost_per_1m_output" => c["cost_per_1m_output"], "p50_latency_ms" => c["p50_latency_ms"],
230
+ "composite_score" => s[:composite],
231
+ "selected" => c["provider"] == chosen["provider"] && c["model"] == chosen["model"],
232
+ "disqualified_reason" => s[:ok] ? nil : s[:reason]
233
+ }
234
+ end
235
+
236
+ # ⛔ Q34: innsparing BERRE mot ei EKTE grunnlinje.
237
+ savings_usd = 0.0
238
+ savings_pct = 0.0
239
+ if declared_cost && declared_cost > 0.0
240
+ savings_usd = [0.0, declared_cost - chosen["cost_per_1m_output"]].max
241
+ savings_pct = (savings_usd / declared_cost) * 100.0
242
+ end
243
+
244
+ {
245
+ "strategy" => req["strategy"], "quality_floor" => effective_floor,
246
+ "candidates" => candidate_scores, "route_chosen" => chosen,
247
+ "savings_vs_passthrough_usd" => savings_usd, "savings_vs_passthrough_pct" => savings_pct,
248
+ "classifier_model_id" => CLF_VERSION, "classifier_model_sha256" => "N/A",
249
+ "decision_latency_ms" => now_ms - start, "classifier_degraded" => false,
250
+ "routed_client_side" => true
251
+ }
252
+ end
253
+
254
+ # ── content classification (client-only) ─────────────────────────────────
255
+
256
+ def messages_have_vision(messages)
257
+ messages.any? do |m|
258
+ content = m[:content] || m["content"]
259
+ content.is_a?(Array) && content.any? do |part|
260
+ t = (part[:type] || part["type"]).to_s
261
+ %w[image_url image input_image].include?(t)
262
+ end
263
+ end
264
+ end
265
+
266
+ def flatten_text(messages)
267
+ parts = []
268
+ messages.each do |m|
269
+ content = m[:content] || m["content"]
270
+ if content.is_a?(String)
271
+ parts << content
272
+ elsif content.is_a?(Array)
273
+ content.each do |p|
274
+ txt = p[:text] || p["text"]
275
+ parts << txt if txt.is_a?(String)
276
+ end
277
+ end
278
+ end
279
+ parts.join("\n").downcase
280
+ end
281
+
282
+ # ~4 chars/token heuristic (bucketed length is all the classifier needs).
283
+ def estimate_tokens(messages)
284
+ [1, (flatten_text(messages).length / 4.0).ceil].max
285
+ end
286
+
287
+ def classify_task(messages)
288
+ return "multimodal_vision" if messages_have_vision(messages)
289
+
290
+ text = flatten_text(messages)
291
+ has = ->(*needles) { needles.any? { |n| text.include?(n) } }
292
+
293
+ if has.call("```", "function ", "def ", "import ", "class ", "const ", "refactor", "stack trace")
294
+ return has.call("complete this", "autocomplete", "finish the") ? "code_completion" : "code_generation"
295
+ end
296
+ return "translation" if has.call("translate", "translation", "in french", "in spanish", "in german", "to english")
297
+ return "summarisation" if has.call("summarise", "summarize", "tl;dr", "in short", "summary of")
298
+ return "extraction" if has.call("extract", "parse out", "pull out the", "list all the")
299
+ return "classification" if has.call("classify", "categorise", "categorize", "what category", "is this spam")
300
+ if has.call("prove", "reason step by step", "think step by step", "solve for", "derive", "chain of thought")
301
+ return "reasoning"
302
+ end
303
+ return "factual_lookup" if has.call("who is", "what is the capital", "when did", "how many", "what year", "define ")
304
+
305
+ "general"
306
+ end
307
+
308
+ # OFFLINE FALLBACK ONLY — production callers pass the fetched catalogue's pool.
309
+ def default_candidates(local_allowed)
310
+ c = [
311
+ { "provider" => "anthropic", "model" => "claude-sonnet-4-6", "cost_per_1m_input" => 3.0,
312
+ "cost_per_1m_output" => 15.0, "is_local" => false, "benchmark_quality" => 0.93, "p50_latency_ms" => 800 },
313
+ { "provider" => "anthropic", "model" => "claude-haiku-4-5", "cost_per_1m_input" => 0.8,
314
+ "cost_per_1m_output" => 4.0, "is_local" => false, "benchmark_quality" => 0.85, "p50_latency_ms" => 400 },
315
+ { "provider" => "openai", "model" => "gpt-4o", "cost_per_1m_input" => 2.5,
316
+ "cost_per_1m_output" => 10.0, "is_local" => false, "benchmark_quality" => 0.93, "p50_latency_ms" => 600 },
317
+ { "provider" => "openai", "model" => "gpt-4o-mini", "cost_per_1m_input" => 0.15,
318
+ "cost_per_1m_output" => 0.6, "is_local" => false, "benchmark_quality" => 0.84, "p50_latency_ms" => 400 }
319
+ ]
320
+ if local_allowed
321
+ c << { "provider" => "ollama", "model" => "qwen2.5:32b", "cost_per_1m_input" => 0.0,
322
+ "cost_per_1m_output" => 0.0, "is_local" => true, "benchmark_quality" => 0.86, "p50_latency_ms" => 2000 }
323
+ c << { "provider" => "ollama", "model" => "deepseek-v3", "cost_per_1m_input" => 0.0,
324
+ "cost_per_1m_output" => 0.0, "is_local" => true, "benchmark_quality" => 0.9, "p50_latency_ms" => 3000 }
325
+ end
326
+ c
327
+ end
328
+
329
+ # Classify the (raw, client-held) prompt and pick provider+model. Returns
330
+ # +{ "provider" =>, "model" =>, "strategy" =>, "decision" => }+.
331
+ def pick_route(messages, declared_provider:, declared_model:, strategy:, quality_floor: 0.9,
332
+ max_cost_per_1m: nil, allowed_providers: nil, local_allowed: false,
333
+ candidates: nil, benchmark_scores: BUNDLED_BENCHMARK_SCORES)
334
+ req = {
335
+ "declared_provider" => declared_provider, "declared_model" => declared_model,
336
+ "strategy" => strategy, "quality_floor" => quality_floor, "max_cost_per_1m" => max_cost_per_1m,
337
+ "allowed_providers" => allowed_providers || [], "local_allowed" => local_allowed,
338
+ "input_tokens" => estimate_tokens(messages), "task_class" => classify_task(messages)
339
+ }
340
+ pool = candidates || default_candidates(local_allowed)
341
+ decision = route(req, pool, benchmark_scores)
342
+ {
343
+ "provider" => decision["route_chosen"]["provider"], "model" => decision["route_chosen"]["model"],
344
+ "strategy" => strategy, "decision" => decision
345
+ }
346
+ end
347
+
348
+ # ── catalogue helpers ─────────────────────────────────────────────────────
349
+
350
+ def catalogue_candidates(cat, local_allowed: false)
351
+ (cat["candidates"] || []).select { |c| local_allowed || !c["is_local"] }
352
+ end
353
+
354
+ def model_in_catalogue?(cat, provider, model)
355
+ key = "#{provider.to_s.downcase}:#{model.to_s.downcase}"
356
+ return true if (cat["benchmark_scores"] || {}).key?(key)
357
+
358
+ (cat["candidates"] || []).any? do |c|
359
+ c["provider"].to_s.downcase == provider.to_s.downcase &&
360
+ c["model"].to_s.downcase == model.to_s.downcase
361
+ end
362
+ end
363
+
364
+ # Raised when a chosen model is not in the current catalogue (dead-model gate).
365
+ class CatalogueStaleError < StandardError
366
+ CODE = "model_unknown_refresh_catalogue"
367
+ attr_reader :provider, :model, :catalogue_version
368
+
369
+ def initialize(provider, model, catalogue_version)
370
+ @provider = provider
371
+ @model = model
372
+ @catalogue_version = catalogue_version
373
+ super("Model \"#{provider}:#{model}\" is not in catalogue v#{catalogue_version}. " \
374
+ "Refresh your catalogue and retry.")
375
+ end
376
+
377
+ def code = CODE
378
+ end
379
+
380
+ def assert_model_in_catalogue(cat, provider, model)
381
+ return if model_in_catalogue?(cat, provider, model)
382
+
383
+ raise CatalogueStaleError.new(provider, model, cat["catalogue_version"])
384
+ end
385
+
386
+ # Detect the gateway's "refresh your catalogue" rejection from a parsed body.
387
+ def catalogue_stale_error?(err_body)
388
+ return false unless err_body.is_a?(Hash)
389
+
390
+ code = err_body["code"] || err_body.dig("error", "code")
391
+ code == CatalogueStaleError::CODE
392
+ end
393
+
394
+ def now_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
395
+
396
+ # A per-client catalogue holder: fetch + in-process cache + on-demand refresh.
397
+ # One instance is created per SDK client (cache scoped to the client lifetime).
398
+ class CatalogueClient
399
+ def initialize(url: nil, http: nil, timeout: 10)
400
+ @url = url || DEFAULT_CATALOGUE_URL
401
+ @http = http # injected for tests: respond_to?(:call) -> returns catalogue Hash
402
+ @timeout = timeout
403
+ @cache = nil # { fetched_at_ms:, catalogue: }
404
+ end
405
+
406
+ # Cache-first (fresh) → network → cache (stale) → bundled seed.
407
+ def load(force_refresh: false)
408
+ if !force_refresh && @cache
409
+ age = Routing.now_ms - @cache[:fetched_at_ms]
410
+ return tag(@cache[:catalogue], "cache") if age < STALE_AFTER_MS
411
+ end
412
+ begin
413
+ fresh = fetch_catalogue
414
+ @cache = { fetched_at_ms: Routing.now_ms, catalogue: fresh }
415
+ fresh
416
+ rescue StandardError
417
+ return tag(@cache[:catalogue], "cache") if @cache
418
+
419
+ tag(SEED_CATALOGUE, "seed")
420
+ end
421
+ end
422
+
423
+ def refresh = load(force_refresh: true)
424
+
425
+ # Fetch the served catalogue; raises on network / non-2xx / malformed body.
426
+ def fetch_catalogue
427
+ body =
428
+ if @http.respond_to?(:call)
429
+ @http.call(@url)
430
+ else
431
+ uri = URI.parse(@url)
432
+ http = Net::HTTP.new(uri.host, uri.port)
433
+ http.use_ssl = uri.scheme == "https"
434
+ http.open_timeout = @timeout
435
+ http.read_timeout = @timeout
436
+ req = Net::HTTP::Get.new(uri.request_uri)
437
+ req["Accept"] = "application/json"
438
+ resp = http.request(req)
439
+ raise "catalogue fetch failed: HTTP #{resp.code}" unless resp.code.to_i.between?(200, 299)
440
+
441
+ JSON.parse(resp.body)
442
+ end
443
+ raise "catalogue fetch: malformed body" unless catalogue?(body)
444
+
445
+ tag(body, "network")
446
+ end
447
+
448
+ private
449
+
450
+ def catalogue?(v)
451
+ v.is_a?(Hash) && v["catalogue_version"].is_a?(Numeric) &&
452
+ v["candidates"].is_a?(Array) && v["benchmark_scores"].is_a?(Hash)
453
+ end
454
+
455
+ def tag(cat, src) = cat.merge("_source" => src)
456
+ end
457
+
458
+ # Per-client router: holds one CatalogueClient and resolves a route per call.
459
+ class Router
460
+ def initialize(strategy: "passthrough", local_allowed: false, quality_floor: nil,
461
+ max_cost_per1m: nil, allowed_providers: nil, catalogue: nil)
462
+ @strategy = strategy
463
+ @local_allowed = local_allowed
464
+ @quality_floor = quality_floor
465
+ @max_cost_per1m = max_cost_per1m
466
+ @allowed_providers = allowed_providers
467
+ @catalogue_client = CatalogueClient.new(**(catalogue || {}))
468
+ end
469
+
470
+ def refresh_catalogue = @catalogue_client.refresh
471
+
472
+ # Resolve the outbound route from the (raw, client-held) messages + the
473
+ # user's declared provider/model. Always returns a client-side decision so
474
+ # the caller sends +X-CloakAPI-Routing: client+. Returns
475
+ # +{ "provider" =>, "model" =>, "strategy" =>, "routed_client_side" => true }+.
476
+ def resolve(messages, declared_provider, declared_model, force_refresh: false)
477
+ cat = @catalogue_client.load(force_refresh: force_refresh)
478
+ candidates = Routing.catalogue_candidates(cat, local_allowed: @local_allowed)
479
+
480
+ if @strategy == "passthrough"
481
+ return { "provider" => declared_provider, "model" => declared_model,
482
+ "strategy" => "passthrough", "routed_client_side" => true }
483
+ end
484
+
485
+ picked = Routing.pick_route(
486
+ messages, declared_provider: declared_provider, declared_model: declared_model,
487
+ strategy: @strategy, quality_floor: @quality_floor || 0.9, max_cost_per_1m: @max_cost_per1m,
488
+ allowed_providers: @allowed_providers, local_allowed: @local_allowed,
489
+ candidates: candidates, benchmark_scores: cat["benchmark_scores"] || BUNDLED_BENCHMARK_SCORES
490
+ )
491
+ { "provider" => picked["provider"], "model" => picked["model"],
492
+ "strategy" => @strategy, "routed_client_side" => true }
493
+ end
494
+
495
+ def known_model?(provider, model)
496
+ Routing.model_in_catalogue?(@catalogue_client.load, provider, model)
497
+ end
498
+ end
499
+ end
500
+ end