feat(ai): pipedream ai sdk (#16699)

TheBestMoshe · web-flow · commit 852838a411fc · 2025-05-16T16:39:44.000-04:00
diff --git a/packages/ai/.env.example b/packages/ai/.env.example
@@ -0,0 +1,7 @@
+OPENAI_API_KEY=
+
+# Get these by following https://pipedream.com/docs/connect/managed-auth/quickstart/#getting-started
+PIPEDREAM_CLIENT_ID=
+PIPEDREAM_CLIENT_SECRET=
+PIPEDREAM_PROJECT_ID=
+PIPEDREAM_PROJECT_ENVIRONMENT=
diff --git a/packages/ai/.gitignore b/packages/ai/.gitignore
@@ -0,0 +1,3 @@
+.env
+node_modules
+dist
diff --git a/packages/ai/README.md b/packages/ai/README.md
@@ -0,0 +1,37 @@
+# @pipedream/ai
+
+> This library is in alpha status. The API is subject to breaking changes.
+
+Create a .env file based on the .env.example file.
+
+Basic example:
+```ts
+import { OpenAiTools } from "@pipedream/ai"
+import { OpenAI } from "openai"
+
+const openai = new OpenAI()
+
+// Replace with a unique identifier for your user
+const userId = <add user id here>
+
+const openAiTools = new OpenAiTools(userId)
+const tools = await openAiTools.getTools({
+  app: "slack",
+})
+
+const completion = await openai.chat.completions.create({
+  messages: [
+    {
+      role: "user",
+      content: "Send a joke to #random channel",
+    },
+  ],
+  model: "gpt-4o",
+  tools,
+})
+
+const results = await openAiTools.handleCompletion(completion)
+
+console.log(JSON.stringify(results, null, 2))
+
+```
diff --git a/packages/ai/package.json b/packages/ai/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@pipedream/ai",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Pipedream AI",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@pipedream/sdk": "workspace:^",
+    "zod": "^3.24.4",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "devDependencies": {
+    "bun": "^1.2.13",
+    "openai": "^4.77.0"
+  }
+}
diff --git a/packages/ai/src/configurablePropsToZod.ts b/packages/ai/src/configurablePropsToZod.ts
@@ -0,0 +1,107 @@
+import {
+  ConfigurableProps, V1Component,
+} from "@pipedream/sdk";
+import {
+  z, ZodRawShape,
+} from "zod";
+import {
+  extractEnumValues, toNonEmptyTuple,
+} from "./lib/helpers";
+
+export const configurablePropsToZod = (
+  component: V1Component,
+  options?: {
+    asyncOptionsDescription?: string;
+    configureComponentDescription?: string;
+    configurableProps?: ConfigurableProps;
+  },
+) => {
+  const schema: ZodRawShape = {};
+
+  for (const cp of options?.configurableProps ||
+    (component.configurable_props as ConfigurableProps)) {
+    if (cp.hidden) {
+      continue;
+    }
+
+    if (cp.type === "app") {
+      // XXX handle directly in implementation
+      continue;
+    } else if (cp.type === "string") {
+      if (cp.options && Array.isArray(cp.options) && cp.options.length > 0) {
+        const enumValues = toNonEmptyTuple(extractEnumValues(cp.options));
+        if (enumValues) {
+          schema[cp.name] = z.enum(enumValues);
+        } else {
+          schema[cp.name] = z.string();
+        }
+      } else {
+        schema[cp.name] = z.string();
+      }
+    } else if (cp.type === "string[]") {
+      if (cp.options && Array.isArray(cp.options) && cp.options.length > 0) {
+        const enumValues = toNonEmptyTuple(extractEnumValues(cp.options));
+        if (enumValues) {
+          schema[cp.name] = z.array(z.enum(enumValues));
+        } else {
+          schema[cp.name] = z.array(z.string());
+        }
+      } else {
+        schema[cp.name] = z.array(z.string());
+      }
+    } else if (cp.type === "$.discord.channel") {
+      schema[cp.name] = z.string();
+    } else if (cp.type === "$.discord.channel[]") {
+      schema[cp.name] = z.array(z.string());
+    } else if (cp.type === "object") {
+      schema[cp.name] = z.object({}).passthrough();
+    } else if (cp.type === "any") {
+      schema[cp.name] = z.any();
+    } else if (cp.type === "integer") {
+      schema[cp.name] = z.number().int();
+    } else if (cp.type === "integer[]") {
+      schema[cp.name] = z.array(z.number().int());
+    } else if (cp.type === "boolean") {
+      schema[cp.name] = z.boolean();
+    } else if (cp.type === "boolean[]") {
+      schema[cp.name] = z.array(z.boolean());
+      // ignore alerts, as no user input required
+    } else {
+      console.error("unhandled type. Skipping", cp.name, cp.type);
+    }
+
+    if (schema[cp.name]) {
+      if (cp.optional) {
+        schema[cp.name] = schema[cp.name].optional().nullable();
+      }
+
+      let description: string = cp.description || "";
+
+      if (cp.hidden) {
+        description +=
+          "\n\nIMPORTANT: This property is hidden. Do not configure it and leave it blank.\n";
+      }
+
+      if (cp.remoteOptions) {
+        if (options?.asyncOptionsDescription) {
+          if (options.configureComponentDescription) {
+            description += `\n\n${options.asyncOptionsDescription}`;
+          }
+        } else {
+          if (options?.configureComponentDescription) {
+            description += `\n\n${options.configureComponentDescription}`;
+          }
+        }
+        // if (cp.name.includes("id")) {
+        //   description += `\n\nIMPORTANT: An ID is required for this property. If you don't have the id and only have the name, use the "${CONFIGURE_COMPONENT_TOOL_NAME}" tool to get the values.`;
+        // }
+      }
+
+      if (description.trim()) {
+        schema[cp.name] = schema[cp.name].describe(description.trim());
+      }
+    }
+  }
+
+  return schema;
+};
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
@@ -0,0 +1,3 @@
+export {
+  OpenAiTools,
+} from "./tool-sets/openai"
diff --git a/packages/ai/src/lib/componentAppKey.ts b/packages/ai/src/lib/componentAppKey.ts
@@ -0,0 +1,5 @@
+import { ConfigurableProps } from "@pipedream/sdk";
+
+export const componentAppKey = (configuredProps: ConfigurableProps) => {
+  return configuredProps.find((prop) => prop.type === "app")?.app;
+};
diff --git a/packages/ai/src/lib/config.ts b/packages/ai/src/lib/config.ts
@@ -0,0 +1,21 @@
+import { z } from "zod";
+
+const configSchema = z.object({
+  PIPEDREAM_CLIENT_ID: z.string().min(1, {
+    message: "PIPEDREAM_CLIENT_ID is required",
+  }),
+  PIPEDREAM_CLIENT_SECRET: z.string().min(1, {
+    message: "PIPEDREAM_CLIENT_SECRET is required",
+  }),
+  PIPEDREAM_PROJECT_ID: z.string().min(1, {
+    message: "PIPEDREAM_PROJECT_ID is required",
+  }),
+  PIPEDREAM_PROJECT_ENVIRONMENT: z.enum([
+    "development",
+    "production",
+  ]),
+});
+
+export const config = configSchema.parse(process?.env);
+
+export type Config = z.infer<typeof configSchema>;
diff --git a/packages/ai/src/lib/helpers.ts b/packages/ai/src/lib/helpers.ts
@@ -0,0 +1,15 @@
+export function toNonEmptyTuple<T extends string>(
+  arr: T[],
+): [T, ...T[]] | undefined {
+  return arr.length > 0
+    ? (arr as [T, ...T[]])
+    : undefined;
+}
+
+type EnumLike = string | { value: string };
+
+export function extractEnumValues(values: EnumLike[]): string[] {
+  return values.map((v) => (typeof v === "string"
+    ? v
+    : v.value));
+}
diff --git a/packages/ai/src/lib/pd-client.ts b/packages/ai/src/lib/pd-client.ts
@@ -0,0 +1,11 @@
+import { createBackendClient } from "@pipedream/sdk";
+import { config } from "./config";
+
+export const pd = createBackendClient({
+  credentials: {
+    clientId: config.PIPEDREAM_CLIENT_ID,
+    clientSecret: config.PIPEDREAM_CLIENT_SECRET,
+  },
+  projectId: config.PIPEDREAM_PROJECT_ID,
+  environment: config.PIPEDREAM_PROJECT_ENVIRONMENT,
+});
diff --git a/packages/ai/src/tool-sets/core.ts b/packages/ai/src/tool-sets/core.ts
@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { configurablePropsToZod } from "../configurablePropsToZod";
+import { pd } from "../lib/pd-client";
+import {
+  Account, V1Component,
+} from "@pipedream/sdk";
+import { componentAppKey } from "../lib/componentAppKey";
+
+type Tool = {
+  name: string;
+  description?: string;
+  schema: z.ZodObject<z.ZodRawShape>;
+  execute: (args: Record<string, unknown>) => Promise<unknown>;
+};
+
+export class CoreTools {
+  userId: string;
+  tools: Tool[] = [];
+
+  constructor(userId: string) {
+    this.userId = userId;
+  }
+
+  async getTools(options?: { app?: string; query?: string }) {
+    const { data: components } = await pd.getComponents({
+      app: options?.app,
+      q: options?.query,
+    });
+
+    for (const component of components) {
+      this.tools.push({
+        name: component.name.replace(/[^a-zA-Z0-9_-]/g, "_"),
+        description: component.description,
+        schema: z.object(configurablePropsToZod(component)),
+        execute: (args) => this.executeTool(component, args),
+      });
+    }
+
+    return this.tools;
+  }
+
+  async getTool(name: string) {
+    return this.tools.find((tool) => tool.name === name);
+  }
+
+  async executeTool(component: V1Component, args: Record<string, unknown>) {
+    const appKey = componentAppKey(component.configurable_props);
+
+    if (!appKey) {
+      throw new Error("App name not found");
+    }
+
+    const authProvision = await this.getAuthProvision({
+      app: appKey,
+      uuid: this.userId,
+    });
+
+    if (typeof authProvision === "string") {
+      return authProvision;
+    }
+
+    return pd.runAction({
+      actionId: component.key,
+      configuredProps: {
+        ...args,
+        [appKey]: {
+          authProvisionId: authProvision.id,
+        },
+      },
+      externalUserId: this.userId,
+    });
+  }
+
+  async getAuthProvision({
+    app,
+    uuid,
+  }: {
+    app: string;
+    uuid: string;
+  }): Promise<Account | string> {
+    const authProvisions = await pd.getAccounts({
+      external_user_id: uuid,
+      include_credentials: false,
+      app,
+    });
+
+    const authProvision = authProvisions.data.find((ap) => ap.healthy);
+
+    if (!authProvision) {
+      const token = await pd.createConnectToken({
+        external_user_id: uuid,
+        webhook_uri: "https://eokyfjps7uqmmrk.m.pipedream.net", // https://pipedream.com/@pd/p_G6Ck6Mk/
+      });
+      return `
+  The user MUST be shown the following URL so they can click on it to connect their account and you MUST NOT modify the URL or it will break: https://pipedream.com/_static/connect.html?token=${token.token}&connectLink=true&app=${encodeURIComponent(app)}
+              `.trim();
+    }
+
+    return authProvision;
+  }
+}
diff --git a/packages/ai/src/tool-sets/openai.ts b/packages/ai/src/tool-sets/openai.ts
diff --git a/packages/ai/tsconfig.json b/packages/ai/tsconfig.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export {`
	`2`	`+ OpenAiTools,`
	`3`	`+} from "./tool-sets/openai"`