nexus-ai-pro 0.2.0

package/dist/utils/tokenizer.js

@@ -0,0 +1,38 @@
+export class Tokenizer {
+    estimateTextTokens(text) {
+        if (!text)
+            return 0;
+        const normalized = text.trim();
+        if (!normalized)
+            return 0;
+        const wordLike = normalized.match(/[\p{L}\p{N}_]+|[^\s\p{L}\p{N}_]/gu) || [];
+        const charEstimate = Math.ceil(normalized.length / 4);
+        return Math.max(1, Math.ceil((wordLike.length + charEstimate) / 2));
+    }
+    estimateMessageTokens(message) {
+        const roleOverhead = 4;
+        if (typeof message.content === 'string') {
+            return roleOverhead + this.estimateTextTokens(message.content);
+        }
+        return roleOverhead + message.content.reduce((total, part) => {
+            if (part.type === 'text')
+                return total + this.estimateTextTokens(part.text);
+            if (part.type === 'image')
+                return total + 85;
+            if (part.type === 'audio')
+                return total + 120;
+            if (part.type === 'video')
+                return total + 250;
+            return total;
+        }, 0);
+    }
+    estimateRequestTokens(request) {
+        const modelOverhead = 8;
+        const toolOverhead = request.tools?.reduce((total, tool) => {
+            return total + this.estimateTextTokens(tool.name) + this.estimateTextTokens(tool.description) + 20;
+        }, 0) || 0;
+        return modelOverhead + toolOverhead + request.messages.reduce((total, message) => {
+            return total + this.estimateMessageTokens(message);
+        }, 0);
+    }
+}

package/dist/workflow/chains.d.ts

@@ -0,0 +1,53 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+import type { ResponseFormatConfig } from '../types/config.js';
+import { type RagChunk } from '../hallucination/rag.js';
+export interface WorkflowClient {
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+}
+export interface WorkflowStepResult {
+    step: string;
+    response: NexusResponse;
+}
+export interface WorkflowResult {
+    content: string;
+    response: NexusResponse;
+    steps: WorkflowStepResult[];
+}
+export interface SummarizeVerifyFormatOptions {
+    model: string;
+    input: string;
+    verifyContext?: string[];
+    responseFormat?: ResponseFormatConfig;
+    summaryInstruction?: string;
+    finalInstruction?: string;
+}
+export interface RagAnswerOptions {
+    model: string;
+    question: string;
+    chunks: RagChunk[];
+    verify?: boolean;
+}
+export interface ExtractStructuredOptions {
+    model: string;
+    input: string;
+    schema: Record<string, unknown>;
+    instruction?: string;
+}
+export interface ClassifyRouteOptions {
+    model: string;
+    input: string;
+    labels: string[];
+    instruction?: string;
+}
+export interface CompareOptions {
+    model: string;
+    input: string;
+    options: string[];
+    criteria?: string[];
+}
+export declare function summarizeVerifyFormat(client: WorkflowClient, options: SummarizeVerifyFormatOptions): Promise<WorkflowResult>;
+export declare function ragAnswer(client: WorkflowClient, options: RagAnswerOptions): Promise<WorkflowResult>;
+export declare function extractStructured(client: WorkflowClient, options: ExtractStructuredOptions): Promise<WorkflowResult>;
+export declare function classifyRoute(client: WorkflowClient, options: ClassifyRouteOptions): Promise<WorkflowResult>;
+export declare function compareAndDecide(client: WorkflowClient, options: CompareOptions): Promise<WorkflowResult>;

package/dist/workflow/chains.js

