@virtualkitchenco/multiverse-sdk 0.0.16 → 0.0.18

package/README.md

@@ -11,7 +11,7 @@ npm install @virtualkitchenco/multiverse-sdk
 ## Quick Start
 
 ```typescript
-import { multiverse, wrap } from '@virtualkitchenco/multiverse-sdk';
+import { multiverse } from '@virtualkitchenco/multiverse-sdk';
 import { z } from 'zod';
 
 // 1. Configure
@@ -21,53 +21,29 @@ multiverse.configure({
   apiKey: process.env.MULTIVERSE_API_KEY,
 });
 
-// 2. Define output schemas
-const SearchResultSchema = z.object({
-  flights: z.array(z.object({
-    id: z.string(),
-    from: z.string(),
-    to: z.string(),
-    price: z.number(),
-    airline: z.string(),
-  })),
-});
-
-const BookingSchema = z.object({
-  bookingId: z.string(),
-  flightId: z.string(),
-  passengerName: z.string(),
-  status: z.enum(['confirmed', 'pending', 'failed']),
-});
+// 2. Register tools (see multiverse.tool() and wrap() below)
 
-// 3. Wrap your tools
-const searchFlights = wrap(searchFlightsTool, {
-  output: SearchResultSchema,
-  effects: (output) =>
-    output.flights.map((f) => ({
-      operation: 'create' as const,
-      collection: 'flights',
-      id: f.id,
-      data: f,
-    })),
-});
-
-const bookFlight = wrap(bookFlightTool, {
-  output: BookingSchema,
-  effects: (output) => [
-    { operation: 'create', collection: 'bookings', id: output.bookingId, data: output },
-  ],
-});
-
-// 4. Define and run tests
+// 3. Describe what you're testing
 const test = multiverse.describe({
   name: 'flight-booking-agent',
-  task: 'Book flights for passengers',
+  task: 'Help the user book a flight',
   agent: runAgent,
 });
 
+// 4. Generate scenarios with typed variables
+const scenarios = await test.generateScenarios({
+  count: 5,
+  variables: z.object({
+    expectedBookings: z.number().describe('Total flight bookings expected'),
+  }),
+});
+
+// 5. Run
 const results = await test.run({
+  scenarios,
   simulateUser: true,
-  success: (world) => world.getCollection('bookings').size > 0,
+  success: (world, trace, scenario) =>
+    world.getCollection('bookings').size === scenario.variables.expectedBookings,
 });
 
 console.log(`${results.passRate}% pass`);
@@ -90,9 +66,46 @@ multiverse.configure({
 });
 ```
 
+### `multiverse.tool(def)`
+
+Register a tool for simulation. Works with any plain function — no framework required.
+
+```typescript
+const searchFlights = multiverse.tool({
+  name: 'searchFlights',
+  description: 'Search for available flights',
+  input: z.object({
+    from: z.string().describe('Departure airport code'),
+    to: z.string().describe('Arrival airport code'),
+    date: z.string().describe('Departure date (YYYY-MM-DD)'),
+  }),
+  output: SearchResultSchema,
+  execute: async (input) => realSearchFlights(input),
+  effects: (output) =>
+    output.flights.map((f) => ({
+      operation: 'create' as const,
+      collection: 'flights',
+      id: f.id,
+      data: f,
+    })),
+});
+```
+
+Returns a callable function `(input) => Promise<output>`. During tests, calls are intercepted and simulated. Outside tests, `execute` is called directly.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | Tool name |
+| `description` | `string` | Tool description |
+| `input` | `ZodSchema` | Input schema |
+| `output` | `ZodSchema` | Output schema |
+| `execute` | `(input) => Promise<output>` | Real implementation |
+| `effects` | `(output, world) => Effect[]` | Declare state changes from output |
+| `invariants` | `Invariant[]` | Constraints to enforce |
+
 ### `wrap(tool, config)`
 
-Wrap a LangChain tool for simulation testing.
+Wrap a LangChain tool for simulation. Extracts `name`, `description`, and `schema` automatically.
 
 ```typescript
 import { wrap } from '@virtualkitchenco/multiverse-sdk';
@@ -102,9 +115,6 @@ const myTool = wrap(langchainTool, {
   effects: (output, world) => [
     { operation: 'create', collection: 'orders', id: output.id, data: output },
   ],
-  invariants: [
-    { collection: 'inventory', field: 'quantity', condition: 'gte', value: 0 },
-  ],
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@virtualkitchenco/multiverse-sdk",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "Simulated worlds for AI agents - 6 months production in 6 minutes",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "nanoid": "^5.0.4",
-    "@virtualkitchenco/multiverse-types": "0.0.16"
+    "@virtualkitchenco/multiverse-types": "0.0.18"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",