@framers/agentos 0.1.0

package/dist/core/llm/routing/IModelRouter.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Defines the interface for the Model Router in AgentOS.
+ * The Model Router is responsible for intelligently selecting the most appropriate
+ * AI model and provider for a given task or query, based on a variety of criteria
+ * such as task requirements, persona preferences, user context, model capabilities,
+ * cost, and performance.
+ *
+ * Implementations of this interface can range from simple rule-based routers
+ * to more sophisticated LLM-driven or learning-based routing systems.
+ * @module backend/agentos/core/llm/routing/IModelRouter
+ */
+import { IProvider, ModelInfo } from '../providers/IProvider';
+import { IPersonaDefinition } from '../../../cognitive_substrate/personas/IPersonaDefinition';
+import type { ISubscriptionTier } from '../../../services/user_auth/types';
+/**
+ * Parameters provided to the model router to aid in its selection process.
+ * This context allows the router to make informed decisions.
+ */
+export interface ModelRouteParams {
+    /** A hint or classification of the current task (e.g., "code_generation", "summarization", "general_chat"). */
+    taskHint: string;
+    /** The ID of the GMI or agent instance making the request. */
+    requestingAgentId?: string;
+    /** The ID of the active persona guiding the interaction. */
+    personaId?: string;
+    /** The full active persona definition. */
+    activePersona?: IPersonaDefinition;
+    /** The ID of the user initiating the request. */
+    userId?: string;
+    /** The subscription tier of the user, which might affect model availability or preference. */
+    userSubscriptionTier?: ISubscriptionTier;
+    /** The user's query or the primary input text for the task. */
+    query?: string;
+    /** The target language for the model's output (e.g., "en", "es", "ja"). */
+    language?: string;
+    /**
+     * A preference for optimizing model selection (e.g., for speed, cost, or quality).
+     * This can guide the router if multiple suitable models are found.
+     */
+    optimizationPreference?: 'cost' | 'speed' | 'quality' | 'balanced';
+    /**
+     * Explicitly required capabilities for the model (e.g., "tool_use", "vision_input", "json_mode").
+     * The router must ensure the selected model supports all listed capabilities.
+     */
+    requiredCapabilities?: string[];
+    /**
+     * A list of preferred model IDs, if any. The router should try to use one of these if suitable.
+     */
+    preferredModelIds?: string[];
+    /**
+     * A list of preferred provider IDs, if any.
+     */
+    preferredProviderIds?: string[];
+    /**
+     * A list of model IDs that should be excluded from consideration.
+     */
+    excludedModelIds?: string[];
+    /**
+     * Maximum acceptable cost per 1000 input tokens (in USD), if cost is a critical factor.
+     */
+    maxCostPerKInputTokens?: number;
+    /**
+     * Maximum acceptable cost per 1000 output tokens (in USD).
+     */
+    maxCostPerKOutputTokens?: number;
+    /** User-provided API keys for specific providers, which might enable access to certain models. */
+    userApiKeys?: Record<string, string>;
+    /** Additional custom parameters or context to aid routing decisions. */
+    customContext?: Record<string, any>;
+}
+/**
+ * The result of a model routing decision.
+ * It specifies the selected provider, model, and provides reasoning for the choice.
+ */
+export interface ModelRouteResult {
+    /** The selected AI model provider instance. */
+    provider: IProvider;
+    /** The ID of the selected model on the chosen provider. */
+    modelId: string;
+    /** Detailed information about the selected model. */
+    modelInfo: ModelInfo;
+    /** A human-readable explanation of why this model and provider were chosen. */
+    reasoning: string;
+    /**
+     * A confidence score (0.0 to 1.0) indicating the router's certainty in this selection.
+     * Higher values mean higher confidence.
+     */
+    confidence: number;
+    /** An optional classification of the estimated cost tier for this model (e.g., "low", "medium", "high"). */
+    estimatedCostTier?: 'low' | 'medium' | 'high' | string;
+    /** Any additional metadata related to the routing decision (e.g., matched rule ID, performance estimates). */
+    metadata?: Record<string, any>;
+}
+/**
+ * Interface for the Model Router.
+ * Implementations are responsible for selecting an appropriate AI model and provider
+ * based on the given parameters and context.
+ */
+export interface IModelRouter {
+    /** A unique identifier for this specific router implementation. */
+    readonly routerId: string;
+    /**
+     * Initializes the model router with its configuration and necessary dependencies,
+     * such as the AIModelProviderManager for accessing information about available models and providers.
+     *
+     * @async
+     * @param {Record<string, any>} config - Router-specific configuration (e.g., rules, model preferences).
+     * @param {any} providerManager - An instance of AIModelProviderManager or a similar service
+     * that provides access to available models and providers.
+     * @param {any} [promptEngine] - Optional: An instance of PromptEngine, if the router uses LLM-based routing decisions.
+     * @returns {Promise<void>} A promise that resolves upon successful initialization.
+     * @throws {Error} If initialization fails (e.g., invalid configuration).
+     */
+    initialize(config: Record<string, any>, providerManager: any, // Should be AIModelProviderManager
+    promptEngine?: any): Promise<void>;
+    /**
+     * Selects an AI model and provider based on the provided parameters and the router's internal logic.
+     *
+     * @async
+     * @param {ModelRouteParams} params - The parameters and context for the routing decision.
+     * @param {ModelInfo[]} [availableModels] - Optional: A pre-fetched list of available models. If not provided,
+     * the router may need to fetch this list from its `providerManager`.
+     * @returns {Promise<ModelRouteResult | null>} A promise that resolves with the routing decision,
+     * or null if no suitable model/provider could be found that meets the criteria.
+     * @throws {Error} If a critical error occurs during the selection process.
+     */
+    selectModel(params: ModelRouteParams, availableModels?: ModelInfo[]): Promise<ModelRouteResult | null>;
+}
+//# sourceMappingURL=IModelRouter.d.ts.map