@@ -0,0 +1,117 @@
+import { withFactualDefaults } from '../hallucination/factual.js';
+import { withRagContext } from '../hallucination/rag.js';
+import { completeVerified } from '../hallucination/verification.js';
+export async function summarizeVerifyFormat(client, options) {
+    const steps = [];
+    const summary = await client.complete(withFactualDefaults({
+        model: options.model,
+        messages: [
+            { role: 'user', content: `${options.summaryInstruction || 'Summarize the following content clearly.'}\n\n${options.input}` },
+        ],
+    }, { chainOfThought: 'private' }));
+    steps.push({ step: 'summarize', response: summary });
+    const verified = options.verifyContext?.length
+        ? await completeVerified(client, {
+            model: options.model,
+            messages: [{ role: 'user', content: summary.content }],
+            responseFormat: toRequestResponseFormat(options.responseFormat),
+        }, {
+            context: options.verifyContext,
+            repair: true,
+        })
+        : summary;
+    steps.push({ step: 'verify', response: verified });
+    const formatted = await client.complete({
+        model: options.model,
+        messages: [
+            {
+                role: 'user',
+                content: `${options.finalInstruction || 'Format this into the final answer.'}\n\n${verified.content}`,
+            },
+        ],
+        responseFormat: toRequestResponseFormat(options.responseFormat),
+    });
+    steps.push({ step: 'format', response: formatted });
+    return {
+        content: formatted.content,
+        response: formatted,
+        steps,
+    };
+}
+export async function ragAnswer(client, options) {
+    const request = withRagContext({
+        model: options.model,
+        messages: [{ role: 'user', content: options.question }],
+    }, {
+        chunks: options.chunks,
+        requireCitations: true,
+    });
+    const response = options.verify
+        ? await completeVerified(client, request, { context: options.chunks.map((chunk) => chunk.content), repair: true })
+        : await client.complete(request);
+    return {
+        content: response.content,
+        response,
+        steps: [{ step: 'rag-answer', response }],
+    };
+}
+export async function extractStructured(client, options) {
+    const response = await client.complete({
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: `${options.instruction || 'Extract the requested structured data from the input.'}\n\n${options.input}`,
+            }],
+        responseFormat: {
+            type: 'json_schema',
+            schema: options.schema,
+        },
+    });
+    return { content: response.content, response, steps: [{ step: 'extract-structured', response }] };
+}
+export async function classifyRoute(client, options) {
+    const response = await client.complete({
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    options.instruction || 'Classify the input into exactly one label.',
+                    `Labels: ${options.labels.join(', ')}`,
+                    `Input: ${options.input}`,
+                ].join('\n'),
+            }],
+        temperature: 0,
+        responseFormat: {
+            type: 'json_schema',
+            schema: {
+                type: 'object',
+                required: ['label'],
+                properties: {
+                    label: { type: 'string' },
+                    confidence: { type: 'number' },
+                },
+            },
+        },
+    });
+    return { content: response.content, response, steps: [{ step: 'classify-route', response }] };
+}
+export async function compareAndDecide(client, options) {
+    const response = await client.complete(withFactualDefaults({
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    'Compare the options and choose the best one.',
+                    `Input: ${options.input}`,
+                    `Options:\n${options.options.map((item, index) => `${index + 1}. ${item}`).join('\n')}`,
+                    options.criteria?.length ? `Criteria: ${options.criteria.join(', ')}` : '',
+                ].filter(Boolean).join('\n\n'),
+            }],
+    }, { chainOfThought: 'private' }));
+    return { content: response.content, response, steps: [{ step: 'compare-and-decide', response }] };
+}
+function toRequestResponseFormat(format) {
+    if (!format || format.type === 'text')
+        return undefined;
+    return { type: format.type, schema: format.schema };
+}

package/dist/workflow/domain.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowClient, WorkflowResult } from './chains.js';
+export interface DomainWorkflowOptions {
+    model: string;
+    input: string;
+    context?: string[];
+}
+export interface SupportWorkflowOptions extends DomainWorkflowOptions {
+    customerTier?: string;
+}
+export interface SalesWorkflowOptions extends DomainWorkflowOptions {
+    product?: string;
+}
+export interface LegalReviewWorkflowOptions extends DomainWorkflowOptions {
+    jurisdiction?: string;
+}
+export interface CodeReviewWorkflowOptions extends DomainWorkflowOptions {
+    language?: string;
+}
+export declare function supportTriageWorkflow(client: WorkflowClient, options: SupportWorkflowOptions): Promise<WorkflowResult>;
+export declare function salesQualificationWorkflow(client: WorkflowClient, options: SalesWorkflowOptions): Promise<WorkflowResult>;
+export declare function legalReviewWorkflow(client: WorkflowClient, options: LegalReviewWorkflowOptions): Promise<WorkflowResult>;
+export declare function codeReviewWorkflow(client: WorkflowClient, options: CodeReviewWorkflowOptions): Promise<WorkflowResult>;

package/dist/workflow/domain.js

@@ -0,0 +1,96 @@
+import { withFactualDefaults } from '../hallucination/factual.js';
+export async function supportTriageWorkflow(client, options) {
+    return singleStepWorkflow(client, 'support-triage', {
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    'Triage this support request.',
+                    'Return severity, category, likely cause, next best action, and a customer-safe reply.',
+                    options.customerTier ? `Customer tier: ${options.customerTier}` : '',
+                    contextBlock(options.context),
+                    `Request:\n${options.input}`,
+                ].filter(Boolean).join('\n\n'),
+            }],
+        responseFormat: {
+            type: 'json_schema',
+            schema: objectSchema(['severity', 'category', 'nextAction', 'reply']),
+        },
+    });
+}
+export async function salesQualificationWorkflow(client, options) {
+    return singleStepWorkflow(client, 'sales-qualification', {
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    'Qualify this sales lead.',
+                    'Return fitScore, painPoints, objections, recommendedOffer, and followUpEmail.',
+                    options.product ? `Product: ${options.product}` : '',
+                    contextBlock(options.context),
+                    `Lead notes:\n${options.input}`,
+                ].filter(Boolean).join('\n\n'),
+            }],
+        responseFormat: {
+            type: 'json_schema',
+            schema: objectSchema(['fitScore', 'painPoints', 'recommendedOffer', 'followUpEmail']),
+        },
+    });
+}
+export async function legalReviewWorkflow(client, options) {
+    return singleStepWorkflow(client, 'legal-review', withFactualDefaults({
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    'Review this text for legal risk. Do not provide legal advice.',
+                    'Return risks, missingClauses, suggestedQuestions, and safeSummary.',
+                    options.jurisdiction ? `Jurisdiction: ${options.jurisdiction}` : '',
+                    contextBlock(options.context),
+                    `Text:\n${options.input}`,
+                ].filter(Boolean).join('\n\n'),
+            }],
+        responseFormat: {
+            type: 'json_schema',
+            schema: objectSchema(['risks', 'suggestedQuestions', 'safeSummary']),
+        },
+    }, { requireUnknownFallback: true, chainOfThought: 'private' }));
+}
+export async function codeReviewWorkflow(client, options) {
+    return singleStepWorkflow(client, 'code-review', {
+        model: options.model,
+        messages: [{
+                role: 'user',
+                content: [
+                    'Review this code for bugs, security risks, performance issues, and missing tests.',
+                    'Return findings ordered by severity with file/line references when available.',
+                    options.language ? `Language: ${options.language}` : '',
+                    contextBlock(options.context),
+                    `Code:\n${options.input}`,
+                ].filter(Boolean).join('\n\n'),
+            }],
+        responseFormat: {
+            type: 'json_schema',
+            schema: objectSchema(['findings', 'riskLevel', 'testSuggestions']),
+        },
+    });
+}
+async function singleStepWorkflow(client, step, request) {
+    const response = await client.complete(request);
+    const steps = [{ step, response }];
+    return {
+        content: response.content,
+        response,
+        steps,
+    };
+}
+function contextBlock(context) {
+    return context?.length ? `Context:\n${context.map((item, index) => `[${index + 1}] ${item}`).join('\n')}` : '';
+}
+function objectSchema(required) {
+    return {
+        type: 'object',
+        required,
+        properties: Object.fromEntries(required.map((key) => [key, {}])),
+    };
+}

package/examples/agent.ts

