feat: update oas and add planner docs

.github/workflows/check-oas-updates.yml

@@ -2,8 +2,8 @@ name: Check OAS Updates
 
 on:
   schedule:
-    # Run at 00:00 UTC on Monday, Wednesday, and Friday
-    - cron: "0 0 * * 1,3,5"
+    # Run at 00:00 UTC every weekday
+    - cron: "0 0 * * 1-5"
   workflow_dispatch:
     # Allow manual triggering
 

README.md

@@ -1,6 +1,58 @@
-# StackOne AI Node.js SDK
+# StackOne AI SDK
 
-StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
+> A unified interface for performing actions on SaaS tools through AI-friendly APIs.
+
+## Toolsets
+
+StackOne provides two toolsets:
+
+- `OpenAPIToolSet`: A toolset generated from supplied OpenAPI specifications
+- `StackOneToolSet`: A toolset preloaded with StackOne APIs
+
+These toolsets provide functionality to filter, transform, and execute tools and have integrations to common AI Agent libraries.
+
+Under the hood the StackOneToolSet uses the same OpenAPIParser as the OpenAPIToolSet, but provides some convenience methods for using StackOne API keys and account IDs.
+
+### Workflow Planning
+
+While building agents you may find that your workflow is too complex for a general purpose agent.
+
+StackOne AI SDK provides access to a state of the art planning agent which allows you to create, cache, and execute complex workflows on [verticals supported by StackOne](https://www.stackone.com/integrations).
+
+For example, onboard a new hire from your ATS to your HRIS.
+
+```typescript
+import { StackOneToolSet } from "@stackone/ai";
+
+const toolset = new StackOneToolSet();
+
+const onboardWorkflow = await toolset.plan({
+  key: "custom_onboarding",
+  input: "Onboard the last new hire from Teamtailor to Workday",
+  model: "stackone-planner-latest",
+  tools: ["hris_*", "ats_*"],
+  accountIds: ["teamtailor_account_id", "workday_account_id"],
+  cache: true, // saves the plan to $HOME/.stackone/plans
+});
+
+// Execute the workflow
+await onboardWorkflow.execute();
+```
+
+Or use it as a tool in a larger agent (using AI SDK)
+
+```typescript
+await generateText({
+  model: openai("gpt-4o"),
+  prompt: "You are a workplace agent, onboard the latest hires to our systems",
+  tools: onboardWorkflow.toAISDK(),
+  maxSteps: 3,
+});
+```
+> [!NOTE]  
+> The workflow planner is in closed beta and only available to design partners. Apply for the waitlist [here](https://www.stackone.com/demo).
+
+[View full example](examples/planning.ts)
 
 ## Installation
 
@@ -15,18 +67,9 @@ yarn add @stackone/ai
 bun add @stackone/ai
 ```
 
-## Toolsets
-
-StackOne provides two toolsets:
-
-- `OpenAPIToolSet`: A toolset generated from OpenAPI specifications
-- `StackOneToolSet`: A toolset for StackOne APIs
-
-Under the hood the StackOneToolSet uses the same OpenAPIParser as the OpenAPIToolSet, but provides some convenience methods for using StackOne API keys and account IDs.
-
 ## Integrations
 
-These integrations work with both the OpenAPIToolSet and StackOneToolSet. They make it super easy to use these APIs in your AI applications.
+The OpenAPIToolSet and StackOneToolSet make it super easy to use these APIs as tools in your AI applications.
 
 ### OpenAI
 
@@ -151,6 +194,8 @@ const toolsetWithHeaders = new OpenAPIToolSet({
 });
 ```
 
+[View full example](examples/openapi-toolset.ts)
+
 ## StackOneToolSet
 
 The StackOneToolSet is an extension of the OpenAPIToolSet that adds some convenience methods for using StackOne API keys and account IDs and some other features.
@@ -273,6 +318,8 @@ const toolset = new OpenAPIToolSet({
 const result = await tool.execute({ user_id: "user123" });
 ```
 
+[View full example](examples/openapi-transformations.ts)
+
 ### Testing with dryRun
 
 You can use the `dryRun` option to return the api arguments from a tool call without making the actual api call:

examples/planning.ts

@@ -0,0 +1,41 @@
+/**
+ * While building agents you may find that your workflow is too complex for a general purpose agent.
+ *
+ * StackOne AI SDK provides access to a state of the art planning agent which allows you to create, cache, and execute complex workflows on [verticals supported by StackOne](https://www.stackone.com/integrations).
+ *
+ * For example, onboard a new hire from your ATS to your HRIS.
+ */
+
+import { StackOneToolSet } from '../src';
+
+const toolset = new StackOneToolSet();
+
+const onboardWorkflow = await toolset.plan({
+  key: 'custom_onboarding',
+  input: 'Onboard the last new hire from Teamtailor to Workday',
+  model: 'stackone-planner-latest',
+  tools: ['hris_*', 'ats_*'],
+  accountIds: ['teamtailor_account_id', 'workday_account_id'],
+  cache: true, // saves the plan to $HOME/.stackone/plans
+});
+
+await onboardWorkflow.execute();
+
+/**
+ * or use as part of a larger agent (using AI SDK by Vercel)
+ */
+
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'You are a workplace agent, onboard the latest hires to our systems',
+  tools: onboardWorkflow.toAISDK(),
+  maxSteps: 3,
+});
+
+/*
+ * The planning model is in closed beta and only available to design partners.
+ * Apply for the waitlist [here](https://www.stackone.com/demo).
+ */

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stackone/ai",
   "version": "0.0.7",
-  "description": "Agents performing actions on your SaaS",
+  "description": "Tools to let agents perform actions on your SaaS",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,20 +33,17 @@
     "@types/bun": "^1.2.4",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^22.13.5",
+    "@ai-sdk/openai": "^1.1.14",
+    "openai": "^4.85.4",
     "dotenv": "^16.3.1",
     "husky": "^9.1.7",
     "json-schema": "^0.4.0",
     "lint-staged": "^15.2.0",
     "mkdocs": "^0.0.1",
     "openapi-types": "^12.1.3",
     "rimraf": "^6.0.1",
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "@ai-sdk/openai": "^1.1.14",
-    "ai": "^4.1.46",
-    "openai": "^4.85.4",
-    "zod": "^3.24.2"
+    "typescript": "^5.0.0",
+    "ai": "^4.1.46"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"