@vistagenic/vista 0.2.16 → 0.3.0

package/dist/ai/agent.js

@@ -0,0 +1,385 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+exports.agent = agent;
+const base_1 = require("./providers/base");
+const memory_1 = require("./memory");
+const stream_1 = require("./stream");
+const observability_1 = require("./observability");
+const tool_1 = require("./tool");
+class Agent {
+    name;
+    model;
+    config;
+    toolsMap;
+    memory;
+    constructor(config) {
+        if (!config.name || typeof config.name !== 'string') {
+            throw new Error('Agent must have a valid string name');
+        }
+        this.name = config.name;
+        this.config = config;
+        this.model = (0, base_1.resolveModel)(config.model);
+        // Initialize tools lookup
+        this.toolsMap = new Map();
+        if (config.tools) {
+            for (const t of config.tools) {
+                if (t && typeof t.name === 'string') {
+                    this.toolsMap.set(t.name, t);
+                }
+            }
+        }
+        // Initialize memory store
+        if (config.memory === true) {
+            this.memory = memory_1.defaultMemoryStore;
+        }
+        else if (typeof config.memory === 'object' && config.memory !== null) {
+            this.memory = config.memory;
+        }
+    }
+    async resolveSystemPrompt() {
+        if (typeof this.config.systemPrompt === 'function') {
+            return await this.config.systemPrompt();
+        }
+        return this.config.systemPrompt;
+    }
+    normalizeInput(input) {
+        if (typeof input === 'string') {
+            return { messages: [{ role: 'user', content: input }] };
+        }
+        if (Array.isArray(input)) {
+            return { messages: [...input] };
+        }
+        const messages = input.messages ? [...input.messages] : [];
+        if (input.prompt) {
+            messages.push({ role: 'user', content: input.prompt });
+        }
+        return {
+            messages,
+            sessionId: input.sessionId,
+            abortSignal: input.abortSignal,
+        };
+    }
+    /**
+     * Run the agent through a multi-step reasoning and tool-execution loop.
+     */
+    async run(input) {
+        const { messages: incomingMessages, sessionId, abortSignal } = this.normalizeInput(input);
+        const telemetry = new observability_1.AgentTelemetry(this.config.observability);
+        telemetry.start();
+        // Load memory history if session provided
+        let conversationHistory = [];
+        if (this.memory && sessionId) {
+            const stored = await this.memory.get(sessionId);
+            conversationHistory = [...stored];
+        }
+        conversationHistory.push(...incomingMessages);
+        const systemPrompt = await this.resolveSystemPrompt();
+        const maxSteps = this.config.maxSteps || 5;
+        const toolsList = Array.from(this.toolsMap.values());
+        const steps = [];
+        let currentStep = 1;
+        let finalAnswer = '';
+        let finishReason = 'stop';
+        while (currentStep <= maxSteps) {
+            if (abortSignal?.aborted) {
+                throw new Error('Agent execution aborted');
+            }
+            telemetry.recordStepStart(currentStep);
+            const stepResult = await this.model.generateText({
+                messages: conversationHistory,
+                systemPrompt,
+                tools: toolsList.length > 0 ? toolsList : undefined,
+                temperature: this.config.temperature,
+                maxTokens: this.config.maxTokens,
+                abortSignal,
+            });
+            const stepRecord = {
+                stepNumber: currentStep,
+                prompt: [...conversationHistory],
+                text: stepResult.text,
+                toolCalls: stepResult.toolCalls,
+                usage: stepResult.usage,
+            };
+            // 1. If no tool calls requested, we have reached the final answer
+            if (!stepResult.toolCalls || stepResult.toolCalls.length === 0) {
+                finalAnswer = stepResult.text;
+                finishReason = stepResult.finishReason || 'stop';
+                conversationHistory.push({
+                    role: 'assistant',
+                    content: finalAnswer,
+                });
+                telemetry.recordStepFinish(stepRecord);
+                steps.push(stepRecord);
+                if (this.config.onStepFinish) {
+                    await this.config.onStepFinish(stepRecord);
+                }
+                break;
+            }
+            // 2. Model requested tool calls
+            conversationHistory.push({
+                role: 'assistant',
+                content: stepResult.text,
+                toolCalls: stepResult.toolCalls,
+            });
+            const toolResults = [];
+            for (const call of stepResult.toolCalls) {
+                telemetry.recordToolCall(call);
+                const registeredTool = this.toolsMap.get(call.name);
+                if (!registeredTool) {
+                    const errRes = {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: `Error: Tool "${call.name}" is not registered on agent "${this.name}".`,
+                        isError: true,
+                    };
+                    toolResults.push(errRes);
+                    telemetry.recordToolResult(errRes);
+                    conversationHistory.push({
+                        role: 'tool',
+                        name: call.name,
+                        toolCallId: call.id,
+                        content: errRes.result,
+                    });
+                    continue;
+                }
+                const toolCtx = {
+                    step: currentStep,
+                    messages: conversationHistory,
+                    agentName: this.name,
+                    abortSignal,
+                };
+                try {
+                    const args = typeof call.arguments === 'object' && call.arguments !== null
+                        ? call.arguments
+                        : typeof call.arguments === 'string'
+                            ? JSON.parse(call.arguments || '{}')
+                            : {};
+                    const rawOutput = await registeredTool.execute(args, toolCtx);
+                    const serializedOutput = typeof rawOutput === 'string' ? rawOutput : JSON.stringify(rawOutput);
+                    const successRes = {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: rawOutput,
+                    };
+                    toolResults.push(successRes);
+                    telemetry.recordToolResult(successRes);
+                    conversationHistory.push({
+                        role: 'tool',
+                        name: call.name,
+                        toolCallId: call.id,
+                        content: serializedOutput,
+                    });
+                }
+                catch (toolError) {
+                    const errMessage = toolError?.message || 'Tool execution failed';
+                    const failureRes = {
+                        toolCallId: call.id,
+                        name: call.name,
+                        result: `Error executing ${call.name}: ${errMessage}`,
+                        isError: true,
+                    };
+                    toolResults.push(failureRes);
+                    telemetry.recordToolResult(failureRes);
+                    conversationHistory.push({
+                        role: 'tool',
+                        name: call.name,
+                        toolCallId: call.id,
+                        content: failureRes.result,
+                    });
+                }
+            }
+            stepRecord.toolResults = toolResults;
+            telemetry.recordStepFinish(stepRecord);
+            steps.push(stepRecord);
+            if (this.config.onStepFinish) {
+                await this.config.onStepFinish(stepRecord);
+            }
+            currentStep++;
+            if (currentStep > maxSteps) {
+                finishReason = 'length';
+                finalAnswer =
+                    stepResult.text ||
+                        `Agent reached maximum step limit (${maxSteps}) before arriving at final answer.`;
+            }
+        }
+        // Save updated memory if configured
+        if (this.memory && sessionId) {
+            await this.memory.save(sessionId, conversationHistory);
+        }
+        const metrics = telemetry.finish();
+        return {
+            text: finalAnswer,
+            messages: conversationHistory,
+            steps,
+            usage: metrics.totalUsage,
+            finishReason,
+        };
+    }
+    /**
+     * Stream the agent's response, yielding real-time text deltas and tool events.
+     */
+    stream(input) {
+        const self = this;
+        const { messages: incomingMessages, sessionId, abortSignal } = this.normalizeInput(input);
+        async function* streamGenerator() {
+            // For streaming, we run the agent steps and yield incremental events
+            let conversationHistory = [];
+            if (self.memory && sessionId) {
+                const stored = await self.memory.get(sessionId);
+                conversationHistory = [...stored];
+            }
+            conversationHistory.push(...incomingMessages);
+            const systemPrompt = await self.resolveSystemPrompt();
+            const maxSteps = self.config.maxSteps || 5;
+            const toolsList = Array.from(self.toolsMap.values());
+            let currentStep = 1;
+            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            while (currentStep <= maxSteps) {
+                if (abortSignal?.aborted) {
+                    yield { type: 'error', error: 'Agent execution aborted' };
+                    return;
+                }
+                // Stream from the underlying model
+                const chunks = [];
+                let accumulatedText = '';
+                const toolCalls = [];
+                for await (const chunk of self.model.streamText({
+                    messages: conversationHistory,
+                    systemPrompt,
+                    tools: toolsList.length > 0 ? toolsList : undefined,
+                    temperature: self.config.temperature,
+                    maxTokens: self.config.maxTokens,
+                    abortSignal,
+                })) {
+                    if (chunk.type === 'text-delta' && chunk.textDelta) {
+                        accumulatedText += chunk.textDelta;
+                        yield chunk;
+                    }
+                    else if (chunk.type === 'tool-call' && chunk.toolCall) {
+                        toolCalls.push(chunk.toolCall);
+                        yield chunk;
+                    }
+                    else if (chunk.type === 'done' && chunk.usage) {
+                        totalUsage.promptTokens += chunk.usage.promptTokens;
+                        totalUsage.completionTokens += chunk.usage.completionTokens;
+                        totalUsage.totalTokens += chunk.usage.totalTokens;
+                    }
+                }
+                // If no tool calls, generation is complete
+                if (toolCalls.length === 0) {
+                    conversationHistory.push({
+                        role: 'assistant',
+                        content: accumulatedText,
+                    });
+                    yield { type: 'step-finish' };
+                    break;
+                }
+                // Handle tool calls
+                conversationHistory.push({
+                    role: 'assistant',
+                    content: accumulatedText,
+                    toolCalls,
+                });
+                for (const call of toolCalls) {
+                    const registeredTool = self.toolsMap.get(call.name);
+                    if (!registeredTool) {
+                        const errRes = {
+                            toolCallId: call.id,
+                            name: call.name,
+                            result: `Tool "${call.name}" not found`,
+                            isError: true,
+                        };
+                        yield { type: 'tool-result', toolResult: errRes };
+                        conversationHistory.push({
+                            role: 'tool',
+                            name: call.name,
+                            toolCallId: call.id,
+                            content: errRes.result,
+                        });
+                        continue;
+                    }
+                    try {
+                        const args = typeof call.arguments === 'object' && call.arguments !== null
+                            ? call.arguments
+                            : typeof call.arguments === 'string'
+                                ? JSON.parse(call.arguments || '{}')
+                                : {};
+                        const result = await registeredTool.execute(args, {
+                            step: currentStep,
+                            messages: conversationHistory,
+                            agentName: self.name,
+                            abortSignal,
+                        });
+                        const serialized = typeof result === 'string' ? result : JSON.stringify(result);
+                        yield {
+                            type: 'tool-result',
+                            toolResult: { toolCallId: call.id, name: call.name, result },
+                        };
+                        conversationHistory.push({
+                            role: 'tool',
+                            name: call.name,
+                            toolCallId: call.id,
+                            content: serialized,
+                        });
+                    }
+                    catch (err) {
+                        const errRes = {
+                            toolCallId: call.id,
+                            name: call.name,
+                            result: err?.message || 'Tool execution error',
+                            isError: true,
+                        };
+                        yield { type: 'tool-result', toolResult: errRes };
+                        conversationHistory.push({
+                            role: 'tool',
+                            name: call.name,
+                            toolCallId: call.id,
+                            content: errRes.result,
+                        });
+                    }
+                }
+                yield { type: 'step-finish' };
+                currentStep++;
+            }
+            if (self.memory && sessionId) {
+                await self.memory.save(sessionId, conversationHistory);
+            }
+            yield { type: 'done', usage: totalUsage };
+        }
+        return new stream_1.AgentStream(streamGenerator());
+    }
+    /**
+     * Composes this agent as a callable Tool for another agent (multi-agent hierarchy).
+     */
+    asTool(options) {
+        const toolName = options?.name || `ask_${this.name.toLowerCase().replace(/[^a-z0-9_]/g, '_')}`;
+        const toolDescription = options?.description ||
+            `Delegate a question, task, or request to the specialized ${this.name} agent.`;
+        return (0, tool_1.tool)({
+            name: toolName,
+            description: toolDescription,
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: `The query or instruction to give to the ${this.name} agent`,
+                    },
+                },
+                required: ['query'],
+            },
+            execute: async ({ query }) => {
+                const result = await this.run(query);
+                return result.text;
+            },
+        });
+    }
+}
+exports.Agent = Agent;
+/**
+ * Creates a Vista AI Agent instance.
+ */
+function agent(config) {
+    return new Agent(config);
+}

