@plasius/ai-router 0.1.2 → 0.1.3
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.
- package/CHANGELOG.md +18 -0
- package/README.md +28 -2
- package/dist/index.cjs +276 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +54 -2
- package/dist/index.d.ts +54 -2
- package/dist/index.js +272 -2
- package/dist/index.js.map +1 -1
- package/docs/adrs/adr-0002-cost-aware-routing-policy.md +25 -0
- package/docs/adrs/index.md +1 -0
- package/package.json +5 -1
package/CHANGELOG.md
CHANGED
|
@@ -18,6 +18,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
18
18
|
- **Security**
|
|
19
19
|
- (placeholder)
|
|
20
20
|
|
|
21
|
+
## [0.1.3] - 2026-05-20
|
|
22
|
+
|
|
23
|
+
- **Added**
|
|
24
|
+
- Added `selectAiProviderRoute` with multi-phase policy selection for primary, escalation, and fallback routing.
|
|
25
|
+
- Added routing policy contracts for confidence, budget, allow/deny lists, and decision telemetry.
|
|
26
|
+
|
|
27
|
+
- **Changed**
|
|
28
|
+
- Updated package feature flag contract to `ai.cost-aware-routing.enabled`.
|
|
29
|
+
- Added dependency on `@plasius/ai-providers` and routing policy tests.
|
|
30
|
+
|
|
31
|
+
- **Fixed**
|
|
32
|
+
- Release automation now prepares version/changelog updates on a release PR before publishing from protected `main`.
|
|
33
|
+
- Budgeted routing now treats missing provider cost estimates as over budget instead of selectable.
|
|
34
|
+
|
|
35
|
+
- **Security**
|
|
36
|
+
- (placeholder)
|
|
37
|
+
|
|
21
38
|
## [0.1.2] - 2026-05-13
|
|
22
39
|
|
|
23
40
|
- **Added**
|
|
@@ -40,3 +57,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
|
40
57
|
|
|
41
58
|
[0.1.1]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.1
|
|
42
59
|
[0.1.2]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.2
|
|
60
|
+
[0.1.3]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.3
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agent
|
|
|
4
4
|
|
|
5
5
|
## Scope
|
|
6
6
|
|
|
7
|
-
This package is part of the layered `@plasius/ai-*` package family. It
|
|
7
|
+
This package is part of the layered `@plasius/ai-*` package family. It provides deterministic route selection with confidence, budget, escalation, and fallback policy controls.
|
|
8
8
|
|
|
9
9
|
## Install
|
|
10
10
|
|
|
@@ -20,16 +20,42 @@ import { packageDescriptor } from "@plasius/ai-router";
|
|
|
20
20
|
console.log(packageDescriptor.packageName);
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
+
```ts
|
|
24
|
+
import {
|
|
25
|
+
selectAiProviderRoute,
|
|
26
|
+
type AiRoutingPolicy,
|
|
27
|
+
} from "@plasius/ai-router";
|
|
28
|
+
import type { AiProviderCandidate } from "@plasius/ai-providers";
|
|
29
|
+
|
|
30
|
+
declare const candidates: readonly AiProviderCandidate[];
|
|
31
|
+
declare const requestId: string;
|
|
32
|
+
|
|
33
|
+
declare const policy: AiRoutingPolicy;
|
|
34
|
+
|
|
35
|
+
const decision = selectAiProviderRoute(requestId, candidates, policy);
|
|
36
|
+
console.log(decision.mode, decision.selected?.providerId);
|
|
37
|
+
```
|
|
38
|
+
|
|
23
39
|
## Development
|
|
24
40
|
|
|
25
41
|
```bash
|
|
26
42
|
npm install
|
|
27
43
|
npm run build
|
|
28
|
-
npm
|
|
44
|
+
npm run typecheck
|
|
45
|
+
npm run test
|
|
29
46
|
npm run test:coverage
|
|
47
|
+
npm run lint
|
|
30
48
|
npm run pack:check
|
|
31
49
|
```
|
|
32
50
|
|
|
51
|
+
## Release Workflow
|
|
52
|
+
|
|
53
|
+
Protected `main` releases use a two-step flow:
|
|
54
|
+
|
|
55
|
+
1. Run `.github/workflows/cd.yml` with `bump=patch|minor|major` to open or refresh a `release/vX.Y.Z` prep PR.
|
|
56
|
+
2. Merge that PR to `main`.
|
|
57
|
+
3. Rerun `.github/workflows/cd.yml` on `main` with `bump=none` to tag, draft the GitHub release, and publish to npm.
|
|
58
|
+
|
|
33
59
|
## Governance
|
|
34
60
|
|
|
35
61
|
- Security policy: [SECURITY.md](./SECURITY.md)
|
package/dist/index.cjs
CHANGED
|
@@ -20,14 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
20
20
|
// src/index.ts
|
|
21
21
|
var index_exports = {};
|
|
22
22
|
__export(index_exports, {
|
|
23
|
+
AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER: () => AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER,
|
|
24
|
+
AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE: () => AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,
|
|
23
25
|
AI_ROUTER_ENV_PREFIX: () => AI_ROUTER_ENV_PREFIX,
|
|
24
26
|
AI_ROUTER_FEATURE_FLAG_ID: () => AI_ROUTER_FEATURE_FLAG_ID,
|
|
25
27
|
AI_ROUTER_PACKAGE: () => AI_ROUTER_PACKAGE,
|
|
26
|
-
packageDescriptor: () => packageDescriptor
|
|
28
|
+
packageDescriptor: () => packageDescriptor,
|
|
29
|
+
selectAiProviderRoute: () => selectAiProviderRoute
|
|
27
30
|
});
|
|
28
31
|
module.exports = __toCommonJS(index_exports);
|
|
29
32
|
var AI_ROUTER_PACKAGE = "@plasius/ai-router";
|
|
30
|
-
var AI_ROUTER_FEATURE_FLAG_ID = "ai.
|
|
33
|
+
var AI_ROUTER_FEATURE_FLAG_ID = "ai.cost-aware-routing.enabled";
|
|
31
34
|
var AI_ROUTER_ENV_PREFIX = "AI_ROUTER";
|
|
32
35
|
var packageDescriptor = Object.freeze({
|
|
33
36
|
packageName: AI_ROUTER_PACKAGE,
|
|
@@ -35,11 +38,281 @@ var packageDescriptor = Object.freeze({
|
|
|
35
38
|
envPrefix: AI_ROUTER_ENV_PREFIX,
|
|
36
39
|
summary: "Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads."
|
|
37
40
|
});
|
|
41
|
+
var AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;
|
|
42
|
+
var AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;
|
|
43
|
+
var DEFAULT_ROUTING_ESCALATION_POLICY = Object.freeze({
|
|
44
|
+
enabled: true,
|
|
45
|
+
overageMultiplier: AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER
|
|
46
|
+
});
|
|
47
|
+
var DEFAULT_ROUTING_FALLBACK_POLICY = Object.freeze({
|
|
48
|
+
enabled: true
|
|
49
|
+
});
|
|
50
|
+
var DEFAULT_ROUTING_POLICY = Object.freeze({
|
|
51
|
+
enabled: true,
|
|
52
|
+
minimumConfidence: AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,
|
|
53
|
+
escalation: DEFAULT_ROUTING_ESCALATION_POLICY,
|
|
54
|
+
fallback: DEFAULT_ROUTING_FALLBACK_POLICY
|
|
55
|
+
});
|
|
56
|
+
var DEFAULT_BASELINE_CONFIDENCE = {
|
|
57
|
+
free: 0.45,
|
|
58
|
+
development: 0.62,
|
|
59
|
+
standard: 0.82,
|
|
60
|
+
premium: 0.96
|
|
61
|
+
};
|
|
62
|
+
var DECISION_COMPARATOR = (left, right) => {
|
|
63
|
+
const leftCost = left.estimatedCostUsd ?? Number.POSITIVE_INFINITY;
|
|
64
|
+
const rightCost = right.estimatedCostUsd ?? Number.POSITIVE_INFINITY;
|
|
65
|
+
const costComparison = leftCost - rightCost;
|
|
66
|
+
if (costComparison !== 0) {
|
|
67
|
+
return costComparison;
|
|
68
|
+
}
|
|
69
|
+
const confidenceComparison = right.estimatedConfidence - left.estimatedConfidence;
|
|
70
|
+
if (confidenceComparison !== 0) {
|
|
71
|
+
return confidenceComparison;
|
|
72
|
+
}
|
|
73
|
+
return left.providerId.localeCompare(right.providerId);
|
|
74
|
+
};
|
|
75
|
+
function normalizeBoolean(value) {
|
|
76
|
+
return value === true;
|
|
77
|
+
}
|
|
78
|
+
function clampConfidence(value) {
|
|
79
|
+
if (!Number.isFinite(value)) {
|
|
80
|
+
return 0;
|
|
81
|
+
}
|
|
82
|
+
if (value < 0) {
|
|
83
|
+
return 0;
|
|
84
|
+
}
|
|
85
|
+
if (value > 1) {
|
|
86
|
+
return 1;
|
|
87
|
+
}
|
|
88
|
+
return value;
|
|
89
|
+
}
|
|
90
|
+
function asFrozenReasons(reasons) {
|
|
91
|
+
return Object.freeze([...reasons]);
|
|
92
|
+
}
|
|
93
|
+
function normalizePolicy(policy = DEFAULT_ROUTING_POLICY) {
|
|
94
|
+
const minimumConfidence = clampConfidence(
|
|
95
|
+
policy.minimumConfidence ?? DEFAULT_ROUTING_POLICY.minimumConfidence
|
|
96
|
+
);
|
|
97
|
+
const escalation = policy.escalation ?? DEFAULT_ROUTING_POLICY.escalation;
|
|
98
|
+
const fallback = policy.fallback ?? DEFAULT_ROUTING_POLICY.fallback;
|
|
99
|
+
const normalizedEscalation = Object.freeze({
|
|
100
|
+
enabled: normalizeBoolean(escalation.enabled),
|
|
101
|
+
overageMultiplier: escalation.overageMultiplier ?? DEFAULT_ROUTING_POLICY.escalation.overageMultiplier
|
|
102
|
+
});
|
|
103
|
+
const normalizedFallback = Object.freeze({
|
|
104
|
+
enabled: normalizeBoolean(fallback.enabled)
|
|
105
|
+
});
|
|
106
|
+
return Object.freeze({
|
|
107
|
+
enabled: normalizeBoolean(policy.enabled),
|
|
108
|
+
minimumConfidence,
|
|
109
|
+
allowProviderIds: policy.allowProviderIds ? Object.freeze([...policy.allowProviderIds]) : void 0,
|
|
110
|
+
denyProviderIds: policy.denyProviderIds ? Object.freeze([...policy.denyProviderIds]) : void 0,
|
|
111
|
+
budget: policy.budget ? Object.freeze({ ...policy.budget }) : void 0,
|
|
112
|
+
confidenceEstimator: policy.confidenceEstimator,
|
|
113
|
+
escalation: normalizedEscalation,
|
|
114
|
+
fallback: normalizedFallback
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
function estimateConfidence(candidate, policy, mode) {
|
|
118
|
+
const baseline = DEFAULT_BASELINE_CONFIDENCE[candidate.config.tier ?? "standard"];
|
|
119
|
+
if (policy.confidenceEstimator) {
|
|
120
|
+
return clampConfidence(
|
|
121
|
+
policy.confidenceEstimator({
|
|
122
|
+
candidate,
|
|
123
|
+
mode
|
|
124
|
+
})
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
return baseline;
|
|
128
|
+
}
|
|
129
|
+
function isReady(candidate) {
|
|
130
|
+
return candidate.readiness.supported && candidate.readiness.enabled && candidate.config.enabled && !candidate.readiness.diagnostics.some(
|
|
131
|
+
(diagnostic) => diagnostic.severity === "error"
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
function isAllowedByPolicy(candidate, policy) {
|
|
135
|
+
if (policy.denyProviderIds?.includes(candidate.descriptor.providerId)) {
|
|
136
|
+
return { allowed: false, reason: "provider-denied-by-policy" };
|
|
137
|
+
}
|
|
138
|
+
if (policy.allowProviderIds && !policy.allowProviderIds.includes(candidate.descriptor.providerId)) {
|
|
139
|
+
return { allowed: false, reason: "provider-allowlist-miss" };
|
|
140
|
+
}
|
|
141
|
+
return { allowed: true };
|
|
142
|
+
}
|
|
143
|
+
function estimateLatency(candidate) {
|
|
144
|
+
const slo = candidate.descriptor.slo;
|
|
145
|
+
return slo?.timeoutMs;
|
|
146
|
+
}
|
|
147
|
+
function estimateCost(candidate) {
|
|
148
|
+
return candidate.estimatedCostUsd;
|
|
149
|
+
}
|
|
150
|
+
function buildAssessments(requestId, candidates, policy, mode) {
|
|
151
|
+
const evaluations = candidates.map((candidate) => {
|
|
152
|
+
const reasons = [];
|
|
153
|
+
const allowed = isAllowedByPolicy(candidate, policy);
|
|
154
|
+
if (!allowed.allowed && allowed.reason) {
|
|
155
|
+
reasons.push(allowed.reason);
|
|
156
|
+
}
|
|
157
|
+
if (!candidate.config.enabled) {
|
|
158
|
+
reasons.push("provider-disabled");
|
|
159
|
+
}
|
|
160
|
+
if (!isReady(candidate)) {
|
|
161
|
+
reasons.push("provider-not-ready");
|
|
162
|
+
}
|
|
163
|
+
const estimatedConfidence = estimateConfidence(candidate, policy, mode);
|
|
164
|
+
const estimatedLatencyMs = estimateLatency(candidate);
|
|
165
|
+
const estimatedCostUsd = estimateCost(candidate);
|
|
166
|
+
const maxCost = policy.budget?.maxCostUsd;
|
|
167
|
+
if (maxCost !== void 0 && (estimatedCostUsd === void 0 || estimatedCostUsd > maxCost)) {
|
|
168
|
+
reasons.push("cost-over-budget");
|
|
169
|
+
}
|
|
170
|
+
const maxLatency = policy.budget?.maxLatencyMs;
|
|
171
|
+
if (maxLatency !== void 0 && estimatedLatencyMs !== void 0 && estimatedLatencyMs > maxLatency) {
|
|
172
|
+
reasons.push("latency-over-budget");
|
|
173
|
+
}
|
|
174
|
+
if (policy.minimumConfidence > estimatedConfidence) {
|
|
175
|
+
reasons.push("confidence-under-threshold");
|
|
176
|
+
}
|
|
177
|
+
if (reasons.length === 0) {
|
|
178
|
+
reasons.push("selected");
|
|
179
|
+
}
|
|
180
|
+
return Object.freeze({
|
|
181
|
+
providerId: candidate.descriptor.providerId,
|
|
182
|
+
providerModelId: candidate.readiness.selectedModelId,
|
|
183
|
+
estimatedCostUsd,
|
|
184
|
+
estimatedLatencyMs,
|
|
185
|
+
estimatedConfidence,
|
|
186
|
+
descriptor: candidate.descriptor,
|
|
187
|
+
providerTier: candidate.config.tier,
|
|
188
|
+
reasons: asFrozenReasons(reasons),
|
|
189
|
+
mode
|
|
190
|
+
});
|
|
191
|
+
});
|
|
192
|
+
return Object.freeze([...evaluations].sort(DECISION_COMPARATOR));
|
|
193
|
+
}
|
|
194
|
+
function hasBlockingReasons(assessment, includeConfidence) {
|
|
195
|
+
const blocking = new Set(assessment.reasons);
|
|
196
|
+
const hardBlockingReasons = [
|
|
197
|
+
"provider-allowlist-miss",
|
|
198
|
+
"provider-denied-by-policy",
|
|
199
|
+
"provider-disabled",
|
|
200
|
+
"provider-not-ready",
|
|
201
|
+
"cost-over-budget",
|
|
202
|
+
"latency-over-budget"
|
|
203
|
+
];
|
|
204
|
+
return hardBlockingReasons.some((reason) => blocking.has(reason)) || includeConfidence && blocking.has("confidence-under-threshold");
|
|
205
|
+
}
|
|
206
|
+
function pickCandidate(candidates, includeConfidence) {
|
|
207
|
+
return candidates.find(
|
|
208
|
+
(candidate) => !hasBlockingReasons(candidate, includeConfidence)
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
function createUnavailableDecision(requestId, policy, candidates) {
|
|
212
|
+
const assessments = buildAssessments(
|
|
213
|
+
requestId,
|
|
214
|
+
candidates,
|
|
215
|
+
policy,
|
|
216
|
+
"fallback"
|
|
217
|
+
);
|
|
218
|
+
const reasons = ["no-eligible-candidate"];
|
|
219
|
+
return Object.freeze({
|
|
220
|
+
requestId,
|
|
221
|
+
mode: "unavailable",
|
|
222
|
+
policy,
|
|
223
|
+
candidates: assessments,
|
|
224
|
+
unavailableReasons: asFrozenReasons(reasons)
|
|
225
|
+
});
|
|
226
|
+
}
|
|
227
|
+
function selectAiProviderRoute(requestId, candidates, policy = DEFAULT_ROUTING_POLICY) {
|
|
228
|
+
const normalizedPolicy = normalizePolicy(policy);
|
|
229
|
+
if (!normalizedPolicy.enabled) {
|
|
230
|
+
return Object.freeze({
|
|
231
|
+
requestId,
|
|
232
|
+
mode: "disabled",
|
|
233
|
+
policy: normalizedPolicy,
|
|
234
|
+
candidates: [],
|
|
235
|
+
unavailableReasons: asFrozenReasons(["disabled-by-flag"])
|
|
236
|
+
});
|
|
237
|
+
}
|
|
238
|
+
const primaryAssessments = buildAssessments(
|
|
239
|
+
requestId,
|
|
240
|
+
candidates,
|
|
241
|
+
normalizedPolicy,
|
|
242
|
+
"selected"
|
|
243
|
+
);
|
|
244
|
+
const primary = pickCandidate(primaryAssessments, true);
|
|
245
|
+
if (primary) {
|
|
246
|
+
return Object.freeze({
|
|
247
|
+
requestId,
|
|
248
|
+
mode: "selected",
|
|
249
|
+
policy: normalizedPolicy,
|
|
250
|
+
selected: primary,
|
|
251
|
+
candidates: primaryAssessments,
|
|
252
|
+
unavailableReasons: []
|
|
253
|
+
});
|
|
254
|
+
}
|
|
255
|
+
const escalation = normalizedPolicy.escalation;
|
|
256
|
+
const escalationPolicy = escalation.enabled ? Object.freeze({
|
|
257
|
+
...normalizedPolicy,
|
|
258
|
+
minimumConfidence: 0,
|
|
259
|
+
budget: normalizedPolicy.budget?.maxCostUsd ? Object.freeze({
|
|
260
|
+
...normalizedPolicy.budget,
|
|
261
|
+
maxCostUsd: normalizedPolicy.budget.maxCostUsd * escalation.overageMultiplier
|
|
262
|
+
}) : normalizedPolicy.budget
|
|
263
|
+
}) : normalizedPolicy;
|
|
264
|
+
if (escalation.enabled) {
|
|
265
|
+
const escalatedAssessments = buildAssessments(
|
|
266
|
+
requestId,
|
|
267
|
+
candidates,
|
|
268
|
+
escalationPolicy,
|
|
269
|
+
"escalated"
|
|
270
|
+
);
|
|
271
|
+
const escalated = pickCandidate(escalatedAssessments, false);
|
|
272
|
+
if (escalated) {
|
|
273
|
+
return Object.freeze({
|
|
274
|
+
requestId,
|
|
275
|
+
mode: "escalated",
|
|
276
|
+
policy: normalizedPolicy,
|
|
277
|
+
selected: escalated,
|
|
278
|
+
candidates: escalatedAssessments,
|
|
279
|
+
unavailableReasons: []
|
|
280
|
+
});
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
if (normalizedPolicy.fallback.enabled) {
|
|
284
|
+
const fallbackAssessments = buildAssessments(
|
|
285
|
+
requestId,
|
|
286
|
+
candidates,
|
|
287
|
+
{
|
|
288
|
+
...normalizedPolicy,
|
|
289
|
+
minimumConfidence: 0,
|
|
290
|
+
budget: void 0
|
|
291
|
+
},
|
|
292
|
+
"fallback"
|
|
293
|
+
);
|
|
294
|
+
const fallback = pickCandidate(fallbackAssessments, false);
|
|
295
|
+
if (fallback) {
|
|
296
|
+
return Object.freeze({
|
|
297
|
+
requestId,
|
|
298
|
+
mode: "fallback",
|
|
299
|
+
policy: normalizedPolicy,
|
|
300
|
+
selected: fallback,
|
|
301
|
+
candidates: fallbackAssessments,
|
|
302
|
+
unavailableReasons: []
|
|
303
|
+
});
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
return createUnavailableDecision(requestId, normalizedPolicy, candidates);
|
|
307
|
+
}
|
|
38
308
|
// Annotate the CommonJS export names for ESM import in node:
|
|
39
309
|
0 && (module.exports = {
|
|
310
|
+
AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER,
|
|
311
|
+
AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,
|
|
40
312
|
AI_ROUTER_ENV_PREFIX,
|
|
41
313
|
AI_ROUTER_FEATURE_FLAG_ID,
|
|
42
314
|
AI_ROUTER_PACKAGE,
|
|
43
|
-
packageDescriptor
|
|
315
|
+
packageDescriptor,
|
|
316
|
+
selectAiProviderRoute
|
|
44
317
|
});
|
|
45
318
|
//# sourceMappingURL=index.cjs.map
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport const AI_ROUTER_PACKAGE = \"@plasius/ai-router\";\nexport const AI_ROUTER_FEATURE_FLAG_ID = \"ai.router.enabled\";\nexport const AI_ROUTER_ENV_PREFIX = \"AI_ROUTER\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n packageName: AI_ROUTER_PACKAGE,\n featureFlagId: AI_ROUTER_FEATURE_FLAG_ID,\n envPrefix: AI_ROUTER_ENV_PREFIX,\n summary: \"Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads.\",\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOO,IAAM,oBAAoB;AAC1B,IAAM,4BAA4B;AAClC,IAAM,uBAAuB;AAE7B,IAAM,oBAAyC,OAAO,OAAO;AAAA,EAClE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SAAS;AACX,CAAC;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n AiProviderCandidate,\n AiProviderTier,\n AiProviderDescriptor,\n AiProviderDiagnostic,\n} from \"@plasius/ai-providers\";\n\nexport interface AiPackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport const AI_ROUTER_PACKAGE = \"@plasius/ai-router\";\nexport const AI_ROUTER_FEATURE_FLAG_ID = \"ai.cost-aware-routing.enabled\";\nexport const AI_ROUTER_ENV_PREFIX = \"AI_ROUTER\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n packageName: AI_ROUTER_PACKAGE,\n featureFlagId: AI_ROUTER_FEATURE_FLAG_ID,\n envPrefix: AI_ROUTER_ENV_PREFIX,\n summary:\n \"Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads.\",\n});\n\nexport const AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;\nexport const AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;\n\nexport type AiRoutingDecisionMode =\n | \"disabled\"\n | \"selected\"\n | \"escalated\"\n | \"fallback\"\n | \"unavailable\";\n\nexport type AiRoutingDecisionReason =\n | \"disabled-by-flag\"\n | \"provider-list-empty\"\n | \"provider-denied-by-policy\"\n | \"provider-allowlist-miss\"\n | \"provider-disabled\"\n | \"provider-not-ready\"\n | \"cost-over-budget\"\n | \"latency-over-budget\"\n | \"confidence-under-threshold\"\n | \"no-eligible-candidate\"\n | \"selected\";\n\nexport interface AiProviderConfidenceEstimatorContext {\n readonly candidate: AiProviderCandidate;\n readonly mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">;\n}\n\nexport type AiProviderConfidenceEstimator = (\n context: AiProviderConfidenceEstimatorContext\n) => number;\n\nexport interface AiRoutingBudgetPolicy {\n readonly maxCostUsd?: number;\n readonly maxLatencyMs?: number;\n}\n\nexport interface AiRoutingEscalationPolicy {\n readonly enabled: boolean;\n readonly overageMultiplier?: number;\n}\n\nexport interface AiRoutingFallbackPolicy {\n readonly enabled: boolean;\n}\n\nexport interface AiRoutingPolicy {\n readonly enabled: boolean;\n readonly minimumConfidence?: number;\n readonly allowProviderIds?: readonly string[];\n readonly denyProviderIds?: readonly string[];\n readonly budget?: AiRoutingBudgetPolicy;\n readonly confidenceEstimator?: AiProviderConfidenceEstimator;\n readonly escalation?: AiRoutingEscalationPolicy;\n readonly fallback?: AiRoutingFallbackPolicy;\n}\n\nexport interface AiRoutingCandidateAssessment {\n readonly providerId: string;\n readonly providerModelId?: string;\n readonly estimatedCostUsd?: number;\n readonly estimatedLatencyMs?: number;\n readonly estimatedConfidence: number;\n readonly descriptor: AiProviderDescriptor;\n readonly providerTier: AiProviderTier;\n readonly reasons: readonly AiRoutingDecisionReason[];\n readonly mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">;\n}\n\nexport interface AiRoutingDecision {\n readonly requestId: string;\n readonly mode: AiRoutingDecisionMode;\n readonly policy: Readonly<AiRoutingPolicy>;\n readonly selected?: AiRoutingCandidateAssessment;\n readonly candidates: readonly AiRoutingCandidateAssessment[];\n readonly unavailableReasons: readonly AiRoutingDecisionReason[];\n}\n\ntype NormalizedAiRoutingPolicy = Readonly<\n Omit<AiRoutingPolicy, \"minimumConfidence\" | \"escalation\" | \"fallback\"> & {\n readonly minimumConfidence: number;\n readonly escalation: Readonly<Required<AiRoutingEscalationPolicy>>;\n readonly fallback: Readonly<Required<AiRoutingFallbackPolicy>>;\n }\n>;\n\nconst DEFAULT_ROUTING_ESCALATION_POLICY: Readonly<\n Required<AiRoutingEscalationPolicy>\n> = Object.freeze({\n enabled: true,\n overageMultiplier: AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER,\n});\n\nconst DEFAULT_ROUTING_FALLBACK_POLICY: Readonly<\n Required<AiRoutingFallbackPolicy>\n> = Object.freeze({\n enabled: true,\n});\n\nconst DEFAULT_ROUTING_POLICY: NormalizedAiRoutingPolicy = Object.freeze({\n enabled: true,\n minimumConfidence: AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,\n escalation: DEFAULT_ROUTING_ESCALATION_POLICY,\n fallback: DEFAULT_ROUTING_FALLBACK_POLICY,\n});\n\nconst DEFAULT_BASELINE_CONFIDENCE: Record<AiProviderTier, number> = {\n free: 0.45,\n development: 0.62,\n standard: 0.82,\n premium: 0.96,\n};\n\nconst DECISION_COMPARATOR = (left: AiRoutingCandidateAssessment, right: AiRoutingCandidateAssessment): number => {\n const leftCost = left.estimatedCostUsd ?? Number.POSITIVE_INFINITY;\n const rightCost = right.estimatedCostUsd ?? Number.POSITIVE_INFINITY;\n const costComparison = leftCost - rightCost;\n if (costComparison !== 0) {\n return costComparison;\n }\n\n const confidenceComparison = right.estimatedConfidence - left.estimatedConfidence;\n if (confidenceComparison !== 0) {\n return confidenceComparison;\n }\n\n return left.providerId.localeCompare(right.providerId);\n};\n\nfunction normalizeBoolean(value: boolean): boolean {\n return value === true;\n}\n\nfunction clampConfidence(value: number): number {\n if (!Number.isFinite(value)) {\n return 0;\n }\n\n if (value < 0) {\n return 0;\n }\n\n if (value > 1) {\n return 1;\n }\n\n return value;\n}\n\nfunction asFrozenReasons(\n reasons: readonly AiRoutingDecisionReason[]\n): readonly AiRoutingDecisionReason[] {\n return Object.freeze([...reasons]);\n}\n\nfunction normalizePolicy(policy: AiRoutingPolicy = DEFAULT_ROUTING_POLICY): NormalizedAiRoutingPolicy {\n const minimumConfidence = clampConfidence(\n policy.minimumConfidence ?? DEFAULT_ROUTING_POLICY.minimumConfidence\n );\n const escalation = policy.escalation ?? DEFAULT_ROUTING_POLICY.escalation;\n const fallback = policy.fallback ?? DEFAULT_ROUTING_POLICY.fallback;\n const normalizedEscalation = Object.freeze({\n enabled: normalizeBoolean(escalation.enabled),\n overageMultiplier:\n escalation.overageMultiplier ??\n DEFAULT_ROUTING_POLICY.escalation.overageMultiplier,\n });\n const normalizedFallback = Object.freeze({\n enabled: normalizeBoolean(fallback.enabled),\n });\n\n return Object.freeze({\n enabled: normalizeBoolean(policy.enabled),\n minimumConfidence,\n allowProviderIds: policy.allowProviderIds\n ? Object.freeze([...policy.allowProviderIds])\n : undefined,\n denyProviderIds: policy.denyProviderIds\n ? Object.freeze([...policy.denyProviderIds])\n : undefined,\n budget: policy.budget ? Object.freeze({ ...policy.budget }) : undefined,\n confidenceEstimator: policy.confidenceEstimator,\n escalation: normalizedEscalation,\n fallback: normalizedFallback,\n });\n}\n\nfunction estimateConfidence(\n candidate: AiProviderCandidate,\n policy: NormalizedAiRoutingPolicy,\n mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">\n): number {\n const baseline = DEFAULT_BASELINE_CONFIDENCE[candidate.config.tier ?? \"standard\"];\n if (policy.confidenceEstimator) {\n return clampConfidence(\n policy.confidenceEstimator({\n candidate,\n mode,\n })\n );\n }\n\n return baseline;\n}\n\nfunction isReady(candidate: AiProviderCandidate): boolean {\n return (\n candidate.readiness.supported &&\n candidate.readiness.enabled &&\n candidate.config.enabled &&\n !candidate.readiness.diagnostics.some(\n (diagnostic: AiProviderDiagnostic) => diagnostic.severity === \"error\"\n )\n );\n}\n\nfunction isAllowedByPolicy(\n candidate: AiProviderCandidate,\n policy: NormalizedAiRoutingPolicy\n): {\n allowed: boolean;\n reason?: AiRoutingDecisionReason;\n} {\n if (policy.denyProviderIds?.includes(candidate.descriptor.providerId)) {\n return { allowed: false, reason: \"provider-denied-by-policy\" };\n }\n\n if (\n policy.allowProviderIds &&\n !policy.allowProviderIds.includes(candidate.descriptor.providerId)\n ) {\n return { allowed: false, reason: \"provider-allowlist-miss\" };\n }\n\n return { allowed: true };\n}\n\nfunction estimateLatency(candidate: AiProviderCandidate): number | undefined {\n const slo = candidate.descriptor.slo;\n return slo?.timeoutMs;\n}\n\nfunction estimateCost(candidate: AiProviderCandidate): number | undefined {\n return candidate.estimatedCostUsd;\n}\n\nfunction buildAssessments(\n requestId: string,\n candidates: readonly AiProviderCandidate[],\n policy: NormalizedAiRoutingPolicy,\n mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">\n): readonly AiRoutingCandidateAssessment[] {\n const evaluations = candidates.map((candidate) => {\n const reasons: AiRoutingDecisionReason[] = [];\n const allowed = isAllowedByPolicy(candidate, policy);\n if (!allowed.allowed && allowed.reason) {\n reasons.push(allowed.reason);\n }\n\n if (!candidate.config.enabled) {\n reasons.push(\"provider-disabled\");\n }\n\n if (!isReady(candidate)) {\n reasons.push(\"provider-not-ready\");\n }\n\n const estimatedConfidence = estimateConfidence(candidate, policy, mode);\n const estimatedLatencyMs = estimateLatency(candidate);\n const estimatedCostUsd = estimateCost(candidate);\n\n const maxCost = policy.budget?.maxCostUsd;\n if (\n maxCost !== undefined &&\n (estimatedCostUsd === undefined || estimatedCostUsd > maxCost)\n ) {\n reasons.push(\"cost-over-budget\");\n }\n\n const maxLatency = policy.budget?.maxLatencyMs;\n if (\n maxLatency !== undefined &&\n estimatedLatencyMs !== undefined &&\n estimatedLatencyMs > maxLatency\n ) {\n reasons.push(\"latency-over-budget\");\n }\n\n if (policy.minimumConfidence > estimatedConfidence) {\n reasons.push(\"confidence-under-threshold\");\n }\n\n if (reasons.length === 0) {\n reasons.push(\"selected\");\n }\n\n return Object.freeze({\n providerId: candidate.descriptor.providerId,\n providerModelId: candidate.readiness.selectedModelId,\n estimatedCostUsd,\n estimatedLatencyMs,\n estimatedConfidence,\n descriptor: candidate.descriptor,\n providerTier: candidate.config.tier,\n reasons: asFrozenReasons(reasons),\n mode,\n });\n });\n\n return Object.freeze([...evaluations].sort(DECISION_COMPARATOR));\n}\n\nfunction hasBlockingReasons(\n assessment: AiRoutingCandidateAssessment,\n includeConfidence: boolean\n): boolean {\n const blocking = new Set<AiRoutingDecisionReason>(assessment.reasons);\n const hardBlockingReasons: readonly AiRoutingDecisionReason[] = [\n \"provider-allowlist-miss\",\n \"provider-denied-by-policy\",\n \"provider-disabled\",\n \"provider-not-ready\",\n \"cost-over-budget\",\n \"latency-over-budget\",\n ];\n\n return (\n hardBlockingReasons.some((reason) => blocking.has(reason)) ||\n (includeConfidence && blocking.has(\"confidence-under-threshold\"))\n );\n}\n\nfunction pickCandidate(\n candidates: readonly AiRoutingCandidateAssessment[],\n includeConfidence: boolean\n): AiRoutingCandidateAssessment | undefined {\n return candidates.find(\n (candidate) => !hasBlockingReasons(candidate, includeConfidence)\n );\n}\n\nfunction createUnavailableDecision(\n requestId: string,\n policy: NormalizedAiRoutingPolicy,\n candidates: readonly AiProviderCandidate[]\n): AiRoutingDecision {\n const assessments = buildAssessments(\n requestId,\n candidates,\n policy,\n \"fallback\"\n );\n const reasons = [\"no-eligible-candidate\"] as AiRoutingDecisionReason[];\n\n return Object.freeze({\n requestId,\n mode: \"unavailable\",\n policy,\n candidates: assessments,\n unavailableReasons: asFrozenReasons(reasons),\n });\n}\n\nexport function selectAiProviderRoute(\n requestId: string,\n candidates: readonly AiProviderCandidate[],\n policy: AiRoutingPolicy = DEFAULT_ROUTING_POLICY\n): AiRoutingDecision {\n const normalizedPolicy = normalizePolicy(policy);\n if (!normalizedPolicy.enabled) {\n return Object.freeze({\n requestId,\n mode: \"disabled\",\n policy: normalizedPolicy,\n candidates: [],\n unavailableReasons: asFrozenReasons([\"disabled-by-flag\"]),\n });\n }\n\n const primaryAssessments = buildAssessments(\n requestId,\n candidates,\n normalizedPolicy,\n \"selected\"\n );\n\n const primary = pickCandidate(primaryAssessments, true);\n if (primary) {\n return Object.freeze({\n requestId,\n mode: \"selected\",\n policy: normalizedPolicy,\n selected: primary,\n candidates: primaryAssessments,\n unavailableReasons: [],\n });\n }\n\n const escalation = normalizedPolicy.escalation;\n const escalationPolicy: NormalizedAiRoutingPolicy = escalation.enabled\n ? Object.freeze({\n ...normalizedPolicy,\n minimumConfidence: 0,\n budget: normalizedPolicy.budget?.maxCostUsd\n ? Object.freeze({\n ...normalizedPolicy.budget,\n maxCostUsd:\n normalizedPolicy.budget.maxCostUsd *\n escalation.overageMultiplier,\n })\n : normalizedPolicy.budget,\n })\n : normalizedPolicy;\n\n if (escalation.enabled) {\n const escalatedAssessments = buildAssessments(\n requestId,\n candidates,\n escalationPolicy,\n \"escalated\"\n );\n const escalated = pickCandidate(escalatedAssessments, false);\n\n if (escalated) {\n return Object.freeze({\n requestId,\n mode: \"escalated\",\n policy: normalizedPolicy,\n selected: escalated,\n candidates: escalatedAssessments,\n unavailableReasons: [],\n });\n }\n }\n\n if (normalizedPolicy.fallback.enabled) {\n const fallbackAssessments = buildAssessments(\n requestId,\n candidates,\n {\n ...normalizedPolicy,\n minimumConfidence: 0,\n budget: undefined,\n },\n \"fallback\"\n );\n const fallback = pickCandidate(fallbackAssessments, false);\n\n if (fallback) {\n return Object.freeze({\n requestId,\n mode: \"fallback\",\n policy: normalizedPolicy,\n selected: fallback,\n candidates: fallbackAssessments,\n unavailableReasons: [],\n });\n }\n }\n\n return createUnavailableDecision(requestId, normalizedPolicy, candidates);\n}\n"],"mappings":"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","names":[]}
|
package/dist/index.d.cts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { AiProviderCandidate, AiProviderDescriptor, AiProviderTier } from '@plasius/ai-providers';
|
|
2
|
+
|
|
1
3
|
interface AiPackageDescriptor {
|
|
2
4
|
readonly packageName: string;
|
|
3
5
|
readonly featureFlagId: string;
|
|
@@ -5,8 +7,58 @@ interface AiPackageDescriptor {
|
|
|
5
7
|
readonly summary: string;
|
|
6
8
|
}
|
|
7
9
|
declare const AI_ROUTER_PACKAGE = "@plasius/ai-router";
|
|
8
|
-
declare const AI_ROUTER_FEATURE_FLAG_ID = "ai.
|
|
10
|
+
declare const AI_ROUTER_FEATURE_FLAG_ID = "ai.cost-aware-routing.enabled";
|
|
9
11
|
declare const AI_ROUTER_ENV_PREFIX = "AI_ROUTER";
|
|
10
12
|
declare const packageDescriptor: AiPackageDescriptor;
|
|
13
|
+
declare const AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;
|
|
14
|
+
declare const AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;
|
|
15
|
+
type AiRoutingDecisionMode = "disabled" | "selected" | "escalated" | "fallback" | "unavailable";
|
|
16
|
+
type AiRoutingDecisionReason = "disabled-by-flag" | "provider-list-empty" | "provider-denied-by-policy" | "provider-allowlist-miss" | "provider-disabled" | "provider-not-ready" | "cost-over-budget" | "latency-over-budget" | "confidence-under-threshold" | "no-eligible-candidate" | "selected";
|
|
17
|
+
interface AiProviderConfidenceEstimatorContext {
|
|
18
|
+
readonly candidate: AiProviderCandidate;
|
|
19
|
+
readonly mode: Exclude<AiRoutingDecisionMode, "unavailable" | "disabled">;
|
|
20
|
+
}
|
|
21
|
+
type AiProviderConfidenceEstimator = (context: AiProviderConfidenceEstimatorContext) => number;
|
|
22
|
+
interface AiRoutingBudgetPolicy {
|
|
23
|
+
readonly maxCostUsd?: number;
|
|
24
|
+
readonly maxLatencyMs?: number;
|
|
25
|
+
}
|
|
26
|
+
interface AiRoutingEscalationPolicy {
|
|
27
|
+
readonly enabled: boolean;
|
|
28
|
+
readonly overageMultiplier?: number;
|
|
29
|
+
}
|
|
30
|
+
interface AiRoutingFallbackPolicy {
|
|
31
|
+
readonly enabled: boolean;
|
|
32
|
+
}
|
|
33
|
+
interface AiRoutingPolicy {
|
|
34
|
+
readonly enabled: boolean;
|
|
35
|
+
readonly minimumConfidence?: number;
|
|
36
|
+
readonly allowProviderIds?: readonly string[];
|
|
37
|
+
readonly denyProviderIds?: readonly string[];
|
|
38
|
+
readonly budget?: AiRoutingBudgetPolicy;
|
|
39
|
+
readonly confidenceEstimator?: AiProviderConfidenceEstimator;
|
|
40
|
+
readonly escalation?: AiRoutingEscalationPolicy;
|
|
41
|
+
readonly fallback?: AiRoutingFallbackPolicy;
|
|
42
|
+
}
|
|
43
|
+
interface AiRoutingCandidateAssessment {
|
|
44
|
+
readonly providerId: string;
|
|
45
|
+
readonly providerModelId?: string;
|
|
46
|
+
readonly estimatedCostUsd?: number;
|
|
47
|
+
readonly estimatedLatencyMs?: number;
|
|
48
|
+
readonly estimatedConfidence: number;
|
|
49
|
+
readonly descriptor: AiProviderDescriptor;
|
|
50
|
+
readonly providerTier: AiProviderTier;
|
|
51
|
+
readonly reasons: readonly AiRoutingDecisionReason[];
|
|
52
|
+
readonly mode: Exclude<AiRoutingDecisionMode, "unavailable" | "disabled">;
|
|
53
|
+
}
|
|
54
|
+
interface AiRoutingDecision {
|
|
55
|
+
readonly requestId: string;
|
|
56
|
+
readonly mode: AiRoutingDecisionMode;
|
|
57
|
+
readonly policy: Readonly<AiRoutingPolicy>;
|
|
58
|
+
readonly selected?: AiRoutingCandidateAssessment;
|
|
59
|
+
readonly candidates: readonly AiRoutingCandidateAssessment[];
|
|
60
|
+
readonly unavailableReasons: readonly AiRoutingDecisionReason[];
|
|
61
|
+
}
|
|
62
|
+
declare function selectAiProviderRoute(requestId: string, candidates: readonly AiProviderCandidate[], policy?: AiRoutingPolicy): AiRoutingDecision;
|
|
11
63
|
|
|
12
|
-
export { AI_ROUTER_ENV_PREFIX, AI_ROUTER_FEATURE_FLAG_ID, AI_ROUTER_PACKAGE, type AiPackageDescriptor, packageDescriptor };
|
|
64
|
+
export { AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER, AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE, AI_ROUTER_ENV_PREFIX, AI_ROUTER_FEATURE_FLAG_ID, AI_ROUTER_PACKAGE, type AiPackageDescriptor, type AiProviderConfidenceEstimator, type AiProviderConfidenceEstimatorContext, type AiRoutingBudgetPolicy, type AiRoutingCandidateAssessment, type AiRoutingDecision, type AiRoutingDecisionMode, type AiRoutingDecisionReason, type AiRoutingEscalationPolicy, type AiRoutingFallbackPolicy, type AiRoutingPolicy, packageDescriptor, selectAiProviderRoute };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import { AiProviderCandidate, AiProviderDescriptor, AiProviderTier } from '@plasius/ai-providers';
|
|
2
|
+
|
|
1
3
|
interface AiPackageDescriptor {
|
|
2
4
|
readonly packageName: string;
|
|
3
5
|
readonly featureFlagId: string;
|
|
@@ -5,8 +7,58 @@ interface AiPackageDescriptor {
|
|
|
5
7
|
readonly summary: string;
|
|
6
8
|
}
|
|
7
9
|
declare const AI_ROUTER_PACKAGE = "@plasius/ai-router";
|
|
8
|
-
declare const AI_ROUTER_FEATURE_FLAG_ID = "ai.
|
|
10
|
+
declare const AI_ROUTER_FEATURE_FLAG_ID = "ai.cost-aware-routing.enabled";
|
|
9
11
|
declare const AI_ROUTER_ENV_PREFIX = "AI_ROUTER";
|
|
10
12
|
declare const packageDescriptor: AiPackageDescriptor;
|
|
13
|
+
declare const AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;
|
|
14
|
+
declare const AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;
|
|
15
|
+
type AiRoutingDecisionMode = "disabled" | "selected" | "escalated" | "fallback" | "unavailable";
|
|
16
|
+
type AiRoutingDecisionReason = "disabled-by-flag" | "provider-list-empty" | "provider-denied-by-policy" | "provider-allowlist-miss" | "provider-disabled" | "provider-not-ready" | "cost-over-budget" | "latency-over-budget" | "confidence-under-threshold" | "no-eligible-candidate" | "selected";
|
|
17
|
+
interface AiProviderConfidenceEstimatorContext {
|
|
18
|
+
readonly candidate: AiProviderCandidate;
|
|
19
|
+
readonly mode: Exclude<AiRoutingDecisionMode, "unavailable" | "disabled">;
|
|
20
|
+
}
|
|
21
|
+
type AiProviderConfidenceEstimator = (context: AiProviderConfidenceEstimatorContext) => number;
|
|
22
|
+
interface AiRoutingBudgetPolicy {
|
|
23
|
+
readonly maxCostUsd?: number;
|
|
24
|
+
readonly maxLatencyMs?: number;
|
|
25
|
+
}
|
|
26
|
+
interface AiRoutingEscalationPolicy {
|
|
27
|
+
readonly enabled: boolean;
|
|
28
|
+
readonly overageMultiplier?: number;
|
|
29
|
+
}
|
|
30
|
+
interface AiRoutingFallbackPolicy {
|
|
31
|
+
readonly enabled: boolean;
|
|
32
|
+
}
|
|
33
|
+
interface AiRoutingPolicy {
|
|
34
|
+
readonly enabled: boolean;
|
|
35
|
+
readonly minimumConfidence?: number;
|
|
36
|
+
readonly allowProviderIds?: readonly string[];
|
|
37
|
+
readonly denyProviderIds?: readonly string[];
|
|
38
|
+
readonly budget?: AiRoutingBudgetPolicy;
|
|
39
|
+
readonly confidenceEstimator?: AiProviderConfidenceEstimator;
|
|
40
|
+
readonly escalation?: AiRoutingEscalationPolicy;
|
|
41
|
+
readonly fallback?: AiRoutingFallbackPolicy;
|
|
42
|
+
}
|
|
43
|
+
interface AiRoutingCandidateAssessment {
|
|
44
|
+
readonly providerId: string;
|
|
45
|
+
readonly providerModelId?: string;
|
|
46
|
+
readonly estimatedCostUsd?: number;
|
|
47
|
+
readonly estimatedLatencyMs?: number;
|
|
48
|
+
readonly estimatedConfidence: number;
|
|
49
|
+
readonly descriptor: AiProviderDescriptor;
|
|
50
|
+
readonly providerTier: AiProviderTier;
|
|
51
|
+
readonly reasons: readonly AiRoutingDecisionReason[];
|
|
52
|
+
readonly mode: Exclude<AiRoutingDecisionMode, "unavailable" | "disabled">;
|
|
53
|
+
}
|
|
54
|
+
interface AiRoutingDecision {
|
|
55
|
+
readonly requestId: string;
|
|
56
|
+
readonly mode: AiRoutingDecisionMode;
|
|
57
|
+
readonly policy: Readonly<AiRoutingPolicy>;
|
|
58
|
+
readonly selected?: AiRoutingCandidateAssessment;
|
|
59
|
+
readonly candidates: readonly AiRoutingCandidateAssessment[];
|
|
60
|
+
readonly unavailableReasons: readonly AiRoutingDecisionReason[];
|
|
61
|
+
}
|
|
62
|
+
declare function selectAiProviderRoute(requestId: string, candidates: readonly AiProviderCandidate[], policy?: AiRoutingPolicy): AiRoutingDecision;
|
|
11
63
|
|
|
12
|
-
export { AI_ROUTER_ENV_PREFIX, AI_ROUTER_FEATURE_FLAG_ID, AI_ROUTER_PACKAGE, type AiPackageDescriptor, packageDescriptor };
|
|
64
|
+
export { AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER, AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE, AI_ROUTER_ENV_PREFIX, AI_ROUTER_FEATURE_FLAG_ID, AI_ROUTER_PACKAGE, type AiPackageDescriptor, type AiProviderConfidenceEstimator, type AiProviderConfidenceEstimatorContext, type AiRoutingBudgetPolicy, type AiRoutingCandidateAssessment, type AiRoutingDecision, type AiRoutingDecisionMode, type AiRoutingDecisionReason, type AiRoutingEscalationPolicy, type AiRoutingFallbackPolicy, type AiRoutingPolicy, packageDescriptor, selectAiProviderRoute };
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// src/index.ts
|
|
2
2
|
var AI_ROUTER_PACKAGE = "@plasius/ai-router";
|
|
3
|
-
var AI_ROUTER_FEATURE_FLAG_ID = "ai.
|
|
3
|
+
var AI_ROUTER_FEATURE_FLAG_ID = "ai.cost-aware-routing.enabled";
|
|
4
4
|
var AI_ROUTER_ENV_PREFIX = "AI_ROUTER";
|
|
5
5
|
var packageDescriptor = Object.freeze({
|
|
6
6
|
packageName: AI_ROUTER_PACKAGE,
|
|
@@ -8,10 +8,280 @@ var packageDescriptor = Object.freeze({
|
|
|
8
8
|
envPrefix: AI_ROUTER_ENV_PREFIX,
|
|
9
9
|
summary: "Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads."
|
|
10
10
|
});
|
|
11
|
+
var AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;
|
|
12
|
+
var AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;
|
|
13
|
+
var DEFAULT_ROUTING_ESCALATION_POLICY = Object.freeze({
|
|
14
|
+
enabled: true,
|
|
15
|
+
overageMultiplier: AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER
|
|
16
|
+
});
|
|
17
|
+
var DEFAULT_ROUTING_FALLBACK_POLICY = Object.freeze({
|
|
18
|
+
enabled: true
|
|
19
|
+
});
|
|
20
|
+
var DEFAULT_ROUTING_POLICY = Object.freeze({
|
|
21
|
+
enabled: true,
|
|
22
|
+
minimumConfidence: AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,
|
|
23
|
+
escalation: DEFAULT_ROUTING_ESCALATION_POLICY,
|
|
24
|
+
fallback: DEFAULT_ROUTING_FALLBACK_POLICY
|
|
25
|
+
});
|
|
26
|
+
var DEFAULT_BASELINE_CONFIDENCE = {
|
|
27
|
+
free: 0.45,
|
|
28
|
+
development: 0.62,
|
|
29
|
+
standard: 0.82,
|
|
30
|
+
premium: 0.96
|
|
31
|
+
};
|
|
32
|
+
var DECISION_COMPARATOR = (left, right) => {
|
|
33
|
+
const leftCost = left.estimatedCostUsd ?? Number.POSITIVE_INFINITY;
|
|
34
|
+
const rightCost = right.estimatedCostUsd ?? Number.POSITIVE_INFINITY;
|
|
35
|
+
const costComparison = leftCost - rightCost;
|
|
36
|
+
if (costComparison !== 0) {
|
|
37
|
+
return costComparison;
|
|
38
|
+
}
|
|
39
|
+
const confidenceComparison = right.estimatedConfidence - left.estimatedConfidence;
|
|
40
|
+
if (confidenceComparison !== 0) {
|
|
41
|
+
return confidenceComparison;
|
|
42
|
+
}
|
|
43
|
+
return left.providerId.localeCompare(right.providerId);
|
|
44
|
+
};
|
|
45
|
+
function normalizeBoolean(value) {
|
|
46
|
+
return value === true;
|
|
47
|
+
}
|
|
48
|
+
function clampConfidence(value) {
|
|
49
|
+
if (!Number.isFinite(value)) {
|
|
50
|
+
return 0;
|
|
51
|
+
}
|
|
52
|
+
if (value < 0) {
|
|
53
|
+
return 0;
|
|
54
|
+
}
|
|
55
|
+
if (value > 1) {
|
|
56
|
+
return 1;
|
|
57
|
+
}
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
function asFrozenReasons(reasons) {
|
|
61
|
+
return Object.freeze([...reasons]);
|
|
62
|
+
}
|
|
63
|
+
function normalizePolicy(policy = DEFAULT_ROUTING_POLICY) {
|
|
64
|
+
const minimumConfidence = clampConfidence(
|
|
65
|
+
policy.minimumConfidence ?? DEFAULT_ROUTING_POLICY.minimumConfidence
|
|
66
|
+
);
|
|
67
|
+
const escalation = policy.escalation ?? DEFAULT_ROUTING_POLICY.escalation;
|
|
68
|
+
const fallback = policy.fallback ?? DEFAULT_ROUTING_POLICY.fallback;
|
|
69
|
+
const normalizedEscalation = Object.freeze({
|
|
70
|
+
enabled: normalizeBoolean(escalation.enabled),
|
|
71
|
+
overageMultiplier: escalation.overageMultiplier ?? DEFAULT_ROUTING_POLICY.escalation.overageMultiplier
|
|
72
|
+
});
|
|
73
|
+
const normalizedFallback = Object.freeze({
|
|
74
|
+
enabled: normalizeBoolean(fallback.enabled)
|
|
75
|
+
});
|
|
76
|
+
return Object.freeze({
|
|
77
|
+
enabled: normalizeBoolean(policy.enabled),
|
|
78
|
+
minimumConfidence,
|
|
79
|
+
allowProviderIds: policy.allowProviderIds ? Object.freeze([...policy.allowProviderIds]) : void 0,
|
|
80
|
+
denyProviderIds: policy.denyProviderIds ? Object.freeze([...policy.denyProviderIds]) : void 0,
|
|
81
|
+
budget: policy.budget ? Object.freeze({ ...policy.budget }) : void 0,
|
|
82
|
+
confidenceEstimator: policy.confidenceEstimator,
|
|
83
|
+
escalation: normalizedEscalation,
|
|
84
|
+
fallback: normalizedFallback
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
function estimateConfidence(candidate, policy, mode) {
|
|
88
|
+
const baseline = DEFAULT_BASELINE_CONFIDENCE[candidate.config.tier ?? "standard"];
|
|
89
|
+
if (policy.confidenceEstimator) {
|
|
90
|
+
return clampConfidence(
|
|
91
|
+
policy.confidenceEstimator({
|
|
92
|
+
candidate,
|
|
93
|
+
mode
|
|
94
|
+
})
|
|
95
|
+
);
|
|
96
|
+
}
|
|
97
|
+
return baseline;
|
|
98
|
+
}
|
|
99
|
+
function isReady(candidate) {
|
|
100
|
+
return candidate.readiness.supported && candidate.readiness.enabled && candidate.config.enabled && !candidate.readiness.diagnostics.some(
|
|
101
|
+
(diagnostic) => diagnostic.severity === "error"
|
|
102
|
+
);
|
|
103
|
+
}
|
|
104
|
+
function isAllowedByPolicy(candidate, policy) {
|
|
105
|
+
if (policy.denyProviderIds?.includes(candidate.descriptor.providerId)) {
|
|
106
|
+
return { allowed: false, reason: "provider-denied-by-policy" };
|
|
107
|
+
}
|
|
108
|
+
if (policy.allowProviderIds && !policy.allowProviderIds.includes(candidate.descriptor.providerId)) {
|
|
109
|
+
return { allowed: false, reason: "provider-allowlist-miss" };
|
|
110
|
+
}
|
|
111
|
+
return { allowed: true };
|
|
112
|
+
}
|
|
113
|
+
function estimateLatency(candidate) {
|
|
114
|
+
const slo = candidate.descriptor.slo;
|
|
115
|
+
return slo?.timeoutMs;
|
|
116
|
+
}
|
|
117
|
+
function estimateCost(candidate) {
|
|
118
|
+
return candidate.estimatedCostUsd;
|
|
119
|
+
}
|
|
120
|
+
function buildAssessments(requestId, candidates, policy, mode) {
|
|
121
|
+
const evaluations = candidates.map((candidate) => {
|
|
122
|
+
const reasons = [];
|
|
123
|
+
const allowed = isAllowedByPolicy(candidate, policy);
|
|
124
|
+
if (!allowed.allowed && allowed.reason) {
|
|
125
|
+
reasons.push(allowed.reason);
|
|
126
|
+
}
|
|
127
|
+
if (!candidate.config.enabled) {
|
|
128
|
+
reasons.push("provider-disabled");
|
|
129
|
+
}
|
|
130
|
+
if (!isReady(candidate)) {
|
|
131
|
+
reasons.push("provider-not-ready");
|
|
132
|
+
}
|
|
133
|
+
const estimatedConfidence = estimateConfidence(candidate, policy, mode);
|
|
134
|
+
const estimatedLatencyMs = estimateLatency(candidate);
|
|
135
|
+
const estimatedCostUsd = estimateCost(candidate);
|
|
136
|
+
const maxCost = policy.budget?.maxCostUsd;
|
|
137
|
+
if (maxCost !== void 0 && (estimatedCostUsd === void 0 || estimatedCostUsd > maxCost)) {
|
|
138
|
+
reasons.push("cost-over-budget");
|
|
139
|
+
}
|
|
140
|
+
const maxLatency = policy.budget?.maxLatencyMs;
|
|
141
|
+
if (maxLatency !== void 0 && estimatedLatencyMs !== void 0 && estimatedLatencyMs > maxLatency) {
|
|
142
|
+
reasons.push("latency-over-budget");
|
|
143
|
+
}
|
|
144
|
+
if (policy.minimumConfidence > estimatedConfidence) {
|
|
145
|
+
reasons.push("confidence-under-threshold");
|
|
146
|
+
}
|
|
147
|
+
if (reasons.length === 0) {
|
|
148
|
+
reasons.push("selected");
|
|
149
|
+
}
|
|
150
|
+
return Object.freeze({
|
|
151
|
+
providerId: candidate.descriptor.providerId,
|
|
152
|
+
providerModelId: candidate.readiness.selectedModelId,
|
|
153
|
+
estimatedCostUsd,
|
|
154
|
+
estimatedLatencyMs,
|
|
155
|
+
estimatedConfidence,
|
|
156
|
+
descriptor: candidate.descriptor,
|
|
157
|
+
providerTier: candidate.config.tier,
|
|
158
|
+
reasons: asFrozenReasons(reasons),
|
|
159
|
+
mode
|
|
160
|
+
});
|
|
161
|
+
});
|
|
162
|
+
return Object.freeze([...evaluations].sort(DECISION_COMPARATOR));
|
|
163
|
+
}
|
|
164
|
+
function hasBlockingReasons(assessment, includeConfidence) {
|
|
165
|
+
const blocking = new Set(assessment.reasons);
|
|
166
|
+
const hardBlockingReasons = [
|
|
167
|
+
"provider-allowlist-miss",
|
|
168
|
+
"provider-denied-by-policy",
|
|
169
|
+
"provider-disabled",
|
|
170
|
+
"provider-not-ready",
|
|
171
|
+
"cost-over-budget",
|
|
172
|
+
"latency-over-budget"
|
|
173
|
+
];
|
|
174
|
+
return hardBlockingReasons.some((reason) => blocking.has(reason)) || includeConfidence && blocking.has("confidence-under-threshold");
|
|
175
|
+
}
|
|
176
|
+
function pickCandidate(candidates, includeConfidence) {
|
|
177
|
+
return candidates.find(
|
|
178
|
+
(candidate) => !hasBlockingReasons(candidate, includeConfidence)
|
|
179
|
+
);
|
|
180
|
+
}
|
|
181
|
+
function createUnavailableDecision(requestId, policy, candidates) {
|
|
182
|
+
const assessments = buildAssessments(
|
|
183
|
+
requestId,
|
|
184
|
+
candidates,
|
|
185
|
+
policy,
|
|
186
|
+
"fallback"
|
|
187
|
+
);
|
|
188
|
+
const reasons = ["no-eligible-candidate"];
|
|
189
|
+
return Object.freeze({
|
|
190
|
+
requestId,
|
|
191
|
+
mode: "unavailable",
|
|
192
|
+
policy,
|
|
193
|
+
candidates: assessments,
|
|
194
|
+
unavailableReasons: asFrozenReasons(reasons)
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
function selectAiProviderRoute(requestId, candidates, policy = DEFAULT_ROUTING_POLICY) {
|
|
198
|
+
const normalizedPolicy = normalizePolicy(policy);
|
|
199
|
+
if (!normalizedPolicy.enabled) {
|
|
200
|
+
return Object.freeze({
|
|
201
|
+
requestId,
|
|
202
|
+
mode: "disabled",
|
|
203
|
+
policy: normalizedPolicy,
|
|
204
|
+
candidates: [],
|
|
205
|
+
unavailableReasons: asFrozenReasons(["disabled-by-flag"])
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
const primaryAssessments = buildAssessments(
|
|
209
|
+
requestId,
|
|
210
|
+
candidates,
|
|
211
|
+
normalizedPolicy,
|
|
212
|
+
"selected"
|
|
213
|
+
);
|
|
214
|
+
const primary = pickCandidate(primaryAssessments, true);
|
|
215
|
+
if (primary) {
|
|
216
|
+
return Object.freeze({
|
|
217
|
+
requestId,
|
|
218
|
+
mode: "selected",
|
|
219
|
+
policy: normalizedPolicy,
|
|
220
|
+
selected: primary,
|
|
221
|
+
candidates: primaryAssessments,
|
|
222
|
+
unavailableReasons: []
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
const escalation = normalizedPolicy.escalation;
|
|
226
|
+
const escalationPolicy = escalation.enabled ? Object.freeze({
|
|
227
|
+
...normalizedPolicy,
|
|
228
|
+
minimumConfidence: 0,
|
|
229
|
+
budget: normalizedPolicy.budget?.maxCostUsd ? Object.freeze({
|
|
230
|
+
...normalizedPolicy.budget,
|
|
231
|
+
maxCostUsd: normalizedPolicy.budget.maxCostUsd * escalation.overageMultiplier
|
|
232
|
+
}) : normalizedPolicy.budget
|
|
233
|
+
}) : normalizedPolicy;
|
|
234
|
+
if (escalation.enabled) {
|
|
235
|
+
const escalatedAssessments = buildAssessments(
|
|
236
|
+
requestId,
|
|
237
|
+
candidates,
|
|
238
|
+
escalationPolicy,
|
|
239
|
+
"escalated"
|
|
240
|
+
);
|
|
241
|
+
const escalated = pickCandidate(escalatedAssessments, false);
|
|
242
|
+
if (escalated) {
|
|
243
|
+
return Object.freeze({
|
|
244
|
+
requestId,
|
|
245
|
+
mode: "escalated",
|
|
246
|
+
policy: normalizedPolicy,
|
|
247
|
+
selected: escalated,
|
|
248
|
+
candidates: escalatedAssessments,
|
|
249
|
+
unavailableReasons: []
|
|
250
|
+
});
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
if (normalizedPolicy.fallback.enabled) {
|
|
254
|
+
const fallbackAssessments = buildAssessments(
|
|
255
|
+
requestId,
|
|
256
|
+
candidates,
|
|
257
|
+
{
|
|
258
|
+
...normalizedPolicy,
|
|
259
|
+
minimumConfidence: 0,
|
|
260
|
+
budget: void 0
|
|
261
|
+
},
|
|
262
|
+
"fallback"
|
|
263
|
+
);
|
|
264
|
+
const fallback = pickCandidate(fallbackAssessments, false);
|
|
265
|
+
if (fallback) {
|
|
266
|
+
return Object.freeze({
|
|
267
|
+
requestId,
|
|
268
|
+
mode: "fallback",
|
|
269
|
+
policy: normalizedPolicy,
|
|
270
|
+
selected: fallback,
|
|
271
|
+
candidates: fallbackAssessments,
|
|
272
|
+
unavailableReasons: []
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
}
|
|
276
|
+
return createUnavailableDecision(requestId, normalizedPolicy, candidates);
|
|
277
|
+
}
|
|
11
278
|
export {
|
|
279
|
+
AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER,
|
|
280
|
+
AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,
|
|
12
281
|
AI_ROUTER_ENV_PREFIX,
|
|
13
282
|
AI_ROUTER_FEATURE_FLAG_ID,
|
|
14
283
|
AI_ROUTER_PACKAGE,
|
|
15
|
-
packageDescriptor
|
|
284
|
+
packageDescriptor,
|
|
285
|
+
selectAiProviderRoute
|
|
16
286
|
};
|
|
17
287
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export interface AiPackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport const AI_ROUTER_PACKAGE = \"@plasius/ai-router\";\nexport const AI_ROUTER_FEATURE_FLAG_ID = \"ai.router.enabled\";\nexport const AI_ROUTER_ENV_PREFIX = \"AI_ROUTER\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n packageName: AI_ROUTER_PACKAGE,\n featureFlagId: AI_ROUTER_FEATURE_FLAG_ID,\n envPrefix: AI_ROUTER_ENV_PREFIX,\n summary: \"Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads.\",\n});\n"],"mappings":";AAOO,IAAM,oBAAoB;AAC1B,IAAM,4BAA4B;AAClC,IAAM,uBAAuB;AAE7B,IAAM,oBAAyC,OAAO,OAAO;AAAA,EAClE,aAAa;AAAA,EACb,eAAe;AAAA,EACf,WAAW;AAAA,EACX,SAAS;AACX,CAAC;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type {\n AiProviderCandidate,\n AiProviderTier,\n AiProviderDescriptor,\n AiProviderDiagnostic,\n} from \"@plasius/ai-providers\";\n\nexport interface AiPackageDescriptor {\n readonly packageName: string;\n readonly featureFlagId: string;\n readonly envPrefix: string;\n readonly summary: string;\n}\n\nexport const AI_ROUTER_PACKAGE = \"@plasius/ai-router\";\nexport const AI_ROUTER_FEATURE_FLAG_ID = \"ai.cost-aware-routing.enabled\";\nexport const AI_ROUTER_ENV_PREFIX = \"AI_ROUTER\";\n\nexport const packageDescriptor: AiPackageDescriptor = Object.freeze({\n packageName: AI_ROUTER_PACKAGE,\n featureFlagId: AI_ROUTER_FEATURE_FLAG_ID,\n envPrefix: AI_ROUTER_ENV_PREFIX,\n summary:\n \"Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads.\",\n});\n\nexport const AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE = 0.75;\nexport const AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER = 1.5;\n\nexport type AiRoutingDecisionMode =\n | \"disabled\"\n | \"selected\"\n | \"escalated\"\n | \"fallback\"\n | \"unavailable\";\n\nexport type AiRoutingDecisionReason =\n | \"disabled-by-flag\"\n | \"provider-list-empty\"\n | \"provider-denied-by-policy\"\n | \"provider-allowlist-miss\"\n | \"provider-disabled\"\n | \"provider-not-ready\"\n | \"cost-over-budget\"\n | \"latency-over-budget\"\n | \"confidence-under-threshold\"\n | \"no-eligible-candidate\"\n | \"selected\";\n\nexport interface AiProviderConfidenceEstimatorContext {\n readonly candidate: AiProviderCandidate;\n readonly mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">;\n}\n\nexport type AiProviderConfidenceEstimator = (\n context: AiProviderConfidenceEstimatorContext\n) => number;\n\nexport interface AiRoutingBudgetPolicy {\n readonly maxCostUsd?: number;\n readonly maxLatencyMs?: number;\n}\n\nexport interface AiRoutingEscalationPolicy {\n readonly enabled: boolean;\n readonly overageMultiplier?: number;\n}\n\nexport interface AiRoutingFallbackPolicy {\n readonly enabled: boolean;\n}\n\nexport interface AiRoutingPolicy {\n readonly enabled: boolean;\n readonly minimumConfidence?: number;\n readonly allowProviderIds?: readonly string[];\n readonly denyProviderIds?: readonly string[];\n readonly budget?: AiRoutingBudgetPolicy;\n readonly confidenceEstimator?: AiProviderConfidenceEstimator;\n readonly escalation?: AiRoutingEscalationPolicy;\n readonly fallback?: AiRoutingFallbackPolicy;\n}\n\nexport interface AiRoutingCandidateAssessment {\n readonly providerId: string;\n readonly providerModelId?: string;\n readonly estimatedCostUsd?: number;\n readonly estimatedLatencyMs?: number;\n readonly estimatedConfidence: number;\n readonly descriptor: AiProviderDescriptor;\n readonly providerTier: AiProviderTier;\n readonly reasons: readonly AiRoutingDecisionReason[];\n readonly mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">;\n}\n\nexport interface AiRoutingDecision {\n readonly requestId: string;\n readonly mode: AiRoutingDecisionMode;\n readonly policy: Readonly<AiRoutingPolicy>;\n readonly selected?: AiRoutingCandidateAssessment;\n readonly candidates: readonly AiRoutingCandidateAssessment[];\n readonly unavailableReasons: readonly AiRoutingDecisionReason[];\n}\n\ntype NormalizedAiRoutingPolicy = Readonly<\n Omit<AiRoutingPolicy, \"minimumConfidence\" | \"escalation\" | \"fallback\"> & {\n readonly minimumConfidence: number;\n readonly escalation: Readonly<Required<AiRoutingEscalationPolicy>>;\n readonly fallback: Readonly<Required<AiRoutingFallbackPolicy>>;\n }\n>;\n\nconst DEFAULT_ROUTING_ESCALATION_POLICY: Readonly<\n Required<AiRoutingEscalationPolicy>\n> = Object.freeze({\n enabled: true,\n overageMultiplier: AI_ROUTER_DEFAULT_BUDGET_OVERAGE_MULTIPLIER,\n});\n\nconst DEFAULT_ROUTING_FALLBACK_POLICY: Readonly<\n Required<AiRoutingFallbackPolicy>\n> = Object.freeze({\n enabled: true,\n});\n\nconst DEFAULT_ROUTING_POLICY: NormalizedAiRoutingPolicy = Object.freeze({\n enabled: true,\n minimumConfidence: AI_ROUTER_DEFAULT_MINIMUM_CONFIDENCE,\n escalation: DEFAULT_ROUTING_ESCALATION_POLICY,\n fallback: DEFAULT_ROUTING_FALLBACK_POLICY,\n});\n\nconst DEFAULT_BASELINE_CONFIDENCE: Record<AiProviderTier, number> = {\n free: 0.45,\n development: 0.62,\n standard: 0.82,\n premium: 0.96,\n};\n\nconst DECISION_COMPARATOR = (left: AiRoutingCandidateAssessment, right: AiRoutingCandidateAssessment): number => {\n const leftCost = left.estimatedCostUsd ?? Number.POSITIVE_INFINITY;\n const rightCost = right.estimatedCostUsd ?? Number.POSITIVE_INFINITY;\n const costComparison = leftCost - rightCost;\n if (costComparison !== 0) {\n return costComparison;\n }\n\n const confidenceComparison = right.estimatedConfidence - left.estimatedConfidence;\n if (confidenceComparison !== 0) {\n return confidenceComparison;\n }\n\n return left.providerId.localeCompare(right.providerId);\n};\n\nfunction normalizeBoolean(value: boolean): boolean {\n return value === true;\n}\n\nfunction clampConfidence(value: number): number {\n if (!Number.isFinite(value)) {\n return 0;\n }\n\n if (value < 0) {\n return 0;\n }\n\n if (value > 1) {\n return 1;\n }\n\n return value;\n}\n\nfunction asFrozenReasons(\n reasons: readonly AiRoutingDecisionReason[]\n): readonly AiRoutingDecisionReason[] {\n return Object.freeze([...reasons]);\n}\n\nfunction normalizePolicy(policy: AiRoutingPolicy = DEFAULT_ROUTING_POLICY): NormalizedAiRoutingPolicy {\n const minimumConfidence = clampConfidence(\n policy.minimumConfidence ?? DEFAULT_ROUTING_POLICY.minimumConfidence\n );\n const escalation = policy.escalation ?? DEFAULT_ROUTING_POLICY.escalation;\n const fallback = policy.fallback ?? DEFAULT_ROUTING_POLICY.fallback;\n const normalizedEscalation = Object.freeze({\n enabled: normalizeBoolean(escalation.enabled),\n overageMultiplier:\n escalation.overageMultiplier ??\n DEFAULT_ROUTING_POLICY.escalation.overageMultiplier,\n });\n const normalizedFallback = Object.freeze({\n enabled: normalizeBoolean(fallback.enabled),\n });\n\n return Object.freeze({\n enabled: normalizeBoolean(policy.enabled),\n minimumConfidence,\n allowProviderIds: policy.allowProviderIds\n ? Object.freeze([...policy.allowProviderIds])\n : undefined,\n denyProviderIds: policy.denyProviderIds\n ? Object.freeze([...policy.denyProviderIds])\n : undefined,\n budget: policy.budget ? Object.freeze({ ...policy.budget }) : undefined,\n confidenceEstimator: policy.confidenceEstimator,\n escalation: normalizedEscalation,\n fallback: normalizedFallback,\n });\n}\n\nfunction estimateConfidence(\n candidate: AiProviderCandidate,\n policy: NormalizedAiRoutingPolicy,\n mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">\n): number {\n const baseline = DEFAULT_BASELINE_CONFIDENCE[candidate.config.tier ?? \"standard\"];\n if (policy.confidenceEstimator) {\n return clampConfidence(\n policy.confidenceEstimator({\n candidate,\n mode,\n })\n );\n }\n\n return baseline;\n}\n\nfunction isReady(candidate: AiProviderCandidate): boolean {\n return (\n candidate.readiness.supported &&\n candidate.readiness.enabled &&\n candidate.config.enabled &&\n !candidate.readiness.diagnostics.some(\n (diagnostic: AiProviderDiagnostic) => diagnostic.severity === \"error\"\n )\n );\n}\n\nfunction isAllowedByPolicy(\n candidate: AiProviderCandidate,\n policy: NormalizedAiRoutingPolicy\n): {\n allowed: boolean;\n reason?: AiRoutingDecisionReason;\n} {\n if (policy.denyProviderIds?.includes(candidate.descriptor.providerId)) {\n return { allowed: false, reason: \"provider-denied-by-policy\" };\n }\n\n if (\n policy.allowProviderIds &&\n !policy.allowProviderIds.includes(candidate.descriptor.providerId)\n ) {\n return { allowed: false, reason: \"provider-allowlist-miss\" };\n }\n\n return { allowed: true };\n}\n\nfunction estimateLatency(candidate: AiProviderCandidate): number | undefined {\n const slo = candidate.descriptor.slo;\n return slo?.timeoutMs;\n}\n\nfunction estimateCost(candidate: AiProviderCandidate): number | undefined {\n return candidate.estimatedCostUsd;\n}\n\nfunction buildAssessments(\n requestId: string,\n candidates: readonly AiProviderCandidate[],\n policy: NormalizedAiRoutingPolicy,\n mode: Exclude<AiRoutingDecisionMode, \"unavailable\" | \"disabled\">\n): readonly AiRoutingCandidateAssessment[] {\n const evaluations = candidates.map((candidate) => {\n const reasons: AiRoutingDecisionReason[] = [];\n const allowed = isAllowedByPolicy(candidate, policy);\n if (!allowed.allowed && allowed.reason) {\n reasons.push(allowed.reason);\n }\n\n if (!candidate.config.enabled) {\n reasons.push(\"provider-disabled\");\n }\n\n if (!isReady(candidate)) {\n reasons.push(\"provider-not-ready\");\n }\n\n const estimatedConfidence = estimateConfidence(candidate, policy, mode);\n const estimatedLatencyMs = estimateLatency(candidate);\n const estimatedCostUsd = estimateCost(candidate);\n\n const maxCost = policy.budget?.maxCostUsd;\n if (\n maxCost !== undefined &&\n (estimatedCostUsd === undefined || estimatedCostUsd > maxCost)\n ) {\n reasons.push(\"cost-over-budget\");\n }\n\n const maxLatency = policy.budget?.maxLatencyMs;\n if (\n maxLatency !== undefined &&\n estimatedLatencyMs !== undefined &&\n estimatedLatencyMs > maxLatency\n ) {\n reasons.push(\"latency-over-budget\");\n }\n\n if (policy.minimumConfidence > estimatedConfidence) {\n reasons.push(\"confidence-under-threshold\");\n }\n\n if (reasons.length === 0) {\n reasons.push(\"selected\");\n }\n\n return Object.freeze({\n providerId: candidate.descriptor.providerId,\n providerModelId: candidate.readiness.selectedModelId,\n estimatedCostUsd,\n estimatedLatencyMs,\n estimatedConfidence,\n descriptor: candidate.descriptor,\n providerTier: candidate.config.tier,\n reasons: asFrozenReasons(reasons),\n mode,\n });\n });\n\n return Object.freeze([...evaluations].sort(DECISION_COMPARATOR));\n}\n\nfunction hasBlockingReasons(\n assessment: AiRoutingCandidateAssessment,\n includeConfidence: boolean\n): boolean {\n const blocking = new Set<AiRoutingDecisionReason>(assessment.reasons);\n const hardBlockingReasons: readonly AiRoutingDecisionReason[] = [\n \"provider-allowlist-miss\",\n \"provider-denied-by-policy\",\n \"provider-disabled\",\n \"provider-not-ready\",\n \"cost-over-budget\",\n \"latency-over-budget\",\n ];\n\n return (\n hardBlockingReasons.some((reason) => blocking.has(reason)) ||\n (includeConfidence && blocking.has(\"confidence-under-threshold\"))\n );\n}\n\nfunction pickCandidate(\n candidates: readonly AiRoutingCandidateAssessment[],\n includeConfidence: boolean\n): AiRoutingCandidateAssessment | undefined {\n return candidates.find(\n (candidate) => !hasBlockingReasons(candidate, includeConfidence)\n );\n}\n\nfunction createUnavailableDecision(\n requestId: string,\n policy: NormalizedAiRoutingPolicy,\n candidates: readonly AiProviderCandidate[]\n): AiRoutingDecision {\n const assessments = buildAssessments(\n requestId,\n candidates,\n policy,\n \"fallback\"\n );\n const reasons = [\"no-eligible-candidate\"] as AiRoutingDecisionReason[];\n\n return Object.freeze({\n requestId,\n mode: \"unavailable\",\n policy,\n candidates: assessments,\n unavailableReasons: asFrozenReasons(reasons),\n });\n}\n\nexport function selectAiProviderRoute(\n requestId: string,\n candidates: readonly AiProviderCandidate[],\n policy: AiRoutingPolicy = DEFAULT_ROUTING_POLICY\n): AiRoutingDecision {\n const normalizedPolicy = normalizePolicy(policy);\n if (!normalizedPolicy.enabled) {\n return Object.freeze({\n requestId,\n mode: \"disabled\",\n policy: normalizedPolicy,\n candidates: [],\n unavailableReasons: asFrozenReasons([\"disabled-by-flag\"]),\n });\n }\n\n const primaryAssessments = buildAssessments(\n requestId,\n candidates,\n normalizedPolicy,\n \"selected\"\n );\n\n const primary = pickCandidate(primaryAssessments, true);\n if (primary) {\n return Object.freeze({\n requestId,\n mode: \"selected\",\n policy: normalizedPolicy,\n selected: primary,\n candidates: primaryAssessments,\n unavailableReasons: [],\n });\n }\n\n const escalation = normalizedPolicy.escalation;\n const escalationPolicy: NormalizedAiRoutingPolicy = escalation.enabled\n ? Object.freeze({\n ...normalizedPolicy,\n minimumConfidence: 0,\n budget: normalizedPolicy.budget?.maxCostUsd\n ? Object.freeze({\n ...normalizedPolicy.budget,\n maxCostUsd:\n normalizedPolicy.budget.maxCostUsd *\n escalation.overageMultiplier,\n })\n : normalizedPolicy.budget,\n })\n : normalizedPolicy;\n\n if (escalation.enabled) {\n const escalatedAssessments = buildAssessments(\n requestId,\n candidates,\n escalationPolicy,\n \"escalated\"\n );\n const escalated = pickCandidate(escalatedAssessments, false);\n\n if (escalated) {\n return Object.freeze({\n requestId,\n mode: \"escalated\",\n policy: normalizedPolicy,\n selected: escalated,\n candidates: escalatedAssessments,\n unavailableReasons: [],\n });\n }\n }\n\n if (normalizedPolicy.fallback.enabled) {\n const fallbackAssessments = buildAssessments(\n requestId,\n candidates,\n {\n ...normalizedPolicy,\n minimumConfidence: 0,\n budget: undefined,\n },\n \"fallback\"\n );\n const fallback = pickCandidate(fallbackAssessments, false);\n\n if (fallback) {\n return Object.freeze({\n requestId,\n mode: \"fallback\",\n policy: normalizedPolicy,\n selected: fallback,\n candidates: fallbackAssessments,\n unavailableReasons: [],\n });\n }\n }\n\n return createUnavailableDecision(requestId, normalizedPolicy, candidates);\n}\n"],"mappings":"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","names":[]}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# ADR-0002: Cost-aware routing policy engine in @plasius/ai-router
|
|
2
|
+
|
|
3
|
+
- Date: 2026-05-13
|
|
4
|
+
- Status: Accepted
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
`@plasius/ai-router` started with package metadata only and lacked runtime routing logic. We need deterministic provider selection that balances confidence, budget, and availability while preserving transparent observability for product and platform governance.
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
Implement a policy-first route selection function, `selectAiProviderRoute`, that evaluates candidate providers in three phases:
|
|
13
|
+
|
|
14
|
+
- Primary selection with explicit policy constraints for enabled state, allow/deny lists, confidence, and cost/latency budgets.
|
|
15
|
+
- Escalation selection when enabled that relaxes confidence to `0` and temporarily relaxes cost constraints using an overage multiplier.
|
|
16
|
+
- Fallback selection when escalation is disabled or fails, prioritizing cheapest eligible candidates and ignoring confidence and budget constraints.
|
|
17
|
+
|
|
18
|
+
All failures return structured reasons and a deterministic candidate ranking to support auditable behavior in CI, dashboards, and ops tooling.
|
|
19
|
+
|
|
20
|
+
## Consequences
|
|
21
|
+
|
|
22
|
+
- Consumers can apply strict policy in normal operation and tune behavior under pressure with escalation/fallback.
|
|
23
|
+
- Routing output is fully deterministic across ties through secondary sorting by confidence and provider identifier.
|
|
24
|
+
- New feature contract is now public API and documented in package release notes.
|
|
25
|
+
- ADR and changelog are added as part of the same change set.
|
package/docs/adrs/index.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@plasius/ai-router",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
4
4
|
"description": "Cost-aware AI task routing, budget, confidence, and SLO policy for Plasius agentic AI workloads.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -53,6 +53,9 @@
|
|
|
53
53
|
],
|
|
54
54
|
"author": "Plasius LTD <development@plasius.co.uk>",
|
|
55
55
|
"license": "Apache-2.0",
|
|
56
|
+
"dependencies": {
|
|
57
|
+
"@plasius/ai-providers": "^0.1.3"
|
|
58
|
+
},
|
|
56
59
|
"repository": {
|
|
57
60
|
"type": "git",
|
|
58
61
|
"url": "git+https://github.com/Plasius-LTD/ai-router.git"
|
|
@@ -62,6 +65,7 @@
|
|
|
62
65
|
},
|
|
63
66
|
"homepage": "https://github.com/Plasius-LTD/ai-router#readme",
|
|
64
67
|
"devDependencies": {
|
|
68
|
+
"@plasius/ai-config": "^0.1.3",
|
|
65
69
|
"@eslint/js": "^10.0.1",
|
|
66
70
|
"@types/node": "^25.7.0",
|
|
67
71
|
"@typescript-eslint/eslint-plugin": "^8.59.3",
|