nexus-ai-pro 0.2.0

package/dist/router/auto-router.js

@@ -0,0 +1,228 @@
+import { getModelRegistry, listModelsForProvider, resolveModel } from '../models/registry.js';
+export class AutoRouter {
+    route(ctx) {
+        const strategy = ctx.config.routing?.strategy || 'quality';
+        const candidates = this.getCandidates(ctx).map((candidate) => ({
+            ...candidate,
+            score: this.score(candidate.model, strategy, ctx.config) + candidate.weight + this.healthScore(candidate.providerName, ctx),
+            reason: `auto route by ${strategy} score`,
+        }));
+        candidates.sort((a, b) => b.score - a.score);
+        const winner = candidates[0];
+        if (!winner) {
+            throw new Error('No configured providers are available for routing');
+        }
+        return {
+            providerName: winner.providerName,
+            model: winner.model,
+            reason: `${winner.reason}: ${winner.model}`,
+            fallbacks: candidates.slice(1).map((c) => ({ providerName: c.providerName, model: c.model })),
+        };
+    }
+    getCandidates(ctx) {
+        const candidates = [];
+        const configuredModels = ctx.config.routing?.candidateModels;
+        if (configuredModels?.length) {
+            for (const model of configuredModels) {
+                const resolved = resolveModel(model, ctx.config);
+                const providerName = resolved.providerName || model.split('/')[0];
+                if (ctx.providers.has(providerName) && this.isAllowed(resolved.model, ctx.config)) {
+                    candidates.push({ providerName, model: resolved.model, weight: 0 });
+                }
+            }
+            return candidates.filter((candidate) => this.matchesRequirements(candidate.model, ctx.config));
+        }
+        const preferences = ctx.config.routing?.modelPreferences?.[ctx.config.routing?.strategy || 'quality'];
+        for (const providerName of ctx.providers.keys()) {
+            const preferred = this.preferencesForProvider(providerName, preferences, ctx.config);
+            if (preferred.length) {
+                candidates.push(...preferred);
+            }
+        }
+        return candidates.filter((candidate) => {
+            return this.isAllowed(candidate.model, ctx.config)
+                && this.matchesRequirements(candidate.model, ctx.config);
+        });
+    }
+    score(model, strategy, config) {
+        const registry = getModelRegistry(config);
+        const normalized = model.startsWith('ollama/') ? model.slice(7) : model;
+        const caps = registry[model] || registry[normalized] || this.localFallbackCapabilities(model);
+        if (strategy === 'privacy')
+            return model.startsWith('ollama/') ? 100 : 30;
+        if (strategy === 'speed')
+            return this.speedScore(model, caps);
+        if (strategy === 'cost')
+            return this.costScore(model, caps);
+        return this.qualityScore(model, caps);
+    }
+    localFallbackCapabilities(model) {
+        return {
+            modalities: ['text'],
+            streaming: true,
+            toolCalling: false,
+            maxContextTokens: 8192,
+            costPer1kInput: model.startsWith('ollama/') ? 0 : 0.001,
+            costPer1kOutput: model.startsWith('ollama/') ? 0 : 0.003,
+        };
+    }
+    costScore(model, caps) {
+        if (model.startsWith('ollama/'))
+            return 100;
+        const totalCost = caps.costPer1kInput + caps.costPer1kOutput;
+        return Math.max(1, 100 - totalCost * 1000);
+    }
+    speedScore(model, caps) {
+        if (caps.speedScore)
+            return caps.speedScore;
+        if (model.includes('mini') || model.includes('haiku') || model.includes('flash'))
+            return 95;
+        if (model.startsWith('ollama/'))
+            return 80;
+        return caps.streaming ? 70 : 50;
+    }
+    qualityScore(model, caps) {
+        if (caps.qualityScore)
+            return caps.qualityScore;
+        if (model.includes('gpt-5.5'))
+            return 99;
+        if (model.includes('gpt-5.4'))
+            return 96;
+        if (model.includes('opus') || model.includes('gpt-4o'))
+            return 95;
+        if (model.includes('sonnet'))
+            return 90;
+        if (model.includes('gemini-3'))
+            return 94;
+        if (model.includes('gemini-2.5-pro'))
+            return 88;
+        if (model.startsWith('ollama/'))
+            return 65;
+        return Math.min(85, caps.maxContextTokens / 2000);
+    }
+    preferencesForProvider(providerName, preferences, config) {
+        if (preferences?.length) {
+            return preferences
+                .map((preference) => typeof preference === 'string'
+                ? { model: preference, weight: 0 }
+                : { model: preference.model, weight: preference.weight || 0 })
+                .map((preference) => {
+                const resolved = resolveModel(preference.model, config);
+                return {
+                    providerName: resolved.providerName || preference.model.split('/')[0],
+                    model: resolved.model,
+                    weight: preference.weight,
+                };
+            })
+                .filter((candidate) => candidate.providerName === providerName);
+        }
+        const registryModels = listModelsForProvider(providerName, config);
+        if (registryModels.length) {
+            return registryModels
+                .filter((model) => this.isProviderRunnable(providerName, model, config))
+                .map((model) => ({ providerName, model, weight: 0 }));
+        }
+        if (providerName === 'ollama') {
+            return [
+                { providerName, model: 'ollama/llama3.3', weight: 0 },
+                { providerName, model: 'ollama/llama3.2', weight: 0 },
+                { providerName, model: 'ollama/qwen2.5', weight: 0 },
+                { providerName, model: 'ollama/mistral', weight: 0 },
+                { providerName, model: 'ollama/codellama', weight: 0 },
+            ];
+        }
+        if (providerName === 'openrouter') {
+            return [
+                { providerName, model: 'openrouter/openai/gpt-5.4-mini', weight: 0 },
+                { providerName, model: 'openrouter/anthropic/claude-sonnet-4', weight: 0 },
+                { providerName, model: 'openrouter/google/gemini-2.5-flash', weight: 0 },
+                { providerName, model: 'openrouter/meta-llama/llama-3.3-70b-instruct', weight: 0 },
+            ];
+        }
+        return [];
+    }
+    isAllowed(model, config) {
+        const allow = config.routing?.allowModels;
+        const deny = config.routing?.denyModels || [];
+        if (allow?.length && !allow.some((entry) => this.matchesModelPattern(model, entry)))
+            return false;
+        return !deny.some((entry) => this.matchesModelPattern(model, entry));
+    }
+    matchesRequirements(model, config) {
+        const requirements = config.routing?.requiredCapabilities;
+        if (!requirements)
+            return true;
+        const registry = getModelRegistry(config);
+        const normalized = model.startsWith('ollama/') ? model.slice(7) : model;
+        const caps = registry[model] || registry[normalized] || this.localFallbackCapabilities(model);
+        if (requirements.streaming !== undefined && caps.streaming !== requirements.streaming)
+            return false;
+        if (requirements.toolCalling !== undefined && caps.toolCalling !== requirements.toolCalling)
+            return false;
+        if (requirements.structuredOutputs !== undefined && caps.structuredOutputs !== requirements.structuredOutputs)
+            return false;
+        if (requirements.jsonMode !== undefined && caps.jsonMode !== requirements.jsonMode)
+            return false;
+        if (requirements.reasoning !== undefined && Boolean(caps.reasoning) !== requirements.reasoning)
+            return false;
+        if (requirements.minContextTokens && caps.maxContextTokens < requirements.minContextTokens)
+            return false;
+        if (requirements.maxInputCostPer1k !== undefined && caps.costPer1kInput > requirements.maxInputCostPer1k)
+            return false;
+        if (requirements.maxOutputCostPer1k !== undefined && caps.costPer1kOutput > requirements.maxOutputCostPer1k)
+            return false;
+        if (requirements.statuses?.length && caps.status && !requirements.statuses.includes(caps.status))
+            return false;
+        if (requirements.modalities?.length) {
+            for (const modality of requirements.modalities) {
+                if (!caps.modalities.includes(modality))
+                    return false;
+            }
+        }
+        return true;
+    }
+    matchesModelPattern(model, pattern) {
+        if (pattern === model)
+            return true;
+        if (!pattern.includes('*'))
+            return false;
+        const regex = new RegExp(`^${pattern.split('*').map((part) => {
+            return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        }).join('.*')}$`);
+        return regex.test(model);
+    }
+    isProviderRunnable(providerName, model, config) {
+        const registry = getModelRegistry(config);
+        const caps = registry[model];
+        if (!caps?.endpoints)
+            return true;
+        if (providerName === 'openai')
+            return caps.endpoints.includes('chat');
+        if (providerName === 'anthropic')
+            return caps.endpoints.includes('messages');
+        if (providerName === 'google')
+            return caps.endpoints.includes('generateContent');
+        return true;
+    }
+    healthScore(providerName, ctx) {
+        if (!ctx.config.health?.enabled || !ctx.health?.length)
+            return 0;
+        const snapshot = ctx.health.find((item) => item.providerName === providerName);
+        if (!snapshot)
+            return 0;
+        return snapshot.healthy ? snapshot.score / 10 : -100;
+    }
+}
+export function routeDirectModel(model, ctx) {
+    const resolved = resolveModel(model, ctx.config);
+    const providerName = resolved.providerName || model.split('/')[0];
+    if (!ctx.providers.has(providerName)) {
+        throw new Error(`Provider "${providerName}" for model "${model}" is not configured`);
+    }
+    return {
+        providerName,
+        model: resolved.model,
+        reason: `direct model route → ${model}${model === resolved.model ? '' : ` resolved to ${resolved.model}`}`,
+        fallbacks: [],
+    };
+}