package/dist/core/llm/routing/IModelRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModelRouter.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/routing/IModelRouter.ts"],"names":[],"mappings":"AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0DAA0D,CAAC;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+GAA+G;IAC/G,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,oBAAoB,CAAC,EAAE,iBAAiB,CAAC;IACzC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;IACnE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;OAEG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,kGAAkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,SAAS,CAAC;IACpB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,EAAE,SAAS,CAAC;IACrB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,4GAA4G;IAC5G,iBAAiB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACvD,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;OAWG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,eAAe,EAAE,GAAG,EAAE,mCAAmC;IACzD,YAAY,CAAC,EAAE,GAAG,GACjB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;OAUG;IACH,WAAW,CACT,MAAM,EAAE,gBAAgB,EACxB,eAAe,CAAC,EAAE,SAAS,EAAE,GAC5B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CACrC"}

package/dist/core/llm/routing/IModelRouter.js

@@ -0,0 +1,14 @@
+// File: backend/agentos/core/llm/routing/IModelRouter.ts
+/**
+ * @fileoverview Defines the interface for the Model Router in AgentOS.
+ * The Model Router is responsible for intelligently selecting the most appropriate
+ * AI model and provider for a given task or query, based on a variety of criteria
+ * such as task requirements, persona preferences, user context, model capabilities,
+ * cost, and performance.
+ *
+ * Implementations of this interface can range from simple rule-based routers
+ * to more sophisticated LLM-driven or learning-based routing systems.
+ * @module backend/agentos/core/llm/routing/IModelRouter
+ */
+export {};
+//# sourceMappingURL=IModelRouter.js.map

package/dist/core/llm/routing/IModelRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModelRouter.js","sourceRoot":"","sources":["../../../../src/core/llm/routing/IModelRouter.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD;;;;;;;;;;GAUG"}

