@superblocksteam/sdk-api 0.0.4

package/src/integrations/python/README.md

@@ -0,0 +1,566 @@
+# Python Client
+
+Execute Python scripts with type-safe inputs and outputs using the Superblocks SDK.
+
+## 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
+- Access to installed packages (requests, etc.)
+
+## Basic Usage
+
+```typescript
+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(),
+  }),
+
+  output: z.object({
+    greeting: z.string(),
+    timestamp: z.number(),
+  }),
+
+  async run(ctx, { userId }) {
+    const result = await ctx.integrations.runtime.run(
+      `
+      import time
+
+      # userId is available as a direct Python variable
+      current_time = int(time.time())
+
+      # Return a dictionary matching your output schema
+      return {
+        "greeting": f"Hello user {userId}!",
+        "timestamp": current_time
+      }
+      `,
+      z.object({
+        greeting: z.string(),
+        timestamp: z.number(),
+      }),
+      {
+        userId,
+      },
+    );
+
+    return result;
+  },
+});
+```
+
+## API Reference
+
+### `ctx.integrations.<name>.run<T>(code, schema, bindings?, metadata?): Promise<T>`
+
+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. Do not pass `TraceMetadata` here; use the `metadata` parameter instead.
+- `metadata` (TraceMetadata, optional): Trace metadata for diagnostics labeling (see [Trace Metadata](#trace-metadata)).
+
+**Returns:** Promise resolving to validated result matching the schema.
+
+**Throws:** `CodeExecutionError` if execution fails or validation fails.
+
+**Important:** Your Python code must use a `return` statement to return a value.
+
+> **Note:** Because `bindings` and `metadata` are both plain objects, take care not
+> to pass metadata as the third argument. If you need metadata but no bindings,
+> pass `undefined` for `bindings` explicitly:
+>
+> ```typescript
+> await ctx.integrations.runtime.run(code, schema, undefined, {
+>   label: "My trace label",
+> });
+> ```
+
+## Binding Syntax
+
+Bindings are passed as a map and automatically injected as Python variables. Reference them directly in your code by their key names:
+
+```typescript
+// 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
+  return {
+    "message": f"{userName} is {userAge} years old",
+    "active": isActive
+  }
+  `,
+  z.object({
+    message: z.string(),
+    active: z.boolean(),
+  }),
+  {
+    userName: "Alice",
+    userAge: 30,
+    isActive: true,
+  },
+);
+```
+
+The SDK automatically injects bindings as Python variables before your code executes, making them available for immediate use.
+
+## Examples
+
+### Data Transformation
+
+Transform data from another step or API:
+
+```typescript
+// Transform user data (use ctx.integrations.runtime if you declared runtime: python(...))
+const transformed = await ctx.integrations.runtime.run(
+  `
+  import json
+
+  users = {{userList}}
+
+  # Filter and transform
+  active_users = [
+    {
+      "id": u["id"],
+      "email": u["email"],
+      "displayName": f"{u['firstName']} {u['lastName']}"
+    }
+    for u in users
+    if u["status"] == "active"
+  ]
+
+  return {"users": active_users, "count": len(active_users)}
+  `,
+  z.object({
+    users: z.array(
+      z.object({
+        id: z.string(),
+        email: z.string(),
+        displayName: z.string(),
+      }),
+    ),
+    count: z.number(),
+  }),
+  {
+    userList: await getUsersFromDatabase(),
+  },
+);
+```
+
+### HTTP Requests with Requests Library
+
+Make HTTP requests using the `requests` library:
+
+```typescript
+const apiData = await ctx.integrations.runtime.run(
+  `
+  import requests
+
+  api_url = {{apiUrl}}
+  api_key = {{apiKey}}
+
+  response = requests.get(
+    api_url,
+    headers={"Authorization": f"Bearer {api_key}"}
+  )
+
+  data = response.json()
+
+  return {
+    "status": response.status_code,
+    "data": data
+  }
+  `,
+  z.object({
+    status: z.number(),
+    data: z.any(),
+  }),
+  {
+    apiUrl: "https://api.example.com/data",
+    apiKey: ctx.env.API_KEY,
+  },
+);
+```
+
+### Complex Data Processing
+
+Process and aggregate data:
+
+```typescript
+const stats = await ctx.integrations.runtime.run(
+  `
+  import statistics
+
+  values = {{values}}
+
+  return {
+    "mean": statistics.mean(values),
+    "median": statistics.median(values),
+    "stdev": statistics.stdev(values),
+    "min": min(values),
+    "max": max(values)
+  }
+  `,
+  z.object({
+    mean: z.number(),
+    median: z.number(),
+    stdev: z.number(),
+    min: z.number(),
+    max: z.number(),
+  }),
+  {
+    values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+  },
+);
+```
+
+### Combining with Database Queries
+
+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(),
+  }),
+
+  output: z.object({
+    summary: z.string(),
+    totalSales: z.number(),
+    topProducts: z.array(z.string()),
+  }),
+
+  async run(ctx, { startDate, endDate }) {
+    // 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`,
+      z.object({
+        product_id: z.string(),
+        product_name: z.string(),
+        amount: z.number(),
+      }),
+      [startDate, endDate],
+    );
+
+    // Process with Python via ctx.integrations.runtime
+    const analysis = await ctx.integrations.runtime.run(
+      `
+      sales_data = {{salesData}}
+
+      # Group by product
+      from collections import defaultdict
+      product_totals = defaultdict(float)
+
+      for sale in sales_data:
+        product_totals[sale["product_name"]] += sale["amount"]
+
+      # Get top products
+      sorted_products = sorted(
+        product_totals.items(),
+        key=lambda x: x[1],
+        reverse=True
+      )
+      top_5 = [p[0] for p in sorted_products[:5]]
+
+      total = sum(product_totals.values())
+
+      return {
+        "summary": f"Analyzed {len(sales_data)} sales across {len(product_totals)} products",
+        "totalSales": total,
+        "topProducts": top_5
+      }
+      `,
+      z.object({
+        summary: z.string(),
+        totalSales: z.number(),
+        topProducts: z.array(z.string()),
+      }),
+      {
+        salesData: sales,
+      },
+    );
+
+    return analysis;
+  },
+});
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Error Handling
+
+The client throws `CodeExecutionError` when execution or validation fails:
+
+```typescript
+import { CodeExecutionError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.runtime.run(
+    `
+    x = {{value}}
+    return {"result": x * 2}
+    `,
+    z.object({ result: z.number() }),
+    { value: 10 },
+  );
+} catch (error) {
+  if (error instanceof CodeExecutionError) {
+    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);
+    } else if (error.details?.originalError) {
+      // Runtime error in Python code
+      console.error("Python error:", error.details.originalError);
+    }
+  }
+}
+```
+
+## Common Patterns
+
+### Environment Variables
+
+Access environment variables in Python:
+
+```typescript
+const result = await ctx.integrations.runtime.run(
+  `
+  # apiKey and environment are directly available as Python variables
+  return {
+    "configured": apiKey is not None,
+    "environment": environment
+  }
+  `,
+  z.object({
+    configured: z.boolean(),
+    environment: z.string(),
+  }),
+  {
+    apiKey: ctx.env.API_KEY,
+    environment: ctx.env.NODE_ENV,
+  },
+);
+```
+
+### JSON Processing
+
+Work with JSON data:
+
+```typescript
+const processed = await ctx.integrations.runtime.run(
+  `
+  import json
+
+  json_str = {{jsonString}}
+  data = json.loads(json_str)
+
+  # Modify data
+  data["processed"] = True
+  data["timestamp"] = 1234567890
+
+  return {"result": json.dumps(data)}
+  `,
+  z.object({
+    result: z.string(),
+  }),
+  {
+    jsonString: JSON.stringify({ foo: "bar" }),
+  },
+);
+```
+
+## Best Practices
+
+### 1. Keep Python Code Focused
+
+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 ctx.integrations.runtime.run(`...transform logic...`, schema, { data });
+```
+
+❌ **Avoid:**
+
+```typescript
+// Don't make database connections in Python
+await ctx.integrations.runtime.run(
+  `
+  import psycopg2
+  conn = psycopg2.connect(...)  # Avoid this
+  ...
+`,
+  schema,
+);
+```
+
+### 2. Validate All Inputs and Outputs
+
+Always provide a schema to validate Python return values:
+
+✅ **Good:**
+
+```typescript
+const result = await ctx.integrations.runtime.run(
+  code,
+  z.object({
+    value: z.number(),
+    message: z.string(),
+  }),
+  bindings,
+);
+```
+
+❌ **Avoid:**
+
+```typescript
+// Missing schema - no type safety!
+const result = await ctx.integrations.runtime.run(code, z.any(), bindings);
+```
+
+### 3. Use Meaningful Binding Names
+
+Choose clear binding names that match Python conventions:
+
+✅ **Good:**
+
+```typescript
+{
+  user_id: "123",
+  start_date: "2024-01-01",
+  is_active: true
+}
+```
+
+❌ **Avoid:**
+
+```typescript
+{
+  userId: "123",    // Mixing camelCase in Python
+  StartDate: "...", // PascalCase doesn't fit Python
+}
+```
+
+### 4. Handle Errors Gracefully
+
+Use try/catch and check for specific error types:
+
+```typescript
+try {
+  const result = await ctx.integrations.runtime.run(code, schema, bindings);
+  return result;
+} catch (error) {
+  if (error instanceof CodeExecutionError) {
+    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 error;
+}
+```
+
+## Troubleshooting
+
+### "Python execution result validation failed"
+
+The return value from your Python code doesn't match the provided schema.
+
+**Solution:** Check that your Python `return` statement matches the schema exactly:
+
+```typescript
+// Schema expects
+z.object({ count: z.number(), items: z.array(z.string()) });
+
+// Python must return
+return { count: 5, items: ["a", "b", "c"] };
+```
+
+### "Python execution failed"
+
+The Python code had a runtime error.
+
+**Common causes:**
+
+- Syntax errors in Python code
+- Undefined variables or bindings
+- Import errors for unavailable packages
+- Division by zero or other runtime exceptions
+
+**Solution:** Test Python code snippets independently, check that all `{{}}` bindings are provided.
+
+### Missing Binding Values
+
+If a binding is `undefined` or `null`, the orchestrator may handle it differently.
+
+**Solution:** Always provide explicit values for bindings:
+
+```typescript
+// In your run function with destructured input:
+async run(ctx, { value, name }) {
+  const result = await ctx.integrations.runtime.run(
+    code,
+    schema,
+    {
+      value: value ?? 0,  // Provide default
+      name: name || "Unknown"
+    }
+  );
+}
+```
+
+## 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)
+
+For specific package requirements, consult your Superblocks environment documentation.
+
+## See Also
+
+- [API Reference](../../../README.md) - Main SDK documentation
+- [Error Handling](../../../README.md#error-handling) - Error types and handling strategies
+- [Best Practices](../../../README.md#best-practices) - General SDK best practices