nexus-ai-pro 0.2.0

package/dist/testing/provider-conformance.js

@@ -0,0 +1,97 @@
+export const PROVIDER_CONFORMANCE_FIXTURES = {
+    openai: baseFixtures('gpt-5.4-mini'),
+    anthropic: baseFixtures('claude-sonnet-4'),
+    google: baseFixtures('gemini-2.5-flash'),
+    groq: baseFixtures('groq/openai/gpt-oss-20b'),
+    mistral: baseFixtures('mistral/mistral-small-2603'),
+    cohere: baseFixtures('cohere/command-r7b-12-2024'),
+    ollama: baseFixtures('ollama/llama3.2'),
+    openrouter: baseFixtures('openrouter/openai/gpt-5.4-mini'),
+};
+export async function runProviderConformance(providerName, provider, options = {}) {
+    const fixtures = options.fixtures || PROVIDER_CONFORMANCE_FIXTURES[providerName] || baseFixtures(options.model || 'auto');
+    const results = [];
+    const healthOk = options.testHealth ? await provider.healthCheck() : undefined;
+    for (const fixture of fixtures) {
+        const request = {
+            ...fixture.request,
+            model: options.model || fixture.request.model,
+        };
+        try {
+            const response = await provider.complete(request);
+            const completeOk = await fixture.validate(response);
+            let streamOk;
+            if (options.testStream) {
+                streamOk = await validateStream(provider.stream(request));
+            }
+            results.push({
+                providerName,
+                model: request.model,
+                caseName: fixture.name,
+                completeOk,
+                streamOk,
+                healthOk,
+            });
+        }
+        catch (error) {
+            results.push({
+                providerName,
+                model: request.model,
+                caseName: fixture.name,
+                completeOk: false,
+                healthOk,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return results;
+}
+function baseFixtures(model) {
+    return [
+        {
+            name: 'basic-text-completion',
+            request: {
+                model,
+                messages: [{ role: 'user', content: 'Reply with the word ok.' }],
+                temperature: 0,
+                maxTokens: 16,
+            },
+            validate: (response) => response.role === 'assistant' && typeof response.content === 'string',
+        },
+        {
+            name: 'json-response-shape',
+            request: {
+                model,
+                messages: [{ role: 'user', content: 'Return JSON with {"ok": true}.' }],
+                temperature: 0,
+                maxTokens: 64,
+                responseFormat: {
+                    type: 'json_schema',
+                    schema: {
+                        type: 'object',
+                        required: ['ok'],
+                        properties: { ok: { type: 'boolean' } },
+                    },
+                },
+            },
+            validate: (response) => {
+                try {
+                    const parsed = JSON.parse(response.content);
+                    return typeof parsed.ok === 'boolean';
+                }
+                catch {
+                    return false;
+                }
+            },
+        },
+    ];
+}
+async function validateStream(stream) {
+    for await (const chunk of stream) {
+        if (chunk.type === 'text' || chunk.type === 'done' || chunk.type === 'tool_call')
+            return true;
+        if (chunk.type === 'error')
+            return false;
+    }
+    return false;
+}

package/dist/types/agent.d.ts

@@ -0,0 +1,34 @@
+import type { Message, ToolDefinition } from './messages.js';
+import type { NexusResponse } from './response.js';
+export interface AgentStep {
+    iteration: number;
+    type: 'model' | 'tool' | 'final';
+    message: string;
+    toolName?: string;
+    toolArgs?: Record<string, unknown>;
+    toolResult?: unknown;
+}
+export interface AgentConfig {
+    model: string;
+    goal: string;
+    systemPrompt?: string;
+    tools?: ToolDefinition[];
+    maxIterations?: number;
+    temperature?: number;
+    maxTokens?: number;
+    metadata?: Record<string, unknown>;
+    onStep?: (step: AgentStep) => void | Promise<void>;
+    onToolCall?: (step: AgentStep) => void | Promise<void>;
+}
+export interface AgentResult {
+    content: string;
+    steps: AgentStep[];
+    iterations: number;
+    response: NexusResponse;
+    messages: Message[];
+}
+export interface ToolExecutionResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}

package/dist/types/agent.js

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

package/dist/types/config.d.ts

@@ -0,0 +1,171 @@
+import type { SecurityConfig, SecurityLevel } from './security.js';
+import type { TokenOptimizerConfig } from './optimizer.js';
+import type { Modality, ModelCapabilities, ModelStatus, RoutingModelPreference } from './providers.js';
+import type { PipelineConfig } from '../pipeline/types.js';
+import type { CacheAdapter } from '../cache/adapters.js';
+import type { SemanticCacheOptions } from '../cache/semantic-cache.js';
+import type { MetricsConfig } from '../ops/metrics.js';
+import type { HealthConfig } from '../ops/health.js';
+export interface OpenAIProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    organization?: string;
+}
+export interface AnthropicProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface GoogleProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    projectId?: string;
+}
+export interface OllamaProviderConfig {
+    baseUrl?: string;
+    timeout?: number;
+}
+export interface GroqProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface MistralProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface CohereProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface OpenRouterProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    appName?: string;
+    siteUrl?: string;
+}
+export interface CustomProviderConfig {
+    name: string;
+    baseUrl: string;
+    apiKey?: string;
+    format: 'openai' | 'anthropic';
+}
+export interface ProvidersConfig {
+    openai?: OpenAIProviderConfig;
+    anthropic?: AnthropicProviderConfig;
+    google?: GoogleProviderConfig;
+    ollama?: OllamaProviderConfig;
+    groq?: GroqProviderConfig;
+    mistral?: MistralProviderConfig;
+    cohere?: CohereProviderConfig;
+    openrouter?: OpenRouterProviderConfig;
+    custom?: CustomProviderConfig[];
+}
+export interface ModelRegistryConfig {
+    aliases?: Record<string, string>;
+    registry?: Record<string, ModelCapabilities>;
+    includeDefaults?: boolean;
+}
+export interface CacheConfig {
+    enabled?: boolean;
+    ttlSeconds?: number;
+    maxEntries?: number;
+    strategy?: 'exact' | 'semantic' | 'hybrid';
+    adapter?: CacheAdapter;
+    semantic?: SemanticCacheOptions;
+}
+export interface ResponseFormatConfig {
+    type: 'text' | 'json' | 'json_schema';
+    schema?: Record<string, unknown>;
+}
+export interface RateLimitConfig {
+    enabled?: boolean;
+    maxRequests: number;
+    windowMs: number;
+    key?: 'userId' | 'model' | 'global';
+}
+export interface AuditLogConfig {
+    enabled?: boolean;
+    includeInput?: boolean;
+    includeOutput?: boolean;
+    sink?: (event: AuditLogEvent) => void | Promise<void>;
+}
+export interface AuditLogEvent {
+    type: 'request' | 'response' | 'blocked';
+    requestId?: string;
+    userId?: string;
+    model?: string;
+    provider?: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RetryConfig {
+    enabled?: boolean;
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoff?: 'fixed' | 'exponential';
+    retryOn?: Array<'timeout' | 'rate-limit' | 'server-error' | 'network' | 'unknown'>;
+}
+export interface CostBudgetConfig {
+    enabled?: boolean;
+    maxEstimatedCost?: number;
+    estimatedOutputTokens?: number;
+    onExceeded?: 'error' | 'warn';
+}
+export type RoutingStrategy = 'cost' | 'speed' | 'quality' | 'privacy';
+export interface RoutingRule {
+    when: Record<string, unknown> | '*';
+    use: string;
+}
+export interface FallbackConfig {
+    onError?: string[];
+    onTimeout?: {
+        after: number;
+        fallbackTo: string;
+    };
+    onRateLimit?: {
+        retryAfter: number;
+        maxRetries: number;
+        thenFallbackTo: string;
+    };
+}
+export interface RoutingConfig {
+    mode: 'auto' | 'rules' | 'hybrid' | 'direct';
+    strategy?: RoutingStrategy;
+    candidateModels?: string[];
+    allowModels?: string[];
+    denyModels?: string[];
+    requiredCapabilities?: {
+        modalities?: Modality[];
+        streaming?: boolean;
+        toolCalling?: boolean;
+        structuredOutputs?: boolean;
+        jsonMode?: boolean;
+        reasoning?: boolean;
+        minContextTokens?: number;
+        maxInputCostPer1k?: number;
+        maxOutputCostPer1k?: number;
+        statuses?: ModelStatus[];
+    };
+    modelPreferences?: Partial<Record<RoutingStrategy, RoutingModelPreference[]>>;
+    rules?: RoutingRule[];
+    fallback?: FallbackConfig;
+}
+export interface NexusAIConfig {
+    providers: ProvidersConfig;
+    routing?: RoutingConfig;
+    security?: SecurityLevel | SecurityConfig;
+    tokenOptimizer?: TokenOptimizerConfig;
+    models?: ModelRegistryConfig;
+    cache?: CacheConfig;
+    rateLimit?: RateLimitConfig;
+    auditLog?: AuditLogConfig;
+    responseFormat?: ResponseFormatConfig;
+    retry?: RetryConfig;
+    costBudget?: CostBudgetConfig;
+    pipeline?: PipelineConfig;
+    metrics?: MetricsConfig;
+    health?: HealthConfig;
+    defaultModel?: string;
+    timeout?: number;
+    debug?: boolean;
+}

package/dist/types/config.js

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

package/dist/types/messages.d.ts

@@ -0,0 +1,96 @@
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ImageContent {
+    type: 'image';
+    source: {
+        path: string;
+    } | {
+        url: string;
+    } | {
+        buffer: Buffer;
+        mimeType?: string;
+    } | {
+        base64: string;
+        mimeType?: string;
+    };
+}
+export interface AudioContent {
+    type: 'audio';
+    source: {
+        path: string;
+    } | {
+        buffer: Buffer;
+        format?: string;
+    } | {
+        stream: NodeJS.ReadableStream;
+        format?: string;
+        sampleRate?: number;
+    } | {
+        transcript: string;
+    };
+}
+export interface VideoContent {
+    type: 'video';
+    source: {
+        path: string;
+        frameExtractionMode?: 'keyframes' | 'uniform' | 'all';
+        maxFrames?: number;
+        includeAudio?: boolean;
+    };
+}
+export type ContentPart = TextContent | ImageContent | AudioContent | VideoContent;
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export interface ToolCallResult {
+    toolCallId: string;
+    name: string;
+    result: unknown;
+}
+export interface Message {
+    role: MessageRole;
+    content: string | ContentPart[];
+    name?: string;
+    toolCallId?: string;
+    toolCalls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+export interface CompletionRequest {
+    model: string;
+    messages: Message[];
+    tools?: ToolDefinition[];
+    temperature?: number;
+    maxTokens?: number;
+    topP?: number;
+    logitBias?: Record<string, number>;
+    timeoutMs?: number;
+    maxEstimatedCost?: number;
+    estimatedOutputTokens?: number;
+    retry?: {
+        enabled?: boolean;
+        maxRetries?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        backoff?: 'fixed' | 'exponential';
+    };
+    responseFormat?: {
+        type: 'json' | 'json_schema';
+        schema?: Record<string, unknown>;
+    };
+    stop?: string | string[];
+    stream?: boolean;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/types/messages.js

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

package/dist/types/optimizer.d.ts

@@ -0,0 +1,30 @@
+export type BudgetExceededAction = 'error' | 'truncate' | 'densify' | 'allow';
+export interface DensificationConfig {
+    enabled?: boolean;
+    preserveCodeBlocks?: boolean;
+    preserveMarkdown?: boolean;
+    techniques?: Array<'whitespace-cleanup' | 'phrase-compression' | 'list-compaction'>;
+}
+export interface BudgetConfig {
+    enabled?: boolean;
+    maxInputTokens?: number;
+    warnAt?: number;
+    onExceeded?: BudgetExceededAction;
+}
+export interface TokenOptimizerConfig {
+    enabled?: boolean;
+    densification?: DensificationConfig;
+    budget?: BudgetConfig;
+}
+export interface TokenUsageSnapshot {
+    beforeTokens: number;
+    afterTokens: number;
+    savedTokens: number;
+    savedPercent: number;
+}
+export interface OptimizationResult<T> {
+    value: T;
+    usage: TokenUsageSnapshot;
+    techniquesApplied: string[];
+    warnings: string[];
+}

package/dist/types/optimizer.js

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

package/dist/types/planning.d.ts

@@ -0,0 +1,27 @@
+import type { RouteDecision } from '../router/types.js';
+import type { TokenUsageSnapshot } from './optimizer.js';
+import type { SecurityFinding } from './security.js';
+export interface CostEstimate {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+    formatted: string;
+}
+export interface NexusPlan {
+    requestModel: string;
+    providerName: string;
+    model: string;
+    route: RouteDecision;
+    tokenUsage: TokenUsageSnapshot;
+    estimatedCost: CostEstimate;
+    maxContextTokens?: number;
+    fitsContext: boolean;
+    cacheEligible: boolean;
+    wouldBlock: boolean;
+    securityFindings: SecurityFinding[];
+    warnings: string[];
+    guardrailsApplied: string[];
+}

package/dist/types/planning.js

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

package/dist/types/providers.d.ts

@@ -0,0 +1,39 @@
+export type Modality = 'text' | 'vision' | 'audio' | 'video' | 'image' | 'pdf';
+export type ModelStatus = 'stable' | 'preview' | 'latest' | 'deprecated';
+export type ModelEndpoint = 'chat' | 'responses' | 'messages' | 'generateContent' | 'realtime';
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+export type RoutingModelPreference = string | {
+    model: string;
+    weight?: number;
+};
+export interface ModelCapabilities {
+    provider?: string;
+    family?: string;
+    modalities: Modality[];
+    streaming: boolean;
+    toolCalling: boolean;
+    structuredOutputs?: boolean;
+    jsonMode?: boolean;
+    reasoning?: boolean | {
+        efforts?: ReasoningEffort[];
+    };
+    maxContextTokens: number;
+    maxOutputTokens?: number;
+    costPer1kInput: number;
+    costPer1kOutput: number;
+    qualityScore?: number;
+    speedScore?: number;
+    release?: string;
+    knowledgeCutoff?: string;
+    status?: ModelStatus;
+    endpoints?: ModelEndpoint[];
+    notes?: string;
+}
+export interface ProviderCapabilities {
+    name: string;
+    isLocal: boolean;
+    models: Record<string, ModelCapabilities>;
+}
+export declare const KNOWN_MODELS: Record<string, ModelCapabilities>;
+export declare const MODEL_ALIASES: Record<string, string>;
+export declare function resolveProvider(model: string): string | null;