kbot iterator simplified :)

packages/kbot/dist-in/examples/core/iterator-factory-example.d.ts

@@ -1 +1,2 @@
+export declare function simpleTransformExample(): Promise<any>;
 export declare function factoryExample(): Promise<any>;

packages/kbot/dist-in/iterator.d.ts

@@ -5,6 +5,7 @@ import { AsyncTransformer, ErrorCallback, FilterCallback, INetworkOptions } from
  *
  * - this is a wrapper around the async-iterator.ts file, implementing application layer caching and other features
  * - to test it, use `npm run examples:iterator-factory`
+ * - test unit : tests\unit\core\iterator.test.ts - run with `npm run test:core`
  */
 export interface ILogger {
     info: (message: string) => void;
@@ -38,3 +39,14 @@ export { INetworkOptions };
 export declare function createLLMTransformer(options: IKBotTask, logger?: ILogger, cacheConfig?: CacheConfig): AsyncTransformer;
 export declare function createIterator(obj: Record<string, any>, optionsMixin: Partial<IKBotTask>, globalOptions?: IOptions): IteratorFactory;
 export declare function transformWithMappings(obj: Record<string, any>, createTransformer: (options: IKBotTask) => AsyncTransformer, mappings: FieldMapping[], globalOptions?: IOptions): Promise<void>;
+/**
+ * Simplified transformation function that only requires the target object and field mappings.
+ * All other options are optional with sensible defaults.
+ *
+ * @param obj - The object to transform
+ * @param mappings - Field mappings defining what to transform and how
+ * @param optionsMixin - Optional global options to apply to all transformations
+ * @param options - Optional advanced configuration
+ * @returns The transformed object (also modifies the original)
+ */
+export declare function transform(obj: Record<string, any>, mappings: FieldMapping[], optionsMixin?: Partial<IKBotTask>, options?: IOptions): Promise<Record<string, any>>;

packages/kbot/logs/params.json

@@ -3,7 +3,7 @@
   "messages": [
     {
       "role": "user",
-      "content": "Generate a more appealing marketing name for this product\n\nText to transform: \"broccoli\""
+      "content": "Make this description more engaging and detailed, around 10 words\n\nText to transform: \"A yellow tropical fruit\""
     },
     {
       "role": "user",

packages/kbot/src/examples/core/iterator-factory-example.ts

@@ -15,6 +15,33 @@ import { FieldMapping, createIterator, createLLMTransformer, CacheConfig, INetwo
 
 const MODEL = E_OPENROUTER_MODEL.MODEL_OPENROUTER_QUASAR_ALPHA;
 const ROUTER = 'openrouter';
+
+// Example using the simplified transform function
+export async function simpleTransformExample() {
+    try {
+        // Use the same example data and field mappings
+        const data = JSON.parse(JSON.stringify(exampleData));
+        
+        // Import the transform function directly
+        const { transform } = await import('../../iterator.js');
+        
+        // Minimal configuration, just pass the data and mappings
+        await transform(data, fieldMappings, {
+            model: MODEL,
+            router: ROUTER,
+            mode: E_Mode.COMPLETION
+        });
+        
+        console.log("\nSimplified Transform Result:");
+        console.log(JSON.stringify(data.products.fruits[0], null, 2));
+        
+        return data;
+    } catch (error) {
+        console.error("ERROR during simplified transformation:", error);
+        throw error;
+    }
+}
+
 const LOG_LEVEL = 2;
 
 const logger = {
@@ -59,7 +86,7 @@ const fieldMappings: FieldMapping[] = [
         jsonPath: '$.products.fruits[*].description',
         targetPath: null,
         options: {
-            prompt: 'Make this description more engaging and detailed, around 20-30 words'
+            prompt: 'Make this description more engaging and detailed, around 10 words'
         }
     },
     {
@@ -195,7 +222,16 @@ if (process.argv[1] && process.argv[1].includes('iterator-factory-example')) {
         console.log("Running in debug mode with verbose output");
     }
 
-    factoryExample().catch(error => {
-        console.error("Unhandled error:", error);
-    });
+    // Run the standard factory example
+    factoryExample()
+        .then(() => {
+            console.log("\n========================================");
+            console.log("Running simplified transform example:");
+            console.log("========================================");
+            // Run the simplified transform example
+            return simpleTransformExample();
+        })
+        .catch(error => {
+            console.error("Unhandled error:", error);
+        });
 } 

packages/kbot/src/iterator.ts

@@ -19,6 +19,7 @@ import { deepClone } from "@polymech/core/objects"
  * 
  * - this is a wrapper around the async-iterator.ts file, implementing application layer caching and other features
  * - to test it, use `npm run examples:iterator-factory`
+ * - test unit : tests\unit\core\iterator.test.ts - run with `npm run test:core`
  */
 
 export interface ILogger {
@@ -264,4 +265,25 @@ export async function transformWithMappings(
 ): Promise<void> {
     const iterator = createIterator(obj, {}, globalOptions);
     await iterator.transform(mappings);
+}
+
+/**
+ * Simplified transformation function that only requires the target object and field mappings.
+ * All other options are optional with sensible defaults.
+ * 
+ * @param obj - The object to transform
+ * @param mappings - Field mappings defining what to transform and how
+ * @param optionsMixin - Optional global options to apply to all transformations
+ * @param options - Optional advanced configuration
+ * @returns The transformed object (also modifies the original)
+ */
+export async function transform(
+    obj: Record<string, any>,
+    mappings: FieldMapping[],
+    optionsMixin: Partial<IKBotTask> = {},
+    options: IOptions = {}
+): Promise<Record<string, any>> {
+    const iterator = createIterator(obj, optionsMixin, options);
+    await iterator.transform(mappings);
+    return obj;
 } 

packages/kbot/tests/test-data/core/iterator-factory-data.json

@@ -4,7 +4,7 @@
       {
         "id": "f1",
         "name": "apple",
-        "description": "A deliciously sweet fruit with a satisfying crunch, bursting with juicy flavor and vibrant freshness in every bite, perfect for a refreshing and healthy snack.",
+        "description": "A deliciously juicy fruit bursting with sweet flavor and crisp crunch.",
         "details": {
           "color": "red",
           "origin": "Worldwide",
@@ -15,7 +15,7 @@
       {
         "id": "f2",
         "name": "banana",
-        "description": "A vibrant, sun-kissed yellow tropical fruit bursting with juicy sweetness, offering a refreshing taste of paradise with every succulent bite and an irresistibly fragrant aroma.",
+        "description": "A vibrant, sweet, sun-ripened yellow tropical fruit bursting with flavor",
         "details": {
           "color": "yellow",
           "origin": "Southeast Asia",