package/dist/core/llm/routing/ModelRouter.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Implements a rule-based model router for AgentOS.
+ * This router selects an AI model and provider by evaluating a prioritized list of configurable rules
+ * against the provided `ModelRouteParams`. It supports conditions based on task hints,
+ * agent IDs, required capabilities, optimization preferences, language, and custom evaluators.
+ * If no rules match, it falls back to a configured default model and provider.
+ *
+ * This implementation aims for clarity, extensibility through custom conditions, and adherence
+ * to the `IModelRouter` interface.
+ *
+ * @module backend/agentos/core/llm/routing/ModelRouter
+ * @implements {IModelRouter}
+ */
+import { IModelRouter, ModelRouteParams, ModelRouteResult } from './IModelRouter';
+import { ModelInfo } from '../providers/IProvider';
+import { AIModelProviderManager } from '../providers/AIModelProviderManager';
+/**
+ * Custom error class for ModelRouter specific operational errors.
+ * @class ModelRouterError
+ * @extends {Error}
+ */
+export declare class ModelRouterError extends Error {
+    /**
+     * A unique code identifying the type of error.
+     * @example 'INITIALIZATION_FAILED', 'RULE_EVALUATION_ERROR', 'NO_MODEL_MATCHED'
+     */
+    readonly code: string;
+    /** Optional details or context about the error. */
+    readonly details?: unknown;
+    /**
+     * Creates an instance of ModelRouterError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique code identifying the type of error.
+     * @param {unknown} [details] - Optional details or context about the error.
+     */
+    constructor(message: string, code: string, details?: unknown);
+}
+/**
+ * Defines a single routing rule that determines model selection based on conditions.
+ * Rules are evaluated in order of priority.
+ */
+export interface RoutingRule {
+    /** A unique identifier for the rule, useful for logging and debugging. */
+    id: string;
+    /** An optional description of the rule's purpose and logic. */
+    description?: string;
+    /**
+     * Priority of the rule. Lower numbers are evaluated first.
+     * @default 0
+     */
+    priority?: number;
+    /**
+     * A set of conditions that must ALL be met for this rule's action to be applied.
+     * If a condition field is omitted, it is not checked.
+     */
+    conditions: {
+        /** Keywords or regex patterns to match in `ModelRouteParams.query` or `ModelRouteParams.taskHint`. Case-insensitive. */
+        queryOrTaskHintContains?: string[];
+        /** Matches `ModelRouteParams.requestingAgentId`. */
+        requestingAgentId?: string;
+        /** Matches `ModelRouteParams.personaId`. */
+        personaId?: string;
+        /**
+         * All specified capabilities must be present in the candidate model's `ModelInfo.capabilities`.
+         * @example ["tool_use", "json_mode"]
+         */
+        requiredCapabilities?: string[];
+        /** Matches `ModelRouteParams.optimizationPreference`. */
+        optimizationPreference?: ModelRouteParams['optimizationPreference'];
+        /** Matches `ModelRouteParams.language`. */
+        language?: string;
+        /**
+         * Name of a custom condition evaluator function registered with the router.
+         * Allows for complex, programmatic condition checking.
+         * @example "isUserPremiumTier"
+         */
+        customCondition?: string;
+        /** Parameters to be passed to the `customCondition` evaluator function. */
+        customConditionParams?: Record<string, unknown>;
+    };
+    /** The action to take if all conditions are met, specifying the target model and provider. */
+    action: {
+        /** ID of the provider to use (must be configured in `AIModelProviderManager`). */
+        providerId: string;
+        /** ID of the model to use on that provider. */
+        modelId: string;
+        /** Optional reasoning for this choice, to be included in `ModelRouteResult.reasoning`. */
+        reasoning?: string;
+        /** Optional classification of the estimated cost tier (e.g., "low", "medium", "high"). */
+        estimatedCostTier?: ModelRouteResult['estimatedCostTier'];
+    };
+}
+/**
+ * Configuration for the `ModelRouter`.
+ */
+export interface ModelRouterConfig {
+    /**
+     * An array of routing rules. These are sorted by priority before evaluation.
+     * @see {@link RoutingRule}
+     */
+    rules: RoutingRule[];
+    /**
+     * Default provider ID to use if no rules match or if a matched rule's provider is unavailable.
+     * This provider must be configured in the `AIModelProviderManager`.
+     */
+    defaultProviderId: string;
+    /**
+     * Default model ID to use if no rules match.
+     * This model must be available on the `defaultProviderId`.
+     */
+    defaultModelId: string;
+    /** Optional reasoning to use when the default model is selected. */
+    defaultReasoning?: string;
+    /**
+     * A map of custom condition evaluator functions.
+     * The key is the `customCondition` string specified in a rule's conditions,
+     * and the value is the evaluator function.
+     * The function receives `ModelRouteParams` and the rule's `customConditionParams`,
+     * and should return `true` if the condition is met, `false` otherwise.
+     * @example
+     * customConditionEvaluators: {
+     * "isUserPremiumTier": async (params, ruleParams) => params.userSubscriptionTier?.isPremium || false
+     * }
+     */
+    customConditionEvaluators?: Record<string, (params: ModelRouteParams, conditionParams: Record<string, unknown>) => Promise<boolean> | boolean>;
+}
+/**
+ * @class ModelRouter
+ * @implements {IModelRouter}
+ * A rule-based implementation of `IModelRouter`. It selects an AI model by evaluating
+ * a configured set of rules in order of priority. This router is designed to be
+ * flexible and extensible through declarative rules and custom condition evaluators.
+ */
+export declare class ModelRouter implements IModelRouter {
+    /** @inheritdoc */
+    readonly routerId = "rule_based_router_v1.1";
+    private config;
+    private providerManager;
+    private isInitialized;
+    /**
+     * Constructs a ModelRouter instance.
+     * The router must be initialized via `initialize()` before use.
+     */
+    constructor();
+    /**
+     * Ensures the router has been properly initialized.
+     * @private
+     * @throws {ModelRouterError} If not initialized.
+     */
+    private ensureInitialized;
+    /** @inheritdoc */
+    initialize(config: ModelRouterConfig, // Using the more specific ModelRouterConfig
+    providerManager: AIModelProviderManager, _promptEngine?: any): Promise<void>;
+    /** @inheritdoc */
+    selectModel(params: ModelRouteParams, availableModels?: ModelInfo[]): Promise<ModelRouteResult | null>;
+}
+//# sourceMappingURL=ModelRouter.d.ts.map