package/dist/router/failover.d.ts

@@ -0,0 +1,21 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse, NexusStream } from '../types/response.js';
+import type { BaseProvider } from '../providers/base.js';
+import type { RouteDecision } from './types.js';
+import type { RetryConfig } from '../types/config.js';
+export interface ExecutionOptions {
+    timeoutMs?: number;
+    retry?: RetryConfig;
+    onAttemptSuccess?: (providerName: string, latencyMs: number) => void;
+    onAttemptFailure?: (providerName: string, error: unknown) => void;
+}
+export declare class FailoverExecutor {
+    complete(request: CompletionRequest, decision: RouteDecision, providers: Map<string, BaseProvider>, options?: ExecutionOptions): Promise<NexusResponse>;
+    stream(request: CompletionRequest, decision: RouteDecision, providers: Map<string, BaseProvider>, options?: ExecutionOptions): NexusStream;
+    private streamAttempts;
+    private withTimeout;
+    private mergeRetry;
+    private categorizeError;
+    private retryDelay;
+    private delay;
+}

package/dist/router/failover.js

@@ -0,0 +1,126 @@
+export class FailoverExecutor {
+    async complete(request, decision, providers, options = {}) {
+        const attempts = [{ providerName: decision.providerName, model: decision.model }, ...decision.fallbacks];
+        const errors = [];
+        const retry = this.mergeRetry(options.retry, request.retry);
+        for (const attempt of attempts) {
+            const provider = providers.get(attempt.providerName);
+            if (!provider)
+                continue;
+            for (let retryIndex = 0; retryIndex <= retry.maxRetries; retryIndex += 1) {
+                try {
+                    const started = Date.now();
+                    const response = await this.withTimeout(provider.complete({ ...request, model: attempt.model }), request.timeoutMs || options.timeoutMs);
+                    options.onAttemptSuccess?.(attempt.providerName, Date.now() - started);
+                    response.meta.routingDecision = {
+                        reason: decision.reason,
+                        fallbacksConsidered: attempts.length - 1,
+                    };
+                    if (retryIndex > 0) {
+                        response.meta.guardrailsApplied.push(`provider-retry-${retryIndex}`);
+                    }
+                    return response;
+                }
+                catch (err) {
+                    options.onAttemptFailure?.(attempt.providerName, err);
+                    const category = this.categorizeError(err);
+                    const message = `${attempt.providerName}/${attempt.model}: ${err instanceof Error ? err.message : String(err)}`;
+                    errors.push(message);
+                    if (!retry.enabled || retryIndex >= retry.maxRetries || !retry.retryOn.includes(category)) {
+                        break;
+                    }
+                    await this.delay(this.retryDelay(retry, retryIndex));
+                }
+            }
+        }
+        throw new Error(`All routing attempts failed: ${errors.join(' | ')}`);
+    }
+    stream(request, decision, providers, options = {}) {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                const attempts = [{ providerName: decision.providerName, model: decision.model }, ...decision.fallbacks];
+                return self.streamAttempts(request, attempts, providers, options);
+            },
+            abort() {
+                // Each provider stream owns its own abort lifecycle once selected.
+            },
+        };
+    }
+    async *streamAttempts(request, attempts, providers, options) {
+        const retry = this.mergeRetry(options.retry, request.retry);
+        const errors = [];
+        for (const attempt of attempts) {
+            const provider = providers.get(attempt.providerName);
+            if (!provider)
+                continue;
+            for (let retryIndex = 0; retryIndex <= retry.maxRetries; retryIndex += 1) {
+                const started = Date.now();
+                let emitted = false;
+                try {
+                    for await (const chunk of provider.stream({ ...request, model: attempt.model })) {
+                        if (chunk.type === 'error')
+                            throw new Error(chunk.error || 'stream error');
+                        emitted = emitted || chunk.type === 'text' || chunk.type === 'tool_call';
+                        yield chunk;
+                    }
+                    options.onAttemptSuccess?.(attempt.providerName, Date.now() - started);
+                    return;
+                }
+                catch (error) {
+                    options.onAttemptFailure?.(attempt.providerName, error);
+                    errors.push(`${attempt.providerName}/${attempt.model}: ${error instanceof Error ? error.message : String(error)}`);
+                    if (emitted || !retry.enabled || retryIndex >= retry.maxRetries || !retry.retryOn.includes(this.categorizeError(error))) {
+                        break;
+                    }
+                    await this.delay(this.retryDelay(retry, retryIndex));
+                }
+            }
+        }
+        yield { type: 'error', error: `All streaming attempts failed: ${errors.join(' | ')}` };
+    }
+    async withTimeout(promise, timeoutMs) {
+        if (!timeoutMs || timeoutMs <= 0)
+            return promise;
+        let timeout;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeout = setTimeout(() => reject(new Error(`Provider call timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        try {
+            return await Promise.race([promise, timeoutPromise]);
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+    }
+    mergeRetry(global, request) {
+        return {
+            enabled: request?.enabled ?? global?.enabled ?? false,
+            maxRetries: request?.maxRetries ?? global?.maxRetries ?? 1,
+            baseDelayMs: request?.baseDelayMs ?? global?.baseDelayMs ?? 250,
+            maxDelayMs: request?.maxDelayMs ?? global?.maxDelayMs ?? 2000,
+            backoff: request?.backoff ?? global?.backoff ?? 'exponential',
+            retryOn: global?.retryOn || ['timeout', 'rate-limit', 'server-error', 'network'],
+        };
+    }
+    categorizeError(error) {
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        if (message.includes('timed out') || message.includes('timeout'))
+            return 'timeout';
+        if (message.includes('429') || message.includes('rate limit'))
+            return 'rate-limit';
+        if (message.includes('500') || message.includes('502') || message.includes('503') || message.includes('504'))
+            return 'server-error';
+        if (message.includes('network') || message.includes('fetch failed') || message.includes('econnreset'))
+            return 'network';
+        return 'unknown';
+    }
+    retryDelay(retry, retryIndex) {
+        const multiplier = retry.backoff === 'exponential' ? 2 ** retryIndex : 1;
+        return Math.min(retry.baseDelayMs * multiplier, retry.maxDelayMs);
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/router/index.d.ts

@@ -0,0 +1,12 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusAIConfig } from '../types/config.js';
+import type { BaseProvider } from '../providers/base.js';
+import type { RouteDecision } from './types.js';
+import type { ProviderHealthSnapshot } from '../ops/health.js';
+export declare class Router {
+    private autoRouter;
+    private rulesRouter;
+    route(request: CompletionRequest, config: NexusAIConfig, providers: Map<string, BaseProvider>, health?: ProviderHealthSnapshot[]): RouteDecision;
+}
+export type { RouteDecision, RouterContext } from './types.js';
+export { FailoverExecutor } from './failover.js';

package/dist/router/index.js

@@ -0,0 +1,31 @@
+import { AutoRouter, routeDirectModel } from './auto-router.js';
+import { RulesRouter } from './rules-router.js';
+export class Router {
+    autoRouter = new AutoRouter();
+    rulesRouter = new RulesRouter();
+    route(request, config, providers, health) {
+        const ctx = { request, config, providers, health };
+        const routingMode = config.routing?.mode || 'auto';
+        if (request.model !== 'auto') {
+            return routeDirectModel(request.model, ctx);
+        }
+        if (routingMode === 'rules' || routingMode === 'hybrid') {
+            const decision = this.rulesRouter.route(ctx);
+            if (decision)
+                return decision;
+            if (routingMode === 'rules')
+                return this.autoRouter.route(ctx);
+        }
+        if (routingMode === 'hybrid') {
+            return this.autoRouter.route(ctx);
+        }
+        if (routingMode === 'direct') {
+            const model = config.defaultModel;
+            if (!model)
+                throw new Error('routing.mode="direct" requires config.defaultModel');
+            return routeDirectModel(model, { ...ctx, request: { ...request, model } });
+        }
+        return this.autoRouter.route(ctx);
+    }
+}
+export { FailoverExecutor } from './failover.js';

package/dist/router/rules-router.d.ts

@@ -0,0 +1,7 @@
+import type { RouterContext, RouteDecision } from './types.js';
+export declare class RulesRouter {
+    route(ctx: RouterContext): RouteDecision | null;
+    private matches;
+    private readConditionValue;
+    private matchesOperator;
+}

package/dist/router/rules-router.js

@@ -0,0 +1,68 @@
+import { resolveModel } from '../models/registry.js';
+export class RulesRouter {
+    route(ctx) {
+        const rules = ctx.config.routing?.rules;
+        if (!rules || rules.length === 0)
+            return null;
+        for (const rule of rules) {
+            if (rule.when === '*' || this.matches(rule.when, ctx)) {
+                const resolved = resolveModel(rule.use, ctx.config);
+                const providerName = resolved.providerName || rule.use.split('/')[0];
+                if (ctx.providers.has(providerName)) {
+                    return {
+                        providerName,
+                        model: resolved.model,
+                        reason: `matched routing rule -> ${rule.use}${rule.use === resolved.model ? '' : ` resolved to ${resolved.model}`}`,
+                        fallbacks: [],
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    matches(conditions, ctx) {
+        for (const [key, expected] of Object.entries(conditions)) {
+            const actual = this.readConditionValue(key, ctx);
+            if (typeof expected === 'object' && expected !== null && !Array.isArray(expected)) {
+                if (!this.matchesOperator(actual, expected))
+                    return false;
+                continue;
+            }
+            if (actual !== expected)
+                return false;
+        }
+        return true;
+    }
+    readConditionValue(key, ctx) {
+        if (key === 'model')
+            return ctx.request.model;
+        if (key === 'userId')
+            return ctx.request.userId;
+        if (key === 'hasTools')
+            return Boolean(ctx.request.tools?.length);
+        if (key === 'messageCount')
+            return ctx.request.messages.length;
+        if (key === 'containsPII')
+            return false;
+        if (key === 'taskType')
+            return ctx.request.metadata?.taskType;
+        return ctx.request.metadata?.[key];
+    }
+    matchesOperator(actual, operators) {
+        for (const [op, expected] of Object.entries(operators)) {
+            if (op === 'gt' && !(Number(actual) > Number(expected)))
+                return false;
+            if (op === 'gte' && !(Number(actual) >= Number(expected)))
+                return false;
+            if (op === 'lt' && !(Number(actual) < Number(expected)))
+                return false;
+            if (op === 'lte' && !(Number(actual) <= Number(expected)))
+                return false;
+            if (op === 'eq' && actual !== expected)
+                return false;
+            if (op === 'in' && Array.isArray(expected) && !expected.includes(actual))
+                return false;
+        }
+        return true;
+    }
+}

package/dist/router/types.d.ts

@@ -0,0 +1,19 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusAIConfig } from '../types/config.js';
+import type { BaseProvider } from '../providers/base.js';
+import type { ProviderHealthSnapshot } from '../ops/health.js';
+export interface RouteDecision {
+    providerName: string;
+    model: string;
+    reason: string;
+    fallbacks: Array<{
+        providerName: string;
+        model: string;
+    }>;
+}
+export interface RouterContext {
+    request: CompletionRequest;
+    config: NexusAIConfig;
+    providers: Map<string, BaseProvider>;
+    health?: ProviderHealthSnapshot[];
+}

package/dist/router/types.js

@@ -0,0 +1 @@
+export {};

package/dist/security/index.d.ts

@@ -0,0 +1,31 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { SecurityConfig, SecurityFinding, SecurityLevel, SecurityResult } from '../types/security.js';
+import type { NexusResponse } from '../types/response.js';
+export declare class NexusSecurityError extends Error {
+    findings: SecurityFinding[];
+    constructor(findings: SecurityFinding[]);
+}
+export declare class SecurityPipeline {
+    private config;
+    private schemaValidator;
+    private injectionDetector;
+    private piiDetector;
+    private outputGuard;
+    private inputGuard;
+    private semanticInjectionClassifier?;
+    constructor(config?: SecurityLevel | SecurityConfig);
+    protectInput(request: CompletionRequest): SecurityResult<CompletionRequest>;
+    assertSafe(result: SecurityResult<CompletionRequest>): void;
+    protectOutput(response: NexusResponse): SecurityResult<NexusResponse>;
+    private normalizeConfig;
+    private applyPreset;
+    private shouldRunInjectionDetection;
+    private shouldRunPII;
+    private getBlockingFindings;
+}
+export { SchemaValidator } from './schema-validator.js';
+export { InjectionDetector } from './injection-detector.js';
+export { PIIDetector } from './pii-detector.js';
+export { OutputGuard } from './output-guard.js';
+export { InputGuard } from './input-guard.js';
+export { SemanticInjectionClassifier } from './semantic-injection-classifier.js';