overai 1.4.0

package/dist/cli/commands/tools.js

@@ -0,0 +1,576 @@
+"use strict";
+/**
+ * Tools command - List, manage, and test AI SDK tools
+ *
+ * Subcommands:
+ *   list     - List all available tools
+ *   info     - Get detailed info about a tool
+ *   doctor   - Check tool dependencies and env vars
+ *   example  - Show usage example for a tool
+ *   add      - Register a custom tool from npm/local
+ *   test     - Test a tool (dry-run or live)
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execute = execute;
+const decorator_1 = require("../../tools/decorator");
+const registry_1 = require("../../tools/registry/registry");
+const tools_1 = require("../../tools/tools");
+const builtins_1 = require("../../tools/builtins");
+const cli_spec_1 = require("../spec/cli-spec");
+const pretty_logger_1 = require("../../utils/pretty-logger");
+function outputJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function formatSuccess(data) {
+    return { success: true, data };
+}
+function formatError(code, message) {
+    return { success: false, error: { code, message } };
+}
+const ERROR_CODES = {
+    INVALID_ARGS: 'INVALID_ARGS',
+    MISSING_ARG: 'MISSING_ARG',
+    TOOL_NOT_FOUND: 'TOOL_NOT_FOUND',
+    RUNTIME_ERROR: 'RUNTIME_ERROR',
+};
+async function printKeyValue(entries) {
+    for (const [key, value] of Object.entries(entries)) {
+        await pretty_logger_1.PrettyLogger.plain(`  ${key}: ${value}`);
+    }
+}
+// Ensure built-in tools are registered
+let builtinsRegistered = false;
+function ensureBuiltinsRegistered() {
+    if (!builtinsRegistered) {
+        (0, tools_1.registerBuiltinTools)();
+        builtinsRegistered = true;
+    }
+}
+async function execute(args, options) {
+    const subcommand = args[0] || 'list';
+    const outputFormat = options.json ? 'json' : (options.output || 'pretty');
+    switch (subcommand) {
+        case 'list':
+            await listTools(options, outputFormat);
+            break;
+        case 'info':
+            await toolInfo(args.slice(1), options, outputFormat);
+            break;
+        case 'doctor':
+            await toolDoctor(options, outputFormat);
+            break;
+        case 'example':
+            await toolExample(args.slice(1), options, outputFormat);
+            break;
+        case 'add':
+            await toolAdd(args.slice(1), options, outputFormat);
+            break;
+        case 'test':
+            await toolTest(args.slice(1), options, outputFormat);
+            break;
+        default:
+            if (outputFormat === 'json') {
+                outputJson(formatError(ERROR_CODES.INVALID_ARGS, `Unknown subcommand: ${subcommand}`));
+            }
+            else {
+                await pretty_logger_1.PrettyLogger.error(`Unknown subcommand: ${subcommand}`);
+                await pretty_logger_1.PrettyLogger.plain('Available subcommands: list, info, doctor, example, add, test');
+            }
+            process.exit(cli_spec_1.EXIT_CODES.INVALID_ARGUMENTS);
+    }
+}
+async function listTools(options, outputFormat) {
+    ensureBuiltinsRegistered();
+    // Get all built-in tool metadata
+    const builtinMetadata = await (0, builtins_1.getAllBuiltinMetadata)();
+    // Get registered tools from decorator registry (legacy)
+    const decoratorRegistry = (0, decorator_1.getRegistry)();
+    const registeredTools = decoratorRegistry.list();
+    // Filter by tag if specified
+    let filteredMetadata = builtinMetadata;
+    if (options.tag) {
+        filteredMetadata = builtinMetadata.filter(m => m.tags.includes(options.tag));
+    }
+    if (outputFormat === 'json') {
+        outputJson(formatSuccess({
+            builtinTools: filteredMetadata.map(m => ({
+                id: m.id,
+                name: m.displayName,
+                description: m.description,
+                tags: m.tags,
+                packageName: m.packageName,
+                requiredEnv: m.requiredEnv,
+                capabilities: m.capabilities,
+            })),
+            registeredTools: registeredTools.map((t) => ({
+                name: t.name,
+                description: t.description,
+            })),
+            count: filteredMetadata.length + registeredTools.length
+        }));
+    }
+    else {
+        await pretty_logger_1.PrettyLogger.heading('AI SDK Tools Registry');
+        await pretty_logger_1.PrettyLogger.plain('\nBuilt-in Tools:');
+        for (const meta of filteredMetadata) {
+            const tags = meta.tags.slice(0, 3).join(', ');
+            await pretty_logger_1.PrettyLogger.plain(`  • ${meta.id} (${meta.displayName})`);
+            await pretty_logger_1.PrettyLogger.dim(`    ${meta.description}`);
+            await pretty_logger_1.PrettyLogger.dim(`    Tags: ${tags} | Package: ${meta.packageName}`);
+        }
+        if (registeredTools.length > 0) {
+            await pretty_logger_1.PrettyLogger.newline();
+            await pretty_logger_1.PrettyLogger.plain('Custom Registered Tools:');
+            for (const tool of registeredTools) {
+                await pretty_logger_1.PrettyLogger.plain(`  • ${tool.name}`);
+                if (tool.description) {
+                    await pretty_logger_1.PrettyLogger.dim(`    ${tool.description}`);
+                }
+            }
+        }
+        await pretty_logger_1.PrettyLogger.newline();
+        await pretty_logger_1.PrettyLogger.info(`Total: ${filteredMetadata.length + registeredTools.length} tools`);
+        await pretty_logger_1.PrettyLogger.dim('\nUse "overai tools info <id>" for details');
+        await pretty_logger_1.PrettyLogger.dim('Use "overai tools doctor" to check dependencies');
+    }
+}
+async function toolInfo(args, options, outputFormat) {
+    ensureBuiltinsRegistered();
+    const toolId = args[0];
+    if (!toolId) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.MISSING_ARG, 'Please provide a tool ID'));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error('Please provide a tool ID');
+        }
+        process.exit(cli_spec_1.EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    // Look for tool in built-in metadata
+    const builtinMetadata = await (0, builtins_1.getAllBuiltinMetadata)();
+    const metadata = builtinMetadata.find(m => m.id === toolId);
+    // Also check decorator registry
+    const decoratorRegistry = (0, decorator_1.getRegistry)();
+    const registeredTool = decoratorRegistry.get(toolId);
+    if (!metadata && !registeredTool) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.TOOL_NOT_FOUND, `Tool not found: ${toolId}`));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error(`Tool not found: ${toolId}`);
+            await pretty_logger_1.PrettyLogger.dim('Use "overai tools list" to see available tools');
+        }
+        process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+    }
+    if (outputFormat === 'json') {
+        outputJson(formatSuccess({
+            tool: metadata ? {
+                id: metadata.id,
+                name: metadata.displayName,
+                description: metadata.description,
+                tags: metadata.tags,
+                packageName: metadata.packageName,
+                requiredEnv: metadata.requiredEnv,
+                optionalEnv: metadata.optionalEnv,
+                install: metadata.install,
+                capabilities: metadata.capabilities,
+                docsSlug: metadata.docsSlug,
+            } : {
+                name: registeredTool.name,
+                description: registeredTool.description,
+                type: 'registered'
+            }
+        }));
+    }
+    else {
+        if (metadata) {
+            await pretty_logger_1.PrettyLogger.heading(`Tool: ${metadata.displayName}`);
+            await printKeyValue({
+                'ID': metadata.id,
+                'Description': metadata.description,
+                'Package': metadata.packageName,
+                'Tags': metadata.tags.join(', '),
+                'Docs': `https://docs.praison.ai/js/${metadata.docsSlug}`,
+            });
+            await pretty_logger_1.PrettyLogger.newline();
+            await pretty_logger_1.PrettyLogger.plain('Required Environment Variables:');
+            if (metadata.requiredEnv.length > 0) {
+                for (const env of metadata.requiredEnv) {
+                    const isSet = !!process.env[env];
+                    await pretty_logger_1.PrettyLogger.plain(`  ${isSet ? '✓' : '✗'} ${env}`);
+                }
+            }
+            else {
+                await pretty_logger_1.PrettyLogger.dim('  None');
+            }
+            await pretty_logger_1.PrettyLogger.newline();
+            await pretty_logger_1.PrettyLogger.plain('Installation:');
+            await pretty_logger_1.PrettyLogger.plain(`  ${metadata.install.npm}`);
+            await pretty_logger_1.PrettyLogger.newline();
+            await pretty_logger_1.PrettyLogger.plain('Capabilities:');
+            const caps = Object.entries(metadata.capabilities)
+                .filter(([_, v]) => v)
+                .map(([k]) => k);
+            await pretty_logger_1.PrettyLogger.plain(`  ${caps.join(', ') || 'None specified'}`);
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.heading(`Tool: ${registeredTool.name}`);
+            await printKeyValue({
+                'Name': registeredTool.name,
+                'Type': 'Custom Registered',
+                'Description': registeredTool.description || 'No description'
+            });
+        }
+    }
+}
+async function toolDoctor(options, outputFormat) {
+    ensureBuiltinsRegistered();
+    const builtinMetadata = await (0, builtins_1.getAllBuiltinMetadata)();
+    const results = [];
+    for (const meta of builtinMetadata) {
+        // Check env vars
+        const missingEnv = meta.requiredEnv.filter(env => !process.env[env]);
+        // Check if package is installed (check node_modules)
+        let installed = false;
+        try {
+            // First try require.resolve for CJS packages
+            require.resolve(meta.packageName);
+            installed = true;
+        }
+        catch {
+            // For ESM packages, check if the package directory exists
+            try {
+                const path = await Promise.resolve().then(() => __importStar(require('path')));
+                const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+                const packagePath = path.join(process.cwd(), 'node_modules', ...meta.packageName.split('/'));
+                installed = fs.existsSync(packagePath);
+            }
+            catch {
+                installed = false;
+            }
+        }
+        results.push({
+            id: meta.id,
+            name: meta.displayName,
+            installed,
+            missingEnv,
+            installCmd: installed ? undefined : meta.install.npm,
+        });
+    }
+    const allGood = results.every(r => r.installed && r.missingEnv.length === 0);
+    const installedCount = results.filter(r => r.installed).length;
+    const envIssues = results.filter(r => r.missingEnv.length > 0).length;
+    if (outputFormat === 'json') {
+        outputJson(formatSuccess({
+            status: allGood ? 'healthy' : 'issues_found',
+            summary: {
+                total: results.length,
+                installed: installedCount,
+                notInstalled: results.length - installedCount,
+                missingEnvVars: envIssues,
+            },
+            tools: results,
+        }));
+    }
+    else {
+        await pretty_logger_1.PrettyLogger.heading('Tools Health Check');
+        await pretty_logger_1.PrettyLogger.newline();
+        await pretty_logger_1.PrettyLogger.plain(`Summary: ${installedCount}/${results.length} packages installed, ${envIssues} with missing env vars`);
+        await pretty_logger_1.PrettyLogger.newline();
+        for (const result of results) {
+            const status = result.installed && result.missingEnv.length === 0 ? '✓' : '✗';
+            await pretty_logger_1.PrettyLogger.plain(`${status} ${result.id} (${result.name})`);
+            if (!result.installed) {
+                await pretty_logger_1.PrettyLogger.dim(`    Package not installed: ${result.installCmd}`);
+            }
+            if (result.missingEnv.length > 0) {
+                await pretty_logger_1.PrettyLogger.dim(`    Missing env vars: ${result.missingEnv.join(', ')}`);
+            }
+        }
+        await pretty_logger_1.PrettyLogger.newline();
+        if (allGood) {
+            await pretty_logger_1.PrettyLogger.info('All tools are ready to use!');
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.warning('Some tools need attention. Install packages and set env vars as needed.');
+        }
+    }
+}
+async function toolExample(args, options, outputFormat) {
+    const toolId = args[0];
+    if (!toolId) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.MISSING_ARG, 'Please provide a tool ID'));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error('Please provide a tool ID');
+        }
+        process.exit(cli_spec_1.EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    // Tool examples
+    const examples = {
+        'code-execution': `
+import { Agent, tools } from 'overai';
+
+const agent = new Agent({
+  name: 'CodeRunner',
+  instructions: 'You can execute Python code to solve problems.',
+  tools: [tools.codeExecution()],
+});
+
+const result = await agent.run('Calculate the factorial of 10');
+console.log(result.text);
+`,
+        'tavily': `
+import { Agent, tools } from 'overai';
+
+const agent = new Agent({
+  name: 'Researcher',
+  instructions: 'Search the web for information.',
+  tools: [tools.tavily()],
+});
+
+const result = await agent.run('What are the latest AI developments?');
+console.log(result.text);
+`,
+        'exa': `
+import { Agent, tools } from 'overai';
+
+const agent = new Agent({
+  name: 'WebSearcher',
+  instructions: 'Search the web using semantic search.',
+  tools: [tools.exa()],
+});
+
+const result = await agent.run('Find AI companies in Europe');
+console.log(result.text);
+`,
+        'superagent': `
+import { Agent, tools } from 'overai';
+
+const agent = new Agent({
+  name: 'SecureAgent',
+  instructions: 'Process text securely.',
+  tools: [
+    tools.guard(),   // Check for prompt injection
+    tools.redact(),  // Remove PII
+    tools.verify(),  // Verify claims
+  ],
+});
+
+const result = await agent.run('Check this text for security issues');
+console.log(result.text);
+`,
+        'valyu': `
+import { Agent, tools } from 'overai';
+
+const agent = new Agent({
+  name: 'FinanceResearcher',
+  instructions: 'Research financial data.',
+  tools: [
+    tools.valyuFinanceSearch(),
+    tools.valyuSecSearch(),
+  ],
+});
+
+const result = await agent.run('What is Apple stock price trend?');
+console.log(result.text);
+`,
+    };
+    const example = examples[toolId];
+    if (!example) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.TOOL_NOT_FOUND, `No example for tool: ${toolId}`));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error(`No example available for: ${toolId}`);
+            await pretty_logger_1.PrettyLogger.dim(`Available examples: ${Object.keys(examples).join(', ')}`);
+        }
+        process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+    }
+    if (outputFormat === 'json') {
+        outputJson(formatSuccess({ toolId, example: example.trim() }));
+    }
+    else {
+        await pretty_logger_1.PrettyLogger.heading(`Example: ${toolId}`);
+        await pretty_logger_1.PrettyLogger.plain(example);
+    }
+}
+async function toolAdd(args, options, outputFormat) {
+    const packageOrPath = args[0];
+    if (!packageOrPath) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.MISSING_ARG, 'Please provide a package name or path'));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error('Please provide a package name or path');
+            await pretty_logger_1.PrettyLogger.dim('Usage: overai tools add <package-name>');
+            await pretty_logger_1.PrettyLogger.dim('       overai tools add ./path/to/tool.js');
+        }
+        process.exit(cli_spec_1.EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    try {
+        const { registerNpmTool, registerLocalTool } = await Promise.resolve().then(() => __importStar(require('../../tools/builtins/custom')));
+        const isLocalPath = packageOrPath.startsWith('./') || packageOrPath.startsWith('/');
+        const tool = isLocalPath
+            ? await registerLocalTool(packageOrPath)
+            : await registerNpmTool(packageOrPath);
+        if (outputFormat === 'json') {
+            outputJson(formatSuccess({
+                registered: true,
+                tool: {
+                    name: tool.name,
+                    description: tool.description,
+                    source: isLocalPath ? 'local' : 'npm',
+                }
+            }));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.info(`Successfully registered tool: ${tool.name}`);
+            await pretty_logger_1.PrettyLogger.dim(`Description: ${tool.description}`);
+        }
+    }
+    catch (error) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.RUNTIME_ERROR, `Failed to register tool: ${error}`));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error(`Failed to register tool: ${error}`);
+        }
+        process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+    }
+}
+async function toolTest(args, options, outputFormat) {
+    const toolId = args[0];
+    if (!toolId) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.MISSING_ARG, 'Please provide a tool ID'));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error('Please provide a tool ID');
+        }
+        process.exit(cli_spec_1.EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    ensureBuiltinsRegistered();
+    const registry = (0, registry_1.getToolsRegistry)();
+    const metadata = registry.getMetadata(toolId);
+    if (!metadata) {
+        if (outputFormat === 'json') {
+            outputJson(formatError(ERROR_CODES.TOOL_NOT_FOUND, `Tool not found: ${toolId}`));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.error(`Tool not found: ${toolId}`);
+        }
+        process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+    }
+    // Check dependencies
+    const missingEnv = metadata.requiredEnv.filter(env => !process.env[env]);
+    if (missingEnv.length > 0 && !options.live) {
+        if (outputFormat === 'json') {
+            outputJson(formatSuccess({
+                toolId,
+                status: 'dry_run',
+                message: 'Dry run completed. Missing env vars for live test.',
+                missingEnv,
+            }));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.info(`Dry run for ${toolId}:`);
+            await pretty_logger_1.PrettyLogger.plain(`  Tool ID: ${metadata.id}`);
+            await pretty_logger_1.PrettyLogger.plain(`  Package: ${metadata.packageName}`);
+            await pretty_logger_1.PrettyLogger.warning(`  Missing env vars: ${missingEnv.join(', ')}`);
+            await pretty_logger_1.PrettyLogger.dim('\nUse --live flag to run actual test (requires env vars)');
+        }
+        return;
+    }
+    if (options.live) {
+        if (missingEnv.length > 0) {
+            if (outputFormat === 'json') {
+                outputJson(formatError(ERROR_CODES.MISSING_ARG, `Missing required env vars: ${missingEnv.join(', ')}`));
+            }
+            else {
+                await pretty_logger_1.PrettyLogger.error(`Cannot run live test. Missing env vars: ${missingEnv.join(', ')}`);
+            }
+            process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+        }
+        try {
+            const tool = registry.create(toolId);
+            await pretty_logger_1.PrettyLogger.info(`Live test for ${toolId}...`);
+            // Simple test execution
+            const testInput = { query: 'test' };
+            const result = await tool.execute(testInput);
+            if (outputFormat === 'json') {
+                outputJson(formatSuccess({
+                    toolId,
+                    status: 'success',
+                    result,
+                }));
+            }
+            else {
+                await pretty_logger_1.PrettyLogger.info('Test passed!');
+                await pretty_logger_1.PrettyLogger.plain(`Result: ${JSON.stringify(result, null, 2)}`);
+            }
+        }
+        catch (error) {
+            if (outputFormat === 'json') {
+                outputJson(formatError(ERROR_CODES.RUNTIME_ERROR, `Test failed: ${error}`));
+            }
+            else {
+                await pretty_logger_1.PrettyLogger.error(`Test failed: ${error}`);
+            }
+            process.exit(cli_spec_1.EXIT_CODES.RUNTIME_ERROR);
+        }
+    }
+    else {
+        if (outputFormat === 'json') {
+            outputJson(formatSuccess({
+                toolId,
+                status: 'dry_run',
+                message: 'Dry run completed successfully.',
+                metadata: {
+                    id: metadata.id,
+                    package: metadata.packageName,
+                    envVars: metadata.requiredEnv,
+                }
+            }));
+        }
+        else {
+            await pretty_logger_1.PrettyLogger.info(`Dry run for ${toolId}: OK`);
+            await pretty_logger_1.PrettyLogger.plain(`  Tool is registered and ready`);
+            await pretty_logger_1.PrettyLogger.dim('\nUse --live flag to run actual API test');
+        }
+    }
+}

package/dist/cli/commands/vector.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Vector command - Vector store management
+ */
+export interface VectorOptions {
+    verbose?: boolean;
+    output?: 'json' | 'text' | 'pretty';
+    json?: boolean;
+    store?: string;
+}
+export declare function execute(args: string[], options: VectorOptions): Promise<void>;