package/dist/core/llm/routing/ModelRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelRouter.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/routing/ModelRouter.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/routing/ModelRouter.js

@@ -0,0 +1,190 @@
+// File: backend/agentos/core/llm/routing/ModelRouter.ts
+/**
+ * Custom error class for ModelRouter specific operational errors.
+ * @class ModelRouterError
+ * @extends {Error}
+ */
+export class ModelRouterError extends Error {
+    /**
+     * Creates an instance of ModelRouterError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique code identifying the type of error.
+     * @param {unknown} [details] - Optional details or context about the error.
+     */
+    constructor(message, code, details) {
+        super(message);
+        this.name = 'ModelRouterError';
+        this.code = code;
+        this.details = details;
+        Object.setPrototypeOf(this, ModelRouterError.prototype);
+    }
+}
+/**
+ * @class ModelRouter
+ * @implements {IModelRouter}
+ * A rule-based implementation of `IModelRouter`. It selects an AI model by evaluating
+ * a configured set of rules in order of priority. This router is designed to be
+ * flexible and extensible through declarative rules and custom condition evaluators.
+ */
+export class ModelRouter {
+    /**
+     * Constructs a ModelRouter instance.
+     * The router must be initialized via `initialize()` before use.
+     */
+    constructor() {
+        /** @inheritdoc */
+        this.routerId = 'rule_based_router_v1.1'; // Version incremented
+        this.isInitialized = false;
+    }
+    /**
+     * Ensures the router has been properly initialized.
+     * @private
+     * @throws {ModelRouterError} If not initialized.
+     */
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new ModelRouterError('ModelRouter is not initialized. Call initialize() first.', 'NOT_INITIALIZED');
+        }
+    }
+    /** @inheritdoc */
+    async initialize(config, // Using the more specific ModelRouterConfig
+    providerManager, 
+    // PromptEngine is not used by this rule-based router implementation, but kept for interface compliance if needed elsewhere.
+    _promptEngine) {
+        if (!config) {
+            throw new ModelRouterError("Configuration object is required for ModelRouter initialization.", 'INIT_CONFIG_MISSING');
+        }
+        if (!config.rules || !Array.isArray(config.rules)) {
+            throw new ModelRouterError("Configuration 'rules' array is required.", 'INIT_RULES_MISSING');
+        }
+        if (!config.defaultProviderId || !config.defaultModelId) {
+            throw new ModelRouterError("Configuration requires 'defaultProviderId' and 'defaultModelId'.", 'INIT_DEFAULTS_MISSING');
+        }
+        if (!providerManager) {
+            throw new ModelRouterError('AIModelProviderManager instance is required for ModelRouter initialization.', 'INIT_PROVIDER_MANAGER_MISSING');
+        }
+        this.config = {
+            ...config,
+            rules: [...config.rules].sort((a, b) => (a.priority || 0) - (b.priority || 0)), // Sort rules by priority
+            customConditionEvaluators: config.customConditionEvaluators || {},
+            defaultReasoning: config.defaultReasoning || 'Default model selection as no specific rules matched.',
+        };
+        this.providerManager = providerManager;
+        this.isInitialized = true;
+        console.log(`ModelRouter (${this.routerId}) initialized with ${this.config.rules.length} rules.`);
+    }
+    /** @inheritdoc */
+    async selectModel(params, availableModels // Router can use this or fetch its own
+    ) {
+        this.ensureInitialized();
+        const allKnownModels = availableModels || await this.providerManager.listAllAvailableModels();
+        if (allKnownModels.length === 0) {
+            console.warn("ModelRouter: No models available from AIModelProviderManager. Cannot route.");
+            return null;
+        }
+        const contextQuery = params.query?.toLowerCase() || '';
+        const contextTaskHint = params.taskHint?.toLowerCase() || '';
+        const combinedSearchText = `${contextQuery} ${contextTaskHint}`.trim();
+        for (const rule of this.config.rules) {
+            let conditionsMet = true;
+            // Check queryOrTaskHintContains
+            if (rule.conditions.queryOrTaskHintContains) {
+                if (!combinedSearchText || !rule.conditions.queryOrTaskHintContains.some(keyword => combinedSearchText.includes(keyword.toLowerCase()))) {
+                    conditionsMet = false;
+                }
+            }
+            // Check requestingAgentId
+            if (conditionsMet && rule.conditions.requestingAgentId && rule.conditions.requestingAgentId !== params.requestingAgentId) {
+                conditionsMet = false;
+            }
+            // Check personaId
+            if (conditionsMet && rule.conditions.personaId && rule.conditions.personaId !== params.personaId) {
+                conditionsMet = false;
+            }
+            // Check optimizationPreference
+            if (conditionsMet && rule.conditions.optimizationPreference && rule.conditions.optimizationPreference !== params.optimizationPreference) {
+                conditionsMet = false;
+            }
+            // Check language
+            if (conditionsMet && rule.conditions.language && rule.conditions.language.toLowerCase() !== params.language?.toLowerCase()) {
+                conditionsMet = false;
+            }
+            // If basic conditions met, fetch target model info to check capabilities
+            let targetModelInfo;
+            if (conditionsMet) {
+                targetModelInfo = allKnownModels.find(m => m.modelId === rule.action.modelId && m.providerId === rule.action.providerId);
+                if (!targetModelInfo) {
+                    conditionsMet = false; // Target model specified in rule not found/available
+                }
+            }
+            // Check requiredCapabilities against the targetModelInfo
+            if (conditionsMet && targetModelInfo && rule.conditions.requiredCapabilities) {
+                if (!rule.conditions.requiredCapabilities.every(reqCap => targetModelInfo.capabilities.includes(reqCap))) {
+                    conditionsMet = false;
+                }
+            }
+            // Check customCondition
+            if (conditionsMet && rule.conditions.customCondition) {
+                const evaluator = this.config.customConditionEvaluators[rule.conditions.customCondition];
+                if (evaluator) {
+                    try {
+                        if (!(await evaluator(params, rule.conditions.customConditionParams || {}))) {
+                            conditionsMet = false;
+                        }
+                    }
+                    catch (evalError) {
+                        console.error(`ModelRouter: Error evaluating custom condition '${rule.conditions.customCondition}' for rule '${rule.id}':`, evalError);
+                        conditionsMet = false; // Treat evaluation error as condition not met
+                    }
+                }
+                else {
+                    console.warn(`ModelRouter: Custom condition evaluator '${rule.conditions.customCondition}' not found for rule '${rule.id}'. Rule skipped.`);
+                    conditionsMet = false; // Skip rule if evaluator is missing
+                }
+            }
+            if (conditionsMet && targetModelInfo) {
+                const provider = this.providerManager.getProvider(targetModelInfo.providerId);
+                if (provider?.isInitialized) {
+                    console.log(`ModelRouter (${this.routerId}): Rule '${rule.id}' matched. Selecting model '${targetModelInfo.modelId}' on provider '${targetModelInfo.providerId}'.`);
+                    return {
+                        provider: provider,
+                        modelId: targetModelInfo.modelId,
+                        modelInfo: targetModelInfo,
+                        reasoning: rule.action.reasoning || rule.description || `Matched rule '${rule.id}'`,
+                        estimatedCostTier: rule.action.estimatedCostTier,
+                        confidence: 0.9, // High confidence for explicit rule match
+                        metadata: { matchedRuleId: rule.id, source: this.routerId },
+                    };
+                }
+                else {
+                    console.warn(`ModelRouter (${this.routerId}): Rule '${rule.id}' matched, but provider '${targetModelInfo.providerId}' for model '${targetModelInfo.modelId}' is not available or initialized.`);
+                }
+            }
+        }
+        // If no rules matched, use defaults
+        const defaultProvider = this.providerManager.getProvider(this.config.defaultProviderId);
+        if (defaultProvider?.isInitialized) {
+            const defaultModelInfo = allKnownModels.find(m => m.modelId === this.config.defaultModelId && m.providerId === this.config.defaultProviderId);
+            if (defaultModelInfo) {
+                console.log(`ModelRouter (${this.routerId}): No specific rules matched. Using default model '${defaultModelInfo.modelId}' on provider '${defaultModelInfo.providerId}'.`);
+                return {
+                    provider: defaultProvider,
+                    modelId: defaultModelInfo.modelId,
+                    modelInfo: defaultModelInfo,
+                    reasoning: this.config.defaultReasoning,
+                    confidence: 0.5, // Lower confidence for default
+                    metadata: { usingDefaults: true, source: this.routerId },
+                };
+            }
+            else {
+                console.warn(`ModelRouter (${this.routerId}): Default model '${this.config.defaultModelId}' on provider '${this.config.defaultProviderId}' not found in available models.`);
+            }
+        }
+        else {
+            console.warn(`ModelRouter (${this.routerId}): Default provider '${this.config.defaultProviderId}' not found or not initialized.`);
+        }
+        console.error(`ModelRouter (${this.routerId}): No rules matched AND default model/provider configuration is invalid or unavailable. Cannot select a model.`);
+        return null; // No model could be selected
+    }
+}
+//# sourceMappingURL=ModelRouter.js.map

