@supertools-ai/core 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,10 @@
 # Supertools
 
 <p align="center">
-  <img src="assets/banner.svg" alt="Supertools - Let LLMs write code that calls your tools" width="100%">
+  <img src="https://raw.githubusercontent.com/bxxf/supertools/refs/heads/main/assets/banner.svg" alt="Supertools - Let LLMs write code that calls your tools" width="100%">
 </p>
 
-> **🚧 Work in Progress** — This project is under active development. The npm package will be published soon. Contributions are welcome, especially for adding support for other AI providers (OpenAI, Vercel AI SDK, etc.)!
+> **🚧 Work in Progress** — This project is under active development. Contributions are welcome, especially for adding support for other AI providers (OpenAI, Vercel AI SDK, etc.)!
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> •
@@ -47,58 +47,75 @@ User Request → LLM generates code → Sandbox executes → Result
 ## Quick Start
 
 ```bash
-bun add @supertools-ai/core
+bun add @supertools-ai/core @anthropic-ai/sdk e2b
 ```
 
+Set your API keys:
+```bash
+export ANTHROPIC_API_KEY=your-key
+export E2B_API_KEY=your-key
+```
+
+Create `index.ts` and run with `bun run index.ts`:
+
 ```typescript
 import { supertools, defineTool, z } from '@supertools-ai/core';
 import { Sandbox } from 'e2b';
 import Anthropic from '@anthropic-ai/sdk';
 
-// Define your tools with Zod schemas
-const queryDatabase = defineTool({
-  name: 'queryDatabase',
-  description: 'Execute a SQL query',
-  parameters: z.object({
-    sql: z.string().describe('The SQL query to execute'),
-  }),
-  returns: z.array(z.record(z.unknown())),  // Array of row objects
-  execute: async ({ sql }) => db.query(sql),
-});
-
-const sendEmail = defineTool({
-  name: 'sendEmail',
-  description: 'Send an email',
+// Sample data
+const orders = [
+  { id: 1, customer: 'Alice', total: 150, status: 'completed' },
+  { id: 2, customer: 'Bob', total: 75, status: 'pending' },
+  { id: 3, customer: 'Alice', total: 200, status: 'completed' },
+  { id: 4, customer: 'Charlie', total: 50, status: 'completed' },
+];
+
+// Define tools with Zod schemas
+const getOrders = defineTool({
+  name: 'getOrders',
+  description: 'Get orders, optionally filtered by status',
   parameters: z.object({
-    to: z.string(),
-    subject: z.string(),
-    body: z.string(),
+    status: z.enum(['pending', 'completed']).optional(),
   }),
-  returns: z.object({ success: z.boolean(), messageId: z.string() }),
-  execute: async ({ to, subject, body }) => mailer.send({ to, subject, body }),
+  returns: z.array(z.object({
+    id: z.number(),
+    customer: z.string(),
+    total: z.number(),
+    status: z.string(),
+  })),
+  execute: async ({ status }) =>
+    status ? orders.filter(o => o.status === status) : orders,
 });
 
-// Create sandbox and wrap your SDK client
+// Main
 const sandbox = await Sandbox.create('supertools-bun');
-const client = supertools(new Anthropic(), {
-  tools: [queryDatabase, sendEmail],
-  sandbox,
-});
 
-// Use exactly like the normal Anthropic SDK
-const response = await client.messages.create({
-  model: 'claude-haiku-4-5-20251001',
-  max_tokens: 1024,
-  messages: [{
-    role: 'user',
-    content: 'Query sales for all 50 states, find the top 5, and email a report to the CEO'
-  }],
-});
+try {
+  const client = supertools(new Anthropic(), {
+    tools: [getOrders],
+    sandbox,
+    onEvent: (e) => {
+      if (e.type === 'tool_call') console.log(`→ ${e.tool}()`);
+      if (e.type === 'result') console.log('Result:', e.data);
+    },
+  });
 
-// Traditional: 2-3 LLM round-trips + tokens for all 50 results in context
-// Supertools: 1 LLM call, loop runs in sandbox, only final result returned
+  await client.messages.create({
+    model: 'claude-sonnet-4-5-20241022',
+    max_tokens: 1024,
+    messages: [{
+      role: 'user',
+      content: 'Get all completed orders and calculate the total revenue',
+    }],
+  });
+} finally {
+  await sandbox.kill();
+}
 ```
 
+**What happens:** The LLM writes code that calls `getOrders()`, loops through results, and calculates the sum — all in one API call.
+
 ## How It Works
 
 When you ask: *"Query sales for all 50 states, find top 5, email a report"*
@@ -139,7 +156,7 @@ return { topStates: top5, reportSent: true };
 ## Why Supertools?
 
 <p align="center">
