@superblocksteam/sdk-api 2.0.93-next.7 → 2.0.94-next.0

package/src/integrations/python/README.md

@@ -5,6 +5,7 @@ Execute Python scripts with type-safe inputs and outputs using the Superblocks S
 ## Overview
 
 The Python client allows you to run Python code with:
+
 - Type-safe input bindings via `{{}}` syntax
 - Output validation using Zod schemas
 - Full Python 3 standard library support
@@ -13,10 +14,16 @@ The Python client allows you to run Python code with:
 ## Basic Usage
 
 ```typescript
-import { api, z } from '@superblocksteam/sdk-api';
+import { api, z, python } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PYTHON_RUNTIME = "a1b2c3d4-5678-90ab-cdef-python00001";
 
 export default api({
   name: "PythonExample",
+  integrations: {
+    runtime: python(PYTHON_RUNTIME),
+  },
   input: z.object({
     userId: z.string(),
   }),
@@ -27,9 +34,7 @@ export default api({
   }),
 
   async run(ctx, { userId }) {
-    const python = ctx.python('Python Runtime');
-
-    const result = await python.run(
+    const result = await ctx.integrations.runtime.run(
       `
       import time
 
@@ -48,7 +53,7 @@ export default api({
       }),
       {
         userId,
-      }
+      },
     );
 
     return result;
