@spec2tools/core 0.1.2 → 0.2.0

package/README.md

@@ -64,6 +64,39 @@ const tools = createExecutableTools(toolDefs, baseUrl, authManager);
 const result = await executeToolByName(tools, 'getUser', { id: '123' });
 ```
 
+### AI SDK Tools
+
+```ts
+import { toAISDKTools } from '@spec2tools/core';
+
+// Convert core tools to AI SDK-compatible ToolSet
+const aiTools = toAISDKTools(tools);
+```
+
+### Code Mode
+
+Collapse any AI SDK `ToolSet` into 2 tools (`search` + `execute`). The model discovers endpoints via keyword search and calls them by writing Python code, executed in a sandboxed [Monty](https://github.com/pydantic/monty) interpreter.
+
+```ts
+import { toCodeModeTools } from '@spec2tools/core';
+
+// Convert N tools into 2 code-mode tools
+const codeModeTools = toCodeModeTools(aiTools);
+```
+
+This also works with tools from any MCP server via the AI SDK:
+
+```ts
+import { createMCPClient } from 'ai';
+import { toCodeModeTools } from '@spec2tools/core';
+
+const client = await createMCPClient({
+  transport: { type: 'sse', url: 'http://localhost:3000/sse' },
+});
+
+const tools = toCodeModeTools(await client.tools());
+```
+
 ### Error Classes
 
 ```ts

package/dist/ai-tools.d.ts

@@ -0,0 +1,13 @@
+import { generateText } from 'ai';
+import type { Tool } from './types.js';
+type ToolSet = NonNullable<Parameters<typeof generateText>[0]['tools']>;
+/**
+ * Convert core Tool[] into AI SDK ToolSet.
+ *
+ * Wraps each core tool with the `ai` package's `tool()` helper,
+ * producing a `Record<string, CoreTool>` compatible with `generateText`,
+ * `streamText`, etc.
+ */
+export declare function toAISDKTools(tools: Tool[]): ToolSet;
+export type { ToolSet };
+//# sourceMappingURL=ai-tools.d.ts.map

package/dist/ai-tools.js

@@ -0,0 +1,22 @@
+import { tool } from 'ai';
+/**
+ * Convert core Tool[] into AI SDK ToolSet.
+ *
+ * Wraps each core tool with the `ai` package's `tool()` helper,
+ * producing a `Record<string, CoreTool>` compatible with `generateText`,
+ * `streamText`, etc.
+ */
+export function toAISDKTools(tools) {
+    const aiTools = {};
+    for (const t of tools) {
+        aiTools[t.name] = tool({
+            description: t.description,
+            inputSchema: t.parameters,
+            execute: async (params) => {
+                return t.execute(params);
+            },
+        });
+    }
+    return aiTools;
+}
+//# sourceMappingURL=ai-tools.js.map

package/dist/code-mode.d.ts

@@ -0,0 +1,12 @@
+import { generateText } from 'ai';
+type ToolSet = NonNullable<Parameters<typeof generateText>[0]['tools']>;
+/**
+ * Transform an AI SDK ToolSet into exactly 2 code-mode tools: `search` and `execute`.
+ *
+ * The model discovers endpoints via keyword search and calls them by writing
+ * Python code that is executed in a sandboxed Monty interpreter. This reduces
+ * token consumption by ~99.9% for large APIs (N tools → 2 tools).
+ */
+export declare function toCodeModeTools(tools: ToolSet): ToolSet;
+export {};
+//# sourceMappingURL=code-mode.d.ts.map

package/dist/code-mode.js

