@superblocksteam/sdk-api 2.0.105 → 2.0.106-next.0

package/src/integrations/python/README.md

@@ -1,566 +0,0 @@
-# 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