@statelyai/agent 0.0.4 → 0.0.5

package/.vscode/launch.json

@@ -1,17 +1,17 @@
 {
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
   // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
     {
       "type": "node",
       "request": "launch",
-      "name": "Launch Program",
-      "skipFiles": ["<node_internals>/**"],
-      "program": "${file}",
-      "preLaunchTask": "tsc: build - tsconfig.json",
-      "outFiles": ["${workspaceFolder}/**/*.js"]
+      "name": "Debug Current Test File",
+      "autoAttachChildProcesses": true,
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
+      "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
+      "args": ["run", "${relativeFile}"],
+      "smartStep": true,
+      "console": "integratedTerminal"
     }
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @statelyai/agent
 
+## 0.0.5
+
+### Patch Changes
+
+- [#9](https://github.com/statelyai/agent/pull/9) [`d8e7b67`](https://github.com/statelyai/agent/commit/d8e7b673f6d265f37b2096b25d75310845860271) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Add `adapter.fromTool(…)`, which creates an actor that chooses agent logic based on a input.
+
+  ```ts
+  const actor = adapter.fromTool(() => "Draw me a picture of a donut", {
+    // tools
+    makeIllustration: {
+      description: "Makes an illustration",
+      run: async (input) => {
+        /* ... */
+      },
+      inputSchema: {
+        /* ... */
+      },
+    },
+    getWeather: {
+      description: "Gets the weather",
+      run: async (input) => {
+        /* ... */
+      },
+      inputSchema: {
+        /* ... */
+      },
+    },
+  });
+
+  //...
+  ```
+
 ## 0.0.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -3,8 +3,8 @@ import { Prop, Values, AnyStateMachine, createActor, PromiseActorLogic, AnyEvent
 import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
 import { FromSchema } from 'json-schema-to-ts';
 import OpenAI from 'openai';
-import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
-import { ChatCompletionCreateParamsBase, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from 'openai/resources';
 
 type EventSchemas = {
     [key: string]: {
@@ -50,14 +50,9 @@ declare function createSchemas<TContextSchema extends ContextSchema, TEventSchem
 
 declare function createAgent<T extends AnyStateMachine>(...args: Parameters<typeof createActor<T>>): xstate.Actor<T>;
 
-interface OpenAIAdapterOutput<T extends {
-    model: ChatCompletionCreateParamsBase['model'];
-}> {
-    model: T['model'];
-    /**
-     * Determines which event to send to the parent state machine actor based on the prompt.
-     */
-    fromEventChoice: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, options?: {
+interface StatelyAgentAdapter {
+    model: string;
+    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, options?: {
         /**
          * Immediately execute sending the event to the parent actor.
          * @default true
@@ -72,9 +67,28 @@ interface OpenAIAdapterOutput<T extends {
      * Creates observable actor logic that emits a chat completion stream.
      */
     fromChatStream: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming) => ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+    fromTool: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, tools: {
+        [key: string]: Tool<any, any>;
+    }, options?: {
+        /**
+         * Immediately execute sending the event to the parent actor.
+         * @default true
+         */
+        execute?: boolean;
+    }) => PromiseActorLogic<{
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+    } | undefined, TInput>;
 }
+interface Tool<TInput, TOutput> {
+    description: string;
+    inputSchema: any;
+    run: (input: TInput) => TOutput;
+}
+
 declare function createOpenAIAdapter<T extends {
     model: ChatCompletionCreateParamsBase['model'];
-}>(openai: OpenAI, settings: T): OpenAIAdapterOutput<T>;
+}>(openai: OpenAI, settings: T): StatelyAgentAdapter;
 
 export { createAgent, createOpenAIAdapter, createSchemas };

package/dist/index.js

@@ -134,7 +134,7 @@ function fromChatStream(openai, agentSettings, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, agentSettings, inputFn, options) {
+function fromEvent(openai, agentSettings, inputFn, options) {
   return (0, import_xstate2.fromPromise)(
     async ({ input, self, system }) => {
       const parentSnapshot = self._parent?.getSnapshot();
@@ -194,15 +194,60 @@ function fromEventChoice(openai, agentSettings, inputFn, options) {
     }
   );
 }
+function fromTool(openai, agentSettings, tools, inputFn) {
+  return (0, import_xstate2.fromPromise)(async ({ input, self, system }) => {
+    const functionNameMapping = {};
+    const resolvedTools = Object.entries(tools).map(([key, value]) => {
+      return {
+        type: "function",
+        function: {
+          name: key,
+          description: value.description,
+          parameters: value.inputSchema
+        }
+      };
+    });
+    const openAiInput = inputFn(input);
+    const completionParams = typeof openAiInput === "string" ? {
+      model: agentSettings.model,
+      messages: [
+        {
+          role: "user",
+          content: openAiInput
+        }
+      ]
+    } : openAiInput;
+    const completion = await openai.chat.completions.create({
+      ...completionParams,
+      tools: resolvedTools
+    });
+    const toolCalls = completion.choices[0]?.message.tool_calls;
+    if (toolCalls?.length) {
+      const toolCall = toolCalls[0];
+      const tool = tools[toolCall.function.name];
+      const args = JSON.parse(toolCall.function.arguments);
+      if (tool) {
+        const result = await tool.run(args);
+        return {
+          toolCall,
+          tool: toolCall.function.name,
+          result
+        };
+      }
+    }
+    return void 0;
+  });
+}
 function createOpenAIAdapter(openai, settings) {
   const agentSettings = {
     model: settings.model,
-    fromEventChoice: (input) => (
+    fromEvent: (input) => (
       // @ts-ignore infinitely deep
-      fromEventChoice(openai, agentSettings, input, { execute: true })
+      fromEvent(openai, agentSettings, input, { execute: true })
     ),
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
-    fromChatStream: (input) => fromChatStream(openai, agentSettings, input)
+    fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
+    fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input)
   };
   return agentSettings;
 }

package/examples/joke.ts

@@ -61,7 +61,7 @@ const getTopic = fromPromise(async () => {
   return topic;
 });
 
-const decide = adapter.fromEventChoice(
+const decide = adapter.fromEvent(
   (lastRating: string) =>
     `Choose what to do next, given the previous rating of the joke: ${lastRating}`
 );

package/examples/ticTacToe.ts

@@ -80,7 +80,7 @@ const initialContext = {
   events: [],
 } satisfies typeof schemas.types.context;
 
-const bot = adapter.fromEventChoice(
+const bot = adapter.fromEvent(
   ({ context }: { context: typeof schemas.types.context }) => `
 You are playing a game of tic tac toe. This is the current game state. The 3x3 board is represented by a 9-element array. The first element is the top-left cell, the second element is the top-middle cell, the third element is the top-right cell, the fourth element is the middle-left cell, and so on. The value of each cell is either null, x, or o. The value of null means that the cell is empty. The value of x means that the cell is occupied by an x. The value of o means that the cell is occupied by an o.
 

package/examples/weather.ts

@@ -84,7 +84,7 @@ const machine = setup({
   types: schemas.types,
   actors: {
     getWeather,
-    decide: adapter.fromEventChoice(
+    decide: adapter.fromEvent(
       (input: string) =>
         `Decide what to do based on the given input, which may or may not be a location: ${input}`
     ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -17,7 +17,8 @@
     "openai": "^4.24.1",
     "ts-node": "^10.9.2",
     "tsup": "^8.0.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.2"
   },
   "publishConfig": {
     "access": "public"

package/src/adapter.test.ts

@@ -0,0 +1,217 @@
+import { test, expect } from 'vitest';
+import { createOpenAIAdapter, createTool } from './adapters/openai';
+import OpenAI from 'openai';
+import { createActor, toPromise } from 'xstate';
+
+test('fromTool - weather or illustration', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-3.5-turbo',
+  });
+
+  const toolChoice = adapter.fromTool(() => 'Create an image of a donut', {
+    makeIllustration: {
+      description: 'Make an illustration',
+      run: async () => 'Illustration',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'The name of the illustration',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    getWeather: {
+      description: 'Get the weather for a location',
+      run: async () => 'Weather',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'object',
+            properties: {
+              city: {
+                type: 'string',
+                description: 'The name of the city',
+              },
+              state: {
+                type: 'string',
+                description: 'The name of the state',
+              },
+            },
+            required: ['city', 'state'],
+          },
+        },
+        required: ['location'],
+      },
+    },
+  });
+
+  const actor = createActor(toolChoice);
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.result).toBe('Illustration');
+});
+
+test('fromTool - GitHub PR description inserter', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-3.5-turbo-16k-0613',
+  });
+
+  const toolChoice = adapter.fromTool(
+    (input: string) =>
+      `Create a GitHub PR description for the following: ${input}`,
+    {
+      fetchGitHubPR: {
+        description: 'Fetch a GitHub PR',
+        run: async (input: string) => {
+          return {
+            title: 'Title',
+            body: input,
+          };
+        },
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repo: {
+              type: 'string',
+              description: 'The name of the repo',
+            },
+            number: {
+              type: 'number',
+              description: 'The number of the PR',
+            },
+          },
+          required: ['repo', 'number'],
+        },
+      },
+      createPullRequestDescription: {
+        description: 'Create a GitHub PR description',
+        run: () => 'Description',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: {
+              type: 'string',
+              description: 'The title of the PR',
+            },
+            body: {
+              type: 'string',
+              description: 'The body of the PR',
+            },
+          },
+          required: ['title', 'body'],
+        },
+      },
+    }
+  );
+
+  const actor = createActor(toolChoice, {
+    input:
+      // 'Get the details from this: https://github.com/microsoft/TypeScript/pull/47198',
+      'Make a summary of this PR: (some code here)',
+  });
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.tool).toEqual('createPullRequestDescription');
+  expect(res?.result).toEqual('Description');
+});
+
+test('fromTool - joke creator or rater', async () => {
+  const openAi = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  const adapter = createOpenAIAdapter(openAi, {
+    model: 'gpt-4-1106-preview',
+  });
+
+  const rateJoke = createTool({
+    description: 'Rate a joke',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        joke: {
+          type: 'string',
+          description: 'The joke to rate',
+        },
+      },
+    },
+    run: async ({ topic }: { topic: string }) => {
+      return `Here is a joke about ${topic}`;
+    },
+  });
+
+  const createJoke = createTool({
+    description: 'Create a joke',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          description: 'The category of the joke',
+        },
+      },
+      required: ['category'],
+    },
+    run: async () => {
+      return 'Some joke';
+    },
+  });
+
+  const toolChoice = adapter.fromTool(
+    (input: string) => `
+The user provided this input:
+
+<input>
+${input}
+</input>
+
+Determine what to do:
+- If the input is asking for a joke, create a joke,
+- But if the input is providing a joke, then rate the joke.
+    `,
+    {
+      rateJoke,
+      createJoke,
+    }
+  );
+
+  const actor = createActor(toolChoice, {
+    // input: 'Why did the chicken cross the road? To get to the other side!',
+    input: 'Tell me a joke about chickens',
+  });
+
+  actor.start();
+
+  const res = await toPromise(actor);
+
+  expect(res?.tool).toEqual('createJoke');
+  expect(res?.result).toEqual('Some joke');
+
+  const actor2 = createActor(toolChoice, {
+    input:
+      'Check this joke out: Why did the chicken cross the road? To get to the other side!',
+  });
+
+  actor2.start();
+
+  const res2 = await toPromise(actor2);
+  expect(res2?.tool).toEqual('rateJoke');
+});

package/src/adapters/openai.ts

@@ -15,6 +15,7 @@ import {
   ChatCompletionCreateParamsBase,
   ChatCompletionCreateParamsStreaming,
 } from 'openai/resources/chat/completions';
+import { StatelyAgentAdapter, Tool } from '../types';
 
 /**
  * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that uses the OpenAI API to generate a completion.
@@ -117,7 +118,7 @@ export function fromChatStream<TInput>(
  * @param openai The OpenAI instance to use.
  * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
  */
-export function fromEventChoice<TInput>(
+export function fromEvent<TInput>(
   openai: OpenAI,
   agentSettings: OpenAIAdapterOutput<any>,
   inputFn: (
@@ -206,6 +207,95 @@ export function fromEventChoice<TInput>(
   );
 }
 
+export function createTool<TInput, T>({
+  description,
+  inputSchema,
+  run,
+}: Tool<TInput, T>): Tool<TInput, T> {
+  return {
+    description,
+    inputSchema,
+    run,
+  };
+}
+
+/**
+ * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that passes the next possible transitions as functions to [OpenAI tool calls](https://platform.openai.com/docs/guides/function-calling) and returns an array of potential next events.
+ *
+ * @param openai The OpenAI instance to use.
+ * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
+ */
+export function fromTool<TInput>(
+  openai: OpenAI,
+  agentSettings: StatelyAgentAdapter,
+  tools: {
+    [key: string]: Tool<any, any>;
+  },
+  inputFn: (
+    input: TInput
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+) {
+  return fromPromise<
+    | {
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+      }
+    | undefined,
+    TInput
+  >(async ({ input, self, system }) => {
+    const functionNameMapping: Record<string, string> = {};
+    const resolvedTools = Object.entries(tools).map(([key, value]) => {
+      return {
+        type: 'function',
+        function: {
+          name: key,
+          description: value.description,
+          parameters: value.inputSchema,
+        },
+      } as const;
+    });
+
+    const openAiInput = inputFn(input);
+    const completionParams: ChatCompletionCreateParamsNonStreaming =
+      typeof openAiInput === 'string'
+        ? {
+            model: agentSettings.model,
+            messages: [
+              {
+                role: 'user',
+                content: openAiInput,
+              },
+            ],
+          }
+        : openAiInput;
+    const completion = await openai.chat.completions.create({
+      ...completionParams,
+      tools: resolvedTools,
+    });
+
+    const toolCalls = completion.choices[0]?.message.tool_calls;
+
+    if (toolCalls?.length) {
+      const toolCall = toolCalls[0]!;
+      const tool = tools[toolCall.function.name];
+      const args = JSON.parse(toolCall.function.arguments);
+
+      if (tool) {
+        const result = await tool.run(args);
+
+        return {
+          toolCall,
+          tool: toolCall.function.name,
+          result,
+        };
+      }
+    }
+
+    return undefined;
+  });
+}
+
 interface OpenAIAdapterOutput<
   T extends {
     model: ChatCompletionCreateParamsBase['model'];
@@ -215,7 +305,7 @@ interface OpenAIAdapterOutput<
   /**
    * Determines which event to send to the parent state machine actor based on the prompt.
    */
-  fromEventChoice: <TInput>(
+  fromEvent: <TInput>(
     inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
     options?: {
       /**
@@ -246,14 +336,15 @@ export function createOpenAIAdapter<
   T extends {
     model: ChatCompletionCreateParamsBase['model'];
   }
->(openai: OpenAI, settings: T): OpenAIAdapterOutput<T> {
-  const agentSettings: OpenAIAdapterOutput<T> = {
+>(openai: OpenAI, settings: T): StatelyAgentAdapter {
+  const agentSettings: StatelyAgentAdapter = {
     model: settings.model,
-    fromEventChoice: (input) =>
+    fromEvent: (input) =>
       // @ts-ignore infinitely deep
-      fromEventChoice(openai, agentSettings, input, { execute: true }) as any,
+      fromEvent(openai, agentSettings, input, { execute: true }) as any,
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
     fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
+    fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input),
   };
 
   return agentSettings;

package/src/types.ts

@@ -0,0 +1,69 @@
+import OpenAI from 'openai';
+import {
+  ChatCompletionCreateParamsNonStreaming,
+  ChatCompletionCreateParamsStreaming,
+} from 'openai/resources';
+import {
+  AnyActorLogic,
+  AnyActorRef,
+  AnyEventObject,
+  ObservableActorLogic,
+  PromiseActorLogic,
+} from 'xstate';
+
+export interface StatelyAgentAdapter {
+  model: string;
+  fromEvent: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
+    options?: {
+      /**
+       * Immediately execute sending the event to the parent actor.
+       * @default true
+       */
+      execute?: boolean;
+    }
+  ) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+  /**
+   * Creates promise actor logic that resolves with a chat completion.
+   */
+  fromChat: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
+  ) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
+  /**
+   * Creates observable actor logic that emits a chat completion stream.
+   */
+  fromChatStream: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming
+  ) => ObservableActorLogic<
+    OpenAI.Chat.Completions.ChatCompletionChunk,
+    TInput
+  >;
+
+  fromTool: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
+    tools: {
+      [key: string]: Tool<any, any>;
+    },
+    options?: {
+      /**
+       * Immediately execute sending the event to the parent actor.
+       * @default true
+       */
+      execute?: boolean;
+    }
+  ) => PromiseActorLogic<
+    | {
+        result: any;
+        tool: string;
+        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
+      }
+    | undefined,
+    TInput
+  >;
+}
+
+export interface Tool<TInput, TOutput> {
+  description: string;
+  inputSchema: any;
+  run: (input: TInput) => TOutput;
+}