package/dist/ai/embeddings.d.ts

@@ -0,0 +1,11 @@
+export interface EmbedOptions {
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+}
+export declare function embedTexts(texts: string[], options?: EmbedOptions): Promise<number[][]>;
+export declare function embedText(text: string, options?: EmbedOptions): Promise<number[]>;
+export declare function createEmbeddings(options?: EmbedOptions): {
+    embedText: (text: string) => Promise<number[]>;
+    embedTexts: (texts: string[]) => Promise<number[][]>;
+};

package/dist/ai/embeddings.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embedTexts = embedTexts;
+exports.embedText = embedText;
+exports.createEmbeddings = createEmbeddings;
+const base_1 = require("./providers/base");
+function resolveEmbedTarget(options = {}) {
+    const identifier = (0, base_1.parseModelIdentifier)(options.model || 'openai:text-embedding-3-small');
+    const provider = identifier.provider;
+    const modelName = identifier.modelName || 'text-embedding-3-small';
+    if (provider === 'nvidia' || provider === 'nim') {
+        return {
+            modelName,
+            baseURL: (options.baseURL ||
+                process.env.NVIDIA_BASE_URL ||
+                process.env.NIM_BASE_URL ||
+                'https://integrate.api.nvidia.com/v1').replace(/\/+$/, ''),
+            apiKey: options.apiKey || process.env.NVIDIA_API_KEY || process.env.NIM_API_KEY || '',
+        };
+    }
+    if (provider === 'groq') {
+        return {
+            modelName,
+            baseURL: (options.baseURL || process.env.GROQ_BASE_URL || 'https://api.groq.com/openai/v1').replace(/\/+$/, ''),
+            apiKey: options.apiKey || process.env.GROQ_API_KEY || '',
+        };
+    }
+    if (provider === 'ollama') {
+        return {
+            modelName,
+            baseURL: (options.baseURL || process.env.OLLAMA_BASE_URL || 'http://localhost:11434/v1').replace(/\/+$/, ''),
+            apiKey: options.apiKey || 'ollama',
+        };
+    }
+    return {
+        modelName,
+        baseURL: (options.baseURL || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1').replace(/\/+$/, ''),
+        apiKey: options.apiKey || process.env.OPENAI_API_KEY || '',
+    };
+}
+async function embedTexts(texts, options = {}) {
+    const target = resolveEmbedTarget(options);
+    const response = await fetch(`${target.baseURL}/embeddings`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(target.apiKey ? { Authorization: `Bearer ${target.apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+            model: target.modelName,
+            input: texts,
+        }),
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new Error(`Embedding request failed (${response.status}): ${detail || response.statusText}`);
+    }
+    const json = (await response.json());
+    const rows = [...(json.data || [])].sort((left, right) => (left.index || 0) - (right.index || 0));
+    return rows.map((row) => row.embedding || []);
+}
+async function embedText(text, options = {}) {
+    const [vector] = await embedTexts([text], options);
+    return vector || [];
+}
+function createEmbeddings(options = {}) {
+    return {
+        embedText: (text) => embedText(text, options),
+        embedTexts: (texts) => embedTexts(texts, options),
+    };
+}

package/dist/ai/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export * from './tool';
+export * from './agent';
+export * from './memory';
+export * from './stream';
+export * from './rag';
+export * from './embeddings';
+export * from './observability';
+export * from './providers';
+export * from './react';

package/dist/ai/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./tool"), exports);
+__exportStar(require("./agent"), exports);
+__exportStar(require("./memory"), exports);
+__exportStar(require("./stream"), exports);
+__exportStar(require("./rag"), exports);
+__exportStar(require("./embeddings"), exports);
+__exportStar(require("./observability"), exports);
+__exportStar(require("./providers"), exports);
+__exportStar(require("./react"), exports);

package/dist/ai/memory.d.ts

@@ -0,0 +1,16 @@
+import type { AgentMemory, Message } from './types';
+export interface InMemoryStoreOptions {
+    maxMessages?: number;
+    ttlMs?: number;
+}
+export declare class InMemoryStore implements AgentMemory {
+    private sessions;
+    private maxMessages;
+    private ttlMs?;
+    constructor(options?: InMemoryStoreOptions);
+    get(sessionId: string): Promise<Message[]>;
+    save(sessionId: string, messages: Message[]): Promise<void>;
+    clear(sessionId: string): Promise<void>;
+    private cleanExpired;
+}
+export declare const defaultMemoryStore: InMemoryStore;

package/dist/ai/memory.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultMemoryStore = exports.InMemoryStore = void 0;
+class InMemoryStore {
+    sessions = new Map();
+    maxMessages;
+    ttlMs;
+    constructor(options = {}) {
+        this.maxMessages = options.maxMessages || 100;
+        this.ttlMs = options.ttlMs;
+    }
+    async get(sessionId) {
+        this.cleanExpired();
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return [];
+        return [...session.messages];
+    }
+    async save(sessionId, messages) {
+        const trimmed = messages.slice(-this.maxMessages);
+        const expiresAt = this.ttlMs ? Date.now() + this.ttlMs : Infinity;
+        this.sessions.set(sessionId, { messages: trimmed, expiresAt });
+    }
+    async clear(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    cleanExpired() {
+        if (!this.ttlMs)
+            return;
+        const now = Date.now();
+        for (const [id, session] of this.sessions.entries()) {
+            if (session.expiresAt <= now) {
+                this.sessions.delete(id);
+            }
+        }
+    }
+}
+exports.InMemoryStore = InMemoryStore;
+exports.defaultMemoryStore = new InMemoryStore();

package/dist/ai/observability.d.ts

@@ -0,0 +1,21 @@
+import type { AgentStep, ObservabilityHandler, TokenUsage, ToolCall, ToolResult } from './types';
+export interface ObservabilityMetrics {
+    totalSteps: number;
+    totalDurationMs: number;
+    totalUsage: TokenUsage;
+    toolCallsCount: number;
+}
+export declare class AgentTelemetry {
+    private startTime;
+    private endTime;
+    private steps;
+    private handler?;
+    constructor(handler?: ObservabilityHandler | boolean);
+    start(): void;
+    recordStepStart(stepNumber: number): void;
+    recordToolCall(call: ToolCall): void;
+    recordToolResult(result: ToolResult): void;
+    recordStepFinish(step: AgentStep): void;
+    recordError(error: Error): void;
+    finish(): ObservabilityMetrics;
+}

package/dist/ai/observability.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTelemetry = void 0;
+class AgentTelemetry {
+    startTime = 0;
+    endTime = 0;
+    steps = [];
+    handler;
+    constructor(handler) {
+        if (typeof handler === 'object' && handler !== null) {
+            this.handler = handler;
+        }
+        else if (handler === true) {
+            // Default console logger
+            this.handler = {
+                onStepStart: (step) => console.log(`[vista:ai] Starting step ${step}...`),
+                onToolCall: (call) => console.log(`[vista:ai] Tool call: ${call.name}(${JSON.stringify(call.arguments)})`),
+                onToolResult: (res) => console.log(`[vista:ai] Tool result: ${res.name} -> ${JSON.stringify(res.result).slice(0, 80)}`),
+                onError: (err) => console.error(`[vista:ai] Error:`, err),
+            };
+        }
+    }
+    start() {
+        this.startTime = Date.now();
+    }
+    recordStepStart(stepNumber) {
+        this.handler?.onStepStart?.(stepNumber);
+    }
+    recordToolCall(call) {
+        this.handler?.onToolCall?.(call);
+    }
+    recordToolResult(result) {
+        this.handler?.onToolResult?.(result);
+    }
+    recordStepFinish(step) {
+        this.steps.push(step);
+        this.handler?.onStepFinish?.(step);
+    }
+    recordError(error) {
+        this.handler?.onError?.(error);
+    }
+    finish() {
+        this.endTime = Date.now();
+        const duration = this.endTime - this.startTime;
+        const totalUsage = {
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+        };
+        let toolCallsCount = 0;
+        for (const step of this.steps) {
+            if (step.usage) {
+                totalUsage.promptTokens += step.usage.promptTokens;
+                totalUsage.completionTokens += step.usage.completionTokens;
+                totalUsage.totalTokens += step.usage.totalTokens;
+            }
+            if (step.toolCalls) {
+                toolCallsCount += step.toolCalls.length;
+            }
+        }
+        return {
+            totalSteps: this.steps.length,
+            totalDurationMs: duration,
+            totalUsage,
+            toolCallsCount,
+        };
+    }
+}
+exports.AgentTelemetry = AgentTelemetry;

package/dist/ai/providers/anthropic.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageModel, ModelOptions } from '../types';
+export declare function createAnthropicModel(options: ModelOptions): LanguageModel;