@spec2tools/core 0.1.0

package/dist/cli.js

@@ -0,0 +1,315 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import * as readline from 'readline';
+import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+import { AuthManager } from './auth-manager.js';
+import { createExecutableTools, executeToolByName } from './tool-executor.js';
+import { Agent } from './agent.js';
+import { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
+const VERSION = '0.1.5';
+export function createCLI() {
+    const program = new Command();
+    program
+        .name('spec2tools')
+        .description('Dynamically convert OpenAPI specs into AI agent tools at runtime')
+        .version(VERSION);
+    program
+        .command('start')
+        .description('Start the agent with an OpenAPI specification')
+        .requiredOption('-s, --spec <path>', 'Path or URL to OpenAPI specification')
+        .option('--no-auth', 'Skip authentication even if required by spec')
+        .option('--token <token>', 'Provide access token directly')
+        .action(async (options) => {
+        await startAgent(options);
+    });
+    return program;
+}
+async function startAgent(options) {
+    const spinner = ora();
+    try {
+        // Load OpenAPI spec
+        spinner.start('Loading OpenAPI specification...');
+        const spec = await loadOpenAPISpec(options.spec);
+        spinner.succeed(`Loaded: ${spec.info.title} v${spec.info.version}`);
+        // Extract base URL
+        const baseUrl = extractBaseUrl(spec);
+        console.log(chalk.dim(`Base URL: ${baseUrl}`));
+        // Extract auth config
+        const authConfig = extractAuthConfig(spec);
+        // Parse operations
+        spinner.start('Parsing operations...');
+        const toolDefs = parseOperations(spec);
+        spinner.succeed(`Found ${toolDefs.length} operations`);
+        if (toolDefs.length === 0) {
+            console.log(chalk.yellow('No operations found in the specification.'));
+            return;
+        }
+        // Initialize auth manager
+        const authManager = new AuthManager(authConfig);
+        // Handle authentication
+        if (options.token) {
+            authManager.setAccessToken(options.token);
+            console.log(chalk.green('Using provided access token'));
+        }
+        else if (options.auth && authManager.requiresAuth()) {
+            console.log(chalk.yellow(`\nAuthentication required (${authConfig.type})`));
+            await authManager.authenticate();
+            console.log(chalk.green('Authentication successful!'));
+        }
+        else if (authManager.requiresAuth()) {
+            console.log(chalk.yellow('\nWarning: API requires authentication but --no-auth was specified'));
+        }
+        // Create executable tools
+        const tools = createExecutableTools(toolDefs, baseUrl, authManager);
+        // Initialize session
+        const session = {
+            baseUrl,
+            tools,
+            authConfig,
+            accessToken: authManager.getAccessToken(),
+        };
+        // Start chat loop
+        await startChatLoop(session);
+    }
+    catch (error) {
+        spinner.fail();
+        if (error instanceof UnsupportedSchemaError) {
+            console.error(chalk.red(`\nSchema Error: ${error.message}`));
+            console.error(chalk.dim('This OpenAPI specification contains features that are not supported.'));
+        }
+        else if (error instanceof AuthenticationError) {
+            console.error(chalk.red(`\nAuth Error: ${error.message}`));
+        }
+        else if (error instanceof SpecLoadError) {
+            console.error(chalk.red(`\nSpec Error: ${error.message}`));
+        }
+        else {
+            console.error(chalk.red(`\nError: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        process.exit(1);
+    }
+}
+async function startChatLoop(session) {
+    // Initialize agent
+    const agent = new Agent({ tools: session.tools });
+    console.log(chalk.bold('\n--- Spec2Tools ---'));
+    console.log(chalk.dim('Type your message or use special commands:'));
+    console.log(chalk.dim('  /tools  - List available tools'));
+    console.log(chalk.dim('  /call   - Call a tool directly'));
+    console.log(chalk.dim('  /schema - Show tool schema'));
+    console.log(chalk.dim('  /help   - Show help'));
+    console.log(chalk.dim('  /exit   - Exit the CLI'));
+    console.log('');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const prompt = () => {
+        rl.question(chalk.cyan('> '), async (input) => {
+            const trimmedInput = input.trim();
+            if (!trimmedInput) {
+                prompt();
+                return;
+            }
+            // Pause readline during async operations to prevent corruption
+            rl.pause();
+            try {
+                await handleInput(trimmedInput, session, agent);
+            }
+            catch (error) {
+                console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+            }
+            finally {
+                rl.resume();
+                prompt();
+            }
+        });
+    };
+    rl.on('close', () => {
+        console.log(chalk.dim('\nGoodbye!'));
+        process.exit(0);
+    });
+    prompt();
+}
+async function handleInput(input, session, agent) {
+    // Handle special commands
+    if (input.startsWith('/')) {
+        await handleCommand(input, session, agent);
+        return;
+    }
+    // Regular chat message
+    const spinner = ora('Thinking...').start();
+    try {
+        const response = await agent.chat(input);
+        spinner.stop();
+        console.log(chalk.white('\n' + response + '\n'));
+    }
+    catch (error) {
+        spinner.fail('Failed to get response');
+        throw error;
+    }
+}
+async function handleCommand(input, session, agent) {
+    const parts = input.slice(1).split(/\s+/);
+    const command = parts[0].toLowerCase();
+    const args = parts.slice(1);
+    switch (command) {
+        case 'tools':
+            listTools(session.tools);
+            break;
+        case 'call':
+            await callTool(session.tools, args);
+            break;
+        case 'schema':
+            showSchema(session.tools, args[0]);
+            break;
+        case 'help':
+            showHelp();
+            break;
+        case 'exit':
+        case 'quit':
+            console.log(chalk.dim('Goodbye!'));
+            process.exit(0);
+        case 'clear':
+            agent.clearHistory();
+            console.log(chalk.dim('Conversation history cleared.'));
+            break;
+        default:
+            console.log(chalk.yellow(`Unknown command: ${command}`));
+            console.log(chalk.dim('Type /help for available commands.'));
+    }
+}
+function listTools(tools) {
+    console.log(chalk.bold('\nAvailable tools:'));
+    tools.forEach((tool, index) => {
+        const signature = formatToolSignature(tool);
+        console.log(chalk.cyan(`${index + 1}. ${signature}`));
+        console.log(chalk.dim(`   ${tool.description}`));
+    });
+    console.log('');
+}
+async function callTool(tools, args) {
+    if (args.length === 0) {
+        console.log(chalk.yellow('Usage: /call <toolName> [--param value ...]'));
+        console.log(chalk.dim('Example: /call createUser --name "John" --email "john@example.com"'));
+        return;
+    }
+    const toolName = args[0];
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        console.log(chalk.red(`Tool not found: ${toolName}`));
+        console.log(chalk.dim('Use /tools to see available tools.'));
+        return;
+    }
+    // Parse remaining args as --key value pairs
+    const params = parseCallArgs(args.slice(1));
+    const spinner = ora(`Calling ${toolName}...`).start();
+    try {
+        const result = await executeToolByName(tools, toolName, params);
+        spinner.succeed(`${toolName} completed`);
+        console.log(chalk.white('\nResult:'));
+        console.log(JSON.stringify(result, null, 2));
+        console.log('');
+    }
+    catch (error) {
+        spinner.fail(`${toolName} failed`);
+        if (error instanceof ToolExecutionError) {
+            console.error(chalk.red(error.message));
+        }
+        else {
+            console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}
+function parseCallArgs(args) {
+    const params = {};
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const value = args[i + 1];
+            if (value === undefined) {
+                params[key] = true;
+                i++;
+            }
+            else if (value.startsWith('--')) {
+                params[key] = true;
+                i++;
+            }
+            else {
+                // Try to parse as JSON, number, or boolean
+                params[key] = parseValue(value);
+                i += 2;
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return params;
+}
+function parseValue(value) {
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    // Try parsing as number
+    const num = Number(value);
+    if (!isNaN(num)) {
+        return num;
+    }
+    // Check for boolean
+    if (value.toLowerCase() === 'true')
+        return true;
+    if (value.toLowerCase() === 'false')
+        return false;
+    // Try parsing as JSON
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function showSchema(tools, toolName) {
+    if (!toolName) {
+        console.log(chalk.yellow('Usage: /schema <toolName>'));
+        return;
+    }
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        console.log(chalk.red(`Tool not found: ${toolName}`));
+        console.log(chalk.dim('Use /tools to see available tools.'));
+        return;
+    }
+    console.log(chalk.bold(`\nSchema for ${toolName}:`));
+    console.log(chalk.white(formatToolSchema(tool)));
+    console.log('');
+}
+function showHelp() {
+    console.log(chalk.bold('\nAgent CLI Help'));
+    console.log('');
+    console.log(chalk.cyan('Chat Mode:'));
+    console.log('  Just type your message to chat with the AI agent.');
+    console.log('  The agent can use available tools to help you.');
+    console.log('');
+    console.log(chalk.cyan('Special Commands:'));
+    console.log(chalk.white('  /tools') + chalk.dim('  - List all available tools'));
+    console.log(chalk.white('  /call <tool> [args]') +
+        chalk.dim('  - Call a tool directly'));
+    console.log(chalk.white('  /schema <tool>') + chalk.dim('  - Show tool parameter schema'));
+    console.log(chalk.white('  /clear') + chalk.dim('  - Clear conversation history'));
+    console.log(chalk.white('  /help') + chalk.dim('  - Show this help message'));
+    console.log(chalk.white('  /exit') + chalk.dim('  - Exit the CLI'));
+    console.log('');
+    console.log(chalk.cyan('Examples:'));
+    console.log(chalk.dim('  > What can you do?'));
+    console.log(chalk.dim('  > Create a user named John with email john@example.com'));
+    console.log(chalk.dim('  > /call createUser --name "John" --email "john@example.com"'));
+    console.log(chalk.dim('  > /schema createUser'));
+    console.log('');
+}
+//# sourceMappingURL=cli.js.map

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Error thrown when encountering unsupported OpenAPI schema features
+ */
+export declare class UnsupportedSchemaError extends Error {
+    constructor(path: string, reason: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+export declare class AuthenticationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when tool execution fails
+ */
+export declare class ToolExecutionError extends Error {
+    readonly toolName: string;
+    readonly cause: Error;
+    constructor(toolName: string, cause: Error);
+}
+/**
+ * Error thrown when OpenAPI spec is invalid or cannot be fetched
+ */
+export declare class SpecLoadError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,41 @@
+/**
+ * Error thrown when encountering unsupported OpenAPI schema features
+ */
+export class UnsupportedSchemaError extends Error {
+    constructor(path, reason) {
+        super(`Unsupported schema at ${path}: ${reason}`);
+        this.name = 'UnsupportedSchemaError';
+    }
+}
+/**
+ * Error thrown when authentication fails
+ */
+export class AuthenticationError extends Error {
+    constructor(message) {
+        super(`Authentication failed: ${message}`);
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Error thrown when tool execution fails
+ */
+export class ToolExecutionError extends Error {
+    toolName;
+    cause;
+    constructor(toolName, cause) {
+        super(`Tool ${toolName} failed: ${cause.message}`);
+        this.name = 'ToolExecutionError';
+        this.toolName = toolName;
+        this.cause = cause;
+    }
+}
+/**
+ * Error thrown when OpenAPI spec is invalid or cannot be fetched
+ */
+export class SpecLoadError extends Error {
+    constructor(message) {
+        super(`Failed to load OpenAPI spec: ${message}`);
+        this.name = 'SpecLoadError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
+export type { HttpMethod, Tool, AuthType, AuthConfig, Session, OpenAPISpec, PathItem, Operation, Parameter, RequestBody, MediaType, Response, SchemaObject, SecurityScheme, } from './types.js';
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+export { AuthManager } from './auth-manager.js';
+export { createExecutableTools, executeToolByName } from './tool-executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+// Error classes
+export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
+// OpenAPI Parser
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+// Auth Manager
+export { AuthManager } from './auth-manager.js';
+// Tool Executor
+export { createExecutableTools, executeToolByName } from './tool-executor.js';
+//# sourceMappingURL=index.js.map

package/dist/lib.d.ts

@@ -0,0 +1,29 @@
+import { generateText } from 'ai';
+type ToolSet = NonNullable<Parameters<typeof generateText>[0]['tools']>;
+export interface Spec2ToolsOptions {
+    /** Path or URL to OpenAPI specification */
+    spec: string;
+}
+/**
+ * Create AI SDK tools from an OpenAPI specification.
+ *
+ * @example
+ * ```ts
+ * import { createTools } from 'spec2tools';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const tools = await createTools({ spec: './openapi.yaml' });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools,
+ *   prompt: 'List all users',
+ * });
+ * ```
+ *
+ * @throws Error if the API requires authentication
+ */
+export declare function createTools(options: Spec2ToolsOptions): Promise<ToolSet>;
+export {};
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.js

@@ -0,0 +1,99 @@
+import { tool } from 'ai';
+import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, } from './openapi-parser.js';
+import { AuthManager } from './auth-manager.js';
+import { ToolExecutionError } from './errors.js';
+/**
+ * Create AI SDK tools from an OpenAPI specification.
+ *
+ * @example
+ * ```ts
+ * import { createTools } from 'spec2tools';
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const tools = await createTools({ spec: './openapi.yaml' });
+ *
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools,
+ *   prompt: 'List all users',
+ * });
+ * ```
+ *
+ * @throws Error if the API requires authentication
+ */
+export async function createTools(options) {
+    const spec = await loadOpenAPISpec(options.spec);
+    const baseUrl = extractBaseUrl(spec);
+    const authConfig = extractAuthConfig(spec);
+    // Check if auth is required
+    if (authConfig.type !== 'none') {
+        throw new Error(`This API requires authentication (${authConfig.type}). ` +
+            `The createTools() function only supports APIs without authentication. ` +
+            `Use the CLI for authenticated APIs: npx spec2tools start --spec ${options.spec}`);
+    }
+    const toolDefs = parseOperations(spec);
+    const authManager = new AuthManager(authConfig);
+    // Build AI SDK tools
+    const tools = {};
+    for (const toolDef of toolDefs) {
+        const { name, description, parameters, httpMethod, path } = toolDef;
+        tools[name] = tool({
+            description,
+            inputSchema: parameters,
+            execute: async (params) => {
+                // Build URL with path parameters
+                let url = `${baseUrl}${path}`;
+                const queryParams = {};
+                const bodyParams = {};
+                for (const [key, value] of Object.entries(params)) {
+                    if (value === undefined)
+                        continue;
+                    if (url.includes(`{${key}}`)) {
+                        // Path parameter
+                        url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
+                    }
+                    else if (httpMethod === 'GET' || httpMethod === 'DELETE') {
+                        // Query parameter for GET/DELETE
+                        queryParams[key] = String(value);
+                    }
+                    else {
+                        // Body parameter for POST/PUT/PATCH
+                        bodyParams[key] = value;
+                    }
+                }
+                // Add query parameters
+                const queryString = new URLSearchParams(queryParams).toString();
+                if (queryString) {
+                    url += `?${queryString}`;
+                }
+                // Build request options
+                const fetchOptions = {
+                    method: httpMethod,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...authManager.getAuthHeaders(),
+                    },
+                };
+                // Add body for non-GET/DELETE requests
+                if (Object.keys(bodyParams).length > 0 &&
+                    httpMethod !== 'GET' &&
+                    httpMethod !== 'DELETE') {
+                    fetchOptions.body = JSON.stringify(bodyParams);
+                }
+                const response = await fetch(url, fetchOptions);
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    throw new ToolExecutionError(name, new Error(`HTTP ${response.status}: ${errorText}`));
+                }
+                const contentType = response.headers.get('content-type');
+                if (contentType?.includes('application/json')) {
+                    return await response.json();
+                }
+                return await response.text();
+            },
+        });
+    }
+    return tools;
+}
+//# sourceMappingURL=lib.js.map

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+export { createTools, type Spec2ToolsOptions } from './lib.js';
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,3 @@
+// Library exports
+export { createTools } from './lib.js';
+//# sourceMappingURL=main.js.map

package/dist/openapi-parser.d.ts

@@ -0,0 +1,26 @@
+import { OpenAPISpec, Tool, AuthConfig } from './types.js';
+/**
+ * Fetch and parse an OpenAPI specification from URL or file path
+ */
+export declare function loadOpenAPISpec(specPath: string): Promise<OpenAPISpec>;
+/**
+ * Extract the base URL from the OpenAPI spec
+ */
+export declare function extractBaseUrl(spec: OpenAPISpec): string;
+/**
+ * Extract authentication configuration from security schemes
+ */
+export declare function extractAuthConfig(spec: OpenAPISpec): AuthConfig;
+/**
+ * Parse all operations from the OpenAPI spec and generate tool definitions
+ */
+export declare function parseOperations(spec: OpenAPISpec): Omit<Tool, 'execute'>[];
+/**
+ * Format tool schema for display
+ */
+export declare function formatToolSchema(tool: Omit<Tool, 'execute'>): string;
+/**
+ * Format tool signature for display
+ */
+export declare function formatToolSignature(tool: Omit<Tool, 'execute'>): string;
+//# sourceMappingURL=openapi-parser.d.ts.map