@@ -0,0 +1,69 @@
+import { NexusAI, tool } from 'nexus-ai-pro';
+
+const getCurrentTime = tool({
+  name: 'get_current_time',
+  description: 'Get the current ISO timestamp.',
+  parameters: {
+    type: 'object',
+    properties: {},
+  },
+  execute: async () => ({ now: new Date().toISOString() }),
+});
+
+const calculate = tool<{ expression: string }>({
+  name: 'calculate',
+  description: 'Evaluate a simple arithmetic expression. Only supports numbers and arithmetic operators.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: { type: 'string', description: 'Arithmetic expression like 2 + 2 * 10' },
+    },
+    required: ['expression'],
+  },
+  execute: async ({ expression }) => {
+    if (!/^[0-9+\-*/().\s]+$/.test(expression)) {
+      throw new Error('Unsafe expression');
+    }
+
+    return { result: Function(`"use strict"; return (${expression})`)() };
+  },
+});
+
+async function main() {
+  const ai = new NexusAI({
+    providers: {
+      openai: process.env.OPENAI_API_KEY ? { apiKey: process.env.OPENAI_API_KEY } : undefined,
+      anthropic: process.env.ANTHROPIC_API_KEY ? { apiKey: process.env.ANTHROPIC_API_KEY } : undefined,
+      ollama: { baseUrl: 'http://localhost:11434' },
+    },
+    routing: {
+      mode: 'auto',
+      strategy: process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY ? 'quality' : 'privacy',
+    },
+    security: 'standard',
+    tokenOptimizer: {
+      densification: { enabled: true },
+      budget: { enabled: true, maxInputTokens: 4000, onExceeded: 'densify' },
+    },
+    debug: true,
+  });
+
+  const result = await ai.agent({
+    model: 'auto',
+    goal: 'What time is it now, and what is 12 * 7 + 5? Use tools when needed.',
+    tools: [getCurrentTime, calculate],
+    maxIterations: 5,
+    onStep: (step) => {
+      console.log(`[${step.iteration}] ${step.type}: ${step.message}`);
+      if (step.toolName) console.log(`  tool=${step.toolName}`, step.toolArgs, step.toolResult);
+    },
+  });
+
+  console.log('\nFinal answer:\n');
+  console.log(result.content);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/basic.ts

@@ -0,0 +1,37 @@
+import { NexusAI } from 'nexus-ai-pro';
+
+async function main() {
+  const ai = new NexusAI({
+    providers: {
+      ollama: { baseUrl: 'http://localhost:11434' },
+      openai: process.env.OPENAI_API_KEY
+        ? { apiKey: process.env.OPENAI_API_KEY }
+        : undefined,
+      anthropic: process.env.ANTHROPIC_API_KEY
+        ? { apiKey: process.env.ANTHROPIC_API_KEY }
+        : undefined,
+    },
+    routing: {
+      mode: 'auto',
+      strategy: process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY ? 'quality' : 'privacy',
+    },
+    debug: true,
+  });
+
+  const response = await ai.complete({
+    model: 'auto',
+    messages: [
+      { role: 'user', content: 'Explain what nexus-ai-pro is in 2 short bullets.' },
+    ],
+  });
+
+  console.log('\nResponse:\n');
+  console.log(response.content);
+  console.log('\nMeta:\n');
+  console.log(response.meta);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/bullmq-worker.ts

@@ -0,0 +1,36 @@
+import { Queue, Worker } from 'bullmq';
+import { NexusAI } from '../src/index.js';
+
+// Optional example dependency install:
+// npm install bullmq ioredis
+// Start Redis before running this example.
+
+const connection = {
+  host: process.env.REDIS_HOST || '127.0.0.1',
+  port: Number(process.env.REDIS_PORT || 6379),
+};
+
+const queueName = 'nexus-ai-pro-jobs';
+const queue = new Queue(queueName, { connection });
+
+const ai = new NexusAI({
+  providers: {
+    ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },
+  },
+  routing: { mode: 'auto', strategy: 'privacy' },
+});
+
+new Worker(queueName, async (job) => {
+  const response = await ai.complete(job.data);
+  return {
+    content: response.content,
+    meta: response.meta,
+  };
+}, { connection });
+
+const job = await queue.add('completion', {
+  model: 'auto',
+  messages: [{ role: 'user', content: 'Summarize durable queues in one sentence.' }],
+});
+
+console.log(`Queued job ${job.id}`);

package/examples/classifier-calibration.ts

@@ -0,0 +1,7 @@
+import {
+  SEMANTIC_INJECTION_CALIBRATION_SET,
+  calibrateSemanticInjectionClassifier,
+} from '../src/index.js';
+
+const results = calibrateSemanticInjectionClassifier(SEMANTIC_INJECTION_CALIBRATION_SET);
+console.table(results);

package/examples/domain-workflows.ts

@@ -0,0 +1,38 @@
+import {
+  NexusAI,
+  supportTriageWorkflow,
+  salesQualificationWorkflow,
+  legalReviewWorkflow,
+  codeReviewWorkflow,
+} from '../src/index.js';
+
+const ai = new NexusAI({
+  providers: {
+    ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },
+  },
+  routing: { mode: 'auto', strategy: 'privacy' },
+});
+
+console.log(await supportTriageWorkflow(ai, {
+  model: 'auto',
+  input: 'Customer cannot log in after enabling SSO.',
+  customerTier: 'enterprise',
+}));
+
+console.log(await salesQualificationWorkflow(ai, {
+  model: 'auto',
+  input: 'Lead needs secure AI routing for a healthcare app.',
+  product: 'nexus-ai-pro',
+}));
+
+console.log(await legalReviewWorkflow(ai, {
+  model: 'auto',
+  input: 'Draft contract clause text...',
+  jurisdiction: 'US',
+}));
+
+console.log(await codeReviewWorkflow(ai, {
+  model: 'auto',
+  input: 'function add(a,b){ return a-b }',
+  language: 'JavaScript',
+}));

package/examples/feature-flags.ts

