pi-smart-router 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.pi/extensions/smart-router/delegate-stream.ts +7 -1
  2. package/.pi/extensions/smart-router/fleet-bootstrap.ts +2 -0
  3. package/.pi/extensions/smart-router/pi-model-scope.ts +18 -3
  4. package/.pi/extensions/smart-router/routing-context.ts +10 -0
  5. package/README.md +78 -0
  6. package/config/benchmark-profiles.json +2 -2
  7. package/config/operator-config.json.example +7 -0
  8. package/dist/config/defaults.d.ts.map +1 -1
  9. package/dist/config/defaults.js +3 -1
  10. package/dist/config/defaults.js.map +1 -1
  11. package/dist/config/pi-model-mapper.d.ts +12 -1
  12. package/dist/config/pi-model-mapper.d.ts.map +1 -1
  13. package/dist/config/pi-model-mapper.js +33 -8
  14. package/dist/config/pi-model-mapper.js.map +1 -1
  15. package/dist/domain/matching/embedding-provider.d.ts +63 -1
  16. package/dist/domain/matching/embedding-provider.d.ts.map +1 -1
  17. package/dist/domain/matching/embedding-provider.js +117 -0
  18. package/dist/domain/matching/embedding-provider.js.map +1 -1
  19. package/dist/domain/matching/encoder-gate.d.ts +73 -0
  20. package/dist/domain/matching/encoder-gate.d.ts.map +1 -0
  21. package/dist/domain/matching/encoder-gate.js +66 -0
  22. package/dist/domain/matching/encoder-gate.js.map +1 -0
  23. package/dist/domain/matching/hydra-matcher.d.ts +24 -3
  24. package/dist/domain/matching/hydra-matcher.d.ts.map +1 -1
  25. package/dist/domain/matching/hydra-matcher.js +21 -2
  26. package/dist/domain/matching/hydra-matcher.js.map +1 -1
  27. package/dist/domain/pipeline/router-pipeline.d.ts.map +1 -1
  28. package/dist/domain/pipeline/router-pipeline.js +12 -0
  29. package/dist/domain/pipeline/router-pipeline.js.map +1 -1
  30. package/dist/domain/types/entities.d.ts +15 -0
  31. package/dist/domain/types/entities.d.ts.map +1 -1
  32. package/dist/domain/types/schemas.d.ts +63 -7
  33. package/dist/domain/types/schemas.d.ts.map +1 -1
  34. package/dist/domain/types/schemas.js +46 -3
  35. package/dist/domain/types/schemas.js.map +1 -1
  36. package/dist/infrastructure/pricing/price-broker.d.ts +6 -1
  37. package/dist/infrastructure/pricing/price-broker.d.ts.map +1 -1
  38. package/dist/infrastructure/pricing/price-broker.js +16 -1
  39. package/dist/infrastructure/pricing/price-broker.js.map +1 -1
  40. package/package.json +3 -3
  41. package/src/config/defaults.ts +3 -0
  42. package/src/config/pi-model-mapper.ts +48 -9
  43. package/src/domain/matching/embedding-provider.ts +205 -1
  44. package/src/domain/matching/encoder-gate.ts +121 -0
  45. package/src/domain/matching/hydra-matcher.ts +53 -3
  46. package/src/domain/pipeline/router-pipeline.ts +13 -0
  47. package/src/domain/types/entities.ts +15 -0
  48. package/src/domain/types/schemas.ts +56 -7
  49. package/src/infrastructure/pricing/price-broker.ts +18 -2
@@ -303,6 +303,14 @@ export const PlanningDelegateObservabilitySchema = z
303
303
  })
304
304
  .strict();
305
305
 
