@plasius/ai-router 0.1.2 → 0.1.4

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 CHANGED
@@ -18,6 +18,37 @@ 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.4] - 2026-06-22
22
+
23
+ - **Added**
24
+ - (placeholder)
25
+
26
+ - **Changed**
27
+ - (placeholder)
28
+
29
+ - **Fixed**
30
+ - (placeholder)
31
+
32
+ - **Security**
33
+ - (placeholder)
34
+
35
+ ## [0.1.3] - 2026-05-20
36
+
37
+ - **Added**
38
+ - Added `selectAiProviderRoute` with multi-phase policy selection for primary, escalation, and fallback routing.
39
+ - Added routing policy contracts for confidence, budget, allow/deny lists, and decision telemetry.
40
+
41
+ - **Changed**
42
+ - Updated package feature flag contract to `ai.cost-aware-routing.enabled`.
43
+ - Added dependency on `@plasius/ai-providers` and routing policy tests.
44
+
45
+ - **Fixed**
46
+ - Release automation now prepares version/changelog updates on a release PR before publishing from protected `main`.
47
+ - Budgeted routing now treats missing provider cost estimates as over budget instead of selectable.
48
+
49
+ - **Security**
50
+ - (placeholder)
51
+
21
52
  ## [0.1.2] - 2026-05-13
22
53
 
23
54
  - **Added**
@@ -40,3 +71,5 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
40
71
 
41
72
  [0.1.1]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.1
42
73
  [0.1.2]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.2
74
+ [0.1.3]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.3
75
+ [0.1.4]: https://github.com/Plasius-LTD/ai-router/releases/tag/v0.1.4
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 is intentionally bootstrapped with a small public contract surface so implementation can evolve behind tracked Feature/Story/Task work.
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 test
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.router.enabled";
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
@@ -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.router.enabled";
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.router.enabled";
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.router.enabled";
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.
@@ -1,3 +1,4 @@
1
1
  # Architecture Decision Records
2
2
 
3
3
  - [ADR-0001: @plasius/ai-router Package Boundary](./adr-0001-package-boundary.md)
4
+ - [ADR-0002: Cost-aware routing policy engine in @plasius/ai-router](./adr-0002-cost-aware-routing-policy.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plasius/ai-router",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
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",