@@ -0,0 +1,233 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Monty, MontySnapshot, MontyRuntimeError, MontySyntaxError, MontyTypingError, } from '@pydantic/monty';
+/**
+ * Convert a tool name into a valid Python identifier.
+ * Replaces hyphens, dots, spaces, etc. with underscores and
+ * prefixes with `_` if the name starts with a digit.
+ */
+function toPythonName(name) {
+    let py = name.replace(/[^a-zA-Z0-9_]/g, '_');
+    if (/^[0-9]/.test(py))
+        py = `_${py}`;
+    return py || '_unnamed';
+}
+function jsonSchemaTypeToPython(schema) {
+    if (!schema)
+        return 'any';
+    const type = schema.type;
+    if (type === 'string')
+        return 'str';
+    if (type === 'integer')
+        return 'int';
+    if (type === 'number')
+        return 'float';
+    if (type === 'boolean')
+        return 'bool';
+    if (type === 'array')
+        return 'list';
+    if (type === 'object')
+        return 'dict';
+    if (schema.enum)
+        return 'str';
+    return 'any';
+}
+function buildIndex(tools) {
+    const index = [];
+    for (const [name, t] of Object.entries(tools)) {
+        const pyName = toPythonName(name);
+        const description = 'description' in t ? (t.description || '') : '';
+        const params = [];
+        try {
+            // AI SDK tool() stores the schema as inputSchema (raw Zod)
+            // but other wrappers may use parameters
+            const schema = ('inputSchema' in t ? t.inputSchema : null) ??
+                ('parameters' in t ? t.parameters : null);
+            if (schema && typeof schema === 'object') {
+                const schemaObj = schema;
+                let jsonSchema = null;
+                // AI SDK Schema wrapper — has a jsonSchema property
+                if ('jsonSchema' in schemaObj && schemaObj.jsonSchema) {
+                    jsonSchema = schemaObj.jsonSchema;
+                }
+                // Raw Zod schema — has _def property
+                else if ('_def' in schemaObj) {
+                    jsonSchema = zodToJsonSchema(schema, {
+                        target: 'jsonSchema7',
+                    });
+                }
+                if (jsonSchema) {
+                    const properties = jsonSchema.properties || {};
+                    const required = new Set(jsonSchema.required || []);
+                    for (const [pName, pSchema] of Object.entries(properties)) {
+                        params.push({
+                            name: pName,
+                            type: jsonSchemaTypeToPython(pSchema),
+                            required: required.has(pName),
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Cannot introspect schema; proceed with empty params
+        }
+        const paramStrs = params.map((p) => {
+            if (p.required)
+                return `${p.name}: ${p.type}`;
+            return `${p.name}: ${p.type} = None`;
+        });
+        const signature = `${pyName}(${paramStrs.join(', ')})`;
+        const exampleParams = params
+            .filter((p) => p.required)
+            .slice(0, 2)
+            .map((p) => {
+            if (p.type === 'str')
+                return `${p.name}="..."`;
+            if (p.type === 'int' || p.type === 'float')
+                return `${p.name}=1`;
+            if (p.type === 'bool')
+                return `${p.name}=True`;
+            return `${p.name}=...`;
+        });
+        const example = `${pyName}(${exampleParams.join(', ')})`;
+        index.push({
+            originalName: name,
+            pyName,
+            description,
+            signature,
+            example,
+            searchText: `${name} ${pyName} ${description}`.toLowerCase(),
+        });
+    }
+    return index;
+}
+/**
+ * Recursively convert Monty's Map objects (Python dicts) to plain JS objects
+ * so they JSON.stringify correctly.
+ */
+function montyToJson(value) {
+    if (value instanceof Map) {
+        const obj = {};
+        for (const [k, v] of value) {
+            obj[String(k)] = montyToJson(v);
+        }
+        return obj;
+    }
+    if (Array.isArray(value)) {
+        return value.map(montyToJson);
+    }
+    return value;
+}
+/**
+ * Transform an AI SDK ToolSet into exactly 2 code-mode tools: `search` and `execute`.
+ *
+ * The model discovers endpoints via keyword search and calls them by writing
+ * Python code that is executed in a sandboxed Monty interpreter. This reduces
+ * token consumption by ~99.9% for large APIs (N tools → 2 tools).
+ */
+export function toCodeModeTools(tools) {
+    const index = buildIndex(tools);
+    // Build a mapping from Python-safe names to original tool names
+    const pyToOriginal = new Map();
+    for (const entry of index) {
+        pyToOriginal.set(entry.pyName, entry.originalName);
+    }
+    const pythonNames = [...pyToOriginal.keys()];
+    const searchTool = tool({
+        description: 'Search for available API endpoints by keyword. Returns matching ' +
+            'function signatures with parameter types and usage examples. ' +
+            'Use this to discover what functions are available before writing code.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe('Keywords to search for in endpoint names and descriptions'),
+        }),
+        execute: async ({ query }) => {
+            const keywords = query
+                .toLowerCase()
+                .split(/\s+/)
+                .filter(Boolean);
+            const matches = index.filter((entry) => keywords.some((kw) => entry.searchText.includes(kw)));
+            if (matches.length === 0) {
+                return `No endpoints found matching "${query}". Try different keywords.`;
+            }
+            return matches
+                .map((m) => `${m.signature}\n  ${m.description}\n  Example: ${m.example}`)
+                .join('\n\n');
+        },
+    });
+    const executeTool = tool({
+        description: 'Execute Python code that calls API endpoints. Functions discovered ' +
+            'via search are available to call directly. Always use keyword arguments.\n' +
+            'Example:\n' +
+            '  users = listUsers(limit=10)\n' +
+            '  user = getUser(id="123")\n' +
+            '  users',
+        inputSchema: z.object({
+            code: z
+                .string()
+                .describe('Python code to execute. Use keyword arguments when calling API functions.'),
+        }),
+        execute: async ({ code }) => {
+            try {
+                const m = new Monty(code, { externalFunctions: pythonNames });
+                let progress = m.start({
+                    limits: { maxDurationSecs: 30 },
+                });
+                while (progress instanceof MontySnapshot) {
+                    const snapshot = progress;
+                    const originalName = pyToOriginal.get(snapshot.functionName);
+                    const toolEntry = originalName ? tools[originalName] : undefined;
+                    if (!toolEntry ||
+                        !('execute' in toolEntry) ||
+                        !toolEntry.execute) {
+                        // Should not happen since all tool names are registered,
+                        // but handle gracefully
+                        progress = snapshot.resume({
+                            exception: {
+                                type: 'ValueError',
+                                message: `Unknown function: ${snapshot.functionName}`,
+                            },
+                        });
+                        continue;
+                    }
+                    const params = {
+                        ...snapshot.kwargs,
+                    };
+                    try {
+                        const result = await toolEntry.execute(params, {});
+                        progress = snapshot.resume({ returnValue: result });
+                    }
+                    catch (error) {
+                        progress = snapshot.resume({
+                            exception: {
+                                type: 'RuntimeError',
+                                message: error instanceof Error ? error.message : String(error),
+                            },
+                        });
+                    }
+                }
+                return montyToJson(progress.output);
+            }
+            catch (error) {
+                if (error instanceof MontySyntaxError) {
+                    return `Syntax Error: ${error.message}`;
+                }
+                if (error instanceof MontyRuntimeError) {
+                    return `Runtime Error: ${error.message}\n${error.traceback()}`;
+                }
+                if (error instanceof MontyTypingError) {
+                    return `Type Error: ${error.displayDiagnostics()}`;
+                }
+                return `Error: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    });
+    return {
+        search: searchTool,
+        execute: executeTool,
+    };
+}
+//# sourceMappingURL=code-mode.js.map

package/dist/index.d.ts

@@ -3,4 +3,7 @@ export type { HttpMethod, Tool, AuthType, AuthConfig, Session, OpenAPISpec, Path
 export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
 export { AuthManager } from './auth-manager.js';
 export { createExecutableTools, executeToolByName } from './tool-executor.js';
+export { toAISDKTools } from './ai-tools.js';
+export type { ToolSet } from './ai-tools.js';
+export { toCodeModeTools } from './code-mode.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,4 +6,8 @@ export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAut
 export { AuthManager } from './auth-manager.js';
 // Tool Executor
 export { createExecutableTools, executeToolByName } from './tool-executor.js';
+// AI SDK Tools
+export { toAISDKTools } from './ai-tools.js';
+// Code Mode
+export { toCodeModeTools } from './code-mode.js';
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Core utilities for OpenAPI parsing and authentication",
   "type": "module",
   "main": "dist/index.js",
@@ -28,6 +28,8 @@
     "directory": "packages/core"
   },
   "dependencies": {
+    "@pydantic/monty": "^0.0.7",
+    "ai": "^6.0.68",
     "express": "^5.0.0",
     "open": "^10.1.0",
     "yaml": "^2.5.0",
@@ -37,7 +39,8 @@
   "devDependencies": {
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -45,6 +48,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }