prompt-identifiers-baml 0.1.0 → 0.1.1

package/README.md

@@ -11,24 +11,22 @@ npm install prompt-identifiers-baml prompt-identifiers @boundaryml/baml
 ## Quick Start
 
 ```typescript
-import { wrapBamlFunction } from 'prompt-identifiers-baml';
-import { b } from './baml_client';
+import { wrapBamlFunction } from "prompt-identifiers-baml";
+import { b } from "./baml_client";
 
 // Wrap your BAML function
 const analyzeUser = wrapBamlFunction(b.AnalyzeUser, {
-  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+  config: { inputFormat: "UUID", outputFormat: "SafeNumeric" },
 });
 
 // Use normally - IDs are automatically encoded/decoded
 const result = await analyzeUser({
-  user_id: '123e4567-e89b-42d3-a456-426655440000',
-  items: [
-    { id: '987fcdeb-51a2-43f7-8d9c-0123456789ab', name: 'Order 1' },
-  ],
+  user_id: "123e4567-e89b-42d3-a456-426655440000",
+  items: [{ id: "987fcdeb-51a2-43f7-8d9c-0123456789ab", name: "Order 1" }],
 });
 
 // The BAML function receives:
-// { user_id: '<000>', items: [{ id: '<001>', name: 'Order 1' }] }
+// { user_id: '~000~', items: [{ id: '~001~', name: 'Order 1' }] }
 //
 // You receive the response with original UUIDs restored
 ```