package/dist/core/llm/routing/ModelRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelRouter.js","sourceRoot":"","sources":["../../../../src/core/llm/routing/ModelRouter.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/streaming/StreamingBatcher.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Backpressure batching wrapper for provider streaming chunks (`ModelCompletionResponse`).
+ * Combines small, high-frequency deltas into larger aggregated chunks to reduce downstream
+ * dispatch overhead (websocket emissions, DOM updates, etc.) while preserving core invariants:
+ *   - Text remains append-only (merged into a single `responseTextDelta` per batch).
+ *   - Tool/function argument deltas merged per (choiceIndex, toolCallId) into single consolidated delta.
+ *   - Exactly one terminal chunk with `isFinal: true` (forwarded from original final chunk).
+ *   - Usage & error surfaced only when FINAL chunk encountered (or if intermediate provider error semantics change).
+ *
+ * Flush Triggers (any):
+ *   1. Latency: maxLatencyMs elapsed since first unflushed chunk arrival.
+ *   2. Size: accumulated text delta length >= maxTextDeltaChars.
+ *   3. Chunk Count: buffer size >= maxChunksPerBatch.
+ *   4. Explicit final provider chunk.
+ *   5. Manual tool argument size threshold (maxToolArgumentChars) exceeded.
+ *
+ * Design Choices:
+ *   - Aggregated batch `id` composed from first chunk id + suffix `-batch-{sequence}` for traceability.
+ *   - `choices` taken verbatim from first chunk in batch (providers do not mutate choice metadata mid-stream except deltas).
+ *   - Non-final batches omit `usage` & `error` to keep semantics consistent. (If provider emits an error chunk mid-stream
+ *     with `isFinal: true`, it will be flushed immediately as its own batch.)
+ *   - Tool call reconstruction at batch granularity only (full stream reconstruction still delegated to `StreamingReconstructor`).
+ *
+ * NOTE: This is an optional optimization layer. Consumers requiring raw per-token latency should bypass batching.
+ */
+import { ModelCompletionResponse } from '../providers/IProvider';
+/** Configuration options for StreamingBatcher. */
+export interface StreamingBatcherOptions {
+    /** Max wall-clock latency before forcing a flush (milliseconds). */
+    maxLatencyMs?: number;
+    /** Max accumulated text delta characters before flush. */
+    maxTextDeltaChars?: number;
+    /** Max accumulated tool argument characters (combined per tool call) before flush. */
+    maxToolArgumentChars?: number;
+    /** Max number of provider chunks to accumulate before flush. */
+    maxChunksPerBatch?: number;
+    /** If true, include batchSequence on emitted chunk object for diagnostics. */
+    annotateBatches?: boolean;
+}
+/**
+ * Batches an async stream of `ModelCompletionResponse` chunks according to `StreamingBatcherOptions`.
+ * @param stream Underlying provider async generator.
+ * @param options Optional batching thresholds.
+ * @returns AsyncGenerator<ModelCompletionResponse>
+ */
+export declare function batchStream(stream: AsyncGenerator<ModelCompletionResponse, void, undefined>, options?: StreamingBatcherOptions): AsyncGenerator<ModelCompletionResponse, void, undefined>;
+/** Convenience OO wrapper for imperative control (mirrors functional batchStream). */
+export declare class StreamingBatcher {
+    private opts;
+    constructor(options?: StreamingBatcherOptions);
+    batch(stream: AsyncGenerator<ModelCompletionResponse, void, undefined>): AsyncGenerator<ModelCompletionResponse, void, undefined>;
+}
+export default StreamingBatcher;
+//# sourceMappingURL=StreamingBatcher.d.ts.map

package/dist/core/llm/streaming/StreamingBatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamingBatcher.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/streaming/StreamingBatcher.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAmGD;;;;;GAKG;AACH,wBAAuB,WAAW,CAChC,MAAM,EAAE,cAAc,CAAC,uBAAuB,EAAE,IAAI,EAAE,SAAS,CAAC,EAChE,OAAO,GAAE,uBAA4B,GACpC,cAAc,CAAC,uBAAuB,EAAE,IAAI,EAAE,SAAS,CAAC,CA0E1D;AAED,sFAAsF;AACtF,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAAoC;gBACpC,OAAO,GAAE,uBAA4B;IAGjD,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,uBAAuB,EAAE,IAAI,EAAE,SAAS,CAAC;CAGvE;AAED,eAAe,gBAAgB,CAAC"}