@@ -58,11 +63,12 @@ export default api({
 
 ## API Reference
 
-### `python.run<T>(code, schema, bindings?): Promise<T>`
+### `ctx.integrations.<name>.run<T>(code, schema, bindings?): Promise<T>`
 
-Executes Python code with validated output.
+Executes Python code with validated output. Use the **key name** you declared in `integrations` (e.g. `ctx.integrations.runtime.run(...)` if you declared `runtime: python(...)`).
 
 **Parameters:**
+
 - `code` (string): Python script to execute. Bindings are automatically injected as Python variables.
 - `schema` (ZodSchema<T>): **Required** Zod schema for validating the return value.
 - `bindings` (Record<string, unknown>, optional): Key/value pairs that become Python variables in your code.
@@ -78,9 +84,8 @@ Executes Python code with validated output.
 Bindings are passed as a map and automatically injected as Python variables. Reference them directly in your code by their key names:
 
 ```typescript
-const python = ctx.python('Python Runtime');
-
-const result = await python.run(
+// In your run(): use the key you declared in integrations (e.g. runtime: python(...))
+const result = await ctx.integrations.runtime.run(
   `
   # Bindings are available as direct Python variables
   # No {{}} syntax needed - just use the variable names directly
@@ -96,8 +101,8 @@ const result = await python.run(
   {
     userName: "Alice",
     userAge: 30,
-    isActive: true
-  }
+    isActive: true,
+  },
 );
 ```
 
@@ -110,10 +115,8 @@ The SDK automatically injects bindings as Python variables before your code exec
 Transform data from another step or API:
 
 ```typescript
-const python = ctx.python('Python Runtime');
-
-// Transform user data
-const transformed = await python.run(
+// Transform user data (use ctx.integrations.runtime if you declared runtime: python(...))
+const transformed = await ctx.integrations.runtime.run(
   `
   import json
 
@@ -133,16 +136,18 @@ const transformed = await python.run(
   return {"users": active_users, "count": len(active_users)}
   `,
   z.object({
-    users: z.array(z.object({
-      id: z.string(),
-      email: z.string(),
-      displayName: z.string(),
-    })),
+    users: z.array(
+      z.object({
+        id: z.string(),
+        email: z.string(),
+        displayName: z.string(),
+      }),
+    ),
     count: z.number(),
   }),
   {
-    userList: await getUsersFromDatabase()
-  }
+    userList: await getUsersFromDatabase(),
+  },
 );
 ```
 
@@ -151,9 +156,7 @@ const transformed = await python.run(
 Make HTTP requests using the `requests` library:
 
 ```typescript
-const python = ctx.python('Python Runtime');
-
-const apiData = await python.run(
+const apiData = await ctx.integrations.runtime.run(
   `
   import requests
 
@@ -178,8 +181,8 @@ const apiData = await python.run(
   }),
   {
     apiUrl: "https://api.example.com/data",
-    apiKey: ctx.env.API_KEY
-  }
+    apiKey: ctx.env.API_KEY,
+  },
 );
 ```
 
@@ -188,9 +191,7 @@ const apiData = await python.run(
 Process and aggregate data:
 
 ```typescript
-const python = ctx.python('Python Runtime');
-
-const stats = await python.run(
+const stats = await ctx.integrations.runtime.run(
   `
   import statistics
 
@@ -212,8 +213,8 @@ const stats = await python.run(
     max: z.number(),
   }),
   {
-    values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
-  }
+    values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+  },
 );
 ```
 
@@ -222,8 +223,17 @@ const stats = await python.run(
 Use Python to process database results:
 
 ```typescript
+import { api, z, postgres, python } from "@superblocksteam/sdk-api";
+
+const PROD_POSTGRES = "a1b2c3d4-5678-90ab-cdef-postgres01";
+const PYTHON_RUNTIME = "a1b2c3d4-5678-90ab-cdef-python00001";
+
 export default api({
   name: "PythonExample",
+  integrations: {
+    db: postgres(PROD_POSTGRES),
+    runtime: python(PYTHON_RUNTIME),
+  },
   input: z.object({
     startDate: z.string(),
     endDate: z.string(),
@@ -236,9 +246,8 @@ export default api({
   }),
 
   async run(ctx, { startDate, endDate }) {
-    // Query database
-    const postgres = ctx.postgres('Production Postgres');
-    const sales = await postgres.query(
+    // Query database via ctx.integrations.db
+    const sales = await ctx.integrations.db.query(
       `SELECT product_id, product_name, amount
        FROM sales
        WHERE sale_date BETWEEN $1 AND $2`,
@@ -247,12 +256,11 @@ export default api({
         product_name: z.string(),
         amount: z.number(),
       }),
-      [startDate, endDate]
+      [startDate, endDate],
     );
 
-    // Process with Python
-    const python = ctx.python('Python Runtime');
-    const analysis = await python.run(
+    // Process with Python via ctx.integrations.runtime
+    const analysis = await ctx.integrations.runtime.run(
       `
       sales_data = {{salesData}}
 
@@ -285,8 +293,8 @@ export default api({
         topProducts: z.array(z.string()),
       }),
       {
-        salesData: sales
-      }
+        salesData: sales,
+      },
     );
 
     return analysis;
@@ -299,28 +307,28 @@ export default api({
 The client throws `CodeExecutionError` when execution or validation fails:
 
 ```typescript
-import { CodeExecutionError } from '@superblocksteam/sdk-api';
+import { CodeExecutionError } from "@superblocksteam/sdk-api";
 
 try {
-  const result = await python.run(
+  const result = await ctx.integrations.runtime.run(
     `
     x = {{value}}
     return {"result": x * 2}
     `,
     z.object({ result: z.number() }),
-    { value: 10 }
+    { value: 10 },
   );
 } catch (error) {
   if (error instanceof CodeExecutionError) {
-    console.error('Python execution failed:', error.message);
+    console.error("Python execution failed:", error.message);
 
     if (error.details?.zodError) {
       // Validation error - result didn't match schema
-      console.error('Validation errors:', error.details.zodError.issues);
-      console.error('Actual result:', error.details.result);
+      console.error("Validation errors:", error.details.zodError.issues);
+      console.error("Actual result:", error.details.result);
     } else if (error.details?.originalError) {
       // Runtime error in Python code
-      console.error('Python error:', error.details.originalError);
+      console.error("Python error:", error.details.originalError);
     }
   }
 }
@@ -333,7 +341,7 @@ try {
 Access environment variables in Python:
 
 ```typescript
-const result = await python.run(
+const result = await ctx.integrations.runtime.run(
   `
   # apiKey and environment are directly available as Python variables
   return {
@@ -347,8 +355,8 @@ const result = await python.run(
   }),
   {
     apiKey: ctx.env.API_KEY,
-    environment: ctx.env.NODE_ENV
-  }
+    environment: ctx.env.NODE_ENV,
+  },
 );
 ```
 
@@ -357,7 +365,7 @@ const result = await python.run(
 Work with JSON data:
 
 ```typescript
-const processed = await python.run(
+const processed = await ctx.integrations.runtime.run(
   `
   import json
 
@@ -374,8 +382,8 @@ const processed = await python.run(
     result: z.string(),
   }),
   {
-    jsonString: JSON.stringify({ foo: "bar" })
-  }
+    jsonString: JSON.stringify({ foo: "bar" }),
+  },
 );
 ```
 
@@ -386,22 +394,27 @@ const processed = await python.run(
 Python steps should perform data transformation and processing. Use integration clients for I/O operations:
 
 ✅ **Good:**
+
 ```typescript
 // Fetch data with integration client
 const data = await postgres.query(...);
 
 // Transform with Python
-const processed = await python.run(`...transform logic...`, schema, { data });
+const processed = await ctx.integrations.runtime.run(`...transform logic...`, schema, { data });
 ```
 
 ❌ **Avoid:**
+
 ```typescript
 // Don't make database connections in Python
-await python.run(`
+await ctx.integrations.runtime.run(
+  `
   import psycopg2
   conn = psycopg2.connect(...)  # Avoid this
   ...
-`, schema);
+`,
+  schema,
+);
 ```
 
 ### 2. Validate All Inputs and Outputs
@@ -409,21 +422,23 @@ await python.run(`
 Always provide a schema to validate Python return values:
 
 ✅ **Good:**
+
 ```typescript
-const result = await python.run(
+const result = await ctx.integrations.runtime.run(
   code,
   z.object({
     value: z.number(),
     message: z.string(),
   }),
-  bindings
+  bindings,
 );
 ```
 
 ❌ **Avoid:**
+
 ```typescript
 // Missing schema - no type safety!
-const result = await python.run(code, z.any(), bindings);
+const result = await ctx.integrations.runtime.run(code, z.any(), bindings);
 ```
 
 ### 3. Use Meaningful Binding Names
@@ -431,6 +446,7 @@ const result = await python.run(code, z.any(), bindings);
 Choose clear binding names that match Python conventions:
 
 ✅ **Good:**
+
 ```typescript
 {
   user_id: "123",
@@ -440,6 +456,7 @@ Choose clear binding names that match Python conventions:
 ```
 
 ❌ **Avoid:**
+
 ```typescript
 {
   userId: "123",    // Mixing camelCase in Python
@@ -453,16 +470,16 @@ Use try/catch and check for specific error types:
 
 ```typescript
 try {
-  const result = await python.run(code, schema, bindings);
+  const result = await ctx.integrations.runtime.run(code, schema, bindings);
   return result;
 } catch (error) {
   if (error instanceof CodeExecutionError) {
-    ctx.log.error('Python execution failed', {
+    ctx.log.error("Python execution failed", {
       code: error.details?.code,
       bindings: error.details?.bindings,
     });
     // Provide fallback or rethrow
-    throw new Error('Data processing failed');
+    throw new Error("Data processing failed");
   }
   throw error;
 }
@@ -478,10 +495,10 @@ The return value from your Python code doesn't match the provided schema.
 
 ```typescript
 // Schema expects
-z.object({ count: z.number(), items: z.array(z.string()) })
+z.object({ count: z.number(), items: z.array(z.string()) });
 
 // Python must return
-return {"count": 5, "items": ["a", "b", "c"]}
+return { count: 5, items: ["a", "b", "c"] };
 ```
 
 ### "Python execution failed"
@@ -489,6 +506,7 @@ return {"count": 5, "items": ["a", "b", "c"]}
 The Python code had a runtime error.
 
 **Common causes:**
+
 - Syntax errors in Python code
 - Undefined variables or bindings
 - Import errors for unavailable packages
@@ -505,7 +523,7 @@ If a binding is `undefined` or `null`, the orchestrator may handle it differentl
 ```typescript
 // In your run function with destructured input:
 async run(ctx, { value, name }) {
-  const result = await python.run(
+  const result = await ctx.integrations.runtime.run(
     code,
     schema,
     {
@@ -519,6 +537,7 @@ async run(ctx, { value, name }) {
 ## Available Python Packages
 
 The Python runtime includes:
+
 - Python 3.x standard library
 - `requests` - HTTP library
 - Common data science packages (check with your Superblocks administrator for the full list)