nexus-ai-pro 0.2.0

package/dist/core/nexus.js

@@ -0,0 +1,477 @@
+import { OpenAIProvider } from '../providers/openai.js';
+import { AnthropicProvider } from '../providers/anthropic.js';
+import { GoogleProvider } from '../providers/google.js';
+import { OllamaProvider } from '../providers/ollama.js';
+import { OpenRouterProvider } from '../providers/openrouter.js';
+import { GroqProvider } from '../providers/groq.js';
+import { MistralProvider } from '../providers/mistral.js';
+import { CohereProvider } from '../providers/cohere.js';
+import { Router, FailoverExecutor } from '../router/index.js';
+import { Logger } from '../utils/logger.js';
+import { SecurityPipeline } from '../security/index.js';
+import { TokenOptimizer } from '../optimizer/index.js';
+import { AgentLoop } from '../agent/loop.js';
+import { resolveModel } from '../models/registry.js';
+import { createCacheKey, MemoryCache } from '../cache/memory-cache.js';
+import { applyResponseFormat, withResponseFormat } from './response-format.js';
+import { protectStreamOutput } from './secure-stream.js';
+import { AuditLogger } from '../ops/audit-logger.js';
+import { RateLimiter } from '../ops/rate-limiter.js';
+import { completeVerified, } from '../hallucination/verification.js';
+import { completeWithSelfConsistency, } from '../hallucination/consistency.js';
+import { assertWithinCostBudget, estimateCost } from '../optimizer/cost.js';
+import { PipelineRunner, createPipelineContext } from '../pipeline/pipeline.js';
+import { MetricsCollector } from '../ops/metrics.js';
+import { ProviderHealthMonitor } from '../ops/health.js';
+import { SemanticCache } from '../cache/semantic-cache.js';
+import { runBatch } from '../jobs/batch.js';
+import { JobQueue } from '../jobs/queue.js';
+import { EvalRunner } from '../evals/runner.js';
+import { summarizeVerifyFormat } from '../workflow/chains.js';
+export class NexusAI {
+    config;
+    providers = new Map();
+    router = new Router();
+    failover = new FailoverExecutor();
+    logger;
+    security;
+    optimizer;
+    cache;
+    auditLogger;
+    rateLimiter = new RateLimiter();
+    pipeline;
+    metrics;
+    health;
+    semanticCache;
+    constructor(config) {
+        this.config = {
+            routing: { mode: 'auto', strategy: 'quality' },
+            timeout: 60000,
+            ...config,
+        };
+        this.logger = new Logger(this.config.debug);
+        this.security = new SecurityPipeline(this.config.security || 'standard');
+        this.optimizer = new TokenOptimizer(this.config.tokenOptimizer || {});
+        this.cache = new MemoryCache(this.config.cache?.maxEntries || 500);
+        this.auditLogger = new AuditLogger(this.config.auditLog);
+        this.pipeline = new PipelineRunner(this.config.pipeline || {});
+        this.metrics = new MetricsCollector(this.config.metrics || {});
+        this.health = new ProviderHealthMonitor(this.config.health || {});
+        this.semanticCache = new SemanticCache({
+            enabled: this.config.cache?.enabled && (this.config.cache.strategy === 'semantic' || this.config.cache.strategy === 'hybrid'),
+            maxEntries: this.config.cache?.maxEntries,
+            ttlSeconds: this.config.cache?.ttlSeconds,
+            ...this.config.cache?.semantic,
+        });
+        this.registerConfiguredProviders();
+    }
+    async complete(request) {
+        let context = createPipelineContext(request);
+        try {
+            await this.metrics.recordRequest({ model: request.model });
+            this.rateLimiter.check(request, this.config.rateLimit);
+            if (this.isAuditLogEnabled()) {
+                await this.pipeline.trace(context, 'auditLog', () => this.auditLogger.log({
+                    type: 'request',
+                    userId: request.userId,
+                    model: request.model,
+                    timestamp: new Date().toISOString(),
+                    metadata: this.config.auditLog?.includeInput ? { request } : undefined,
+                }));
+            }
+            context = await this.pipeline.runHook('beforeInput', context);
+            context = await this.pipeline.runCustomSteps(context);
+            if (this.hasResponseFormat(context.request)) {
+                const formattedRequest = await this.pipeline.trace(context, 'responseFormat', () => {
+                    return withResponseFormat(context.request, this.config.responseFormat);
+                });
+                context.request = formattedRequest;
+            }
+            const optimizationResult = this.isTokenOptimizerEnabled()
+                ? await this.pipeline.trace(context, 'tokenOptimization', () => {
+                    return this.optimizer.optimize(context.request);
+                })
+                : this.optimizer.optimize(context.request);
+            context.optimization = optimizationResult;
+            context.request = optimizationResult.value;
+            if (this.isSecurityEnabled()) {
+                const securityResult = await this.pipeline.trace(context, 'inputSecurity', () => {
+                    return this.security.protectInput(context.request);
+                });
+                context.request = securityResult.value;
+                context.securityFindings.push(...securityResult.findings);
+                context.guardrailsApplied.push(...securityResult.guardrailsApplied);
+                try {
+                    this.security.assertSafe(securityResult);
+                }
+                catch (error) {
+                    if (this.isAuditLogEnabled()) {
+                        await this.auditLogger.log({
+                            type: 'blocked',
+                            userId: request.userId,
+                            model: request.model,
+                            timestamp: new Date().toISOString(),
+                            metadata: { findings: securityResult.findings },
+                        });
+                    }
+                    throw error;
+                }
+            }
+            context = await this.pipeline.runHook('afterSecurity', context);
+            const decision = await this.pipeline.trace(context, 'routing', () => {
+                return this.router.route(context.request, this.config, this.providers, this.health.snapshot());
+            });
+            context.route = decision;
+            this.logger.info('route decision', decision);
+            context.request = { ...context.request, model: resolveModel(decision.model, this.config).model };
+            if (this.isCostBudgetEnabled(context.request)) {
+                await this.pipeline.trace(context, 'costBudget', () => {
+                    this.enforceCostBudget(context.request);
+                });
+            }
+            const responseFormat = context.request.responseFormat || this.config.responseFormat;
+            const cacheKey = createCacheKey({ request: context.request, responseFormat });
+            if (this.isCacheEnabled()) {
+                const cached = await this.pipeline.trace(context, 'cacheLookup', () => this.getCachedResponse(cacheKey, context.request));
+                if (cached) {
+                    const cachedResponse = this.attachTrace({
+                        ...cached,
+                        meta: { ...cached.meta, cacheHit: true },
+                    }, this.pipeline.finish(context));
+                    return cachedResponse;
+                }
+            }
+            context = await this.pipeline.runHook('beforeProvider', context);
+            const response = await this.pipeline.trace(context, 'providerCall', () => {
+                return this.failover.complete(context.request, decision, this.providers, {
+                    timeoutMs: this.config.timeout,
+                    retry: this.config.retry,
+                    onAttemptSuccess: (providerName, latencyMs) => this.health.recordSuccess(providerName, latencyMs),
+                    onAttemptFailure: (providerName, error) => this.health.recordFailure(providerName, error),
+                });
+            });
+            context.response = response;
+            context = await this.pipeline.runHook('afterProvider', context);
+            context.response.meta.guardrailsApplied.push(...context.guardrailsApplied);
+            context.response.meta.tokensSaved += optimizationResult.usage.savedTokens;
+            context.response.meta.routingDecision = {
+                reason: decision.reason,
+                fallbacksConsidered: decision.fallbacks.length,
+            };
+            if (this.isSecurityEnabled()) {
+                const outputResult = await this.pipeline.trace(context, 'outputSecurity', () => {
+                    return this.security.protectOutput(context.response);
+                });
+                context.response = outputResult.value;
+            }
+            if (responseFormat && responseFormat.type !== 'text') {
+                const formattedResponse = await this.pipeline.trace(context, 'responseValidation', () => {
+                    return applyResponseFormat(context.response, responseFormat);
+                });
+                context.response = formattedResponse;
+            }
+            if (this.isCacheEnabled()) {
+                await this.pipeline.trace(context, 'cacheWrite', () => this.setCachedResponse(cacheKey, context.request, context.response));
+            }
+            context = await this.pipeline.runHook('beforeReturn', context);
+            const finalContext = this.pipeline.finish(context);
+            const finalResponse = this.attachTrace(context.response, finalContext);
+            if (this.isAuditLogEnabled()) {
+                await this.pipeline.trace(finalContext, 'auditLog', () => this.auditLogger.log({
+                    type: 'response',
+                    requestId: finalResponse.meta.requestId,
+                    userId: request.userId,
+                    model: finalResponse.meta.modelUsed,
+                    provider: finalResponse.meta.providerUsed,
+                    timestamp: new Date().toISOString(),
+                    metadata: this.config.auditLog?.includeOutput ? { response: finalResponse } : undefined,
+                }));
+            }
+            await this.metrics.recordResponse({
+                provider: finalResponse.meta.providerUsed,
+                model: finalResponse.meta.modelUsed,
+            }, finalResponse.meta.latencyMs, Number(finalResponse.meta.estimatedCost.replace('$', '')));
+            for (const step of finalResponse.meta.pipeline?.steps || []) {
+                await this.metrics.recordStep(step);
+            }
+            return finalResponse;
+        }
+        catch (error) {
+            await this.metrics.recordError({ model: request.model });
+            throw error;
+        }
+    }
+    async completeVerified(request, options) {
+        return completeVerified(this, request, options);
+    }
+    async completeConsistent(request, options = {}) {
+        return completeWithSelfConsistency(this, request, options);
+    }
+    plan(request) {
+        const formattedRequest = this.hasResponseFormat(request)
+            ? withResponseFormat(request, this.config.responseFormat)
+            : request;
+        const optimizationResult = this.optimizer.optimize(formattedRequest);
+        const securityResult = this.isSecurityEnabled()
+            ? this.security.protectInput(optimizationResult.value)
+            : { ok: true, value: optimizationResult.value, findings: [], guardrailsApplied: [] };
+        const decision = this.router.route(securityResult.value, this.config, this.providers, this.health.snapshot());
+        const resolved = resolveModel(decision.model, this.config);
+        const outputTokens = this.estimatedOutputTokens(securityResult.value);
+        const cost = estimateCost({
+            model: resolved.model,
+            inputTokens: optimizationResult.usage.afterTokens,
+            outputTokens,
+            config: this.config,
+        });
+        const maxContextTokens = resolved.capabilities?.maxContextTokens;
+        const warnings = [
+            ...optimizationResult.warnings,
+            ...securityResult.findings.map((finding) => finding.message),
+        ];
+        if (maxContextTokens && optimizationResult.usage.afterTokens + outputTokens > maxContextTokens) {
+            warnings.push(`Estimated tokens exceed ${resolved.model} context window`);
+        }
+        const maxEstimatedCost = request.maxEstimatedCost ?? this.config.costBudget?.maxEstimatedCost;
+        if (maxEstimatedCost !== undefined && cost.totalCost > maxEstimatedCost) {
+            warnings.push(`Estimated cost ${cost.formatted} exceeds maxEstimatedCost $${maxEstimatedCost.toFixed(4)}`);
+        }
+        return {
+            requestModel: request.model,
+            providerName: decision.providerName,
+            model: resolved.model,
+            route: decision,
+            tokenUsage: optimizationResult.usage,
+            estimatedCost: cost,
+            maxContextTokens,
+            fitsContext: maxContextTokens ? optimizationResult.usage.afterTokens + outputTokens <= maxContextTokens : true,
+            cacheEligible: Boolean(this.config.cache?.enabled),
+            wouldBlock: !securityResult.ok,
+            securityFindings: securityResult.findings,
+            warnings,
+            guardrailsApplied: securityResult.guardrailsApplied,
+        };
+    }
+    stream(request) {
+        this.rateLimiter.check(request, this.config.rateLimit);
+        const formattedRequest = this.hasResponseFormat(request)
+            ? withResponseFormat(request, this.config.responseFormat)
+            : request;
+        const optimizationResult = this.optimizer.optimize(formattedRequest);
+        const securityResult = this.isSecurityEnabled()
+            ? this.security.protectInput(optimizationResult.value)
+            : { ok: true, value: optimizationResult.value, findings: [], guardrailsApplied: [] };
+        if (this.isSecurityEnabled())
+            this.security.assertSafe(securityResult);
+        const decision = this.router.route(securityResult.value, this.config, this.providers, this.health.snapshot());
+        this.logger.info('stream route decision', {
+            ...decision,
+            tokensSaved: optimizationResult.usage.savedTokens,
+        });
+        const routedRequest = { ...securityResult.value, model: resolveModel(decision.model, this.config).model };
+        const stream = this.failover.stream(routedRequest, decision, this.providers, {
+            timeoutMs: this.config.timeout,
+            retry: this.config.retry,
+            onAttemptSuccess: (providerName, latencyMs) => this.health.recordSuccess(providerName, latencyMs),
+            onAttemptFailure: (providerName, error) => this.health.recordFailure(providerName, error),
+        });
+        return this.isSecurityEnabled() ? protectStreamOutput(stream, this.security) : stream;
+    }
+    async agent(config) {
+        const loop = new AgentLoop(this);
+        return loop.run(config);
+    }
+    registerProvider(name, provider) {
+        this.providers.set(name, provider);
+        return this;
+    }
+    hasProvider(name) {
+        return this.providers.has(name);
+    }
+    listProviders() {
+        return [...this.providers.keys()];
+    }
+    use(step) {
+        this.pipeline.use(step);
+        return this;
+    }
+    async batchComplete(requests, options = {}) {
+        return runBatch(requests, (item) => this.complete(item), options);
+    }
+    createQueue(options = {}) {
+        return new JobQueue((payload) => this.complete(payload), options);
+    }
+    runEvals(cases) {
+        return new EvalRunner(this).run(cases);
+    }
+    summarizeVerifyFormat(options) {
+        return summarizeVerifyFormat(this, options);
+    }
+    getProviderHealth() {
+        return this.health.snapshot();
+    }
+    async checkProviders() {
+        const results = [];
+        for (const [providerName, provider] of this.providers) {
+            const started = Date.now();
+            try {
+                const ok = await provider.healthCheck();
+                if (ok)
+                    this.health.recordSuccess(providerName, Date.now() - started);
+                else
+                    this.health.recordFailure(providerName, new Error('Health check returned false'));
+                results.push({ providerName, ok });
+            }
+            catch (error) {
+                this.health.recordFailure(providerName, error);
+                results.push({
+                    providerName,
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return results;
+    }
+    getMetricsSnapshot() {
+        return this.metrics.snapshot();
+    }
+    getPrometheusMetrics() {
+        return this.metrics.toPrometheus();
+    }
+    clearCache() {
+        this.cache.clear();
+        this.semanticCache.clear();
+    }
+    clearExpiredCache() {
+        return this.cache.clearExpired();
+    }
+    getCacheStats() {
+        return this.cache.stats();
+    }
+    isAuditLogEnabled() {
+        return this.config.auditLog?.enabled === true;
+    }
+    isCacheEnabled() {
+        return this.config.cache?.enabled === true;
+    }
+    isCostBudgetEnabled(request) {
+        if (request.maxEstimatedCost !== undefined)
+            return true;
+        if (this.config.costBudget?.enabled === false)
+            return false;
+        return this.config.costBudget?.enabled === true || this.config.costBudget?.maxEstimatedCost !== undefined;
+    }
+    isSecurityEnabled() {
+        const security = this.config.security;
+        if (security === 'off')
+            return false;
+        if (typeof security === 'object' && security.level === 'off')
+            return false;
+        return true;
+    }
+    isTokenOptimizerEnabled() {
+        return this.config.tokenOptimizer?.enabled !== false;
+    }
+    hasResponseFormat(request) {
+        const responseFormat = request.responseFormat || this.config.responseFormat;
+        return Boolean(responseFormat && responseFormat.type !== 'text');
+    }
+    registerConfiguredProviders() {
+        const providers = this.config.providers;
+        if (providers.openai) {
+            this.providers.set('openai', new OpenAIProvider(providers.openai));
+        }
+        if (providers.anthropic) {
+            this.providers.set('anthropic', new AnthropicProvider(providers.anthropic));
+        }
+        if (providers.google) {
+            this.providers.set('google', new GoogleProvider(providers.google));
+        }
+        if (providers.ollama) {
+            this.providers.set('ollama', new OllamaProvider(providers.ollama));
+        }
+        if (providers.openrouter) {
+            this.providers.set('openrouter', new OpenRouterProvider(providers.openrouter));
+        }
+        if (providers.groq) {
+            this.providers.set('groq', new GroqProvider(providers.groq));
+        }
+        if (providers.mistral) {
+            this.providers.set('mistral', new MistralProvider(providers.mistral));
+        }
+        if (providers.cohere) {
+            this.providers.set('cohere', new CohereProvider(providers.cohere));
+        }
+    }
+    attachTrace(response, context) {
+        if (this.config.pipeline?.trace === false)
+            return response;
+        if (this.config.pipeline?.includeTraceInResponse === false)
+            return response;
+        return {
+            ...response,
+            meta: {
+                ...response.meta,
+                pipeline: context.trace,
+            },
+        };
+    }
+    async getCachedResponse(cacheKey, request) {
+        if (!this.config.cache?.enabled)
+            return undefined;
+        if (this.config.cache.strategy === 'semantic' || this.config.cache.strategy === 'hybrid') {
+            const semantic = await this.semanticCache.get(request);
+            if (semantic)
+                return semantic;
+        }
+        if (this.config.cache.strategy === 'semantic')
+            return undefined;
+        if (this.config.cache.adapter) {
+            return await this.config.cache.adapter.get(cacheKey);
+        }
+        return this.cache.get(cacheKey);
+    }
+    async setCachedResponse(cacheKey, request, response) {
+        if (!this.config.cache?.enabled)
+            return;
+        const ttl = this.config.cache.ttlSeconds || 300;
+        if (this.config.cache.strategy === 'semantic' || this.config.cache.strategy === 'hybrid') {
+            await this.semanticCache.set(cacheKey, request, response);
+        }
+        if (this.config.cache.strategy === 'semantic')
+            return;
+        if (this.config.cache.adapter) {
+            await this.config.cache.adapter.set(cacheKey, response, ttl);
+            return;
+        }
+        this.cache.set(cacheKey, response, ttl);
+    }
+    enforceCostBudget(request) {
+        const maxEstimatedCost = request.maxEstimatedCost ?? this.config.costBudget?.maxEstimatedCost;
+        if (maxEstimatedCost === undefined)
+            return;
+        const estimate = estimateCost({
+            model: request.model,
+            inputTokens: this.optimizer.optimize(request).usage.afterTokens,
+            outputTokens: this.estimatedOutputTokens(request),
+            config: this.config,
+        });
+        try {
+            assertWithinCostBudget(estimate, maxEstimatedCost);
+        }
+        catch (error) {
+            if (this.config.costBudget?.onExceeded === 'warn') {
+                this.logger.warn(error instanceof Error ? error.message : String(error));
+                return;
+            }
+            throw error;
+        }
+    }
+    estimatedOutputTokens(request) {
+        return request.estimatedOutputTokens
+            ?? this.config.costBudget?.estimatedOutputTokens
+            ?? request.maxTokens
+            ?? 1000;
+    }
+}

package/dist/core/response-format.d.ts

@@ -0,0 +1,8 @@
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+import type { ResponseFormatConfig } from '../types/config.js';
+export declare class ResponseFormatError extends Error {
+    constructor(message: string);
+}
+export declare function applyResponseFormat(response: NexusResponse, config?: ResponseFormatConfig): NexusResponse;
+export declare function withResponseFormat(request: CompletionRequest, config?: ResponseFormatConfig): CompletionRequest;

package/dist/core/response-format.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+export class ResponseFormatError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResponseFormatError';
+    }
+}
+export function applyResponseFormat(response, config) {
+    if (!config || config.type === 'text')
+        return response;
+    let parsed;
+    try {
+        parsed = JSON.parse(response.content);
+    }
+    catch {
+        throw new ResponseFormatError('Expected model output to be valid JSON');
+    }
+    if (config.type === 'json_schema' && config.schema) {
+        if (isZodShape(config.schema)) {
+            const schema = z.object(config.schema).passthrough();
+            const result = schema.safeParse(parsed);
+            if (!result.success) {
+                throw new ResponseFormatError(`Model output failed JSON schema validation: ${result.error.message}`);
+            }
+        }
+        else {
+            const errors = validateJsonSchemaLike(parsed, config.schema);
+            if (errors.length) {
+                throw new ResponseFormatError(`Model output failed JSON schema validation: ${errors.join('; ')}`);
+            }
+        }
+    }
+    return response;
+}
+export function withResponseFormat(request, config) {
+    const responseFormat = request.responseFormat || config;
+    if (!responseFormat || responseFormat.type === 'text')
+        return request;
+    const requestResponseFormat = {
+        type: responseFormat.type,
+        schema: responseFormat.schema,
+    };
+    const schemaInstruction = responseFormat.type === 'json_schema' && responseFormat.schema
+        ? `The JSON must match this schema description: ${JSON.stringify(responseFormat.schema)}`
+        : 'Use a stable object shape with explicit keys.';
+    const systemMessage = {
+        role: 'system',
+        content: [
+            'Return only valid JSON.',
+            'Do not include markdown, prose, comments, or code fences.',
+            'If a value is unknown, use null or an explicit "unknown" value instead of inventing facts.',
+            schemaInstruction,
+        ].join('\n'),
+    };
+    return {
+        ...request,
+        temperature: request.temperature ?? 0,
+        topP: request.topP ?? 0.1,
+        responseFormat: requestResponseFormat,
+        messages: [systemMessage, ...request.messages],
+    };
+}
+function isZodShape(schema) {
+    return Object.values(schema).some((value) => {
+        return Boolean(value && typeof value === 'object' && 'safeParse' in value);
+    });
+}
+function validateJsonSchemaLike(value, schema, path = '$') {
+    const errors = [];
+    const type = schema.type;
+    if (typeof type === 'string' && !matchesJsonType(value, type)) {
+        errors.push(`${path} expected ${type}`);
+        return errors;
+    }
+    if (type === 'object' || schema.properties) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            errors.push(`${path} expected object`);
+            return errors;
+        }
+        const objectValue = value;
+        const required = Array.isArray(schema.required) ? schema.required : [];
+        for (const key of required) {
+            if (typeof key === 'string' && !(key in objectValue)) {
+                errors.push(`${path}.${key} is required`);
+            }
+        }
+        const properties = schema.properties;
+        if (properties && typeof properties === 'object' && !Array.isArray(properties)) {
+            for (const [key, childSchema] of Object.entries(properties)) {
+                if (key in objectValue && childSchema && typeof childSchema === 'object' && !Array.isArray(childSchema)) {
+                    errors.push(...validateJsonSchemaLike(objectValue[key], childSchema, `${path}.${key}`));
+                }
+            }
+        }
+    }
+    if (type === 'array' && Array.isArray(value) && schema.items && typeof schema.items === 'object') {
+        value.forEach((item, index) => {
+            errors.push(...validateJsonSchemaLike(item, schema.items, `${path}[${index}]`));
+        });
+    }
+    return errors;
+}
+function matchesJsonType(value, type) {
+    switch (type) {
+        case 'object':
+            return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+        case 'array':
+            return Array.isArray(value);
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+        case 'integer':
+            return typeof value === 'number' && Number.isFinite(value) && (type === 'number' || Number.isInteger(value));
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'null':
+            return value === null;
+        default:
+            return true;
+    }
+}