@@ -36,10 +34,10 @@ const result = await analyzeUser({
 ## How It Works
 
 1. **Before BAML call**: Deep traverses input object and encodes all ID fields
-   - `123e4567-e89b-42d3-a456-426655440000` → `<000>`
+   - `123e4567-e89b-42d3-a456-426655440000` → `~000~`
 
 2. **After BAML call**: Deep traverses output object and decodes all placeholders
-   - `<000>` → `123e4567-e89b-42d3-a456-426655440000`
+   - `~000~` → `123e4567-e89b-42d3-a456-426655440000`
 
 This is completely transparent - you work with real IDs, the LLM works with compact placeholders.
 
@@ -49,21 +47,29 @@ This is completely transparent - you work with real IDs, the LLM works with comp
 wrapBamlFunction(fn, {
   // Required: encoding configuration
   config: {
-    inputFormat: 'UUID',      // or 'ULID' or custom RegExp
-    outputFormat: 'SafeNumeric', // or 'Numeric', 'IdToken', { template: '...' }
+    inputFormat: "UUID", // or 'ULID' or custom RegExp
+    outputFormat: "SafeNumeric", // or 'Numeric', 'IdToken', { template: '...' }
   },
 
   // Optional: specify which fields to encode
   // If not provided, all matching strings are encoded
-  encodeFields: ['user_id', 'items[].id', 'metadata.owner_id'],
+  encodeFields: ["user_id", "items[].id", "metadata.owner_id"],
+
+  // Optional: enable debug mode for detailed diagnostics
+  debug: true,
 
   // Optional: callbacks for logging/debugging
   onEncode: (result) => {
-    console.log(`Encoded ${result.encodedCount} IDs`);
-    console.log('Mapping:', result.mapping);
+    console.log("Mapping:", result.mapping);
+    // debugData is only present when debug: true
+    if (result.debugData) {
+      console.log(`Encoded ${result.debugData.encodedCount} IDs in ${result.debugData.durationMs}ms`);
+    }
   },
   onDecode: (result) => {
-    console.log(`Decoded ${result.decodedCount} placeholders`);
+    if (result.debugData) {
+      console.log(`Decoded ${result.debugData.decodedCount} placeholders in ${result.debugData.durationMs}ms`);
+    }
   },
 });
 ```
@@ -72,40 +78,40 @@ wrapBamlFunction(fn, {
 
 The `encodeFields` option supports dot notation and array wildcards:
 
-| Pattern | Description | Example Match |
-|---------|-------------|---------------|
-| `user_id` | Top-level field | `{ user_id: '...' }` |
-| `data.user_id` | Nested field | `{ data: { user_id: '...' } }` |
-| `items[].id` | Array item field | `{ items: [{ id: '...' }] }` |
-| `data.users[].profile.id` | Deep nested | `{ data: { users: [{ profile: { id: '...' } }] } }` |
+| Pattern                   | Description      | Example Match                                       |
+| ------------------------- | ---------------- | --------------------------------------------------- |
+| `user_id`                 | Top-level field  | `{ user_id: '...' }`                                |
+| `data.user_id`            | Nested field     | `{ data: { user_id: '...' } }`                      |
+| `items[].id`              | Array item field | `{ items: [{ id: '...' }] }`                        |
+| `data.users[].profile.id` | Deep nested      | `{ data: { users: [{ profile: { id: '...' } }] } }` |
 
 ### Input Formats
 
-| Format | Description | Example |
-|--------|-------------|---------|
-| `'UUID'` | RFC 4122 UUIDs | `123e4567-e89b-42d3-a456-426655440000` |
-| `'ULID'` | Crockford Base32 ULIDs | `01ARZ3NDEKTSV4RRFFQ69G5FAV` |
-| `RegExp` | Custom pattern | `/user-\d{6}/gi` |
+| Format   | Description            | Example                                |
+| -------- | ---------------------- | -------------------------------------- |
+| `'UUID'` | RFC 4122 UUIDs         | `123e4567-e89b-42d3-a456-426655440000` |
+| `'ULID'` | Crockford Base32 ULIDs | `01ARZ3NDEKTSV4RRFFQ69G5FAV`           |
+| `RegExp` | Custom pattern         | `/user-\d{6}/gi`                       |
 
 ### Output Formats
 
-| Format | Description | Example |
-|--------|-------------|---------|
-| `'SafeNumeric'` | Collision-safe with angle brackets (recommended) | `<000>`, `<001>` |
-| `'Numeric'` | Simple numeric with smart triplet expansion | `000`, `001` |
-| `'IdToken'` | Base62 encoding | `0`, `A`, `z`, `10` |
-| `{ template: '...' }` | Custom template | `{ template: '[ID:{i}]' }` → `[ID:0]` |
+| Format                | Description                                       | Example                               |
+| --------------------- | ------------------------------------------------- | ------------------------------------- |
+| `'SafeNumeric'`       | Collision-safe with tildes (recommended)          | `~000~`, `~001~`                      |
+| `'Numeric'`           | Simple numeric with smart triplet expansion       | `000`, `001`                          |
+| `'IdToken'`           | Base62 encoding                                   | `0`, `A`, `z`, `10`                   |
+| `{ template: '...' }` | Custom template                                   | `{ template: '[ID:{i}]' }` → `[ID:0]` |
 
 ## Streaming Support
 
 Use `wrapBamlStreamingFunction` for BAML streaming functions:
 
 ```typescript
-import { wrapBamlStreamingFunction } from 'prompt-identifiers-baml';
-import { b } from './baml_client';
+import { wrapBamlStreamingFunction } from "prompt-identifiers-baml";
+import { b } from "./baml_client";
 
 const streamAnalysis = wrapBamlStreamingFunction(b.stream.AnalyzeUser, {
-  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+  config: { inputFormat: "UUID", outputFormat: "SafeNumeric" },
 });
 
 // IDs are decoded in real-time as partials arrive
@@ -121,15 +127,15 @@ for await (const partial of streamAnalysis({ user_id: uuid })) {
 Manually encode an object (useful for custom integrations):
 
 ```typescript
-import { encodeObject } from 'prompt-identifiers-baml';
+import { encodeObject } from "prompt-identifiers-baml";
 
 const { encoded, mapping } = encodeObject(
-  { user_id: 'uuid-here', data: { owner: 'other-uuid' } },
-  { inputFormat: 'UUID', outputFormat: 'SafeNumeric' }
+  { user_id: "uuid-here", data: { owner: "other-uuid" } },
+  { inputFormat: "UUID", outputFormat: "SafeNumeric" }
 );
 
-// encoded: { user_id: '<000>', data: { owner: '<001>' } }
-// mapping: { '<000>': 'uuid-here', '<001>': 'other-uuid' }
+// encoded: { user_id: '~000~', data: { owner: '~001~' } }
+// mapping: { '~000~': 'uuid-here', '~001~': 'other-uuid' }
 ```
 
 ### decodeObject
@@ -137,11 +143,11 @@ const { encoded, mapping } = encodeObject(
 Manually decode an object:
 
 ```typescript
-import { decodeObject } from 'prompt-identifiers-baml';
+import { decodeObject } from "prompt-identifiers-baml";
 
 const decoded = decodeObject(
-  { user_id: '<000>', summary: 'User <000> is active' },
-  { '<000>': 'uuid-here' }
+  { user_id: "~000~", summary: "User ~000~ is active" },
+  { "~000~": "uuid-here" }
 );
 
 // decoded: { user_id: 'uuid-here', summary: 'User uuid-here is active' }
@@ -165,11 +171,13 @@ const result: AnalyzeUserOutput = await analyzeUser({
 ## Auto-Detection vs Explicit Fields
 
 **Auto-detection mode** (no `encodeFields`):
+
 - Encodes ALL string fields matching the input pattern
 - Simple to use, works for most cases
 - May encode fields you don't want encoded
 
 **Explicit fields** (with `encodeFields`):
+
 - Only encodes specified fields
 - More precise control
 - Recommended for production use
@@ -177,13 +185,13 @@ const result: AnalyzeUserOutput = await analyzeUser({
 ```typescript
 // Auto-detection: all UUIDs encoded
 const wrapped1 = wrapBamlFunction(fn, {
-  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
+  config: { inputFormat: "UUID", outputFormat: "SafeNumeric" },
 });
 
 // Explicit: only user_id and item IDs encoded
 const wrapped2 = wrapBamlFunction(fn, {
-  config: { inputFormat: 'UUID', outputFormat: 'SafeNumeric' },
-  encodeFields: ['user_id', 'items[].id'],
+  config: { inputFormat: "UUID", outputFormat: "SafeNumeric" },
+  encodeFields: ["user_id", "items[].id"],
 });
 ```
 

package/dist/index.d.mts

@@ -7,6 +7,28 @@ import { EncodeConfig } from 'prompt-identifiers';
  * in inputs and decode them in outputs.
  */
 
+/** Debug data included in onEncode callback when debug is true */
+interface EncodeDebugData {
+    /** Number of unique IDs encoded */
+    encodedCount: number;
+    /** Original input object before encoding */
+    input: unknown;
+    /** Encoded input object */
+    output: unknown;
+    /** Time spent encoding in milliseconds */
+    durationMs: number;
+}
+/** Debug data included in onDecode callback when debug is true */
+interface DecodeDebugData {
+    /** Number of fields containing decoded placeholders */
+    decodedCount: number;
+    /** Raw output from LLM (encoded) */
+    input: unknown;
+    /** Decoded output with original IDs restored */
+    output: unknown;
+    /** Time spent decoding in milliseconds */
+    durationMs: number;
+}
 /** Configuration options for the BAML wrapper */
 interface WrapBamlFunctionOptions {
     /** Encoding configuration (inputFormat and outputFormat) */
@@ -25,18 +47,26 @@ interface WrapBamlFunctionOptions {
      * encodeFields: ['user_id', 'items[].id', 'metadata.owner_id']
      */
     encodeFields?: string[];
+    /**
+     * Enable debug mode to populate debugData in callbacks with
+     * input/output snapshots, counts, and timing information.
+     */
+    debug?: boolean;
     /**
      * Optional callback fired after encoding IDs in the input.
+     * Receives the placeholder→ID mapping. When debug is true,
+     * also receives debugData with input, output, counts, and timing.
      */
     onEncode?: (result: {
         mapping: Record<string, string>;
-        encodedCount: number;
+        debugData?: EncodeDebugData;
     }) => void;
     /**
      * Optional callback fired after decoding IDs in the output.
+     * When debug is true, receives debugData with input, output, counts, and timing.
      */
     onDecode?: (result: {
-        decodedCount: number;
+        debugData?: DecodeDebugData;
     }) => void;
 }
 /** A BAML function type (sync or async) */
@@ -111,4 +141,4 @@ declare function encodeObject<T>(obj: T, config: EncodeConfig, encodeFields?: st
  */
 declare function decodeObject<T>(obj: T, mapping: Record<string, string>): T;
 
-export { type BamlFunction, type BamlStreamingFunction, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };
+export { type BamlFunction, type BamlStreamingFunction, type DecodeDebugData, type EncodeDebugData, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };

package/dist/index.d.ts

@@ -7,6 +7,28 @@ import { EncodeConfig } from 'prompt-identifiers';
  * in inputs and decode them in outputs.
  */
 
+/** Debug data included in onEncode callback when debug is true */
+interface EncodeDebugData {
+    /** Number of unique IDs encoded */
+    encodedCount: number;
+    /** Original input object before encoding */
+    input: unknown;
+    /** Encoded input object */
+    output: unknown;
+    /** Time spent encoding in milliseconds */
+    durationMs: number;
+}
+/** Debug data included in onDecode callback when debug is true */
+interface DecodeDebugData {
+    /** Number of fields containing decoded placeholders */
+    decodedCount: number;
+    /** Raw output from LLM (encoded) */
+    input: unknown;
+    /** Decoded output with original IDs restored */
+    output: unknown;
+    /** Time spent decoding in milliseconds */
+    durationMs: number;
+}
 /** Configuration options for the BAML wrapper */
 interface WrapBamlFunctionOptions {
     /** Encoding configuration (inputFormat and outputFormat) */
@@ -25,18 +47,26 @@ interface WrapBamlFunctionOptions {
      * encodeFields: ['user_id', 'items[].id', 'metadata.owner_id']
      */
     encodeFields?: string[];
+    /**
+     * Enable debug mode to populate debugData in callbacks with
+     * input/output snapshots, counts, and timing information.
+     */
+    debug?: boolean;
     /**
      * Optional callback fired after encoding IDs in the input.
+     * Receives the placeholder→ID mapping. When debug is true,
+     * also receives debugData with input, output, counts, and timing.
      */
     onEncode?: (result: {
         mapping: Record<string, string>;
-        encodedCount: number;
+        debugData?: EncodeDebugData;
     }) => void;
     /**
      * Optional callback fired after decoding IDs in the output.
+     * When debug is true, receives debugData with input, output, counts, and timing.
      */
     onDecode?: (result: {
-        decodedCount: number;
+        debugData?: DecodeDebugData;
     }) => void;
 }
 /** A BAML function type (sync or async) */
@@ -111,4 +141,4 @@ declare function encodeObject<T>(obj: T, config: EncodeConfig, encodeFields?: st
  */
 declare function decodeObject<T>(obj: T, mapping: Record<string, string>): T;
 
-export { type BamlFunction, type BamlStreamingFunction, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };
+export { type BamlFunction, type BamlStreamingFunction, type DecodeDebugData, type EncodeDebugData, type WrapBamlFunctionOptions, decodeObject, encodeObject, wrapBamlFunction, wrapBamlStreamingFunction };

package/dist/index.js

@@ -84,7 +84,7 @@ function formatPlaceholder(outputFormat, index) {
   if (outputFormat === "SafeNumeric") {
     const s = index.toString();
     const width = Math.max(3, Math.ceil(s.length / 3) * 3);
-    return `<${s.padStart(width, "0")}>`;
+    return `~${s.padStart(width, "0")}~`;
   }
   if (outputFormat === "Numeric") {
     const s = index.toString();
@@ -170,9 +170,7 @@ function deepEncode(value, ctx, path = []) {
     return encodeStringWithContext(value, ctx);
   }
   if (Array.isArray(value)) {
-    return value.map(
-      (item, index) => deepEncode(item, ctx, [...path, String(index)])
-    );
+    return value.map((item, index) => deepEncode(item, ctx, [...path, String(index)]));
   }
   if (typeof value === "object") {
     const result = {};
@@ -207,7 +205,7 @@ function deepDecode(value, mapping, countRef) {
   return value;
 }
 function wrapBamlFunction(fn, options) {
-  const { config, encodeFields, onEncode, onDecode } = options;
+  const { config, encodeFields, onEncode, onDecode, debug } = options;
   const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
   return async (input) => {
     const ctx = {
@@ -217,20 +215,40 @@ function wrapBamlFunction(fn, options) {
       mapping: {},
       nextIndex: 0
     };
+    const startEncode = debug ? performance.now() : 0;
     const encodedInput = deepEncode(input, ctx);
+    const encodeDurationMs = debug ? performance.now() - startEncode : 0;
     onEncode?.({
       mapping: ctx.mapping,
-      encodedCount: Object.keys(ctx.mapping).length
+      ...debug && {
+        debugData: {
+          encodedCount: Object.keys(ctx.mapping).length,
+          input,
+          output: encodedInput,
+          durationMs: encodeDurationMs
+        }
+      }
     });
     const output = await fn(encodedInput);
     const countRef = { count: 0 };
+    const startDecode = debug ? performance.now() : 0;
     const decodedOutput = deepDecode(output, ctx.mapping, countRef);
-    onDecode?.({ decodedCount: countRef.count });
+    const decodeDurationMs = debug ? performance.now() - startDecode : 0;
+    onDecode?.({
+      ...debug && {
+        debugData: {
+          decodedCount: countRef.count,
+          input: output,
+          output: decodedOutput,
+          durationMs: decodeDurationMs
+        }
+      }
+    });
     return decodedOutput;
   };
 }
 function wrapBamlStreamingFunction(fn, options) {
-  const { config, encodeFields, onEncode, onDecode } = options;
+  const { config, encodeFields, onEncode, onDecode, debug } = options;
   const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
   return async function* (input) {
     const ctx = {
@@ -240,20 +258,40 @@ function wrapBamlStreamingFunction(fn, options) {
       mapping: {},
       nextIndex: 0
     };
+    const startEncode = debug ? performance.now() : 0;
     const encodedInput = deepEncode(input, ctx);
+    const encodeDurationMs = debug ? performance.now() - startEncode : 0;
     onEncode?.({
       mapping: ctx.mapping,
-      encodedCount: Object.keys(ctx.mapping).length
+      ...debug && {
+        debugData: {
+          encodedCount: Object.keys(ctx.mapping).length,
+          input,
+          output: encodedInput,
+          durationMs: encodeDurationMs
+        }
+      }
     });
     const generator = fn(encodedInput);
     let totalDecoded = 0;
+    const startDecode = debug ? performance.now() : 0;
     while (true) {
       const { value, done } = await generator.next();
       if (done) {
         const countRef2 = { count: 0 };
         const decodedValue2 = deepDecode(value, ctx.mapping, countRef2);
         totalDecoded += countRef2.count;
-        onDecode?.({ decodedCount: totalDecoded });
+        const decodeDurationMs = debug ? performance.now() - startDecode : 0;
+        onDecode?.({
+          ...debug && {
+            debugData: {
+              decodedCount: totalDecoded,
+              input: value,
+              output: decodedValue2,
+              durationMs: decodeDurationMs
+            }
+          }
+        });
         return decodedValue2;
       }
       const countRef = { count: 0 };

package/dist/index.mjs

@@ -57,7 +57,7 @@ function formatPlaceholder(outputFormat, index) {
   if (outputFormat === "SafeNumeric") {
     const s = index.toString();
     const width = Math.max(3, Math.ceil(s.length / 3) * 3);
-    return `<${s.padStart(width, "0")}>`;
+    return `~${s.padStart(width, "0")}~`;
   }
   if (outputFormat === "Numeric") {
     const s = index.toString();
@@ -143,9 +143,7 @@ function deepEncode(value, ctx, path = []) {
     return encodeStringWithContext(value, ctx);
   }
   if (Array.isArray(value)) {
-    return value.map(
-      (item, index) => deepEncode(item, ctx, [...path, String(index)])
-    );
+    return value.map((item, index) => deepEncode(item, ctx, [...path, String(index)]));
   }
   if (typeof value === "object") {
     const result = {};
@@ -180,7 +178,7 @@ function deepDecode(value, mapping, countRef) {
   return value;
 }
 function wrapBamlFunction(fn, options) {
-  const { config, encodeFields, onEncode, onDecode } = options;
+  const { config, encodeFields, onEncode, onDecode, debug } = options;
   const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
   return async (input) => {
     const ctx = {
@@ -190,20 +188,40 @@ function wrapBamlFunction(fn, options) {
       mapping: {},
       nextIndex: 0
     };
+    const startEncode = debug ? performance.now() : 0;
     const encodedInput = deepEncode(input, ctx);
+    const encodeDurationMs = debug ? performance.now() - startEncode : 0;
     onEncode?.({
       mapping: ctx.mapping,
-      encodedCount: Object.keys(ctx.mapping).length
+      ...debug && {
+        debugData: {
+          encodedCount: Object.keys(ctx.mapping).length,
+          input,
+          output: encodedInput,
+          durationMs: encodeDurationMs
+        }
+      }
     });
     const output = await fn(encodedInput);
     const countRef = { count: 0 };
+    const startDecode = debug ? performance.now() : 0;
     const decodedOutput = deepDecode(output, ctx.mapping, countRef);
-    onDecode?.({ decodedCount: countRef.count });
+    const decodeDurationMs = debug ? performance.now() - startDecode : 0;
+    onDecode?.({
+      ...debug && {
+        debugData: {
+          decodedCount: countRef.count,
+          input: output,
+          output: decodedOutput,
+          durationMs: decodeDurationMs
+        }
+      }
+    });
     return decodedOutput;
   };
 }
 function wrapBamlStreamingFunction(fn, options) {
-  const { config, encodeFields, onEncode, onDecode } = options;
+  const { config, encodeFields, onEncode, onDecode, debug } = options;
   const fieldPaths = encodeFields ? encodeFields.map(parseFieldPath) : null;
   return async function* (input) {
     const ctx = {
@@ -213,20 +231,40 @@ function wrapBamlStreamingFunction(fn, options) {
       mapping: {},
       nextIndex: 0
     };
+    const startEncode = debug ? performance.now() : 0;
     const encodedInput = deepEncode(input, ctx);
+    const encodeDurationMs = debug ? performance.now() - startEncode : 0;
     onEncode?.({
       mapping: ctx.mapping,
-      encodedCount: Object.keys(ctx.mapping).length
+      ...debug && {
+        debugData: {
+          encodedCount: Object.keys(ctx.mapping).length,
+          input,
+          output: encodedInput,
+          durationMs: encodeDurationMs
+        }
+      }
     });
     const generator = fn(encodedInput);
     let totalDecoded = 0;
+    const startDecode = debug ? performance.now() : 0;
     while (true) {
       const { value, done } = await generator.next();
       if (done) {
         const countRef2 = { count: 0 };
         const decodedValue2 = deepDecode(value, ctx.mapping, countRef2);
         totalDecoded += countRef2.count;
-        onDecode?.({ decodedCount: totalDecoded });
+        const decodeDurationMs = debug ? performance.now() - startDecode : 0;
+        onDecode?.({
+          ...debug && {
+            debugData: {
+              decodedCount: totalDecoded,
+              input: value,
+              output: decodedValue2,
+              durationMs: decodeDurationMs
+            }
+          }
+        });
         return decodedValue2;
       }
       const countRef = { count: 0 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-identifiers-baml",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "BAML integration for prompt-identifiers. Efficient ID compression for token optimization.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -54,7 +54,7 @@
     "ts-jest": "^29.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.0.0",
-    "prompt-identifiers": "0.1.0"
+    "prompt-identifiers": "0.1.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",