nexus-ai-pro 0.2.0

package/dist/agent/loop.d.ts

@@ -0,0 +1,12 @@
+import type { AgentConfig, AgentResult } from '../types/agent.js';
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+export interface AgentModelClient {
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+}
+export declare class AgentLoop {
+    private client;
+    constructor(client: AgentModelClient);
+    run(config: AgentConfig): Promise<AgentResult>;
+    private parseToolArgs;
+}

package/dist/agent/loop.js

@@ -0,0 +1,89 @@
+import { ToolExecutor } from './tool.js';
+export class AgentLoop {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async run(config) {
+        const maxIterations = config.maxIterations ?? 8;
+        const executor = new ToolExecutor(config.tools || []);
+        const steps = [];
+        const messages = [];
+        if (config.systemPrompt) {
+            messages.push({ role: 'system', content: config.systemPrompt });
+        }
+        messages.push({ role: 'user', content: config.goal });
+        let lastResponse = null;
+        for (let iteration = 1; iteration <= maxIterations; iteration++) {
+            const response = await this.client.complete({
+                model: config.model,
+                messages,
+                tools: executor.list(),
+                temperature: config.temperature,
+                maxTokens: config.maxTokens,
+                metadata: config.metadata,
+            });
+            lastResponse = response;
+            const modelStep = {
+                iteration,
+                type: response.toolCalls?.length ? 'model' : 'final',
+                message: response.content || (response.toolCalls?.length ? 'Model requested tool calls' : ''),
+            };
+            steps.push(modelStep);
+            await config.onStep?.(modelStep);
+            messages.push({
+                role: 'assistant',
+                content: response.content,
+                toolCalls: response.toolCalls,
+            });
+            if (!response.toolCalls || response.toolCalls.length === 0) {
+                return {
+                    content: response.content,
+                    steps,
+                    iterations: iteration,
+                    response,
+                    messages,
+                };
+            }
+            for (const toolCall of response.toolCalls) {
+                const args = this.parseToolArgs(toolCall.function.arguments);
+                const result = await executor.execute(toolCall.function.name, args);
+                const toolStep = {
+                    iteration,
+                    type: 'tool',
+                    message: result.ok ? 'Tool executed successfully' : `Tool failed: ${result.error}`,
+                    toolName: toolCall.function.name,
+                    toolArgs: args,
+                    toolResult: result.ok ? result.result : { error: result.error },
+                };
+                steps.push(toolStep);
+                await config.onToolCall?.(toolStep);
+                await config.onStep?.(toolStep);
+                messages.push({
+                    role: 'tool',
+                    toolCallId: toolCall.id,
+                    content: JSON.stringify(result.ok ? result.result : { error: result.error }),
+                });
+            }
+        }
+        if (!lastResponse) {
+            throw new Error('Agent loop failed before receiving a model response');
+        }
+        return {
+            content: lastResponse.content,
+            steps,
+            iterations: maxIterations,
+            response: lastResponse,
+            messages,
+        };
+    }
+    parseToolArgs(raw) {
+        try {
+            const parsed = JSON.parse(raw || '{}');
+            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+}

package/dist/agent/tool.d.ts

@@ -0,0 +1,16 @@
+import type { ToolDefinition } from '../types/messages.js';
+import type { ToolExecutionResult } from '../types/agent.js';
+export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: TArgs) => Promise<unknown> | unknown;
+}): ToolDefinition;
+export declare class ToolExecutor {
+    private tools;
+    constructor(tools?: ToolDefinition[]);
+    register(toolDefinition: ToolDefinition): this;
+    has(name: string): boolean;
+    list(): ToolDefinition[];
+    execute(name: string, args: Record<string, unknown>): Promise<ToolExecutionResult>;
+}

package/dist/agent/tool.js

@@ -0,0 +1,43 @@
+export function tool(definition) {
+    return {
+        name: definition.name,
+        description: definition.description,
+        parameters: definition.parameters,
+        execute: async (args) => definition.execute(args),
+    };
+}
+export class ToolExecutor {
+    tools = new Map();
+    constructor(tools = []) {
+        tools.forEach((toolDefinition) => this.register(toolDefinition));
+    }
+    register(toolDefinition) {
+        this.tools.set(toolDefinition.name, toolDefinition);
+        return this;
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+    async execute(name, args) {
+        const toolDefinition = this.tools.get(name);
+        if (!toolDefinition) {
+            return { ok: false, error: `Tool "${name}" is not registered` };
+        }
+        if (!toolDefinition.execute) {
+            return { ok: false, error: `Tool "${name}" does not have an execute function` };
+        }
+        try {
+            const result = await toolDefinition.execute(args);
+            return { ok: true, result };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}

package/dist/cache/adapters.d.ts

@@ -0,0 +1,42 @@
+export interface CacheAdapter<T = unknown> {
+    get(key: string): Promise<T | undefined> | T | undefined;
+    set(key: string, value: T, ttlSeconds?: number): Promise<void> | void;
+    delete?(key: string): Promise<boolean> | boolean;
+    clear?(): Promise<void> | void;
+}
+export declare class MemoryCacheAdapter<T = unknown> implements CacheAdapter<T> {
+    private entries;
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttlSeconds?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+}
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null> | string | null;
+    set(key: string, value: string, mode?: string, ttlSeconds?: number): Promise<unknown> | unknown;
+    del?(key: string): Promise<number> | number;
+}
+export declare class RedisCacheAdapter<T = unknown> implements CacheAdapter<T> {
+    private client;
+    private prefix;
+    constructor(client: RedisLikeClient, prefix?: string);
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+export interface SQLiteLikeDatabase {
+    prepare(sql: string): {
+        get?: (...args: unknown[]) => unknown;
+        run?: (...args: unknown[]) => unknown;
+    };
+    exec?(sql: string): unknown;
+}
+export declare class SQLiteCacheAdapter<T = unknown> implements CacheAdapter<T> {
+    private db;
+    private table;
+    constructor(db: SQLiteLikeDatabase, table?: string);
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttlSeconds?: number): void;
+    delete(key: string): boolean;
+    clear(): void;
+}

package/dist/cache/adapters.js

@@ -0,0 +1,76 @@
+export class MemoryCacheAdapter {
+    entries = new Map();
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlSeconds = 300) {
+        this.entries.set(key, {
+            value,
+            expiresAt: Date.now() + ttlSeconds * 1000,
+        });
+    }
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+export class RedisCacheAdapter {
+    client;
+    prefix;
+    constructor(client, prefix = 'nexus-ai-pro:cache:') {
+        this.client = client;
+        this.prefix = prefix;
+    }
+    async get(key) {
+        const raw = await this.client.get(this.prefix + key);
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    async set(key, value, ttlSeconds = 300) {
+        await this.client.set(this.prefix + key, JSON.stringify(value), 'EX', ttlSeconds);
+    }
+    async delete(key) {
+        if (!this.client.del)
+            return false;
+        return (await this.client.del(this.prefix + key)) > 0;
+    }
+}
+export class SQLiteCacheAdapter {
+    db;
+    table;
+    constructor(db, table = 'nexus_cache') {
+        this.db = db;
+        this.table = table;
+        this.db.exec?.(`CREATE TABLE IF NOT EXISTS ${table} (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER NOT NULL)`);
+    }
+    get(key) {
+        const row = this.db.prepare(`SELECT value, expires_at FROM ${this.table} WHERE key = ?`).get?.(key);
+        if (!row)
+            return undefined;
+        if (row.expires_at < Date.now()) {
+            this.delete(key);
+            return undefined;
+        }
+        return JSON.parse(row.value);
+    }
+    set(key, value, ttlSeconds = 300) {
+        this.db.prepare(`INSERT OR REPLACE INTO ${this.table} (key, value, expires_at) VALUES (?, ?, ?)`).run?.(key, JSON.stringify(value), Date.now() + ttlSeconds * 1000);
+    }
+    delete(key) {
+        this.db.prepare(`DELETE FROM ${this.table} WHERE key = ?`).run?.(key);
+        return true;
+    }
+    clear() {
+        this.db.prepare(`DELETE FROM ${this.table}`).run?.();
+    }
+}

package/dist/cache/memory-cache.d.ts

@@ -0,0 +1,20 @@
+export interface CacheEntry<T> {
+    value: T;
+    expiresAt: number;
+}
+export declare class MemoryCache<T> {
+    private maxEntries;
+    private entries;
+    constructor(maxEntries?: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T, ttlSeconds?: number): void;
+    clear(): void;
+    delete(key: string): boolean;
+    clearExpired(): number;
+    stats(): {
+        size: number;
+        maxEntries: number;
+        expiredEntries: number;
+    };
+}
+export declare function createCacheKey(value: unknown): string;

package/dist/cache/memory-cache.js

@@ -0,0 +1,63 @@
+export class MemoryCache {
+    maxEntries;
+    entries = new Map();
+    constructor(maxEntries = 500) {
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        return entry.value;
+    }
+    set(key, value, ttlSeconds = 300) {
+        if (this.entries.size >= this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest)
+                this.entries.delete(oldest);
+        }
+        this.entries.set(key, {
+            value,
+            expiresAt: Date.now() + ttlSeconds * 1000,
+        });
+    }
+    clear() {
+        this.entries.clear();
+    }
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    clearExpired() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this.entries) {
+            if (entry.expiresAt < now) {
+                this.entries.delete(key);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+    stats() {
+        const now = Date.now();
+        let expiredEntries = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.expiresAt < now)
+                expiredEntries += 1;
+        }
+        return {
+            size: this.entries.size,
+            maxEntries: this.maxEntries,
+            expiredEntries,
+        };
+    }
+}
+export function createCacheKey(value) {
+    return JSON.stringify(value, Object.keys(value).sort());
+}

package/dist/cache/semantic-cache.d.ts

@@ -0,0 +1,19 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+import { type EmbeddingProvider } from '../hallucination/retrieval.js';
+export interface SemanticCacheOptions {
+    enabled?: boolean;
+    similarityThreshold?: number;
+    maxEntries?: number;
+    ttlSeconds?: number;
+    embed?: EmbeddingProvider;
+}
+export declare class SemanticCache {
+    private options;
+    private entries;
+    private embed;
+    constructor(options?: SemanticCacheOptions);
+    get(request: CompletionRequest): Promise<NexusResponse | undefined>;
+    set(key: string, request: CompletionRequest, response: NexusResponse): Promise<void>;
+    clear(): void;
+}

package/dist/cache/semantic-cache.js

@@ -0,0 +1,71 @@
+import { createHashEmbeddings, cosineSimilarity } from '../hallucination/retrieval.js';
+export class SemanticCache {
+    options;
+    entries = [];
+    embed;
+    constructor(options = {}) {
+        this.options = options;
+        this.embed = options.embed || createHashEmbeddings;
+    }
+    async get(request) {
+        if (!this.options.enabled)
+            return undefined;
+        const text = requestToSearchText(request);
+        const [embedding] = await this.embed([text]);
+        const threshold = this.options.similarityThreshold ?? 0.88;
+        const now = Date.now();
+        let best;
+        this.entries = this.entries.filter((entry) => entry.expiresAt > now);
+        for (const entry of this.entries) {
+            const score = cosineSimilarity(embedding, entry.embedding);
+            if (score >= threshold && (!best || score > best.score)) {
+                best = { entry, score };
+            }
+        }
+        if (!best)
+            return undefined;
+        return {
+            ...best.entry.response,
+            meta: {
+                ...best.entry.response.meta,
+                cacheHit: true,
+                semanticCache: {
+                    hit: true,
+                    score: best.score,
+                    key: best.entry.key,
+                },
+            },
+        };
+    }
+    async set(key, request, response) {
+        if (!this.options.enabled)
+            return;
+        const text = requestToSearchText(request);
+        const [embedding] = await this.embed([text]);
+        const maxEntries = this.options.maxEntries || 500;
+        if (this.entries.length >= maxEntries)
+            this.entries.shift();
+        this.entries.push({
+            key,
+            text,
+            embedding,
+            response,
+            expiresAt: Date.now() + (this.options.ttlSeconds || 300) * 1000,
+        });
+    }
+    clear() {
+        this.entries = [];
+    }
+}
+function requestToSearchText(request) {
+    return request.messages
+        .map((message) => {
+        if (typeof message.content === 'string')
+            return `${message.role}: ${message.content}`;
+        return `${message.role}: ${message.content
+            .filter((part) => part.type === 'text')
+            .map((part) => part.text)
+            .join('\n')}`;
+    })
+        .join('\n');
+}

package/dist/connectors/web.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from '../types/messages.js';
+export interface WebConnectorOptions {
+    allowedDomains?: string[];
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export declare function createFetchUrlTool(options?: WebConnectorOptions): ToolDefinition;
+export declare function createSearchTool(search: (query: string) => Promise<unknown>, name?: string): ToolDefinition;

package/dist/connectors/web.js

@@ -0,0 +1,60 @@
+import { tool } from '../agent/tool.js';
+export function createFetchUrlTool(options = {}) {
+    return tool({
+        name: 'fetch_url',
+        description: 'Fetch text content from an allowed URL.',
+        parameters: {
+            type: 'object',
+            required: ['url'],
+            properties: {
+                url: { type: 'string' },
+            },
+        },
+        execute: async (args) => {
+            const url = String(args.url || '');
+            assertAllowedUrl(url, options.allowedDomains);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), options.timeoutMs || 10_000);
+            try {
+                const response = await fetch(url, {
+                    signal: controller.signal,
+                    headers: { 'user-agent': options.userAgent || 'nexus-ai-pro/0.1' },
+                });
+                return {
+                    url,
+                    ok: response.ok,
+                    status: response.status,
+                    text: (await response.text()).slice(0, 20_000),
+                };
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        },
+    });
+}
+export function createSearchTool(search, name = 'web_search') {
+    return tool({
+        name,
+        description: 'Search the web or an external search index.',
+        parameters: {
+            type: 'object',
+            required: ['query'],
+            properties: {
+                query: { type: 'string' },
+            },
+        },
+        execute: async (args) => search(String(args.query || '')),
+    });
+}
+function assertAllowedUrl(url, allowedDomains) {
+    const parsed = new URL(url);
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw new Error('Only http and https URLs are allowed');
+    }
+    if (!allowedDomains?.length)
+        return;
+    const allowed = allowedDomains.some((domain) => parsed.hostname === domain || parsed.hostname.endsWith(`.${domain}`));
+    if (!allowed)
+        throw new Error(`URL domain ${parsed.hostname} is not allowed`);
+}