-  <img src="assets/benchmark.svg" alt="Benchmark Results" width="100%">
+  <img src="https://raw.githubusercontent.com/bxxf/supertools/refs/heads/main/assets/benchmark.svg" alt="Benchmark Results" width="100%">
 </p>
 
 The benchmark compares three approaches on the same model (Claude Sonnet 4.5):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertools-ai/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Programmatic tool calling for LLMs - let AI write code that orchestrates your tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node --format esm && tsc --emitDeclarationOnly",
+    "clean": "rm -rf dist",
+    "build": "bun run clean && bun build src/index.ts --outdir dist --target node --format esm && tsc --emitDeclarationOnly",
     "dev": "bun --watch src/index.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",

package/dist/__tests__/protocol.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * Protocol Validation Tests
- */
-export {};
-//# sourceMappingURL=protocol.test.d.ts.map

package/dist/__tests__/protocol.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"protocol.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/protocol.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/security.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * Security Module Tests
- */
-export {};
-//# sourceMappingURL=security.test.d.ts.map

package/dist/__tests__/security.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"security.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/security.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/tool.test.d.ts

@@ -1,5 +0,0 @@
-/**
- * Tool Module Tests
- */
-export {};
-//# sourceMappingURL=tool.test.d.ts.map

package/dist/__tests__/tool.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tool.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/tool.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/errors.d.ts

