cloakapi 1.4.1
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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +160 -0
- data/LICENSE +202 -0
- data/NOTICE +18 -0
- data/README.md +407 -0
- data/THIRD-PARTY-NOTICES.md +22 -0
- data/TRADEMARKS.md +19 -0
- data/examples/fake_gateway.rb +78 -0
- data/examples/hello.rb +64 -0
- data/lib/cloakapi/client.rb +1272 -0
- data/lib/cloakapi/degraded.rb +77 -0
- data/lib/cloakapi/disclosure.rb +252 -0
- data/lib/cloakapi/engine.rb +702 -0
- data/lib/cloakapi/errors.rb +65 -0
- data/lib/cloakapi/pii/bundled_rules.rb +670 -0
- data/lib/cloakapi/pii/card_spans.rb +300 -0
- data/lib/cloakapi/pii/detector.rb +1925 -0
- data/lib/cloakapi/pii/patterns.json +2238 -0
- data/lib/cloakapi/pii/pii_match.rb +7 -0
- data/lib/cloakapi/pii/pii_type.rb +7 -0
- data/lib/cloakapi/pii/ruleset.rb +65 -0
- data/lib/cloakapi/pii/tokenizer.rb +411 -0
- data/lib/cloakapi/posture.rb +82 -0
- data/lib/cloakapi/receipts.rb +406 -0
- data/lib/cloakapi/resources/chat.rb +82 -0
- data/lib/cloakapi/resources/messages.rb +90 -0
- data/lib/cloakapi/resources/models.rb +25 -0
- data/lib/cloakapi/resources/receipts.rb +162 -0
- data/lib/cloakapi/resources/reconstruct.rb +120 -0
- data/lib/cloakapi/resources/request_strings.rb +485 -0
- data/lib/cloakapi/resources/reviewable.rb +163 -0
- data/lib/cloakapi/resources/tokens.rb +28 -0
- data/lib/cloakapi/routing/bundled-catalogue.json +107 -0
- data/lib/cloakapi/routing.rb +500 -0
- data/lib/cloakapi/streaming.rb +196 -0
- data/lib/cloakapi/surrogate_mode.rb +233 -0
- data/lib/cloakapi/version.rb +15 -0
- data/lib/cloakapi/warnings.rb +137 -0
- data/lib/cloakapi.rb +37 -0
- data/licenses/Apache-2.0.txt +202 -0
- data/licenses/CC-BY-4.0.txt +104 -0
- data/licenses/MIT-Faker.txt +21 -0
- data/licenses/MIT.txt +21 -0
- metadata +149 -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
|