306
+ /** HyDRA text encoder selection (SP-156, #80). Hoisted above the feature
307
+ * sidecar schema: cascade telemetry (SP-292) embeds EncoderSchema there. */
308
+ export const EncoderSchema = z.enum(['minilm', 'granite']);
309
+
310
+ export type Encoder = z.infer<typeof EncoderSchema>;
311
+
312
+ export const DEFAULT_ENCODER: Encoder = 'minilm';
313
+
306
314
  /**
307
315
  * Privacy-safe routing feature sidecar attached to live decisions (SP-057).
308
316
  * Mirrors {@link RoutingFeatureSidecar} in entities.ts.
@@ -331,6 +339,12 @@ export const RoutingFeatureSidecarSchema = z
331
339
  prewarm_attempted: z.boolean().nullable().optional(),
332
340
  prewarm_accepted: z.boolean().nullable().optional(),
333
341
  prewarm_disabled_reason: z.string().nullable().optional(),
342
+ // Encoder cascade decision telemetry (SP-292, #173); present only on
343
+ // cascade-enabled hydra_match decisions.
344
+ encoder_selected: EncoderSchema.nullable().optional(),
345
+ token_estimate: z.number().nullable().optional(),
346
+ cascade_threshold: z.number().nullable().optional(),
347
+ cascade_fallback_reason: z.string().nullable().optional(),
334
348
  })
335
349
  .strict();
336
350
 
@@ -437,13 +451,6 @@ export const DEFAULT_LOCAL_ZERO_CONFIG: Readonly<LocalZeroConfig> = {
437
451
  max_tool_use_requirement: 0.25,
438
452
  } as const;
439
453
 
440
- /** HyDRA text encoder selection (SP-156, #80). */
441
- export const EncoderSchema = z.enum(['minilm', 'granite']);
442
-
443
- export type Encoder = z.infer<typeof EncoderSchema>;
444
-
445
- export const DEFAULT_ENCODER: Encoder = 'minilm';
446
-
447
454
  /** HyDRA requirement head mode (SP-158, #81). */
448
455
  export const HydraHeadsSchema = z.enum(['learned_projection', 'modernbert_k4']);
449
456
 
@@ -451,10 +458,52 @@ export type HydraHeads = z.infer<typeof HydraHeadsSchema>;
451
458
 
452
459
  export const DEFAULT_HYDRA_HEADS: HydraHeads = 'learned_projection';
453
460
 
