@jsonstudio/llms 0.6.743 → 0.6.749

package/dist/router/virtual-router/bootstrap.js

@@ -135,6 +135,7 @@ function expandRoutingTable(routingSource, aliasIndex) {
         const expandedPools = [];
         for (const pool of pools) {
             const expandedTargets = [];
+            let orderCounter = 0;
             for (const entry of pool.targets) {
                 const parsed = parseRouteEntry(entry, aliasIndex);
                 if (!parsed) {
@@ -150,16 +151,35 @@ function expandRoutingTable(routingSource, aliasIndex) {
                 for (const alias of aliases) {
                     const runtimeKey = buildRuntimeKey(parsed.providerId, alias);
                     const targetKey = `${runtimeKey}.${parsed.modelId}`;
-                    pushUnique(expandedTargets, targetKey);
+                    const existing = expandedTargets.find((candidate) => candidate.key === targetKey);
+                    if (existing) {
+                        if (parsed.priority > existing.priority) {
+                            existing.priority = parsed.priority;
+                        }
+                        continue;
+                    }
+                    expandedTargets.push({ key: targetKey, priority: parsed.priority, order: orderCounter });
+                    orderCounter += 1;
                     targetKeys.add(targetKey);
                 }
             }
             if (expandedTargets.length) {
+                const sortedTargets = pool.mode === 'priority'
+                    ? [...expandedTargets]
+                        .sort((a, b) => {
+                        if (a.priority !== b.priority) {
+                            return b.priority - a.priority;
+                        }
+                        return a.order - b.order;
+                    })
+                        .map((candidate) => candidate.key)
+                    : expandedTargets.map((candidate) => candidate.key);
                 expandedPools.push({
                     id: pool.id,
                     priority: pool.priority,
                     backup: pool.backup,
-                    targets: expandedTargets,
+                    targets: sortedTargets,
+                    ...(pool.mode ? { mode: pool.mode } : {}),
                     ...(pool.force ? { force: true } : {})
                 });
             }
@@ -277,6 +297,7 @@ function normalizeRoutePoolEntry(routeName, entry, index, total) {
         (typeof record.type === 'string' && record.type.toLowerCase() === 'backup');
     const priority = normalizePriorityValue(record.priority, total - index);
     const targets = normalizeRouteTargets(record);
+    const mode = normalizeRoutePoolMode(record.mode ?? record?.strategy ?? record?.routingMode);
     const force = record.force === true ||
         (typeof record.force === 'string' && record.force.trim().toLowerCase() === 'true');
     return targets.length
@@ -285,10 +306,30 @@ function normalizeRoutePoolEntry(routeName, entry, index, total) {
             priority,
             backup,
             targets,
+            ...(mode ? { mode } : {}),
             ...(force ? { force: true } : {})
         }
         : null;
 }
+function normalizeRoutePoolMode(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (!normalized) {
+        return undefined;
+    }
+    if (normalized === 'priority') {
+        return 'priority';
+    }
+    if (normalized === 'round-robin' ||
+        normalized === 'round_robin' ||
+        normalized === 'roundrobin' ||
+        normalized === 'rr') {
+        return 'round-robin';
+    }
+    return undefined;
+}
 function normalizeRouteTargets(record) {
     const buckets = [
         record.targets,
@@ -867,15 +908,38 @@ function parseRouteEntry(entry, aliasIndex) {
         if (secondDot > 0 && secondDot < remainder.length - 1) {
             const aliasCandidate = remainder.slice(0, secondDot);
             if (aliases.includes(aliasCandidate)) {
+                const parsed = splitModelPriority(remainder.slice(secondDot + 1));
                 return {
                     providerId,
                     keyAlias: aliasCandidate,
-                    modelId: remainder.slice(secondDot + 1)
+                    modelId: parsed.modelId,
+                    priority: parsed.priority
                 };
             }
         }
     }
-    return { providerId, modelId: remainder };
+    const parsed = splitModelPriority(remainder);
+    return { providerId, modelId: parsed.modelId, priority: parsed.priority };
+}
+function splitModelPriority(raw) {
+    const value = typeof raw === 'string' ? raw.trim() : '';
+    if (!value) {
+        return { modelId: value, priority: 100 };
+    }
+    const match = value.match(/^(.*):(\d+)$/);
+    if (!match) {
+        return { modelId: value, priority: 100 };
+    }
+    const modelId = (match[1] ?? '').trim();
+    const priorityRaw = (match[2] ?? '').trim();
+    const parsed = Number(priorityRaw);
+    if (!modelId) {
+        return { modelId: value, priority: 100 };
+    }
+    if (!Number.isFinite(parsed)) {
+        return { modelId, priority: 100 };
+    }
+    return { modelId, priority: parsed };
 }
 function parseTargetKey(targetKey) {
     const value = typeof targetKey === 'string' ? targetKey.trim() : '';

package/dist/router/virtual-router/engine-selection.d.ts

@@ -22,6 +22,12 @@ export declare function selectProviderImpl(requestedRoute: string, metadata: Rou
     pool: string[];
     poolId?: string;
 };
+export declare function selectDirectProviderModel(providerId: string, modelId: string, metadata: RouterMetadataInput, features: RoutingFeatures, activeState: RoutingInstructionState, deps: SelectionDeps): {
+    providerKey: string;
+    routeUsed: string;
+    pool: string[];
+    poolId?: string;
+} | null;
 export declare function selectFromStickyPool(stickyKeySet: Set<string>, metadata: RouterMetadataInput, features: RoutingFeatures, state: RoutingInstructionState, deps: SelectionDeps, options: {
     allowAliasRotation?: boolean;
 }): {

package/dist/router/virtual-router/engine-selection.js

@@ -110,6 +110,54 @@ export function selectProviderImpl(requestedRoute, metadata, classification, fea
         allowAliasRotation
     });
 }
+export function selectDirectProviderModel(providerId, modelId, metadata, features, activeState, deps) {
+    const normalizedProvider = typeof providerId === 'string' ? providerId.trim() : '';
+    const normalizedModel = typeof modelId === 'string' ? modelId.trim() : '';
+    if (!normalizedProvider || !normalizedModel) {
+        return null;
+    }
+    const providerKeys = deps.providerRegistry.listProviderKeys(normalizedProvider);
+    if (providerKeys.length === 0) {
+        return null;
+    }
+    const matchingKeys = providerKeys.filter((key) => {
+        try {
+            const profile = deps.providerRegistry.get(key);
+            return profile?.modelId === normalizedModel;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (matchingKeys.length === 0) {
+        return null;
+    }
+    const attempted = [];
+    const estimatedTokens = typeof features.estimatedTokens === 'number' && Number.isFinite(features.estimatedTokens)
+        ? Math.max(0, features.estimatedTokens)
+        : 0;
+    const tier = {
+        id: `direct:${normalizedProvider}.${normalizedModel}`,
+        targets: matchingKeys,
+        priority: 100,
+        mode: 'round-robin',
+        backup: false
+    };
+    const { providerKey, poolTargets, tierId, failureHint } = trySelectFromTier('direct', tier, undefined, estimatedTokens, features, deps, {
+        disabledProviders: new Set(activeState.disabledProviders),
+        disabledKeysMap: new Map(activeState.disabledKeys),
+        allowedProviders: new Set(activeState.allowedProviders),
+        disabledModels: new Map(activeState.disabledModels),
+        allowAliasRotation: true
+    });
+    if (providerKey) {
+        return { providerKey, routeUsed: 'direct', pool: poolTargets, poolId: tierId };
+    }
+    if (failureHint) {
+        attempted.push(failureHint);
+    }
+    return null;
+}
 function selectFromCandidates(routes, metadata, classification, features, state, deps, options) {
     const allowedProviders = new Set(state.allowedProviders);
     const disabledProviders = new Set(state.disabledProviders);
@@ -272,14 +320,25 @@ function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features
     const prioritizedPools = buildContextCandidatePools(contextResult);
     const quotaView = deps.quotaView;
     const now = quotaView ? Date.now() : 0;
+    const selectFirstAvailable = (candidates) => {
+        for (const key of candidates) {
+            if (deps.healthManager.isAvailable(key)) {
+                return key;
+            }
+        }
+        return null;
+    };
     const selectWithQuota = (candidates) => {
         if (!quotaView) {
+            if (tier.mode === 'priority') {
+                return selectFirstAvailable(candidates);
+            }
             return deps.loadBalancer.select({
                 routeName: `${routeName}:${tier.id}`,
                 candidates,
                 stickyKey: options.allowAliasRotation ? undefined : stickyKey,
                 availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-            });
+            }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
         }
         const buckets = new Map();
         for (const key of candidates) {
@@ -312,14 +371,22 @@ function trySelectFromTier(routeName, tier, stickyKey, estimatedTokens, features
             if (!bucketCandidates.length) {
                 continue;
             }
-            const selected = deps.loadBalancer.select({
-                routeName: `${routeName}:${tier.id}`,
-                candidates: bucketCandidates,
-                stickyKey: options.allowAliasRotation ? undefined : stickyKey,
-                availabilityCheck: (key) => deps.healthManager.isAvailable(key)
-            });
-            if (selected) {
-                return selected;
+            if (tier.mode === 'priority') {
+                const selected = selectFirstAvailable(bucketCandidates);
+                if (selected) {
+                    return selected;
+                }
+            }
+            else {
+                const selected = deps.loadBalancer.select({
+                    routeName: `${routeName}:${tier.id}`,
+                    candidates: bucketCandidates,
+                    stickyKey: options.allowAliasRotation ? undefined : stickyKey,
+                    availabilityCheck: (key) => deps.healthManager.isAvailable(key)
+                }, tier.mode === 'round-robin' ? 'round-robin' : undefined);
+                if (selected) {
+                    return selected;
+                }
             }
         }
         return null;

package/dist/router/virtual-router/engine.d.ts

@@ -29,6 +29,7 @@ export declare class VirtualRouterEngine {
         routingStateStore?: RoutingInstructionStateStore;
         quotaView?: ProviderQuotaView;
     });
+    private parseDirectProviderModel;
     initialize(config: VirtualRouterConfig): void;
     route(request: StandardizedRequest | ProcessedRequest, metadata: RouterMetadataInput): {
         target: TargetMetadata;

package/dist/router/virtual-router/engine.js

@@ -9,7 +9,7 @@ import { getStatsCenter } from '../../telemetry/stats-center.js';
 import { parseRoutingInstructions, applyRoutingInstructions, cleanMessagesFromRoutingInstructions } from './routing-instructions.js';
 import { loadRoutingInstructionStateSync, saveRoutingInstructionStateAsync } from './sticky-session-store.js';
 import { buildHitReason, formatVirtualRouterHit } from './engine-logging.js';
-import { selectProviderImpl } from './engine-selection.js';
+import { selectDirectProviderModel, selectProviderImpl } from './engine-selection.js';
 import { applyQuotaDepletedImpl, applyQuotaRecoveryImpl, applySeriesCooldownImpl, handleProviderFailureImpl, mapProviderErrorImpl } from './engine-health.js';
 export class VirtualRouterEngine {
     routing = {};
@@ -44,6 +44,25 @@ export class VirtualRouterEngine {
             this.quotaView = deps.quotaView;
         }
     }
+    parseDirectProviderModel(model) {
+        const raw = typeof model === 'string' ? model.trim() : '';
+        if (!raw) {
+            return null;
+        }
+        const firstDot = raw.indexOf('.');
+        if (firstDot <= 0 || firstDot === raw.length - 1) {
+            return null;
+        }
+        const providerId = raw.slice(0, firstDot).trim();
+        const modelId = raw.slice(firstDot + 1).trim();
+        if (!providerId || !modelId) {
+            return null;
+        }
+        if (this.providerRegistry.listProviderKeys(providerId).length === 0) {
+            return null;
+        }
+        return { providerId, modelId };
+    }
     initialize(config) {
         this.validateConfig(config);
         this.routing = config.routing;
@@ -198,17 +217,64 @@ export class VirtualRouterEngine {
         }
         const routingMode = this.resolveRoutingMode([...metadataInstructions, ...instructions], routingState);
         const features = buildRoutingFeatures(request, metadata);
-        const classification = metadata.routeHint && metadata.routeHint.trim()
-            ? {
-                routeName: metadata.routeHint.trim(),
+        const directProviderModel = this.parseDirectProviderModel(request?.model);
+        let classification;
+        let requestedRoute;
+        let selection;
+        if (directProviderModel) {
+            const providerKeys = this.providerRegistry.listProviderKeys(directProviderModel.providerId);
+            let hasModel = false;
+            for (const key of providerKeys) {
+                try {
+                    const profile = this.providerRegistry.get(key);
+                    if (profile?.modelId === directProviderModel.modelId) {
+                        hasModel = true;
+                        break;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (!hasModel) {
+                throw new VirtualRouterError(`Unknown model ${directProviderModel.modelId} for provider ${directProviderModel.providerId}`, VirtualRouterErrorCode.CONFIG_ERROR, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
+            }
+            classification = {
+                routeName: 'direct',
                 confidence: 1,
-                reasoning: `route_hint:${metadata.routeHint.trim()}`,
+                reasoning: `direct_model:${directProviderModel.providerId}.${directProviderModel.modelId}`,
                 fallback: false,
-                candidates: [metadata.routeHint.trim()]
+                candidates: ['direct']
+            };
+            requestedRoute = 'direct';
+            const directSelection = selectDirectProviderModel(directProviderModel.providerId, directProviderModel.modelId, metadata, features, routingState, {
+                routing: this.routing,
+                providerRegistry: this.providerRegistry,
+                healthManager: this.healthManager,
+                contextAdvisor: this.contextAdvisor,
+                loadBalancer: this.loadBalancer,
+                isProviderCoolingDown: (key) => this.isProviderCoolingDown(key),
+                resolveStickyKey: (m) => this.resolveStickyKey(m),
+                quotaView: this.quotaView
+            });
+            if (!directSelection) {
+                throw new VirtualRouterError(`All providers unavailable for model ${directProviderModel.providerId}.${directProviderModel.modelId}`, VirtualRouterErrorCode.PROVIDER_NOT_AVAILABLE, { providerId: directProviderModel.providerId, modelId: directProviderModel.modelId });
             }
-            : this.classifier.classify(features);
-        const requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
-        const selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
+            selection = directSelection;
+        }
+        else {
+            classification = metadata.routeHint && metadata.routeHint.trim()
+                ? {
+                    routeName: metadata.routeHint.trim(),
+                    confidence: 1,
+                    reasoning: `route_hint:${metadata.routeHint.trim()}`,
+                    fallback: false,
+                    candidates: [metadata.routeHint.trim()]
+                }
+                : this.classifier.classify(features);
+            requestedRoute = this.normalizeRouteAlias(classification.routeName || DEFAULT_ROUTE);
+            selection = this.selectProvider(requestedRoute, metadata, classification, features, routingState);
+        }
         const baseTarget = this.providerRegistry.buildTarget(selection.providerKey);
         const forceVision = this.routeHasForceFlag('vision');
         const target = {

package/dist/router/virtual-router/load-balancer.d.ts

@@ -0,0 +1,18 @@
+import type { LoadBalancingPolicy } from './types.js';
+export interface LoadBalancingOptions {
+    routeName: string;
+    candidates: string[];
+    stickyKey?: string;
+    availabilityCheck: (providerKey: string) => boolean;
+}
+export declare class RouteLoadBalancer {
+    private policy;
+    private readonly states;
+    constructor(policy?: LoadBalancingPolicy);
+    updatePolicy(policy?: LoadBalancingPolicy): void;
+    select(options: LoadBalancingOptions, strategyOverride?: LoadBalancingPolicy['strategy']): string | null;
+    private selectRoundRobin;
+    private selectWeighted;
+    private selectSticky;
+    private getState;
+}

package/dist/router/virtual-router/load-balancer.js

@@ -9,12 +9,13 @@ export class RouteLoadBalancer {
             this.policy = policy;
         }
     }
-    select(options) {
+    select(options, strategyOverride) {
         const available = options.candidates.filter((candidate) => options.availabilityCheck(candidate));
         if (available.length === 0) {
             return null;
         }
-        switch (this.policy.strategy) {
+        const strategy = strategyOverride ?? this.policy.strategy;
+        switch (strategy) {
             case 'sticky':
                 return this.selectSticky(options.routeName, available, options.stickyKey);
             case 'weighted':

package/dist/router/virtual-router/types.d.ts

@@ -6,10 +6,17 @@ export declare const DEFAULT_MODEL_CONTEXT_TOKENS = 200000;
 export declare const DEFAULT_ROUTE = "default";
 export declare const ROUTE_PRIORITY: string[];
 export type RoutingInstructionMode = 'force' | 'sticky' | 'none';
+export type RoutePoolMode = 'round-robin' | 'priority';
 export interface RoutePoolTier {
     id: string;
     targets: string[];
     priority: number;
+    /**
+     * Pool-level routing mode:
+     * - round-robin: force round-robin selection inside this pool (ignores global loadBalancing strategy)
+     * - priority: always pick highest-priority key first, only fallback when unavailable
+     */
+    mode?: RoutePoolMode;
     backup?: boolean;
     /**
      * Optional force flag for this route pool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/llms",
-  "version": "0.6.743",
+  "version": "0.6.749",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",