@@ -0,0 +1,65 @@
+import { NexusAI, guardrailPolicy } from 'nexus-ai-pro';
+
+function envFlag(name: string): boolean {
+  return process.env[name] === '1' || process.env[name] === 'true';
+}
+
+async function main() {
+  const enableGuardrails = envFlag('NEXUS_GUARDRAILS');
+  const enableCache = envFlag('NEXUS_CACHE');
+  const enableTrace = envFlag('NEXUS_TRACE');
+
+  const ai = new NexusAI({
+    providers: {
+      openai: process.env.OPENAI_API_KEY
+        ? { apiKey: process.env.OPENAI_API_KEY }
+        : undefined,
+      ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },
+    },
+    routing: {
+      mode: process.env.NEXUS_MODEL ? 'direct' : 'auto',
+      strategy: process.env.OPENAI_API_KEY ? 'quality' : 'privacy',
+    },
+    defaultModel: process.env.NEXUS_MODEL,
+    security: enableGuardrails ? guardrailPolicy('enterprise-strict') : 'off',
+    tokenOptimizer: {
+      enabled: envFlag('NEXUS_OPTIMIZER'),
+      densification: { enabled: envFlag('NEXUS_DENSIFY') },
+      budget: {
+        enabled: envFlag('NEXUS_TOKEN_BUDGET'),
+        maxInputTokens: 4000,
+        onExceeded: 'densify',
+      },
+    },
+    cache: {
+      enabled: enableCache,
+      strategy: 'exact',
+      ttlSeconds: 300,
+    },
+    pipeline: {
+      enabled: enableTrace,
+      trace: enableTrace,
+      includeTraceInResponse: enableTrace,
+    },
+    metrics: {
+      enabled: envFlag('NEXUS_METRICS'),
+    },
+  });
+
+  const response = await ai.complete({
+    model: 'auto',
+    messages: [
+      { role: 'user', content: 'Give me a short production checklist for an AI endpoint.' },
+    ],
+  });
+
+  console.log(response.content);
+  if (response.meta.pipeline) {
+    console.log('\nPipeline steps:', response.meta.pipeline.steps.map((step) => step.name));
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/minimal.ts

@@ -0,0 +1,45 @@
+import { NexusAI } from 'nexus-ai-pro';
+
+async function main() {
+  const ai = new NexusAI({
+    providers: {
+      openai: process.env.OPENAI_API_KEY
+        ? { apiKey: process.env.OPENAI_API_KEY }
+        : undefined,
+      ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },
+    },
+    routing: {
+      mode: 'direct',
+    },
+    defaultModel: process.env.NEXUS_MODEL || (process.env.OPENAI_API_KEY ? 'gpt-5.4-mini' : 'ollama/llama3.2'),
+    security: 'off',
+    tokenOptimizer: {
+      enabled: false,
+    },
+    cache: {
+      enabled: false,
+    },
+    pipeline: {
+      enabled: false,
+      trace: false,
+      includeTraceInResponse: false,
+    },
+    metrics: {
+      enabled: false,
+    },
+  });
+
+  const response = await ai.complete({
+    model: 'auto',
+    messages: [
+      { role: 'user', content: 'Explain nexus-ai-pro in one sentence.' },
+    ],
+  });
+
+  console.log(response.content);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/ocr-pdf-ingestion.ts

@@ -0,0 +1,42 @@
+import {
+  createOcrExtractor,
+  createPdfExtractor,
+  ingestFilesAfterScan,
+} from '../src/index.js';
+
+// Wire your preferred OCR/PDF libraries here, for example:
+// - pdf-parse, pdfjs-dist, or a hosted document AI parser for PDFs
+// - tesseract.js, cloud vision, or another OCR service for images
+
+const pdfExtractor = createPdfExtractor(async (file) => {
+  return `[pdf text extracted from ${file.name}]`;
+});
+
+const ocrExtractor = createOcrExtractor(async (file) => {
+  return `[ocr text extracted from ${file.name}]`;
+});
+
+const result = await ingestFilesAfterScan([
+  {
+    name: 'policy.pdf',
+    mimeType: 'application/pdf',
+    sizeBytes: 1200,
+    content: Buffer.from('fake pdf bytes'),
+  },
+  {
+    name: 'diagram.png',
+    mimeType: 'image/png',
+    sizeBytes: 800,
+    content: Buffer.from('fake image bytes'),
+  },
+], {
+  scan: {
+    maxBytes: 5_000_000,
+    allowedMimeTypes: ['application/pdf', 'image/png', 'image/jpeg'],
+  },
+  extractors: [pdfExtractor, ocrExtractor],
+  chunkSize: 800,
+  overlap: 80,
+});
+
+console.log(result.chunks);