461
+ /**
462
+ * Opt-in encoder cascade knobs (SP-291, #173 part 1).
463
+ *
464
+ * When enabled, prompts whose estimated token count reaches
465
+ * `token_threshold` are routed to `long_context_encoder` (Granite) instead of
466
+ * the primary `hydra.encoder` (MiniLM), avoiding 512-token truncation on long
467
+ * prompts. Default OFF: existing single-encoder installs are unaffected and
468
+ * pay zero added cost (the gate is pre-embedding arithmetic).
469
+ *
470
+ * Hard constraint (#173): embeddings from different encoders live in different
471
+ * vector spaces — the cascade must never mix per-encoder artifacts (centroids,
472
+ * learned projection). Per-encoder artifact sets + cascading embedder land in
473
+ * SP-292.
474
+ */
475
+ export const EncoderCascadeConfigSchema = z.object({
476
+ /** When false (default), every prompt uses the primary `hydra.encoder`. */
477
+ enabled: z.boolean().default(false),
478
+ /** Long-context encoder selected at/over the threshold. Granite 97M (SP-156). */
479
+ long_context_encoder: EncoderSchema.default('granite'),
480
+ /**
481
+ * Estimated-token boundary: estimates >= threshold route to the long-context
482
+ * encoder. Default 512 matches the MiniLM context window.
483
+ */
484
+ token_threshold: z.number().int().min(1).default(512),
485
+ });
486
+
487
+ export type EncoderCascadeConfig = z.infer<typeof EncoderCascadeConfigSchema>;
488
+
489
+ /** Encoder cascade defaults per #173: opt-in, default off, 512-token threshold. */
490
+ export const DEFAULT_ENCODER_CASCADE_CONFIG: Readonly<EncoderCascadeConfig> = {
491
+ enabled: false,
492
+ long_context_encoder: 'granite',
493
+ token_threshold: 512,
494
+ } as const;
495
+
454
496
  export const HydraConfigSchema = z.object({
455
497
  artifact_cache_path: z.string(),
456
498
  /** ONNX encoder: MiniLM (default) or Granite 97M 384-dim long-context trial. */
457
499
  encoder: EncoderSchema.default(DEFAULT_ENCODER),
500
+ /**
501
+ * Opt-in per-prompt encoder cascade (SP-291, #173). Default off; when
502
+ * enabled, over-threshold prompts use the long-context encoder.
503
+ */
504
+ encoder_cascade: EncoderCascadeConfigSchema.default(
505
+ DEFAULT_ENCODER_CASCADE_CONFIG,
506
+ ),
458
507
  /**
459
508
  * Requirement extraction mode:
460
509
  * - `learned_projection` — SP-115 384×3 linear projection (default)
@@ -11,10 +11,14 @@
11
11
  * to finish the domain→infra inversion; this module re-exports them for
12
12
  * import-path stability. What remains here is limit resolution and
13
13
  * fleet-mapping, which depend on `config/pi-model-mapper` tier defaults.
14
+ *
15
+ * SP-299 (#177): limit resolution is a four-level cascade — YAML profile
16
+ * override → LiteLLM registry snapshot → pi registry (`contextWindow` /
17
+ * `maxTokens` carried on the mapped profile) → tier default.
14
18
  */
15
19
 
16
20
  import type { ModelProfile, ModelLimits, PriceCatalog } from '../../domain/types/index.js';
17
- import { getDefaultLimitsForTier } from '../../config/pi-model-mapper.js';
21
+ import { getDefaultLimitsForTier, type MappedModelProfile } from '../../config/pi-model-mapper.js';
18
22
 
19
23
  export {
20
24
  resolvePrice,
@@ -44,10 +48,19 @@ function lookupRegistryLimits(
44
48
  return snapshot[registryKey] ?? snapshot[model.id];
45
49
  }
46
50
 
51
+ /**
52
+ * Pi registry limits attached by `mapPiModelToProfile` (SP-299 / #177).
53
+ * Profiles built from fleet YAML never carry this field.
54
+ */
55
+ function lookupPiRegistryLimits(model: ModelProfile): ModelLimits | undefined {
56
+ return (model as MappedModelProfile).pi_registry_limits;
57
+ }
58
+
47
59
  /**
48
60
  * Resolve effective context limits for a model.
49
61
  *
50
- * Priority: YAML/profile override → LiteLLM registry snapshot → tier default.
62
+ * Priority: YAML/profile override → LiteLLM registry snapshot → pi registry
63
+ * (`contextWindow`/`maxTokens`) → tier default (SP-299 / #177).
51
64
  */
52
65
  export function resolveLimits(
53
66
  model: ModelProfile,
@@ -55,6 +68,7 @@ export function resolveLimits(
55
68
  ): ResolvedLimits {
56
69
  const yamlLimits = model.limits;
57
70
  const registryLimits = catalog ? lookupRegistryLimits(model, catalog) : undefined;
71
+ const piRegistryLimits = lookupPiRegistryLimits(model);
58
72
  const defaults = getDefaultLimitsForTier(model.tier);
59
73
 
60
74
  return {
@@ -63,10 +77,12 @@ export function resolveLimits(
63
77
  max_input_tokens:
64
78
  yamlLimits?.max_input_tokens ??
65
79
  registryLimits?.max_input_tokens ??
80
+ piRegistryLimits?.max_input_tokens ??
66
81
  defaults.max_input_tokens,
67
82
  max_output_tokens:
68
83
  yamlLimits?.max_output_tokens ??
69
84
  registryLimits?.max_output_tokens ??
85
+ piRegistryLimits?.max_output_tokens ??
70
86
  defaults.max_output_tokens,
71
87
  },
72
88
  };