@robosystems/client 0.2.22 → 0.2.24

package/extensions/AgentClient.js

@@ -43,7 +43,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info
@@ -87,7 +87,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info

package/extensions/AgentClient.ts

@@ -102,7 +102,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 
@@ -158,7 +158,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 

package/extensions/MaterializationClient.d.ts

@@ -2,6 +2,7 @@ export interface MaterializationOptions {
     ignoreErrors?: boolean;
     rebuild?: boolean;
     force?: boolean;
+    timeout?: number;
     onProgress?: (message: string) => void;
 }
 export interface MaterializationResult {
@@ -27,6 +28,7 @@ export interface MaterializationStatus {
 }
 export declare class MaterializationClient {
     private config;
+    private operationClient;
     constructor(config: {
         baseUrl: string;
         credentials?: 'include' | 'same-origin' | 'omit';
@@ -36,11 +38,15 @@ export declare class MaterializationClient {
     /**
      * Materialize graph from DuckDB staging tables
      *
-     * Rebuilds the complete graph database from the current state of DuckDB
-     * staging tables. Automatically discovers all tables, materializes them in
-     * the correct order (nodes before relationships), and clears the staleness flag.
+     * Submits a materialization job to Dagster and monitors progress via SSE.
+     * The operation runs asynchronously on the server but this method waits
+     * for completion and returns the final result.
      */
     materialize(graphId: string, options?: MaterializationOptions): Promise<MaterializationResult>;
+    /**
+     * Convert SSE operation result to MaterializationResult
+     */
+    private convertOperationResult;
     /**
      * Get current materialization status for the graph
      *
@@ -48,4 +54,8 @@ export declare class MaterializationClient {
      * when it was last materialized, and how long since last materialization.
      */
     status(graphId: string): Promise<MaterializationStatus | null>;
+    /**
+     * Close any active SSE connections
+     */
+    close(): void;
 }

package/extensions/MaterializationClient.js

@@ -6,23 +6,25 @@ exports.MaterializationClient = void 0;
  * Materialization Client for RoboSystems API
  *
  * Manages graph materialization from DuckDB staging tables.
- * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ * Submits materialization jobs to Dagster and monitors progress via SSE.
  */
 const sdk_gen_1 = require("../sdk.gen");
+const OperationClient_1 = require("./OperationClient");
 class MaterializationClient {
     constructor(config) {
         this.config = config;
+        this.operationClient = new OperationClient_1.OperationClient(config);
     }
     /**
      * Materialize graph from DuckDB staging tables
      *
-     * Rebuilds the complete graph database from the current state of DuckDB
-     * staging tables. Automatically discovers all tables, materializes them in
-     * the correct order (nodes before relationships), and clears the staleness flag.
+     * Submits a materialization job to Dagster and monitors progress via SSE.
+     * The operation runs asynchronously on the server but this method waits
+     * for completion and returns the final result.
      */
     async materialize(graphId, options = {}) {
         try {
-            options.onProgress?.('Starting graph materialization...');
+            options.onProgress?.('Submitting materialization job...');
             const request = {
                 ignore_errors: options.ignoreErrors ?? true,
                 rebuild: options.rebuild ?? false,
@@ -44,19 +46,24 @@ class MaterializationClient {
                     error: `Failed to materialize graph: ${response.error}`,
                 };
             }
-            const result = response.data;
-            options.onProgress?.(`✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
-                `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`);
-            return {
-                status: result.status,
-                wasStale: result.was_stale,
-                staleReason: result.stale_reason,
-                tablesMaterialized: result.tables_materialized || [],
-                totalRows: result.total_rows || 0,
-                executionTimeMs: result.execution_time_ms || 0,
-                message: result.message || 'Materialization complete',
-                success: true,
-            };
+            const queuedResponse = response.data;
+            const operationId = queuedResponse.operation_id;
+            options.onProgress?.(`Materialization queued (operation: ${operationId})`);
+            // Monitor the operation via SSE until completion
+            const opResult = await this.operationClient.monitorOperation(operationId, {
+                timeout: (options.timeout ?? 600) * 1000, // Convert to milliseconds, 10 minute default
+                onProgress: (progress) => {
+                    if (options.onProgress) {
+                        let msg = progress.message;
+                        if (progress.progressPercent !== undefined) {
+                            msg += ` (${progress.progressPercent.toFixed(0)}%)`;
+                        }
+                        options.onProgress(msg);
+                    }
+                },
+            });
+            // Convert operation result to materialization result
+            return this.convertOperationResult(opResult, options);
         }
         catch (error) {
             return {
@@ -71,6 +78,43 @@ class MaterializationClient {
             };
         }
     }
+    /**
+     * Convert SSE operation result to MaterializationResult
+     */
+    convertOperationResult(opResult, options) {
+        if (opResult.success) {
+            // Extract details from SSE completion event result
+            const sseResult = opResult.result || {};
+            const tables = sseResult.tables_materialized || [];
+            const rows = sseResult.total_rows || 0;
+            const timeMs = sseResult.execution_time_ms || 0;
+            options.onProgress?.(`✅ Materialization complete: ${tables.length} tables, ` +
+                `${rows.toLocaleString()} rows in ${timeMs.toFixed(2)}ms`);
+            return {
+                status: 'success',
+                wasStale: sseResult.was_stale || false,
+                staleReason: sseResult.stale_reason,
+                tablesMaterialized: tables,
+                totalRows: rows,
+                executionTimeMs: timeMs,
+                message: sseResult.message || 'Graph materialized successfully',
+                success: true,
+            };
+        }
+        else {
+            // Operation failed or was cancelled
+            return {
+                status: 'failed',
+                wasStale: false,
+                tablesMaterialized: [],
+                totalRows: 0,
+                executionTimeMs: 0,
+                message: opResult.error || 'Operation failed',
+                success: false,
+                error: opResult.error,
+            };
+        }
+    }
     /**
      * Get current materialization status for the graph
      *
@@ -103,5 +147,11 @@ class MaterializationClient {
             return null;
         }
     }
+    /**
+     * Close any active SSE connections
+     */
+    close() {
+        this.operationClient.closeAll();
+    }
 }
 exports.MaterializationClient = MaterializationClient;

package/extensions/MaterializationClient.ts

@@ -4,16 +4,18 @@
  * Materialization Client for RoboSystems API
  *
  * Manages graph materialization from DuckDB staging tables.
- * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ * Submits materialization jobs to Dagster and monitors progress via SSE.
  */
 
 import { getMaterializationStatus, materializeGraph } from '../sdk.gen'
 import type { MaterializeRequest } from '../types.gen'
+import { OperationClient, type OperationResult } from './OperationClient'
 
 export interface MaterializationOptions {
   ignoreErrors?: boolean
   rebuild?: boolean
   force?: boolean
+  timeout?: number // Default 10 minutes
   onProgress?: (message: string) => void
 }
 
@@ -47,6 +49,7 @@ export class MaterializationClient {
     headers?: Record<string, string>
     token?: string
   }
+  private operationClient: OperationClient
 
   constructor(config: {
     baseUrl: string
@@ -55,21 +58,22 @@ export class MaterializationClient {
     token?: string
   }) {
     this.config = config
+    this.operationClient = new OperationClient(config)
   }
 
   /**
    * Materialize graph from DuckDB staging tables
    *
-   * Rebuilds the complete graph database from the current state of DuckDB
-   * staging tables. Automatically discovers all tables, materializes them in
-   * the correct order (nodes before relationships), and clears the staleness flag.
+   * Submits a materialization job to Dagster and monitors progress via SSE.
+   * The operation runs asynchronously on the server but this method waits
+   * for completion and returns the final result.
    */
   async materialize(
     graphId: string,
     options: MaterializationOptions = {}
   ): Promise<MaterializationResult> {
     try {
-      options.onProgress?.('Starting graph materialization...')
+      options.onProgress?.('Submitting materialization job...')
 
       const request: MaterializeRequest = {
         ignore_errors: options.ignoreErrors ?? true,
@@ -95,33 +99,82 @@ export class MaterializationClient {
         }
       }
 
-      const result = response.data as any
+      const queuedResponse = response.data as { operation_id: string; message: string }
+      const operationId = queuedResponse.operation_id
+
+      options.onProgress?.(`Materialization queued (operation: ${operationId})`)
+
+      // Monitor the operation via SSE until completion
+      const opResult = await this.operationClient.monitorOperation(operationId, {
+        timeout: (options.timeout ?? 600) * 1000, // Convert to milliseconds, 10 minute default
+        onProgress: (progress) => {
+          if (options.onProgress) {
+            let msg = progress.message
+            if (progress.progressPercent !== undefined) {
+              msg += ` (${progress.progressPercent.toFixed(0)}%)`
+            }
+            options.onProgress(msg)
+          }
+        },
+      })
+
+      // Convert operation result to materialization result
+      return this.convertOperationResult(opResult, options)
+    } catch (error) {
+      return {
+        status: 'failed',
+        wasStale: false,
+        tablesMaterialized: [],
+        totalRows: 0,
+        executionTimeMs: 0,
+        message: error instanceof Error ? error.message : String(error),
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  /**
+   * Convert SSE operation result to MaterializationResult
+   */
+  private convertOperationResult(
+    opResult: OperationResult,
+    options: MaterializationOptions
+  ): MaterializationResult {
+    if (opResult.success) {
+      // Extract details from SSE completion event result
+      const sseResult = opResult.result || {}
+
+      const tables = sseResult.tables_materialized || []
+      const rows = sseResult.total_rows || 0
+      const timeMs = sseResult.execution_time_ms || 0
 
       options.onProgress?.(
-        `✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
-          `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`
+        `✅ Materialization complete: ${tables.length} tables, ` +
+          `${rows.toLocaleString()} rows in ${timeMs.toFixed(2)}ms`
       )
 
       return {
-        status: result.status,
-        wasStale: result.was_stale,
-        staleReason: result.stale_reason,
-        tablesMaterialized: result.tables_materialized || [],
-        totalRows: result.total_rows || 0,
-        executionTimeMs: result.execution_time_ms || 0,
-        message: result.message || 'Materialization complete',
+        status: 'success',
+        wasStale: sseResult.was_stale || false,
+        staleReason: sseResult.stale_reason,
+        tablesMaterialized: tables,
+        totalRows: rows,
+        executionTimeMs: timeMs,
+        message: sseResult.message || 'Graph materialized successfully',
         success: true,
       }
-    } catch (error) {
+    } else {
+      // Operation failed or was cancelled
       return {
         status: 'failed',
         wasStale: false,
         tablesMaterialized: [],
         totalRows: 0,
         executionTimeMs: 0,
-        message: error instanceof Error ? error.message : String(error),
+        message: opResult.error || 'Operation failed',
         success: false,
-        error: error instanceof Error ? error.message : String(error),
+        error: opResult.error,
       }
     }
   }
@@ -160,4 +213,11 @@ export class MaterializationClient {
       return null
     }
   }
+
+  /**
+   * Close any active SSE connections
+   */
+  close(): void {
+    this.operationClient.closeAll()
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/client",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "TypeScript client library for RoboSystems Financial Knowledge Graph API",
   "main": "index.js",
   "types": "index.d.ts",

package/sdk/sdk.gen.d.ts

@@ -433,7 +433,7 @@ export declare const listAgents: <ThrowOnError extends boolean = false>(options:
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -494,7 +494,7 @@ export declare const getAgentMetadata: <ThrowOnError extends boolean = false>(op
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1708,7 +1708,7 @@ export declare const getFile: <ThrowOnError extends boolean = false>(options: Op
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/sdk/sdk.gen.js

@@ -1079,7 +1079,7 @@ exports.listAgents = listAgents;
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1176,7 +1176,7 @@ exports.getAgentMetadata = getAgentMetadata;
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -3130,7 +3130,7 @@ exports.getFile = getFile;
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/sdk/sdk.gen.ts

@@ -1092,7 +1092,7 @@ export const listAgents = <ThrowOnError extends boolean = false>(options: Option
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1189,7 +1189,7 @@ export const getAgentMetadata = <ThrowOnError extends boolean = false>(options:
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -3143,7 +3143,7 @@ export const getFile = <ThrowOnError extends boolean = false>(options: Options<G
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/sdk/types.gen.d.ts

@@ -3018,43 +3018,24 @@ export type MaterializeRequest = {
 };
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message

package/sdk/types.gen.ts

@@ -3112,43 +3112,24 @@ export type MaterializeRequest = {
 
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message

package/sdk-extensions/AgentClient.js

@@ -43,7 +43,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info
@@ -87,7 +87,7 @@ class AgentClient {
                 timestamp: new Date().toISOString(),
             };
         }
-        // Check if this is a queued response (async Celery execution)
+        // Check if this is a queued response (async background task execution)
         if (responseData?.operation_id) {
             const queuedResponse = responseData;
             // If user doesn't want to wait, throw with queue info

package/sdk-extensions/AgentClient.ts

@@ -102,7 +102,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 
@@ -158,7 +158,7 @@ export class AgentClient {
       }
     }
 
-    // Check if this is a queued response (async Celery execution)
+    // Check if this is a queued response (async background task execution)
     if (responseData?.operation_id) {
       const queuedResponse = responseData as QueuedAgentResponse
 

package/sdk-extensions/MaterializationClient.d.ts

@@ -2,6 +2,7 @@ export interface MaterializationOptions {
     ignoreErrors?: boolean;
     rebuild?: boolean;
     force?: boolean;
+    timeout?: number;
     onProgress?: (message: string) => void;
 }
 export interface MaterializationResult {
@@ -27,6 +28,7 @@ export interface MaterializationStatus {
 }
 export declare class MaterializationClient {
     private config;
+    private operationClient;
     constructor(config: {
         baseUrl: string;
         credentials?: 'include' | 'same-origin' | 'omit';
@@ -36,11 +38,15 @@ export declare class MaterializationClient {
     /**
      * Materialize graph from DuckDB staging tables
      *
-     * Rebuilds the complete graph database from the current state of DuckDB
-     * staging tables. Automatically discovers all tables, materializes them in
-     * the correct order (nodes before relationships), and clears the staleness flag.
+     * Submits a materialization job to Dagster and monitors progress via SSE.
+     * The operation runs asynchronously on the server but this method waits
+     * for completion and returns the final result.
      */
     materialize(graphId: string, options?: MaterializationOptions): Promise<MaterializationResult>;
+    /**
+     * Convert SSE operation result to MaterializationResult
+     */
+    private convertOperationResult;
     /**
      * Get current materialization status for the graph
      *
@@ -48,4 +54,8 @@ export declare class MaterializationClient {
      * when it was last materialized, and how long since last materialization.
      */
     status(graphId: string): Promise<MaterializationStatus | null>;
+    /**
+     * Close any active SSE connections
+     */
+    close(): void;
 }

package/sdk-extensions/MaterializationClient.js

@@ -6,23 +6,25 @@ exports.MaterializationClient = void 0;
  * Materialization Client for RoboSystems API
  *
  * Manages graph materialization from DuckDB staging tables.
- * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ * Submits materialization jobs to Dagster and monitors progress via SSE.
  */
 const sdk_gen_1 = require("../sdk/sdk.gen");
+const OperationClient_1 = require("./OperationClient");
 class MaterializationClient {
     constructor(config) {
         this.config = config;
+        this.operationClient = new OperationClient_1.OperationClient(config);
     }
     /**
      * Materialize graph from DuckDB staging tables
      *
-     * Rebuilds the complete graph database from the current state of DuckDB
-     * staging tables. Automatically discovers all tables, materializes them in
-     * the correct order (nodes before relationships), and clears the staleness flag.
+     * Submits a materialization job to Dagster and monitors progress via SSE.
+     * The operation runs asynchronously on the server but this method waits
+     * for completion and returns the final result.
      */
     async materialize(graphId, options = {}) {
         try {
-            options.onProgress?.('Starting graph materialization...');
+            options.onProgress?.('Submitting materialization job...');
             const request = {
                 ignore_errors: options.ignoreErrors ?? true,
                 rebuild: options.rebuild ?? false,
@@ -44,19 +46,24 @@ class MaterializationClient {
                     error: `Failed to materialize graph: ${response.error}`,
                 };
             }
-            const result = response.data;
-            options.onProgress?.(`✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
-                `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`);
-            return {
-                status: result.status,
-                wasStale: result.was_stale,
-                staleReason: result.stale_reason,
-                tablesMaterialized: result.tables_materialized || [],
-                totalRows: result.total_rows || 0,
-                executionTimeMs: result.execution_time_ms || 0,
-                message: result.message || 'Materialization complete',
-                success: true,
-            };
+            const queuedResponse = response.data;
+            const operationId = queuedResponse.operation_id;
+            options.onProgress?.(`Materialization queued (operation: ${operationId})`);
+            // Monitor the operation via SSE until completion
+            const opResult = await this.operationClient.monitorOperation(operationId, {
+                timeout: (options.timeout ?? 600) * 1000, // Convert to milliseconds, 10 minute default
+                onProgress: (progress) => {
+                    if (options.onProgress) {
+                        let msg = progress.message;
+                        if (progress.progressPercent !== undefined) {
+                            msg += ` (${progress.progressPercent.toFixed(0)}%)`;
+                        }
+                        options.onProgress(msg);
+                    }
+                },
+            });
+            // Convert operation result to materialization result
+            return this.convertOperationResult(opResult, options);
         }
         catch (error) {
             return {
@@ -71,6 +78,43 @@ class MaterializationClient {
             };
         }
     }
+    /**
+     * Convert SSE operation result to MaterializationResult
+     */
+    convertOperationResult(opResult, options) {
+        if (opResult.success) {
+            // Extract details from SSE completion event result
+            const sseResult = opResult.result || {};
+            const tables = sseResult.tables_materialized || [];
+            const rows = sseResult.total_rows || 0;
+            const timeMs = sseResult.execution_time_ms || 0;
+            options.onProgress?.(`✅ Materialization complete: ${tables.length} tables, ` +
+                `${rows.toLocaleString()} rows in ${timeMs.toFixed(2)}ms`);
+            return {
+                status: 'success',
+                wasStale: sseResult.was_stale || false,
+                staleReason: sseResult.stale_reason,
+                tablesMaterialized: tables,
+                totalRows: rows,
+                executionTimeMs: timeMs,
+                message: sseResult.message || 'Graph materialized successfully',
+                success: true,
+            };
+        }
+        else {
+            // Operation failed or was cancelled
+            return {
+                status: 'failed',
+                wasStale: false,
+                tablesMaterialized: [],
+                totalRows: 0,
+                executionTimeMs: 0,
+                message: opResult.error || 'Operation failed',
+                success: false,
+                error: opResult.error,
+            };
+        }
+    }
     /**
      * Get current materialization status for the graph
      *
@@ -103,5 +147,11 @@ class MaterializationClient {
             return null;
         }
     }
+    /**
+     * Close any active SSE connections
+     */
+    close() {
+        this.operationClient.closeAll();
+    }
 }
 exports.MaterializationClient = MaterializationClient;

package/sdk-extensions/MaterializationClient.ts

@@ -4,16 +4,18 @@
  * Materialization Client for RoboSystems API
  *
  * Manages graph materialization from DuckDB staging tables.
- * Treats the graph database as a materialized view of the mutable DuckDB data lake.
+ * Submits materialization jobs to Dagster and monitors progress via SSE.
  */
 
 import { getMaterializationStatus, materializeGraph } from '../sdk/sdk.gen'
 import type { MaterializeRequest } from '../sdk/types.gen'
+import { OperationClient, type OperationResult } from './OperationClient'
 
 export interface MaterializationOptions {
   ignoreErrors?: boolean
   rebuild?: boolean
   force?: boolean
+  timeout?: number // Default 10 minutes
   onProgress?: (message: string) => void
 }
 
@@ -47,6 +49,7 @@ export class MaterializationClient {
     headers?: Record<string, string>
     token?: string
   }
+  private operationClient: OperationClient
 
   constructor(config: {
     baseUrl: string
@@ -55,21 +58,22 @@ export class MaterializationClient {
     token?: string
   }) {
     this.config = config
+    this.operationClient = new OperationClient(config)
   }
 
   /**
    * Materialize graph from DuckDB staging tables
    *
-   * Rebuilds the complete graph database from the current state of DuckDB
-   * staging tables. Automatically discovers all tables, materializes them in
-   * the correct order (nodes before relationships), and clears the staleness flag.
+   * Submits a materialization job to Dagster and monitors progress via SSE.
+   * The operation runs asynchronously on the server but this method waits
+   * for completion and returns the final result.
    */
   async materialize(
     graphId: string,
     options: MaterializationOptions = {}
   ): Promise<MaterializationResult> {
     try {
-      options.onProgress?.('Starting graph materialization...')
+      options.onProgress?.('Submitting materialization job...')
 
       const request: MaterializeRequest = {
         ignore_errors: options.ignoreErrors ?? true,
@@ -95,33 +99,82 @@ export class MaterializationClient {
         }
       }
 
-      const result = response.data as any
+      const queuedResponse = response.data as { operation_id: string; message: string }
+      const operationId = queuedResponse.operation_id
+
+      options.onProgress?.(`Materialization queued (operation: ${operationId})`)
+
+      // Monitor the operation via SSE until completion
+      const opResult = await this.operationClient.monitorOperation(operationId, {
+        timeout: (options.timeout ?? 600) * 1000, // Convert to milliseconds, 10 minute default
+        onProgress: (progress) => {
+          if (options.onProgress) {
+            let msg = progress.message
+            if (progress.progressPercent !== undefined) {
+              msg += ` (${progress.progressPercent.toFixed(0)}%)`
+            }
+            options.onProgress(msg)
+          }
+        },
+      })
+
+      // Convert operation result to materialization result
+      return this.convertOperationResult(opResult, options)
+    } catch (error) {
+      return {
+        status: 'failed',
+        wasStale: false,
+        tablesMaterialized: [],
+        totalRows: 0,
+        executionTimeMs: 0,
+        message: error instanceof Error ? error.message : String(error),
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  /**
+   * Convert SSE operation result to MaterializationResult
+   */
+  private convertOperationResult(
+    opResult: OperationResult,
+    options: MaterializationOptions
+  ): MaterializationResult {
+    if (opResult.success) {
+      // Extract details from SSE completion event result
+      const sseResult = opResult.result || {}
+
+      const tables = sseResult.tables_materialized || []
+      const rows = sseResult.total_rows || 0
+      const timeMs = sseResult.execution_time_ms || 0
 
       options.onProgress?.(
-        `✅ Materialization complete: ${result.tables_materialized?.length || 0} tables, ` +
-          `${result.total_rows?.toLocaleString() || 0} rows in ${result.execution_time_ms?.toFixed(2) || 0}ms`
+        `✅ Materialization complete: ${tables.length} tables, ` +
+          `${rows.toLocaleString()} rows in ${timeMs.toFixed(2)}ms`
       )
 
       return {
-        status: result.status,
-        wasStale: result.was_stale,
-        staleReason: result.stale_reason,
-        tablesMaterialized: result.tables_materialized || [],
-        totalRows: result.total_rows || 0,
-        executionTimeMs: result.execution_time_ms || 0,
-        message: result.message || 'Materialization complete',
+        status: 'success',
+        wasStale: sseResult.was_stale || false,
+        staleReason: sseResult.stale_reason,
+        tablesMaterialized: tables,
+        totalRows: rows,
+        executionTimeMs: timeMs,
+        message: sseResult.message || 'Graph materialized successfully',
         success: true,
       }
-    } catch (error) {
+    } else {
+      // Operation failed or was cancelled
       return {
         status: 'failed',
         wasStale: false,
         tablesMaterialized: [],
         totalRows: 0,
         executionTimeMs: 0,
-        message: error instanceof Error ? error.message : String(error),
+        message: opResult.error || 'Operation failed',
         success: false,
-        error: error instanceof Error ? error.message : String(error),
+        error: opResult.error,
       }
     }
   }
@@ -160,4 +213,11 @@ export class MaterializationClient {
       return null
     }
   }
+
+  /**
+   * Close any active SSE connections
+   */
+  close(): void {
+    this.operationClient.closeAll()
+  }
 }

package/sdk-extensions/README.md

@@ -1,6 +1,6 @@
 # RoboSystems Typescript Client Extensions
 
-🚀 **Enhanced SSE and Real-time Features** for the RoboSystems Typescript Client
+**Enhanced SSE and Real-time Features** for the RoboSystems Typescript Client
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -17,7 +17,7 @@ The RoboSystems Typescript Client Extensions provide production-ready enhancemen
 - **React Hooks** for seamless UI integration
 - **Full TypeScript Support** with comprehensive type definitions
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Installation
 
@@ -137,7 +137,7 @@ if (result.success) {
 }
 ```
 
-## 📊 SSE Event Types
+## SSE Event Types
 
 The SDK supports all RoboSystems SSE event types:
 
@@ -162,7 +162,7 @@ enum EventType {
 }
 ```
 
-## 🔄 Advanced SSE Features
+## Advanced SSE Features
 
 ### Automatic Reconnection
 
@@ -227,7 +227,7 @@ try {
 }
 ```
 
-## 📤 Table Ingestion
+## Table Ingestion
 
 ### TableIngestClient for Parquet File Uploads
 
@@ -250,9 +250,9 @@ const result = await tableClient.uploadParquetFile('graph-id', 'Entity', Buffer.
 })
 
 if (result.success) {
-  console.log(`✅ Uploaded ${result.rowCount} rows to ${result.tableName}`)
+  console.log(`Uploaded ${result.rowCount} rows to ${result.tableName}`)
 } else {
-  console.error(`❌ Upload failed: ${result.error}`)
+  console.error(`Upload failed: ${result.error}`)
 }
 ```
 
@@ -331,7 +331,7 @@ if (result.success) {
 }
 ```
 
-## 🎯 Operation Monitoring
+## Operation Monitoring
 
 ### OperationClient for Long-Running Tasks
 
@@ -420,7 +420,7 @@ await operationClient.monitor('operation-id', {
 })
 ```
 
-## ⚛️ React Integration
+## React Integration
 
 ### useSSE Hook
 
@@ -569,7 +569,7 @@ function DataImporter({ graphId }: { graphId: string }) {
 
       {result && result.status === 'completed' && (
         <div style={{ color: 'green' }}>
-          <p>✅ Successfully imported {result.rowsImported} rows</p>
+          <p>Successfully imported {result.rowsImported} rows</p>
           <p>Execution time: {(result.executionTimeMs / 1000).toFixed(2)}s</p>
         </div>
       )}
@@ -578,7 +578,7 @@ function DataImporter({ graphId }: { graphId: string }) {
 }
 ```
 
-## 🛡️ Error Handling & Resilience
+## Error Handling & Resilience
 
 ### Circuit Breaker Pattern
 
@@ -649,7 +649,7 @@ sseClient.on('connection_recycled', ({ old, new }) => {
 })
 ```
 
-## 🔧 Configuration
+## Configuration
 
 ### Environment Variables
 
@@ -713,7 +713,7 @@ const result = await extensions.files.upload('graph-id', 'TableName', fileBuffer
 })
 ```
 
-## 📊 Performance Optimization
+## Performance Optimization
 
 ### Stream Processing for Large Datasets
 
@@ -761,7 +761,7 @@ cachedClient.on('cache_invalidated', (query) => {
 })
 ```
 
-## 🧪 Testing
+## Testing
 
 ### Mock SSE for Testing
 
@@ -796,7 +796,7 @@ describe('SSE Integration', () => {
 })
 ```
 
-## 📚 API Reference
+## API Reference
 
 ### Core Classes
 
@@ -826,7 +826,7 @@ describe('SSE Integration', () => {
 - **`formatDuration`** - Human-readable duration formatting
 - **`parseSSEEvent`** - SSE event parsing utility
 
-## 🐛 Troubleshooting
+## Troubleshooting
 
 ### Common Issues
 
@@ -882,15 +882,15 @@ sseClient.on('*', (event, data) => {
 })
 ```
 
-## 📄 License
+## License
 
 MIT License - see [LICENSE](../../LICENSE) file for details.
 
-## 🤝 Contributing
+## Contributing
 
 See the [Contributing Guide](../../CONTRIBUTING.md) for development setup and guidelines.
 
-## 📞 Support
+## Support
 
 - **API Reference**: [api.robosystems.ai/docs](https://api.robosystems.ai/docs)
 - **Discord**: [Join our community](https://discord.gg/V9vjcqstxX)
@@ -899,5 +899,3 @@ See the [Contributing Guide](../../CONTRIBUTING.md) for development setup and gu
 ---
 
 **RoboSystems Typescript Client Extensions** - Production-ready SSE streaming and real-time monitoring for financial knowledge graphs.
-
-_Built with ❤️ by the RoboSystems team_

package/sdk.gen.d.ts

@@ -433,7 +433,7 @@ export declare const listAgents: <ThrowOnError extends boolean = false>(options:
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -494,7 +494,7 @@ export declare const getAgentMetadata: <ThrowOnError extends boolean = false>(op
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1708,7 +1708,7 @@ export declare const getFile: <ThrowOnError extends boolean = false>(options: Op
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/sdk.gen.js

@@ -1079,7 +1079,7 @@ exports.listAgents = listAgents;
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1176,7 +1176,7 @@ exports.getAgentMetadata = getAgentMetadata;
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -3130,7 +3130,7 @@ exports.getFile = getFile;
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/sdk.gen.ts

@@ -1092,7 +1092,7 @@ export const listAgents = <ThrowOnError extends boolean = false>(options: Option
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -1189,7 +1189,7 @@ export const getAgentMetadata = <ThrowOnError extends boolean = false>(options:
  * **Execution Strategies (automatic):**
  * - Fast operations (<5s): Immediate synchronous response
  * - Medium operations (5-30s): SSE streaming with progress updates
- * - Long operations (>30s): Async Celery worker with operation tracking
+ * - Long operations (>30s): Background queue with operation tracking
  *
  * **Response Mode Override:**
  * Use query parameter `?mode=sync|async` to override automatic strategy selection.
@@ -3143,7 +3143,7 @@ export const getFile = <ThrowOnError extends boolean = false>(options: Options<G
  * **What Happens (status='uploaded'):**
  * 1. File validated in S3
  * 2. Row count calculated
- * 3. DuckDB staging triggered immediately (Celery task)
+ * 3. DuckDB staging triggered immediately (background task)
  * 4. If ingest_to_graph=true, graph ingestion queued
  * 5. File queryable in DuckDB within seconds
  *

package/types.gen.d.ts

@@ -3018,43 +3018,24 @@ export type MaterializeRequest = {
 };
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message

package/types.gen.ts

@@ -3112,43 +3112,24 @@ export type MaterializeRequest = {
 
 /**
  * MaterializeResponse
+ * Response for queued materialization operation.
  */
 export type MaterializeResponse = {
     /**
      * Status
-     * Materialization status
+     * Operation status
      */
-    status: string;
+    status?: string;
     /**
      * Graph Id
      * Graph database identifier
      */
     graph_id: string;
     /**
-     * Was Stale
-     * Whether graph was stale before materialization
-     */
-    was_stale: boolean;
-    /**
-     * Stale Reason
-     * Reason graph was stale
-     */
-    stale_reason?: string | null;
-    /**
-     * Tables Materialized
-     * List of tables successfully materialized
-     */
-    tables_materialized: Array<string>;
-    /**
-     * Total Rows
-     * Total rows materialized across all tables
-     */
-    total_rows: number;
-    /**
-     * Execution Time Ms
-     * Total materialization time
+     * Operation Id
+     * SSE operation ID for progress tracking
      */
-    execution_time_ms: number;
+    operation_id: string;
     /**
      * Message
      * Human-readable status message