@@ -1,64 +0,0 @@
-export type ErrorCode = 'CODE_GENERATION_ERROR' | 'EXECUTION_ERROR' | 'TOOL_ERROR' | 'RELAY_CONNECTION_ERROR' | 'RELAY_TIMEOUT_ERROR' | 'PROTOCOL_ERROR' | 'SANDBOX_ERROR' | 'AUTHENTICATION_ERROR' | 'VALIDATION_ERROR' | 'CONFIGURATION_ERROR';
-export declare class OPTError extends Error {
-    readonly code: ErrorCode;
-    readonly cause?: Error;
-    constructor(message: string, code: ErrorCode, cause?: Error);
-    toJSON(): {
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-export declare class CodeGenerationError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-export declare class ExecutionError extends OPTError {
-    readonly output?: string;
-    constructor(message: string, output?: string, cause?: Error);
-    toJSON(): {
-        output: string | undefined;
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-export declare class ToolError extends OPTError {
-    readonly toolName: string;
-    constructor(message: string, toolName: string, cause?: Error);
-    toJSON(): {
-        toolName: string;
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-export declare class RelayConnectionError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-export declare class RelayTimeoutError extends OPTError {
-    constructor(message: string);
-}
-export declare class SandboxError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-export declare class AuthenticationError extends OPTError {
-    constructor(message: string);
-}
-export declare class ConfigurationError extends OPTError {
-    constructor(message: string);
-}
-export declare class ValidationError extends OPTError {
-    readonly field?: string;
-    constructor(message: string, field?: string);
-    toJSON(): {
-        field: string | undefined;
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GACjB,uBAAuB,GACvB,iBAAiB,GACjB,YAAY,GACZ,wBAAwB,GACxB,qBAAqB,GACrB,gBAAgB,GAChB,eAAe,GACf,sBAAsB,GACtB,kBAAkB,GAClB,qBAAqB,CAAC;AAE1B,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,KAAK;IAQ3D,MAAM;;;;;;CAQP;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;IAMlD,MAAM;;;;;;;CAGhB;AAED,qBAAa,SAAU,SAAQ,QAAQ;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;IAMnD,MAAM;;;;;;;CAGhB;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,YAAa,SAAQ,QAAQ;gBAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,qBAAa,mBAAoB,SAAQ,QAAQ;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;IAMlC,MAAM;;;;;;;CAGhB"}

package/dist/index.d.mts

@@ -1,183 +0,0 @@
-import { z } from 'zod';
-export { z } from 'zod';
-
-declare const TOOL_BRAND: unique symbol;
-type ZodSchema = z.ZodType;
-type InferInput<T extends ZodSchema> = z.infer<T>;
-type ExecuteFn<T extends ZodSchema> = (params: InferInput<T>) => unknown | Promise<unknown>;
-interface ToolDefinition<T extends ZodSchema> {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: T;
-    readonly execute: ExecuteFn<T>;
-}
-interface Tool<T extends ZodSchema = ZodSchema> {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: T;
-    readonly execute: ExecuteFn<T>;
-    readonly [TOOL_BRAND]: true;
-}
-interface NormalizedParameter {
-    readonly name: string;
-    readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'any';
-    readonly description: string;
-    readonly required: boolean;
-    readonly default?: unknown;
-}
-interface NormalizedTool {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: readonly NormalizedParameter[];
-    readonly execute: (params: Record<string, unknown>) => unknown | Promise<unknown>;
-}
-/**
- * Define a tool with type-safe parameters.
- *
- * @example
- * const searchUsers = defineTool({
- *   name: 'searchUsers',
- *   description: 'Search users by name or email',
- *   parameters: z.object({
- *     query: z.string().describe('Search query'),
- *     limit: z.number().optional().default(10),
- *   }),
- *   execute: async ({ query, limit }) => db.users.search(query).limit(limit),
- * });
- */
-declare function defineTool<T extends ZodSchema>(definition: ToolDefinition<T>): Tool<T>;
-declare function isTool(value: unknown): value is Tool;
-declare function normalizeTools(tools: readonly Tool[]): NormalizedTool[];
-
-type ToolCollection = readonly Tool[];
-interface ExecutionResult {
-    readonly success: boolean;
-    readonly output: string;
-    readonly error?: string;
-    readonly executionTimeMs: number;
-    readonly images?: readonly string[];
-}
-interface GeneratedCode {
-    readonly code: string;
-    readonly explanation?: string;
-    readonly rawResponse?: string;
-}
-interface ProgrammaticResult {
-    readonly code: string;
-    readonly explanation?: string;
-    readonly result: ExecutionResult;
-}
-interface ToolCallRequest {
-    readonly tool: string;
-    readonly arguments: Readonly<Record<string, unknown>>;
-}
-interface ToolCallResponse {
-    readonly success: boolean;
-    readonly result?: unknown;
-    readonly error?: string;
-}
-interface LLMAdapter {
-    generateCode(userRequest: string, systemPrompt: string): Promise<GeneratedCode>;
-}
-interface ExecutorConfig {
-    readonly tools: ToolCollection;
-    readonly timeout?: number;
-    readonly e2bApiKey?: string;
-    readonly instructions?: string;
-    readonly debug?: boolean;
-}
-
-/**
- * Programmatic Executor
- *
- * Orchestrates the complete flow:
- * 1. LLM generates JavaScript code
- * 2. Code executes in secure E2B Bun sandbox
- * 3. Tool calls relay back to host via WebSocket
- * 4. Results return to user
- */
-
-interface CreateExecutorOptions extends ExecutorConfig {
-    readonly llm: LLMAdapter;
-}
-declare function createExecutor(options: CreateExecutorOptions): ProgrammaticExecutor;
-declare class ProgrammaticExecutor {
-    private readonly originalTools;
-    private readonly normalizedTools;
-    private readonly toolsMap;
-    private readonly llm;
-    private readonly timeout;
-    private readonly e2bApiKey?;
-    private readonly instructions?;
-    private readonly debug;
-    constructor(options: CreateExecutorOptions);
-    run(userRequest: string): Promise<ProgrammaticResult>;
-    executeCode(code: string): Promise<ExecutionResult>;
-    getTools(): readonly NormalizedTool[];
-    getToolDocumentation(): string;
-    private generateCode;
-    private createSandbox;
-    private connectRelay;
-    private cleanup;
-    private log;
-}
-
-type ErrorCode = 'CODE_GENERATION_ERROR' | 'EXECUTION_ERROR' | 'TOOL_ERROR' | 'RELAY_CONNECTION_ERROR' | 'RELAY_TIMEOUT_ERROR' | 'PROTOCOL_ERROR' | 'SANDBOX_ERROR' | 'AUTHENTICATION_ERROR' | 'VALIDATION_ERROR' | 'CONFIGURATION_ERROR';
-declare class OPTError extends Error {
-    readonly code: ErrorCode;
-    readonly cause?: Error;
-    constructor(message: string, code: ErrorCode, cause?: Error);
-    toJSON(): {
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-declare class CodeGenerationError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-declare class ExecutionError extends OPTError {
-    readonly output?: string;
-    constructor(message: string, output?: string, cause?: Error);
-    toJSON(): {
-        output: string | undefined;
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-declare class ToolError extends OPTError {
-    readonly toolName: string;
-    constructor(message: string, toolName: string, cause?: Error);
-    toJSON(): {
-        toolName: string;
-        name: string;
-        code: ErrorCode;
-        message: string;
-        cause: string | undefined;
-    };
-}
-declare class RelayConnectionError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-declare class RelayTimeoutError extends OPTError {
-    constructor(message: string);
-}
-declare class SandboxError extends OPTError {
-    constructor(message: string, cause?: Error);
-}
-declare class AuthenticationError extends OPTError {
-    constructor(message: string);
-}
-declare class ConfigurationError extends OPTError {
-    constructor(message: string);
-}
-
-declare function buildSystemPrompt(toolDefinitions: string, additionalInstructions?: string): string;
-declare function extractCode(response: string): string;
-
-declare function generateTypeHints(tools: readonly Tool[]): string;
-
-export { AuthenticationError, CodeGenerationError, ConfigurationError, type CreateExecutorOptions, ExecutionError, type ExecutionResult, type ExecutorConfig, type GeneratedCode, type LLMAdapter, type NormalizedParameter, type NormalizedTool, OPTError, ProgrammaticExecutor, type ProgrammaticResult, RelayConnectionError, RelayTimeoutError, SandboxError, type Tool, type ToolCallRequest, type ToolCallResponse, type ToolCollection, type ToolDefinition, ToolError, buildSystemPrompt, createExecutor, defineTool, extractCode, generateTypeHints, isTool, normalizeTools };