package/dist/core/nexus.d.ts

@@ -0,0 +1,71 @@
+import type { NexusAIConfig } from '../types/config.js';
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusPlan } from '../types/planning.js';
+import type { NexusResponse, NexusStream } from '../types/response.js';
+import type { AgentConfig, AgentResult } from '../types/agent.js';
+import type { PipelineStep } from '../pipeline/types.js';
+import { BaseProvider } from '../providers/base.js';
+import { type VerificationOptions } from '../hallucination/verification.js';
+import { type SelfConsistencyOptions } from '../hallucination/consistency.js';
+import { type BatchOptions, type BatchItemResult } from '../jobs/batch.js';
+import { JobQueue, type QueueOptions } from '../jobs/queue.js';
+import { type EvalCase, type EvalRunResult } from '../evals/runner.js';
+import { type SummarizeVerifyFormatOptions, type WorkflowResult } from '../workflow/chains.js';
+export declare class NexusAI {
+    private config;
+    private providers;
+    private router;
+    private failover;
+    private logger;
+    private security;
+    private optimizer;
+    private cache;
+    private auditLogger;
+    private rateLimiter;
+    private pipeline;
+    private metrics;
+    private health;
+    private semanticCache;
+    constructor(config: NexusAIConfig);
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+    completeVerified(request: CompletionRequest, options: VerificationOptions): Promise<NexusResponse>;
+    completeConsistent(request: CompletionRequest, options?: SelfConsistencyOptions): Promise<NexusResponse>;
+    plan(request: CompletionRequest): NexusPlan;
+    stream(request: CompletionRequest): NexusStream;
+    agent(config: AgentConfig): Promise<AgentResult>;
+    registerProvider(name: string, provider: BaseProvider): this;
+    hasProvider(name: string): boolean;
+    listProviders(): string[];
+    use(step: PipelineStep): this;
+    batchComplete(requests: CompletionRequest[], options?: BatchOptions): Promise<Array<BatchItemResult<NexusResponse>>>;
+    createQueue(options?: QueueOptions): JobQueue<CompletionRequest, NexusResponse>;
+    runEvals(cases: EvalCase<NexusResponse>[]): Promise<EvalRunResult<NexusResponse>>;
+    summarizeVerifyFormat(options: SummarizeVerifyFormatOptions): Promise<WorkflowResult>;
+    getProviderHealth(): import("../ops/health.js").ProviderHealthSnapshot[];
+    checkProviders(): Promise<Array<{
+        providerName: string;
+        ok: boolean;
+        error?: string;
+    }>>;
+    getMetricsSnapshot(): Record<string, unknown>;
+    getPrometheusMetrics(): string;
+    clearCache(): void;
+    clearExpiredCache(): number;
+    getCacheStats(): {
+        size: number;
+        maxEntries: number;
+        expiredEntries: number;
+    };
+    private isAuditLogEnabled;
+    private isCacheEnabled;
+    private isCostBudgetEnabled;
+    private isSecurityEnabled;
+    private isTokenOptimizerEnabled;
+    private hasResponseFormat;
+    private registerConfiguredProviders;
+    private attachTrace;
+    private getCachedResponse;
+    private setCachedResponse;
+    private enforceCostBudget;
+    private estimatedOutputTokens;
+}