package/dist/core/secure-stream.d.ts

@@ -0,0 +1,3 @@
+import type { SecurityPipeline } from '../security/index.js';
+import type { NexusStream } from '../types/response.js';
+export declare function protectStreamOutput(stream: NexusStream, security: SecurityPipeline): NexusStream;

package/dist/core/secure-stream.js

@@ -0,0 +1,41 @@
+export function protectStreamOutput(stream, security) {
+    let aborted = false;
+    return {
+        async *[Symbol.asyncIterator]() {
+            let buffered = '';
+            for await (const chunk of stream) {
+                if (aborted)
+                    return;
+                if (chunk.type !== 'text' || !chunk.content) {
+                    yield chunk;
+                    continue;
+                }
+                buffered += chunk.content;
+                const pseudoResponse = {
+                    content: buffered,
+                    role: 'assistant',
+                    finishReason: 'stop',
+                    meta: {
+                        requestId: chunk.meta?.requestId || 'stream',
+                        providerUsed: chunk.meta?.providerUsed || 'unknown',
+                        modelUsed: chunk.meta?.modelUsed || 'unknown',
+                        latencyMs: chunk.meta?.latencyMs || 0,
+                        tokensInput: chunk.meta?.tokensInput || 0,
+                        tokensOutput: chunk.meta?.tokensOutput || 0,
+                        tokensSaved: chunk.meta?.tokensSaved || 0,
+                        estimatedCost: chunk.meta?.estimatedCost || '$0.00',
+                        cacheHit: chunk.meta?.cacheHit || false,
+                        guardrailsApplied: chunk.meta?.guardrailsApplied || [],
+                    },
+                };
+                const protectedOutput = security.protectOutput(pseudoResponse).value.content;
+                const safeDelta = protectedOutput.slice(Math.max(0, protectedOutput.length - chunk.content.length));
+                yield { ...chunk, content: safeDelta };
+            }
+        },
+        abort() {
+            aborted = true;
+            stream.abort();
+        },
+    };
+}

package/dist/core/streaming.d.ts

@@ -0,0 +1,4 @@
+import type { NexusStream, StreamChunk } from '../types/response.js';
+export declare function collectStream(stream: NexusStream): Promise<string>;
+export declare function mapStream(stream: NexusStream, mapChunk: (chunk: StreamChunk) => StreamChunk | Promise<StreamChunk>): AsyncGenerator<StreamChunk>;
+export declare function createTextStream(text: string): NexusStream;