@ekairos/dataset 1.22.55-beta.development.0 → 1.22.56-beta.development.0

package/dist/file/file-dataset.agent.d.ts

@@ -1,59 +1,6 @@
-import { createContext, type ContextReactor } from "@ekairos/events";
-import { FilePreviewContext } from "./filepreview.js";
-export type FileParseContext = {
-    datasetId: string;
-    fileId: string;
-    instructions: string;
-    sandboxConfig: {
-        filePath: string;
-    };
-    analysis: any[];
-    schema: any | null;
-    plan: any | null;
-    executionResult: any | null;
-    errors: string[];
-    iterationCount: number;
-    filePreview?: FilePreviewContext;
-};
-export type FileParseContextParams = {
-    fileId?: string;
-    instructions?: string;
-    sandboxId?: string;
-    datasetId?: string;
-    model?: string;
-    reactor?: ContextReactor<any, any>;
-};
-export type FileParseRunOptions = {
-    prompt?: string;
-    durable?: boolean;
-};
-export type FileParseContextBuilder<Env extends {
-    orgId: string;
-}> = {
-    datasetId: string;
-    context: ReturnType<ReturnType<typeof createContext<Env>>["context"]> extends any ? any : any;
-};
-export type DatasetResult = {
-    id: string;
-    status?: string;
-    title?: string;
-    schema?: any;
-    analysis?: any;
-    calculatedTotalRows?: number;
-    actualGeneratedRowCount?: number;
-    createdAt?: number;
-    updatedAt?: number;
-};
-/**
- * Factory (DX-first):
- *
- * Usage:
- *   const { datasetId } = await createFileParseContext(fileId, { instructions }).parse(runtime)
- *
- * - Uses the caller runtime; no secondary runtime is created.
- * - All I/O happens in `"use step"` functions via the provided Ekairos runtime.
- * - `parse()` is the entrypoint; it calls `context.react(...)` internally.
- */
+import { type ContextReactor } from "@ekairos/events";
+import type { FileParseRunOptions } from "./file-dataset.types.js";
+export type { DatasetResult, FileParseContext, FileParseContextBuilder, FileParseContextParams, FileParseRunOptions, SandboxState, } from "./file-dataset.types.js";
 export declare function createFileParseContext<Env extends {
     orgId: string;
 }>(fileId: string, opts?: {

package/dist/file/file-dataset.agent.js

@@ -1,15 +1,11 @@
-import { createContext, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL } from "@ekairos/events";
-import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
-import { createGenerateSchemaTool } from "./generateSchema.tool.js";
-import { createCompleteDatasetTool, didCompleteDatasetSucceed } from "../completeDataset.tool.js";
-import { createExecuteCommandTool } from "../executeCommand.tool.js";
-import { createClearDatasetTool } from "../clearDataset.tool.js";
-import { buildFileDatasetPrompt } from "./prompts.js";
-import { generateFilePreview, ensurePreviewScriptsAvailable } from "./filepreview.js";
+import { createContext, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL, } from "@ekairos/events";
 import { id } from "@instantdb/admin";
-import { getDatasetWorkstation } from "../datasetFiles.js";
-import { readInstantFileStep } from "./steps.js";
+import { createClearDatasetTool } from "../clearDataset.tool.js";
+import { createCompleteDatasetTool, didCompleteDatasetSucceed, } from "../completeDataset.tool.js";
 import { datasetGetByIdStep } from "../dataset/steps.js";
+import { createExecuteCommandTool } from "../executeCommand.tool.js";
+import { createGenerateSchemaTool } from "./generateSchema.tool.js";
+import { buildFileDatasetPromptStep, generateFileParsePreviewStep, initializeFileParseSandboxStep, } from "./file-dataset.steps.js";
 async function awaitContextRun(run) {
     if (!run)
         return;
@@ -19,63 +15,6 @@ async function awaitContextRun(run) {
     }
     await run;
 }
-async function initializeSandbox(runtime, sandboxId, datasetId, fileId, state) {
-    "use step";
-    if (state.initialized) {
-        return state.filePath;
-    }
-    console.log(`[FileParseContext ${datasetId}] Initializing sandbox...`);
-    await ensurePreviewScriptsAvailable(runtime, sandboxId);
-    console.log(`[FileParseContext ${datasetId}] Installing Python dependencies...`);
-    const pipInstall = await runDatasetSandboxCommandStep({
-        runtime,
-        sandboxId,
-        cmd: "python",
-        args: ["-m", "pip", "install", "pandas", "openpyxl", "--quiet", "--upgrade"],
-    });
-    const installStderr = pipInstall.stderr;
-    if (installStderr && (installStderr.includes("ERROR") || installStderr.includes("FAILED"))) {
-        throw new Error(`pip install failed: ${installStderr.substring(0, 300)}`);
-    }
-    console.log(`[FileParseContext ${datasetId}] Fetching file from InstantDB...`);
-    const file = await readInstantFileStep({ runtime, fileId });
-    console.log(`[FileParseContext ${datasetId}] Creating dataset workstation...`);
-    const workstation = getDatasetWorkstation(datasetId);
-    await runDatasetSandboxCommandStep({
-        runtime,
-        sandboxId,
-        cmd: "mkdir",
-        args: ["-p", workstation],
-    });
-    const fileName = file.contentDisposition ?? "";
-    const fileExtension = fileName.includes(".") ? fileName.substring(fileName.lastIndexOf(".")) : "";
-    const sandboxFilePath = `${workstation}/${fileId}${fileExtension}`;
-    await writeDatasetSandboxFilesStep({
-        runtime,
-        sandboxId,
-        files: [
-            {
-                path: sandboxFilePath,
-                contentBase64: file.contentBase64,
-            },
-        ],
-    });
-    console.log(`[FileParseContext ${datasetId}] ✅ Workstation created: ${workstation}`);
-    console.log(`[FileParseContext ${datasetId}] ✅ File saved: ${sandboxFilePath}`);
-    state.filePath = sandboxFilePath;
-    state.initialized = true;
-    return sandboxFilePath;
-}
-/**
- * FileParseContext
- *
- * Uso:
- * - Crear una instancia con `fileId`, `instructions` y un `sandbox`
- * - Llamar `getDataset()` para crear un dataset nuevo (crea un datasetId interno)
- * - Llamar `followUp(datasetId, feedback)` para iterar el mismo dataset con feedback
- *
- * Internamente corre un Context (`createContext("file.parse")`) que itera hasta que se ejecuta el tool `completeDataset`.
- */
 function createFileParseContextDefinition(params) {
     const fallbackDatasetId = params.datasetId;
     const model = params.model ?? "openai/gpt-5";
@@ -96,18 +35,31 @@ function createFileParseContextDefinition(params) {
         if (!sandboxId) {
             throw new Error("dataset_sandbox_required");
         }
-        const sandboxFilePath = await initializeSandbox(runtime, sandboxId, datasetId, fileId, sandboxState);
+        const initialized = await initializeFileParseSandboxStep({
+            runtime,
+            sandboxId,
+            datasetId,
+            fileId,
+            state: sandboxState,
+        });
+        const sandboxFilePath = initialized.filePath;
         let filePreview = undefined;
         try {
-            filePreview = await generateFilePreview(runtime, sandboxId, sandboxFilePath, datasetId);
+            filePreview = await generateFileParsePreviewStep({
+                runtime,
+                sandboxId,
+                sandboxFilePath,
+                datasetId,
+            });
         }
         catch {
-            // optional
+            // Preview is optional; parsing can still proceed from the file path.
         }
         let schema = null;
         const datasetResult = await datasetGetByIdStep({ runtime, datasetId });
-        if (datasetResult.ok && datasetResult.data.schema)
+        if (datasetResult.ok && datasetResult.data.schema) {
             schema = datasetResult.data.schema;
+        }
         const ctx = {
             datasetId,
             fileId,
@@ -127,13 +79,13 @@ function createFileParseContextDefinition(params) {
             fileId,
             instructions,
             sandboxId,
-            sandboxState,
+            sandboxState: initialized.state,
             ctx,
         };
     })
         .narrative(async (stored) => {
         const ctx = stored?.content?.ctx;
-        const base = buildFileDatasetPrompt(ctx);
+        const base = await buildFileDatasetPromptStep({ context: ctx });
         const userInstructions = String(ctx?.instructions ?? "").trim();
         if (!userInstructions)
             return base;
@@ -195,16 +147,6 @@ function createFileParseContextDefinition(params) {
     const context = contextBuilder.build();
     return { datasetId: fallbackDatasetId ?? "", context };
 }
-/**
- * Factory (DX-first):
- *
- * Usage:
- *   const { datasetId } = await createFileParseContext(fileId, { instructions }).parse(runtime)
- *
- * - Uses the caller runtime; no secondary runtime is created.
- * - All I/O happens in `"use step"` functions via the provided Ekairos runtime.
- * - `parse()` is the entrypoint; it calls `context.react(...)` internally.
- */
 export function createFileParseContext(fileId, opts) {
     const datasetId = opts?.datasetId ?? id();
     const params = {
@@ -225,14 +167,25 @@ export function createFileParseContext(fileId, opts) {
                 channel: WEB_CHANNEL,
                 createdAt: new Date().toISOString(),
                 content: {
-                    parts: [{ type: "text", text: options.prompt ?? "generate a dataset for this file" }],
+                    parts: [
+                        {
+                            type: "text",
+                            text: options.prompt ?? "generate a dataset for this file",
+                        },
+                    ],
                 },
             };
             const shell = await context.react(triggerEvent, {
                 runtime: runtime,
                 context: { key: `dataset:${datasetId}` },
                 durable: options.durable ?? false,
-                options: { silent: true, preventClose: true, sendFinish: false, maxIterations: 20, maxModelSteps: 5 },
+                options: {
+                    silent: true,
+                    preventClose: true,
+                    sendFinish: false,
+                    maxIterations: 20,
+                    maxModelSteps: 5,
+                },
                 __initialContent: {
                     datasetId,
                     fileId,
@@ -244,7 +197,6 @@ export function createFileParseContext(fileId, opts) {
             await awaitContextRun(shell.run);
             return { datasetId };
         },
-        // Optional: expose the built context for advanced callers (not required for parse DX)
         context,
     };
 }

package/dist/file/file-dataset.steps.d.ts

@@ -0,0 +1,21 @@
+import type { FileParseContext, SandboxState } from "./file-dataset.types.js";
+import type { FilePreviewContext } from "./filepreview.types.js";
+export declare function initializeFileParseSandboxStep(params: {
+    runtime: any;
+    sandboxId: string;
+    datasetId: string;
+    fileId: string;
+    state: SandboxState;
+}): Promise<{
+    filePath: string;
+    state: SandboxState;
+}>;
+export declare function generateFileParsePreviewStep(params: {
+    runtime: any;
+    sandboxId: string;
+    sandboxFilePath: string;
+    datasetId: string;
+}): Promise<FilePreviewContext>;
+export declare function buildFileDatasetPromptStep(params: {
+    context: FileParseContext;
+}): Promise<string>;

package/dist/file/file-dataset.steps.js

@@ -0,0 +1,62 @@
+import { getDatasetWorkstation } from "../datasetFiles.js";
+import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
+import { buildFileDatasetPrompt } from "./prompts.js";
+import { generateFilePreview, ensurePreviewScriptsAvailable } from "./filepreview.js";
+import { readInstantFileStep } from "./steps.js";
+export async function initializeFileParseSandboxStep(params) {
+    "use step";
+    if (params.state.initialized) {
+        return { filePath: params.state.filePath, state: params.state };
+    }
+    console.log(`[FileParseContext ${params.datasetId}] Initializing sandbox...`);
+    await ensurePreviewScriptsAvailable(params.runtime, params.sandboxId);
+    console.log(`[FileParseContext ${params.datasetId}] Installing Python dependencies...`);
+    const pipInstall = await runDatasetSandboxCommandStep({
+        runtime: params.runtime,
+        sandboxId: params.sandboxId,
+        cmd: "python",
+        args: ["-m", "pip", "install", "pandas", "openpyxl", "--quiet", "--upgrade"],
+    });
+    const installStderr = pipInstall.stderr;
+    if (installStderr && (installStderr.includes("ERROR") || installStderr.includes("FAILED"))) {
+        throw new Error(`pip install failed: ${installStderr.substring(0, 300)}`);
+    }
+    console.log(`[FileParseContext ${params.datasetId}] Fetching file from InstantDB...`);
+    const file = await readInstantFileStep({ runtime: params.runtime, fileId: params.fileId });
+    console.log(`[FileParseContext ${params.datasetId}] Creating dataset workstation...`);
+    const workstation = getDatasetWorkstation(params.datasetId);
+    await runDatasetSandboxCommandStep({
+        runtime: params.runtime,
+        sandboxId: params.sandboxId,
+        cmd: "mkdir",
+        args: ["-p", workstation],
+    });
+    const fileName = file.contentDisposition ?? "";
+    const fileExtension = fileName.includes(".") ? fileName.substring(fileName.lastIndexOf(".")) : "";
+    const sandboxFilePath = `${workstation}/${params.fileId}${fileExtension}`;
+    await writeDatasetSandboxFilesStep({
+        runtime: params.runtime,
+        sandboxId: params.sandboxId,
+        files: [
+            {
+                path: sandboxFilePath,
+                contentBase64: file.contentBase64,
+            },
+        ],
+    });
+    console.log(`[FileParseContext ${params.datasetId}] Workstation created: ${workstation}`);
+    console.log(`[FileParseContext ${params.datasetId}] File saved: ${sandboxFilePath}`);
+    const state = {
+        initialized: true,
+        filePath: sandboxFilePath,
+    };
+    return { filePath: sandboxFilePath, state };
+}
+export async function generateFileParsePreviewStep(params) {
+    "use step";
+    return await generateFilePreview(params.runtime, params.sandboxId, params.sandboxFilePath, params.datasetId);
+}
+export async function buildFileDatasetPromptStep(params) {
+    "use step";
+    return buildFileDatasetPrompt(params.context);
+}

package/dist/file/file-dataset.types.d.ts

@@ -0,0 +1,50 @@
+import type { ContextReactor } from "@ekairos/events";
+import type { FilePreviewContext } from "./filepreview.types.js";
+export type SandboxState = {
+    initialized: boolean;
+    filePath: string;
+};
+export type FileParseContext = {
+    datasetId: string;
+    fileId: string;
+    instructions: string;
+    sandboxConfig: {
+        filePath: string;
+    };
+    analysis: any[];
+    schema: any | null;
+    plan: any | null;
+    executionResult: any | null;
+    errors: string[];
+    iterationCount: number;
+    filePreview?: FilePreviewContext;
+};
+export type FileParseContextParams = {
+    fileId?: string;
+    instructions?: string;
+    sandboxId?: string;
+    datasetId?: string;
+    model?: string;
+    reactor?: ContextReactor<any, any>;
+};
+export type FileParseRunOptions = {
+    prompt?: string;
+    durable?: boolean;
+};
+export type FileParseContextBuilder<Env extends {
+    orgId: string;
+}> = {
+    datasetId: string;
+    context: any;
+};
+export type DatasetResult = {
+    id: string;
+    status?: string;
+    title?: string;
+    schema?: any;
+    analysis?: any;
+    calculatedTotalRows?: number;
+    actualGeneratedRowCount?: number;
+    createdAt?: number;
+    updatedAt?: number;
+};

package/dist/file/file-dataset.types.js

@@ -0,0 +1 @@
+export {};

package/dist/file/filepreview.d.ts

@@ -1,34 +1,5 @@
-export type FilePreviewContext = {
-    totalRows: number;
-    metadata?: {
-        description: string;
-        script: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-    };
-    head?: {
-        description: string;
-        script: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-    };
-    tail?: {
-        description: string;
-        script: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-    };
-    mid?: {
-        description: string;
-        script: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-    };
-};
+import type { FilePreviewContext } from "./filepreview.types.js";
+export type { FilePreviewContext } from "./filepreview.types.js";
 interface PreviewOptions {
     headLines?: number;
     tailLines?: number;
@@ -36,4 +7,3 @@ interface PreviewOptions {
 }
 export declare function ensurePreviewScriptsAvailable(runtime: any, sandboxId: string): Promise<void>;
 export declare function generateFilePreview(runtime: any, sandboxId: string, sandboxFilePath: string, datasetId: string, options?: PreviewOptions): Promise<FilePreviewContext>;
-export {};

package/dist/file/filepreview.types.d.ts

@@ -0,0 +1,31 @@
+export type FilePreviewContext = {
+    totalRows: number;
+    metadata?: {
+        description: string;
+        script: string;
+        command: string;
+        stdout: string;
+        stderr: string;
+    };
+    head?: {
+        description: string;
+        script: string;
+        command: string;
+        stdout: string;
+        stderr: string;
+    };
+    tail?: {
+        description: string;
+        script: string;
+        command: string;
+        stdout: string;
+        stderr: string;
+    };
+    mid?: {
+        description: string;
+        script: string;
+        command: string;
+        stdout: string;
+        stderr: string;
+    };
+};

package/dist/file/filepreview.types.js

@@ -0,0 +1 @@
+export {};

package/dist/file/prompts.d.ts

@@ -1,2 +1,2 @@
-import { FileParseContext } from "./file-dataset.agent.js";
+import type { FileParseContext } from "./file-dataset.types.js";
 export declare function buildFileDatasetPrompt(context: FileParseContext): string;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import "./builder/materialize.js";
 export * from "./dataset.js";
 export * from "./domain.js";
 export * from "./materializeDataset.tool.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+import "./builder/materialize.js";
 export * from "./dataset.js";
 export * from "./domain.js";
 export * from "./materializeDataset.tool.js";

package/dist/transform/index.d.ts

@@ -1,2 +1,2 @@
-export { createTransformDatasetContext, type TransformDatasetAgentParams, type TransformDatasetContext, } from "./transform-dataset.agent.js";
+export { createTransformDatasetContext, registerTransformDatasetContext, type TransformDatasetAgentParams, type TransformDatasetContext, type TransformDatasetRunOptions, } from "./transform-dataset.agent.js";
 export { transformDataset, type TransformDatasetInput, type TransformDatasetResult, } from "./transformDataset.js";

package/dist/transform/index.js

@@ -1,2 +1,2 @@
-export { createTransformDatasetContext, } from "./transform-dataset.agent.js";
+export { createTransformDatasetContext, registerTransformDatasetContext, } from "./transform-dataset.agent.js";
 export { transformDataset, } from "./transformDataset.js";

package/dist/transform/prompts.d.ts

@@ -1,34 +1,2 @@
-export type TransformPromptContext = {
-    datasetId: string;
-    sourceDatasetIds: string[];
-    outputSchema: any;
-    sandboxConfig: {
-        sourcePaths: Array<{
-            datasetId: string;
-            path: string;
-        }>;
-        outputPath: string;
-    };
-    sourcePreviews?: Array<{
-        datasetId: string;
-        preview: {
-            totalRows: number;
-            metadata?: {
-                description: string;
-                script: string;
-                command: string;
-                stdout: string;
-                stderr: string;
-            };
-            head?: {
-                description: string;
-                script: string;
-                command: string;
-                stdout: string;
-                stderr: string;
-            };
-        };
-    }>;
-    errors: string[];
-};
+import type { TransformPromptContext } from "./transform-dataset.types.js";
 export declare function buildTransformDatasetPrompt(context: TransformPromptContext): string;

package/dist/transform/transform-dataset.agent.d.ts

@@ -1,48 +1,6 @@
 import { type ContextReactor } from "@ekairos/events";
-import { TransformSourcePreviewContext } from "./filepreview.js";
-export type TransformDatasetContext = {
-    datasetId: string;
-    sourceDatasetIds: string[];
-    outputSchema: any;
-    sandboxConfig: {
-        sourcePaths: Array<{
-            datasetId: string;
-            path: string;
-        }>;
-        outputPath: string;
-    };
-    sourcePreviews?: Array<{
-        datasetId: string;
-        preview: TransformSourcePreviewContext;
-    }>;
-    errors: string[];
-    iterationCount: number;
-    instructions?: string;
-};
-export type TransformDatasetAgentParams = {
-    sourceDatasetIds?: string[];
-    outputSchema?: any;
-    instructions?: string;
-    datasetId?: string;
-    model?: string;
-    sandboxId?: string;
-    reactor?: ContextReactor<any, any>;
-};
-export type TransformDatasetRunOptions = {
-    prompt?: string;
-    durable?: boolean;
-};
-export type TransformDatasetResult = {
-    id: string;
-    status?: string;
-    title?: string;
-    schema?: any;
-    analysis?: any;
-    calculatedTotalRows?: number;
-    actualGeneratedRowCount?: number;
-    createdAt?: number;
-    updatedAt?: number;
-};
+import type { TransformDatasetRunOptions } from "./transform-dataset.types.js";
+export type { TransformDatasetAgentParams, TransformDatasetContext, TransformDatasetResult, TransformDatasetRunOptions, TransformPromptContext, TransformSandboxState, } from "./transform-dataset.types.js";
 export declare function createTransformDatasetContext<Env extends {
     orgId: string;
 }>(params: {

package/dist/transform/transform-dataset.agent.js

@@ -1,13 +1,10 @@
-import { createContext, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL } from "@ekairos/events";
-import { createCompleteDatasetTool, didCompleteDatasetSucceed } from "../completeDataset.tool.js";
-import { createExecuteCommandTool } from "../executeCommand.tool.js";
-import { createClearDatasetTool } from "../clearDataset.tool.js";
-import { buildTransformDatasetPrompt } from "./prompts.js";
-import { getDatasetWorkstation, getDatasetOutputPath } from "../datasetFiles.js";
+import { createContext, INPUT_TEXT_ITEM_TYPE, WEB_CHANNEL, } from "@ekairos/events";
 import { id } from "@instantdb/admin";
-import { generateSourcePreview } from "./filepreview.js";
-import { datasetReadOutputJsonlStep, datasetUpdateSchemaStep } from "../dataset/steps.js";
-import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
+import { createClearDatasetTool } from "../clearDataset.tool.js";
+import { createCompleteDatasetTool, didCompleteDatasetSucceed, } from "../completeDataset.tool.js";
+import { datasetUpdateSchemaStep } from "../dataset/steps.js";
+import { createExecuteCommandTool } from "../executeCommand.tool.js";
+import { buildTransformDatasetPromptStep, ensureTransformSourcesInSandboxStep, generateTransformSourcePreviewsStep, } from "./transform-dataset.steps.js";
 async function awaitContextRun(run) {
     if (!run)
         return;
@@ -17,28 +14,6 @@ async function awaitContextRun(run) {
     }
     await run;
 }
-async function ensureSourcesInSandbox(runtime, sandboxId, datasetId, sourceDatasetIds, state) {
-    "use step";
-    if (state.initialized) {
-        return { sourcePaths: state.sourcePaths, outputPath: getDatasetOutputPath(datasetId) };
-    }
-    const workstation = getDatasetWorkstation(datasetId);
-    await runDatasetSandboxCommandStep({ runtime, sandboxId, cmd: "mkdir", args: ["-p", workstation] });
-    const sourcePaths = [];
-    for (const sourceDatasetId of sourceDatasetIds) {
-        const sourcePath = `${workstation}/source_${sourceDatasetId}.jsonl`;
-        const source = await datasetReadOutputJsonlStep({ runtime, datasetId: sourceDatasetId });
-        await writeDatasetSandboxFilesStep({
-            runtime,
-            sandboxId,
-            files: [{ path: sourcePath, contentBase64: source.contentBase64 }],
-        });
-        sourcePaths.push({ datasetId: sourceDatasetId, path: sourcePath });
-    }
-    state.sourcePaths = sourcePaths;
-    state.initialized = true;
-    return { sourcePaths, outputPath: getDatasetOutputPath(datasetId) };
-}
 function createTransformDatasetContextDefinition(params) {
     const fallbackDatasetId = params.datasetId;
     const model = params.model ?? "openai/gpt-5";
@@ -67,18 +42,19 @@ function createTransformDatasetContextDefinition(params) {
         if (!sandboxId) {
             throw new Error("dataset_sandbox_required");
         }
-        const { sourcePaths, outputPath } = await ensureSourcesInSandbox(runtime, sandboxId, datasetId, sourceDatasetIds, sandboxState);
-        const sourcePreviews = [];
-        for (const sp of sourcePaths) {
-            try {
-                const preview = await generateSourcePreview(runtime, sandboxId, sp.path, datasetId);
-                sourcePreviews.push({ datasetId: sp.datasetId, preview });
-            }
-            catch {
-                // optional
-            }
-        }
-        // Persist output schema on the dataset record (so completeDataset validates against it)
+        const initialized = await ensureTransformSourcesInSandboxStep({
+            runtime,
+            sandboxId,
+            datasetId,
+            sourceDatasetIds,
+            state: sandboxState,
+        });
+        const sourcePreviews = await generateTransformSourcePreviewsStep({
+            runtime,
+            sandboxId,
+            datasetId,
+            sourcePaths: initialized.sourcePaths,
+        });
         await datasetUpdateSchemaStep({
             runtime,
             datasetId,
@@ -89,11 +65,16 @@ function createTransformDatasetContextDefinition(params) {
             datasetId,
             sourceDatasetIds,
             outputSchema,
-            sandboxConfig: { sourcePaths, outputPath },
+            sandboxConfig: {
+                sourcePaths: initialized.sourcePaths,
+                outputPath: initialized.outputPath,
+            },
             sourcePreviews: sourcePreviews.length > 0 ? sourcePreviews : undefined,
             errors: [],
         };
-        const basePrompt = buildTransformDatasetPrompt(promptContext);
+        const basePrompt = await buildTransformDatasetPromptStep({
+            context: promptContext,
+        });
         const userInstructions = String(instructions ?? "").trim();
         const system = userInstructions
             ? [
@@ -112,9 +93,12 @@ function createTransformDatasetContextDefinition(params) {
             outputSchema,
             instructions,
             sandboxId,
-            sandboxState,
+            sandboxState: initialized.state,
             system,
-            sandboxConfig: { sourcePaths, outputPath },
+            sandboxConfig: {
+                sourcePaths: initialized.sourcePaths,
+                outputPath: initialized.outputPath,
+            },
         };
     })
         .narrative(async (stored) => {
@@ -193,7 +177,13 @@ export function createTransformDatasetContext(params) {
                 runtime: runtime,
                 context: { key: `dataset:${datasetId}` },
                 durable: options.durable ?? false,
-                options: { silent: true, preventClose: true, sendFinish: false, maxIterations: 20, maxModelSteps: 5 },
+                options: {
+                    silent: true,
+                    preventClose: true,
+                    sendFinish: false,
+                    maxIterations: 20,
+                    maxModelSteps: 5,
+                },
                 __initialContent: {
                     datasetId,
                     sourceDatasetIds: params.sourceDatasetIds,

package/dist/transform/transform-dataset.steps.d.ts

@@ -0,0 +1,30 @@
+import type { TransformPromptContext, TransformSandboxState, TransformSourcePreviewContext } from "./transform-dataset.types.js";
+export declare function ensureTransformSourcesInSandboxStep(params: {
+    runtime: any;
+    sandboxId: string;
+    datasetId: string;
+    sourceDatasetIds: string[];
+    state: TransformSandboxState;
+}): Promise<{
+    sourcePaths: Array<{
+        datasetId: string;
+        path: string;
+    }>;
+    outputPath: string;
+    state: TransformSandboxState;
+}>;
+export declare function generateTransformSourcePreviewsStep(params: {
+    runtime: any;
+    sandboxId: string;
+    datasetId: string;
+    sourcePaths: Array<{
+        datasetId: string;
+        path: string;
+    }>;
+}): Promise<Array<{
+    datasetId: string;
+    preview: TransformSourcePreviewContext;
+}>>;
+export declare function buildTransformDatasetPromptStep(params: {
+    context: TransformPromptContext;
+}): Promise<string>;

package/dist/transform/transform-dataset.steps.js

@@ -0,0 +1,62 @@
+import { getDatasetOutputPath, getDatasetWorkstation } from "../datasetFiles.js";
+import { datasetReadOutputJsonlStep } from "../dataset/steps.js";
+import { runDatasetSandboxCommandStep, writeDatasetSandboxFilesStep } from "../sandbox/steps.js";
+import { generateSourcePreview } from "./filepreview.js";
+import { buildTransformDatasetPrompt } from "./prompts.js";
+export async function ensureTransformSourcesInSandboxStep(params) {
+    "use step";
+    if (params.state.initialized) {
+        return {
+            sourcePaths: params.state.sourcePaths,
+            outputPath: getDatasetOutputPath(params.datasetId),
+            state: params.state,
+        };
+    }
+    const workstation = getDatasetWorkstation(params.datasetId);
+    await runDatasetSandboxCommandStep({
+        runtime: params.runtime,
+        sandboxId: params.sandboxId,
+        cmd: "mkdir",
+        args: ["-p", workstation],
+    });
+    const sourcePaths = [];
+    for (const sourceDatasetId of params.sourceDatasetIds) {
+        const sourcePath = `${workstation}/source_${sourceDatasetId}.jsonl`;
+        const source = await datasetReadOutputJsonlStep({
+            runtime: params.runtime,
+            datasetId: sourceDatasetId,
+        });
+        await writeDatasetSandboxFilesStep({
+            runtime: params.runtime,
+            sandboxId: params.sandboxId,
+            files: [{ path: sourcePath, contentBase64: source.contentBase64 }],
+        });
+        sourcePaths.push({ datasetId: sourceDatasetId, path: sourcePath });
+    }
+    return {
+        sourcePaths,
+        outputPath: getDatasetOutputPath(params.datasetId),
+        state: {
+            initialized: true,
+            sourcePaths,
+        },
+    };
+}
+export async function generateTransformSourcePreviewsStep(params) {
+    "use step";
+    const sourcePreviews = [];
+    for (const sourcePath of params.sourcePaths) {
+        try {
+            const preview = await generateSourcePreview(params.runtime, params.sandboxId, sourcePath.path, params.datasetId);
+            sourcePreviews.push({ datasetId: sourcePath.datasetId, preview });
+        }
+        catch {
+            // Source preview is optional; transformation can still read the JSONL files.
+        }
+    }
+    return sourcePreviews;
+}
+export async function buildTransformDatasetPromptStep(params) {
+    "use step";
+    return buildTransformDatasetPrompt(params.context);
+}

package/dist/transform/transform-dataset.types.d.ts

@@ -0,0 +1,86 @@
+import type { ContextReactor } from "@ekairos/events";
+import type { TransformSourcePreviewContext } from "./filepreview.js";
+export type { TransformSourcePreviewContext } from "./filepreview.js";
+export type TransformSandboxState = {
+    initialized: boolean;
+    sourcePaths: Array<{
+        datasetId: string;
+        path: string;
+    }>;
+};
+export type TransformDatasetContext = {
+    datasetId: string;
+    sourceDatasetIds: string[];
+    outputSchema: any;
+    sandboxConfig: {
+        sourcePaths: Array<{
+            datasetId: string;
+            path: string;
+        }>;
+        outputPath: string;
+    };
+    sourcePreviews?: Array<{
+        datasetId: string;
+        preview: TransformSourcePreviewContext;
+    }>;
+    errors: string[];
+    iterationCount: number;
+    instructions?: string;
+};
+export type TransformDatasetAgentParams = {
+    sourceDatasetIds?: string[];
+    outputSchema?: any;
+    instructions?: string;
+    datasetId?: string;
+    model?: string;
+    sandboxId?: string;
+    reactor?: ContextReactor<any, any>;
+};
+export type TransformDatasetRunOptions = {
+    prompt?: string;
+    durable?: boolean;
+};
+export type TransformDatasetResult = {
+    id: string;
+    status?: string;
+    title?: string;
+    schema?: any;
+    analysis?: any;
+    calculatedTotalRows?: number;
+    actualGeneratedRowCount?: number;
+    createdAt?: number;
+    updatedAt?: number;
+};
+export type TransformPromptContext = {
+    datasetId: string;
+    sourceDatasetIds: string[];
+    outputSchema: any;
+    sandboxConfig: {
+        sourcePaths: Array<{
+            datasetId: string;
+            path: string;
+        }>;
+        outputPath: string;
+    };
+    sourcePreviews?: Array<{
+        datasetId: string;
+        preview: {
+            totalRows: number;
+            metadata?: {
+                description: string;
+                script: string;
+                command: string;
+                stdout: string;
+                stderr: string;
+            };
+            head?: {
+                description: string;
+                script: string;
+                command: string;
+                stdout: string;
+                stderr: string;
+            };
+        };
+    }>;
+    errors: string[];
+};

package/dist/transform/transform-dataset.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/dataset",
-  "version": "1.22.55-beta.development.0",
+  "version": "1.22.56-beta.development.0",
   "description": "Pulzar Dataset Tools",
   "type": "module",
   "main": "dist/index.js",
@@ -65,9 +65,9 @@
     "test:ai-sdk:instant": "vitest run -c vitest.codex.config.mts src/tests/materializeDataset.ai-sdk.instant.test.ts"
   },
   "dependencies": {
-    "@ekairos/domain": "^1.22.55-beta.development.0",
-    "@ekairos/events": "^1.22.55-beta.development.0",
-    "@ekairos/sandbox": "^1.22.55-beta.development.0",
+    "@ekairos/domain": "^1.22.56-beta.development.0",
+    "@ekairos/events": "^1.22.56-beta.development.0",
+    "@ekairos/sandbox": "^1.22.56-beta.development.0",
     "@instantdb/admin": "0.22.158",
     "@instantdb/core": "0.22.142",
     "ai": "^5.0.44",