@statelyai/agent 0.0.2 → 0.0.4

package/examples/joke.ts

@@ -1,13 +1,13 @@
 import OpenAI from 'openai';
-import { assign, fromPromise, createActor, setup, log, raise } from 'xstate';
-import { createAgent } from '../src';
+import { assign, fromCallback, fromPromise, log, setup } from 'xstate';
+import { createAgent, createOpenAIAdapter, createSchemas } from '../src';
+import { loadingAnimation } from './helpers/loader';
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
 });
 
-const agent = createAgent(openai, {
-  model: 'gpt-3.5-turbo-1106',
+const schemas = createSchemas({
   context: {
     topic: { type: 'string' },
     jokes: {
@@ -15,24 +15,41 @@ const agent = createAgent(openai, {
       items: {
         type: 'string',
       },
-      desire: { type: ['string', 'null'] },
-      lastRating: { type: ['string', 'null'] },
+    },
+    desire: { type: ['string', 'null'] as const },
+    lastRating: { type: ['string', 'null'] as const },
+  },
+  events: {
+    askForTopic: {
+      type: 'object',
+      properties: {
+        topic: {
+          type: 'string',
+        },
+      },
+    },
+    endJokes: {
+      type: 'object',
+      properties: {},
     },
   },
-  events: {},
 });
 
-const promptTemplate = (topic: string) => `Tell me a joke about ${topic}.`;
+const adapter = createOpenAIAdapter(openai, {
+  model: 'gpt-3.5-turbo-1106',
+});
 
-const getJokeCompletion = agent.fromChatCompletion(promptTemplate);
+const getJokeCompletion = adapter.fromChat(
+  (topic: string) => `Tell me a joke about ${topic}.`
+);
 
-const rateJoke = agent.fromChatCompletion(
+const rateJoke = adapter.fromChat(
   (joke: string) => `Rate this joke on a scale of 1 to 10: ${joke}`
 );
 
 const getTopic = fromPromise(async () => {
   const topic = await new Promise<string>((res) => {
-    console.log('Give me a topic: \n\n');
+    console.log('Give me a joke topic:');
     const listener = (data: Buffer) => {
       const result = data.toString().trim();
       process.stdin.off('data', listener);
@@ -44,33 +61,66 @@ const getTopic = fromPromise(async () => {
   return topic;
 });
 
-const decide = agent.fromEventChoice(
+const decide = adapter.fromEventChoice(
   (lastRating: string) =>
     `Choose what to do next, given the previous rating of the joke: ${lastRating}`
 );
+export function getRandomFunnyPhrase() {
+  const funnyPhrases = [
+    'Concocting chuckles...',
+    'Brewing belly laughs...',
+    'Fabricating funnies...',
+    'Assembling amusement...',
+    'Molding merriment...',
+    'Whipping up wisecracks...',
+    'Generating guffaws...',
+    'Inventing hilarity...',
+    'Cultivating chortles...',
+    'Hatching howlers...',
+  ];
+  return funnyPhrases[Math.floor(Math.random() * funnyPhrases.length)]!;
+}
+
+export function getRandomRatingPhrase() {
+  const ratingPhrases = [
+    'Assessing amusement...',
+    'Evaluating hilarity...',
+    'Ranking chuckles...',
+    'Classifying cackles...',
+    'Scoring snickers...',
+    'Rating roars...',
+    'Judging jollity...',
+    'Measuring merriment...',
+    'Rating rib-ticklers...',
+  ];
+  return ratingPhrases[Math.floor(Math.random() * ratingPhrases.length)]!;
+}
+
+const loader = fromCallback(({ input }: { input: string }) => {
+  const anim = loadingAnimation(input);
+
+  return () => {
+    anim.stop();
+  };
+});
 
 const jokeMachine = setup({
-  types: {
-    context: {} as {
-      topic: string;
-      jokes: string[];
-      desire: string | null;
-      lastRating: string | null;
-    },
-    input: {} as { topic: string },
-  },
+  schemas,
+  types: schemas.types,
   actors: {
     getJokeCompletion,
     getTopic,
     rateJoke,
     decide,
+    loader,
   },
 }).createMachine({
-  context: ({ input }) => ({
-    topic: input.topic,
+  context: () => ({
+    topic: '',
     jokes: [],
     desire: null,
     lastRating: null,
+    loader: null,
   }),
   initial: 'waitingForTopic',
   states: {
@@ -86,56 +136,69 @@ const jokeMachine = setup({
       },
     },
     tellingJoke: {
-      invoke: {
-        src: 'getJokeCompletion',
-        input: ({ context }) => context.topic,
-        onDone: {
-          actions: [
-            assign({
-              jokes: ({ context, event }) =>
-                context.jokes.concat(event.output.choices[0]!.message.content!),
-            }),
-            log((x) => x.context.jokes.at(-1)),
-          ],
-          target: 'rateJoke',
+      invoke: [
+        {
+          src: 'getJokeCompletion',
+          input: ({ context }) => context.topic,
+          onDone: {
+            actions: [
+              assign({
+                jokes: ({ context, event }) =>
+                  context.jokes.concat(
+                    event.output.choices[0]!.message.content!
+                  ),
+              }),
+              log((x) => `\n` + x.context.jokes.at(-1)),
+            ],
+            target: 'rateJoke',
+          },
         },
-      },
+        {
+          src: 'loader',
+          input: getRandomFunnyPhrase,
+        },
+      ],
     },
     rateJoke: {
-      invoke: {
-        src: 'rateJoke',
-        input: ({ context }) => context.jokes[context.jokes.length - 1]!,
-        onDone: {
-          actions: [
-            assign({
-              lastRating: ({ event }) =>
-                event.output.choices[0]!.message.content!,
-            }),
-            log(({ context }) => context.lastRating),
-          ],
-          target: 'decide',
+      invoke: [
+        {
+          src: 'rateJoke',
+          input: ({ context }) => context.jokes[context.jokes.length - 1]!,
+          onDone: {
+            actions: [
+              assign({
+                lastRating: ({ event }) =>
+                  event.output.choices[0]!.message.content!,
+              }),
+              log(({ context }) => '\n' + context.lastRating),
+            ],
+            target: 'decide',
+          },
         },
-      },
+        {
+          src: 'loader',
+          input: getRandomRatingPhrase,
+        },
+      ],
     },
     decide: {
       invoke: {
         src: 'decide',
         input: ({ context }) => context.lastRating!,
         onDone: {
-          actions: [
-            log(({ event }) => event),
-            raise(({ event }) => event.output![0]!),
-          ],
+          actions: log(({ event }) => event),
         },
       },
       on: {
         askForTopic: {
           target: 'waitingForTopic',
+          actions: log("That joke wasn't good enough. Let's try again."),
           description:
             'Ask for a new topic, because the last joke rated 6 or lower',
         },
         endJokes: {
           target: 'end',
+          actions: log('That joke was good enough. Goodbye!'),
           description: 'End the jokes, since the last joke rated 7 or higher',
         },
       },
@@ -144,8 +207,10 @@ const jokeMachine = setup({
       type: 'final',
     },
   },
+  exit: () => {
+    process.exit();
+  },
 });
 
-const actor = createActor(jokeMachine);
-
-actor.start();
+const agent = createAgent(jokeMachine);
+agent.start();

package/examples/ticTacToe.ts

@@ -1,6 +1,6 @@
-import { assign, setup, assertEvent, createActor, raise } from 'xstate';
+import { assign, setup, assertEvent } from 'xstate';
 import OpenAI from 'openai';
-import { createAgent } from '../src/openai';
+import { createOpenAIAdapter, createSchemas, createAgent } from '../src';
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
@@ -8,8 +8,7 @@ const openai = new OpenAI({
 
 type Player = 'x' | 'o';
 
-const agent = createAgent(openai, {
-  model: 'gpt-3.5-turbo-1106',
+const schemas = createSchemas({
   context: {
     board: {
       type: 'array',
@@ -30,11 +29,6 @@ const agent = createAgent(openai, {
       enum: ['x', 'o'],
       description: 'The player whose turn it is',
     },
-    winner: {
-      type: ['null', 'string'],
-      enum: [null, 'x', 'o'],
-      description: 'The player who won the game',
-    },
     gameReport: {
       type: 'string',
       description: 'The game report',
@@ -74,17 +68,20 @@ const agent = createAgent(openai, {
   },
 });
 
+const adapter = createOpenAIAdapter(openai, {
+  model: 'gpt-4-1106-preview',
+});
+
 const initialContext = {
   board: Array(9).fill(null) as Array<Player | null>,
   moves: 0,
   player: 'x' as Player,
-  winner: null as Player | null,
   gameReport: '',
   events: [],
-} satisfies typeof agent.types.context;
+} satisfies typeof schemas.types.context;
 
-const bot = agent.fromEventChoice(
-  ({ context }: { context: typeof agent.types.context }) => `
+const bot = adapter.fromEventChoice(
+  ({ 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.
 
 ${JSON.stringify(context, null, 2)}
@@ -92,14 +89,12 @@ ${JSON.stringify(context, null, 2)}
 Execute the single best next move to try to win the game. Do not play on an existing cell.`
 );
 
-const gameReporter = agent.fromChatCompletionStream(
+const gameReporter = adapter.fromChatStream(
   ({
     context,
   }: {
-    context: typeof agent.types.context;
-  }) => `The tic-tac-toe game is over. The winner is ${
-    context.winner ?? 'nobody'
-  }. This was the ending board state, represented as a 9-element array:
+    context: typeof schemas.types.context;
+  }) => `Here is the game board:
 
 ${JSON.stringify(context.board, null, 2)}
 
@@ -107,11 +102,33 @@ And here are the events that led to this game state:
 
 ${context.events.join('\n')}
 
+The winner is ${getWinner(context.board)}.
+
 Provide a very short game report analyzing the game.`
 );
 
+function getWinner(board: typeof initialContext.board): Player | null {
+  const lines = [
+    [0, 1, 2],
+    [3, 4, 5],
+    [6, 7, 8],
+    [0, 3, 6],
+    [1, 4, 7],
+    [2, 5, 8],
+    [0, 4, 8],
+    [2, 4, 6],
+  ] as const;
+  for (const [a, b, c] of lines) {
+    if (board[a] !== null && board[a] === board[b] && board[a] === board[c]) {
+      return board[a]!;
+    }
+  }
+  return null;
+}
+
 export const ticTacToeMachine = setup({
-  types: agent.types,
+  schemas,
+  types: schemas.types,
   actors: {
     bot,
     gameReporter,
@@ -131,9 +148,6 @@ export const ticTacToeMachine = setup({
       },
     }),
     resetGame: assign(initialContext),
-    setWinner: assign({
-      winner: ({ context }) => (context.player === 'x' ? 'o' : 'x'),
-    }),
     recordEvent: assign({
       events: ({ context, event }) => {
         return [...context.events, JSON.stringify(event)];
@@ -142,37 +156,9 @@ export const ticTacToeMachine = setup({
   },
   guards: {
     checkWin: ({ context }) => {
-      const { board } = context;
-      const winningLines = [
-        [0, 1, 2],
-        [3, 4, 5],
-        [6, 7, 8],
-        [0, 3, 6],
-        [1, 4, 7],
-        [2, 5, 8],
-        [0, 4, 8],
-        [2, 4, 6],
-      ];
-
-      for (let line of winningLines) {
-        const xWon = line.every((index) => {
-          return board[index] === 'x';
-        });
+      const winner = getWinner(context.board);
 
-        if (xWon) {
-          return true;
-        }
-
-        const oWon = line.every((index) => {
-          return board[index] === 'o';
-        });
-
-        if (oWon) {
-          return true;
-        }
-      }
-
-      return false;
+      return !!winner;
     },
     checkDraw: ({ context }) => {
       return context.moves === 9;
@@ -202,11 +188,6 @@ export const ticTacToeMachine = setup({
           invoke: {
             src: 'bot',
             input: ({ context }) => ({ context }),
-            onDone: {
-              actions: raise(({ event }) => {
-                return event.output![0] as any;
-              }),
-            },
           },
           on: {
             'x.play': [
@@ -223,11 +204,6 @@ export const ticTacToeMachine = setup({
           invoke: {
             src: 'bot',
             input: ({ context }) => ({ context }),
-            onDone: {
-              actions: raise(({ event }) => {
-                return event.output![0]!;
-              }),
-            },
           },
           on: {
             'o.play': [
@@ -261,7 +237,6 @@ export const ticTacToeMachine = setup({
       states: {
         winner: {
           tags: 'winner',
-          entry: 'setWinner',
         },
         draw: {
           tags: 'draw',
@@ -277,8 +252,8 @@ export const ticTacToeMachine = setup({
   },
 });
 
-const actor = createActor(ticTacToeMachine);
-actor.subscribe((s) => {
+const agent = createAgent(ticTacToeMachine);
+agent.subscribe((s) => {
   console.log(s.value, s.context);
 });
-actor.start();
+agent.start();

package/examples/weather.ts

@@ -0,0 +1,160 @@
+import OpenAI from 'openai';
+import { createAgent, createOpenAIAdapter, createSchemas } from '../src';
+import { assign, fromPromise, log, setup } from 'xstate';
+import { getFromTerminal } from './helpers/helpers';
+
+async function searchTavily(
+  input: string,
+  options: {
+    maxResults?: number;
+    apiKey: string;
+  }
+) {
+  const body: Record<string, unknown> = {
+    query: input,
+    max_results: options.maxResults,
+    api_key: options.apiKey,
+  };
+
+  const response = await fetch('https://api.tavily.com/search', {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+
+  const json = await response.json();
+  if (!response.ok) {
+    throw new Error(
+      `Request failed with status code ${response.status}: ${json.error}`
+    );
+  }
+  if (!Array.isArray(json.results)) {
+    throw new Error(`Could not parse Tavily results. Please try again.`);
+  }
+  return JSON.stringify(json.results);
+}
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const schemas = createSchemas({
+  context: {
+    location: { type: 'string' },
+    history: { type: 'array', items: { type: 'string' } },
+    count: { type: 'number' },
+  },
+  events: {
+    getWeather: {
+      description: 'Get the weather for a location',
+      properties: {
+        location: {
+          type: 'string',
+          description: 'The location to get the weather for',
+        },
+      },
+    },
+    doSomethingElse: {
+      description:
+        'Do something else, because the user did not provide a location',
+      properties: {},
+    },
+  },
+});
+
+const adapter = createOpenAIAdapter(openai, {
+  model: 'gpt-4-1106-preview',
+});
+
+const getWeather = fromPromise(async ({ input }: { input: string }) => {
+  const results = await searchTavily(
+    `Get the weather for this location: ${input}`,
+    {
+      maxResults: 5,
+      apiKey: process.env.TAVILY_API_KEY!,
+    }
+  );
+  return results;
+});
+
+const machine = setup({
+  schemas,
+  types: schemas.types,
+  actors: {
+    getWeather,
+    decide: adapter.fromEventChoice(
+      (input: string) =>
+        `Decide what to do based on the given input, which may or may not be a location: ${input}`
+    ),
+    getFromTerminal,
+  },
+}).createMachine({
+  initial: 'getLocation',
+  context: {
+    location: '',
+    count: 0,
+    history: [],
+  },
+  states: {
+    getLocation: {
+      invoke: {
+        src: 'getFromTerminal',
+        input: 'Location?',
+        onDone: {
+          actions: assign({
+            location: ({ event }) => event.output,
+          }),
+          target: 'decide',
+        },
+      },
+      always: {
+        guard: ({ context }) => context.count >= 3,
+        target: 'stopped',
+      },
+    },
+    decide: {
+      entry: log('Deciding...'),
+      invoke: {
+        src: 'decide',
+        input: ({ context }) => context.location,
+      },
+      on: {
+        getWeather: {
+          actions: log(({ event }) => event),
+          target: 'gettingWeather',
+        },
+        doSomethingElse: 'getLocation',
+      },
+    },
+    gettingWeather: {
+      entry: log('Getting weather...'),
+      invoke: {
+        src: 'getWeather',
+        input: ({ context }) => context.location,
+        onDone: {
+          actions: [
+            log(({ event }) => event.output),
+            assign({
+              count: ({ context }) => context.count + 1,
+            }),
+          ],
+          target: 'getLocation',
+        },
+      },
+    },
+    stopped: {
+      entry: log('You have used up your search quota. Goodbye!'),
+    },
+  },
+  exit: () => {
+    process.exit();
+  },
+});
+
+createAgent(machine, {
+  input: {
+    location: 'New York',
+  },
+}).start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -9,22 +9,30 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.0",
     "@changesets/cli": "^2.27.1",
     "@types/node": "^20.10.6",
+    "dotenv": "^16.3.1",
     "json-schema-to-ts": "^3.0.0",
+    "openai": "^4.24.1",
+    "ts-node": "^10.9.2",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   },
-  "dependencies": {
-    "openai": "^4.24.1",
-    "xstate": "^5.3.1"
-  },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "xstate": "^5.6.0"
+  },
+  "packageManager": "pnpm@8.11.0",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc",
-    "test": "vitest run"
+    "test": "vitest run",
+    "example": "ts-node examples/helpers/runner.ts",
+    "changeset": "changeset",
+    "release": "changeset publish",
+    "version": "changeset version"
   }
 }

package/readme.md

@@ -0,0 +1,41 @@
+# Stately Agent (alpha)
+
+🚧 Documentation in progress! Please see [the examples directory](https://github.com/statelyai/agent/tree/main/examples) for working examples.
+
+## Installation
+
+Install `openai`, and `@statelyai/agent`:
+
+```bash
+npm install openai @statelyai/agent
+```
+
+## Usage
+
+Work in progress. For now, see the examples:
+
+- [Joke generator](https://github.com/statelyai/agent/tree/main/examples/joke.ts)
+  - Demonstrates `agent.fromChatCompletion(...)` to generate a joke and provide a joke rating
+  - Demonstrates `agent.fromEvent(...)` to choose whether to keep generating jokes or stop
+- [Tic-tac-toe](https://github.com/statelyai/agent/tree/main/examples/ticTacToe.ts)
+  - Demonstrates `agent.fromEvent(...)` to have an agent play itself in a game of tic-tac-toe with precise events
+  - Demonstrates `agent.fromChatCompletionStream(...)` to produce a game report at the end of the game
+- [Weather](https://github.com/statelyai/agent/tree/main/examples/weather.ts)
+  - Demonstrates using [Tavily](https://tavily.com/) as an external API
+  - Demonstrates `agent.fromEvent(...)` to only use Tavily to get the weather if the user provides a valid location
+
+## Examples
+
+First, clone this repo locally. To run the examples in this repo, create a `.env` file at the root of the repo with the following contents:
+
+```bash
+OPENAI_API_KEY="your-openai-api-key"
+```
+
+Then, install the dependencies (`npm install`) and run the examples:
+
+```bash
+npm run example joke
+# or:
+# npm run example ticTacToe
+```