@statelyai/agent 0.0.2 → 0.0.3

package/.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
-  "changelog": "@changesets/cli/changelog",
+  "changelog": ["@changesets/changelog-github", { "repo": "statelyai/agent" }],
   "commit": false,
   "fixed": [],
   "linked": [],

package/.env.template

@@ -0,0 +1,6 @@
+
+# Get your OpenAI API key from: https://platform.openai.com/signup/
+OPENAI_API_KEY="sk-..."
+
+# Get your Tavily API key from: https://app.tavily.com/
+TAVILY_API_KEY="tvly-..."

package/.github/actions/ci-setup/action.yml

@@ -0,0 +1,24 @@
+name: Setup Workflow
+description: Composite action that sets up pnpm
+runs:
+  using: 'composite'
+  steps:
+    - uses: pnpm/action-setup@v2
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20.x
+
+    - name: Get pnpm store directory
+      shell: bash
+      id: pnpm-cache
+      run: |
+        echo "pnpm_cache_dir=$(pnpm store path)" >> $GITHUB_OUTPUT
+    - uses: actions/cache@v4
+      name: Setup pnpm cache
+      with:
+        path: ${{ steps.pnpm-cache.outputs.pnpm_cache_dir }}
+        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-
+    - run: pnpm install
+      shell: bash

package/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions: {}
+jobs:
+  release:
+    permissions:
+      contents: write  # to create release (changesets/action)
+      issues: write # to post issue comments (changesets/action)
+      pull-requests: write  # to create pull request (changesets/action)
+
+    if: github.repository == 'statelyai/agent'
+
+    timeout-minutes: 20
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/ci-setup
+
+      - name: Create Release Pull Request or Publish to npm
+        uses: changesets/action@v1
+        with:
+          publish: pnpm run release
+          version: pnpm run version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @statelyai/agent
 
+## 0.0.3
+
+### Patch Changes
+
+- [#1](https://github.com/statelyai/agent/pull/1) [`3dc2880`](https://github.com/statelyai/agent/commit/3dc28809a7ffd915a69d9f3374531c31fc1ee357) Thanks [@mellson](https://github.com/mellson)! - Adds a convenient way to run the examples with `pnpm example ${exampleName}`. If no example name is provided, the script will print the available examples. Also, adds a fun little loading animation to the joke example.
+
 ## 0.0.2
 
 ### Patch Changes

package/dist/index.d.ts

@@ -42,26 +42,27 @@ type ConvertContextToJSONSchema<T extends ContextSchema> = {
  * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
  *
  */
-declare function fromChatCompletion<TInput>(openai: OpenAI, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
+declare function fromChatCompletion<TInput>(openai: OpenAI, agentSettings: CreateAgentOutput<any>, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
 /**
  * Creates [observable actor logic](https://stately.ai/docs/observable-actors) that uses the OpenAI API to generate a completion stream.
  *
  * @param openai The OpenAI instance to use.
  * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
  */
-declare function fromChatCompletionStream<TInput>(openai: OpenAI, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming): ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+declare function fromChatCompletionStream<TInput>(openai: OpenAI, agentSettings: CreateAgentOutput<any>, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming): ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
 /**
  * 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.
  */
-declare function fromEventChoice<TInput>(openai: OpenAI, machineTypes: {
-    schemas: {
-        context: ContextSchema;
-        events: EventSchemas;
-    };
-}, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+declare function fromEventChoice<TInput>(openai: OpenAI, agentSettings: CreateAgentOutput<any>, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming, options?: {
+    /**
+     * Immediately execute sending the event to the parent actor.
+     * @default false
+     */
+    execute?: boolean;
+}): PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
 interface CreateAgentOutput<T extends {
     model: ChatCompletionCreateParamsBase['model'];
     context: ContextSchema;
@@ -73,6 +74,7 @@ interface CreateAgentOutput<T extends {
         context: FromSchema<ConvertContextToJSONSchema<T['context']>>;
         events: FromSchema<Values<ConvertToJSONSchemas<T['events']>>>;
     };
+    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<FromSchema<Values<ConvertToJSONSchemas<T['events']>>>[] | undefined, TInput>;
     fromEventChoice: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<FromSchema<Values<ConvertToJSONSchemas<T['events']>>>[] | undefined, TInput>;
     fromChatCompletion: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
     fromChatCompletionStream: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming) => ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;

package/dist/index.js

@@ -56,12 +56,12 @@ function createEventSchemas(eventSchemaMap) {
 }
 
 // src/openai.ts
-function fromChatCompletion(openai, inputFn) {
+function fromChatCompletion(openai, agentSettings, inputFn) {
   return (0, import_xstate.fromPromise)(
     async ({ input }) => {
       const openAiInput = inputFn(input);
       const params = typeof openAiInput === "string" ? {
-        model: "gpt-3.5-turbo-1106",
+        model: agentSettings.model,
         messages: [
           {
             role: "user",
@@ -74,14 +74,14 @@ function fromChatCompletion(openai, inputFn) {
     }
   );
 }
-function fromChatCompletionStream(openai, inputFn) {
+function fromChatCompletionStream(openai, agentSettings, inputFn) {
   return (0, import_xstate.fromObservable)(
     ({ input }) => {
       const observers = /* @__PURE__ */ new Set();
       (async () => {
         const openAiInput = inputFn(input);
         const resolvedParams = typeof openAiInput === "string" ? {
-          model: "gpt-3.5-turbo-1106",
+          model: agentSettings.model,
           messages: [
             {
               role: "user",
@@ -113,9 +113,9 @@ function fromChatCompletionStream(openai, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, machineTypes, inputFn) {
+function fromEventChoice(openai, agentSettings, inputFn, options) {
   return (0, import_xstate.fromPromise)(
-    async ({ input, self }) => {
+    async ({ input, self, system }) => {
       const transitions = getAllTransitions(self._parent.getSnapshot());
       const functionNameMapping = {};
       const tools = transitions.filter((t) => {
@@ -127,17 +127,17 @@ function fromEventChoice(openai, machineTypes, inputFn) {
           type: "function",
           function: {
             name,
-            description: t.description ?? machineTypes.schemas.events[t.eventType]?.description,
+            description: t.description ?? agentSettings.schemas.events[t.eventType]?.description,
             parameters: {
               type: "object",
-              properties: machineTypes.schemas.events[t.eventType]?.properties ?? {}
+              properties: agentSettings.schemas.events[t.eventType]?.properties ?? {}
             }
           }
         };
       });
       const openAiInput = inputFn(input);
       const completionParams = typeof openAiInput === "string" ? {
-        model: "gpt-4-1106-preview",
+        model: agentSettings.model,
         messages: [
           {
             role: "user",
@@ -151,19 +151,24 @@ function fromEventChoice(openai, machineTypes, inputFn) {
       });
       const toolCalls = completion.choices[0]?.message.tool_calls;
       if (toolCalls) {
-        return toolCalls.map((tc) => {
+        const events = toolCalls.map((tc) => {
           return {
             type: functionNameMapping[tc.function.name],
             ...JSON.parse(tc.function.arguments)
           };
         });
+        if (options?.execute) {
+          events.forEach((event) => {
+            system._relay(self, self._parent, event);
+          });
+        }
       }
       return void 0;
     }
   );
 }
 function createAgent(openai, settings) {
-  const obj = {
+  const agentSettings = {
     model: settings.model,
     schemas: {
       context: {
@@ -174,11 +179,16 @@ function createAgent(openai, settings) {
       events: createEventSchemas(settings.events)
     },
     types: {},
-    fromEventChoice: (input) => fromEventChoice(openai, obj, input),
-    fromChatCompletion: (input) => fromChatCompletion(openai, input),
-    fromChatCompletionStream: (input) => fromChatCompletionStream(openai, input)
+    fromEvent: (input) => (
+      // @ts-ignore
+      fromEventChoice(openai, agentSettings, input, { execute: true })
+    ),
+    // @ts-ignore infinitely deep
+    fromEventChoice: (input) => fromEventChoice(openai, agentSettings, input),
+    fromChatCompletion: (input) => fromChatCompletion(openai, agentSettings, input),
+    fromChatCompletionStream: (input) => fromChatCompletionStream(openai, agentSettings, input)
   };
-  return obj;
+  return agentSettings;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/examples/helpers/helpers.ts

@@ -0,0 +1,17 @@
+import { fromPromise } from 'xstate';
+
+export const getFromTerminal = fromPromise<string, string>(
+  async ({ input }) => {
+    const topic = await new Promise<string>((res) => {
+      console.log(input);
+      const listener = (data: Buffer) => {
+        const result = data.toString().trim();
+        process.stdin.off('data', listener);
+        res(result);
+      };
+      process.stdin.on('data', listener);
+    });
+
+    return topic;
+  }
+);

package/examples/helpers/loader.ts

@@ -0,0 +1,32 @@
+// Adapted from https://stackoverflow.com/questions/34848505/how-to-make-a-loading-animation-in-console-application-written-in-javascript-or
+
+/**
+ * Create and display a loader in the console.
+ *
+ * @param {string} [text=""] Text to display after loader
+ * @param {array.<string>} [chars=["⠙", "⠘", "⠰", "⠴", "⠤", "⠦", "⠆", "⠃", "⠋", "⠉"]]
+ * Array of characters representing loader steps
+ * @param {number} [delay=100] Delay in ms between loader steps
+ * @example
+ * let loader = loadingAnimation("Loading…");
+ *
+ * // Stop loader after 1 second
+ * setTimeout(() => clearInterval(loader), 1000);
+ * @returns {number} An interval that can be cleared to stop the animation
+ */
+export function loadingAnimation(
+  text: string = '',
+  chars: Array<string> = ['⠙', '⠘', '⠰', '⠴', '⠤', '⠦', '⠆', '⠃', '⠋', '⠉'],
+  delay: number = 100
+) {
+  let x = 0;
+
+  const i = setInterval(function () {
+    process.stdout.write('\r' + chars[x++] + ' ' + text);
+    x = x % chars.length;
+  }, delay);
+
+  return {
+    stop: () => clearInterval(i),
+  };
+}

package/examples/helpers/runner.ts

@@ -0,0 +1,27 @@
+import dotenv from 'dotenv';
+import { existsSync, readdirSync } from 'fs';
+dotenv.config();
+
+function showExamples() {
+  const exampleFiles = readdirSync('./examples', { withFileTypes: true });
+  exampleFiles.forEach((file) => {
+    if (file.isDirectory()) return;
+    const exampleName = file.name.split('.')[0];
+    console.log(`- ${exampleName}`);
+  });
+  process.exit();
+}
+
+const exampleParams = process.argv.slice(2);
+if (exampleParams.length === 0) {
+  console.error('No example specified, you can choose from:');
+  showExamples();
+}
+const exampleName = exampleParams[0];
+const filePath = `./examples/${exampleName}.ts`;
+if (existsSync(filePath)) {
+  require(`../${exampleName}.ts`);
+} else {
+  console.error(`Example ${exampleName} does not exist, you can choose from:`);
+  showExamples();
+}

package/examples/joke.ts

@@ -1,6 +1,14 @@
 import OpenAI from 'openai';
-import { assign, fromPromise, createActor, setup, log, raise } from 'xstate';
+import {
+  assign,
+  createActor,
+  fromCallback,
+  fromPromise,
+  log,
+  setup,
+} from 'xstate';
 import { createAgent } from '../src';
+import { loadingAnimation } from './helpers/loader';
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
@@ -22,9 +30,9 @@ const agent = createAgent(openai, {
   events: {},
 });
 
-const promptTemplate = (topic: string) => `Tell me a joke about ${topic}.`;
-
-const getJokeCompletion = agent.fromChatCompletion(promptTemplate);
+const getJokeCompletion = agent.fromChatCompletion(
+  (topic: string) => `Tell me a joke about ${topic}.`
+);
 
 const rateJoke = agent.fromChatCompletion(
   (joke: string) => `Rate this joke on a scale of 1 to 10: ${joke}`
@@ -32,7 +40,7 @@ const rateJoke = agent.fromChatCompletion(
 
 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,10 +52,48 @@ const getTopic = fromPromise(async () => {
   return topic;
 });
 
-const decide = agent.fromEventChoice(
+const decide = agent.fromEvent(
   (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: {
@@ -64,13 +110,15 @@ const jokeMachine = setup({
     getTopic,
     rateJoke,
     decide,
+    loader,
   },
 }).createMachine({
-  context: ({ input }) => ({
-    topic: input.topic,
+  context: () => ({
+    topic: '',
     jokes: [],
     desire: null,
     lastRating: null,
+    loader: null,
   }),
   initial: 'waitingForTopic',
   states: {
@@ -86,56 +134,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) => 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 }) => 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 +205,10 @@ const jokeMachine = setup({
       type: 'final',
     },
   },
+  exit: () => {
+    process.exit();
+  },
 });
 
 const actor = createActor(jokeMachine);
-
 actor.start();

package/examples/ticTacToe.ts

@@ -1,4 +1,4 @@
-import { assign, setup, assertEvent, createActor, raise } from 'xstate';
+import { assign, setup, assertEvent, createActor } from 'xstate';
 import OpenAI from 'openai';
 import { createAgent } from '../src/openai';
 
@@ -9,7 +9,7 @@ const openai = new OpenAI({
 type Player = 'x' | 'o';
 
 const agent = createAgent(openai, {
-  model: 'gpt-3.5-turbo-1106',
+  model: 'gpt-4-1106-preview',
   context: {
     board: {
       type: 'array',
@@ -30,11 +30,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',
@@ -78,12 +73,11 @@ 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;
 
-const bot = agent.fromEventChoice(
+const bot = agent.fromEvent(
   ({ context }: { context: typeof agent.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.
 
@@ -97,9 +91,7 @@ const gameReporter = agent.fromChatCompletionStream(
     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:
+  }) => `Here is the game board:
 
 ${JSON.stringify(context.board, null, 2)}
 
@@ -107,9 +99,30 @@ 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,
   actors: {
@@ -131,9 +144,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 +152,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';
-        });
-
-        if (xWon) {
-          return true;
-        }
-
-        const oWon = line.every((index) => {
-          return board[index] === 'o';
-        });
+      const winner = getWinner(context.board);
 
-        if (oWon) {
-          return true;
-        }
-      }
-
-      return false;
+      return !!winner;
     },
     checkDraw: ({ context }) => {
       return context.moves === 9;
@@ -202,11 +184,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 +200,6 @@ export const ticTacToeMachine = setup({
           invoke: {
             src: 'bot',
             input: ({ context }) => ({ context }),
-            onDone: {
-              actions: raise(({ event }) => {
-                return event.output![0]!;
-              }),
-            },
           },
           on: {
             'o.play': [
@@ -261,7 +233,6 @@ export const ticTacToeMachine = setup({
       states: {
         winner: {
           tags: 'winner',
-          entry: 'setWinner',
         },
         draw: {
           tags: 'draw',
@@ -277,7 +248,13 @@ export const ticTacToeMachine = setup({
   },
 });
 
-const actor = createActor(ticTacToeMachine);
+const actor = createActor(ticTacToeMachine, {
+  inspect: (e) => {
+    if (e.type === '@xstate.event') {
+      console.log(e.event);
+    }
+  },
+});
 actor.subscribe((s) => {
   console.log(s.value, s.context);
 });

package/examples/weather.ts

@@ -0,0 +1,147 @@
+import OpenAI from 'openai';
+import { createAgent, fromEventChoice } from '../src';
+import { assign, createActor, 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 agent = createAgent(openai, {
+  model: 'gpt-4-1106-preview',
+  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 machine = setup({
+  types: agent.types,
+  actors: {
+    searchTavily: fromPromise(async ({ input }: { input: string }) => {
+      const results = await searchTavily(input, {
+        maxResults: 5,
+        apiKey: process.env.TAVILY_API_KEY!,
+      });
+      return results;
+    }),
+    decide: agent.fromEvent(
+      (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: 'searchTavily',
+        input: ({ context }) =>
+          `Get the weather for this location: ${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();
+  },
+});
+
+createActor(machine).start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "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.5.1"
+  },
+  "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
+```

package/src/openai.ts

@@ -1,4 +1,4 @@
-import OpenAI from 'openai';
+import type OpenAI from 'openai';
 import {
   AnyEventObject,
   ObservableActorLogic,
@@ -34,6 +34,7 @@ import {
  */
 export function fromChatCompletion<TInput>(
   openai: OpenAI,
+  agentSettings: CreateAgentOutput<any>,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
@@ -44,7 +45,7 @@ export function fromChatCompletion<TInput>(
       const params: ChatCompletionCreateParamsNonStreaming =
         typeof openAiInput === 'string'
           ? {
-              model: 'gpt-3.5-turbo-1106',
+              model: agentSettings.model,
               messages: [
                 {
                   role: 'user',
@@ -68,6 +69,7 @@ export function fromChatCompletion<TInput>(
  */
 export function fromChatCompletionStream<TInput>(
   openai: OpenAI,
+  agentSettings: CreateAgentOutput<any>,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming
@@ -81,7 +83,7 @@ export function fromChatCompletionStream<TInput>(
         const resolvedParams: ChatCompletionCreateParamsBase =
           typeof openAiInput === 'string'
             ? {
-                model: 'gpt-3.5-turbo-1106',
+                model: agentSettings.model,
                 messages: [
                   {
                     role: 'user',
@@ -126,13 +128,20 @@ export function fromChatCompletionStream<TInput>(
  */
 export function fromEventChoice<TInput>(
   openai: OpenAI,
-  machineTypes: { schemas: { context: ContextSchema; events: EventSchemas } },
+  agentSettings: CreateAgentOutput<any>,
   inputFn: (
     input: TInput
-  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming,
+  options?: {
+    /**
+     * Immediately execute sending the event to the parent actor.
+     * @default false
+     */
+    execute?: boolean;
+  }
 ) {
   return fromPromise<AnyEventObject[] | undefined, TInput>(
-    async ({ input, self }) => {
+    async ({ input, self, system }) => {
       const transitions = getAllTransitions(self._parent!.getSnapshot());
       const functionNameMapping: Record<string, string> = {};
       const tools = transitions
@@ -148,11 +157,11 @@ export function fromEventChoice<TInput>(
               name,
               description:
                 t.description ??
-                machineTypes.schemas.events[t.eventType]?.description,
+                agentSettings.schemas.events[t.eventType]?.description,
               parameters: {
                 type: 'object',
                 properties:
-                  machineTypes.schemas.events[t.eventType]?.properties ?? {},
+                  agentSettings.schemas.events[t.eventType]?.properties ?? {},
               },
             },
           } as const;
@@ -162,7 +171,7 @@ export function fromEventChoice<TInput>(
       const completionParams: ChatCompletionCreateParamsNonStreaming =
         typeof openAiInput === 'string'
           ? {
-              model: 'gpt-4-1106-preview',
+              model: agentSettings.model,
               messages: [
                 {
                   role: 'user',
@@ -179,12 +188,19 @@ export function fromEventChoice<TInput>(
       const toolCalls = completion.choices[0]?.message.tool_calls;
 
       if (toolCalls) {
-        return toolCalls.map((tc) => {
+        const events = toolCalls.map((tc) => {
           return {
             type: functionNameMapping[tc.function.name],
             ...JSON.parse(tc.function.arguments),
           };
         });
+
+        if (options?.execute) {
+          events.forEach((event) => {
+            // @ts-ignore
+            system._relay(self, self._parent, event);
+          });
+        }
       }
 
       return undefined;
@@ -205,6 +221,12 @@ interface CreateAgentOutput<
     context: FromSchema<ConvertContextToJSONSchema<T['context']>>;
     events: FromSchema<Values<ConvertToJSONSchemas<T['events']>>>;
   };
+  fromEvent: <TInput>(
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
+  ) => PromiseActorLogic<
+    FromSchema<Values<ConvertToJSONSchemas<T['events']>>>[] | undefined,
+    TInput
+  >;
   fromEventChoice: <TInput>(
     inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
   ) => PromiseActorLogic<
@@ -229,7 +251,7 @@ export function createAgent<
     events: EventSchemas;
   }
 >(openai: OpenAI, settings: T): CreateAgentOutput<T> {
-  const obj: CreateAgentOutput<T> = {
+  const agentSettings: CreateAgentOutput<T> = {
     model: settings.model,
     schemas: {
       context: {
@@ -240,11 +262,16 @@ export function createAgent<
       events: createEventSchemas(settings.events),
     } as any,
     types: {} as any,
-    fromEventChoice: (input) => fromEventChoice(openai, obj, input) as any,
-    fromChatCompletion: (input) => fromChatCompletion(openai, input),
+    fromEvent: (input) =>
+      // @ts-ignore
+      fromEventChoice(openai, agentSettings, input, { execute: true }),
+    // @ts-ignore infinitely deep
+    fromEventChoice: (input) => fromEventChoice(openai, agentSettings, input),
+    fromChatCompletion: (input) =>
+      fromChatCompletion(openai, agentSettings, input),
     fromChatCompletionStream: (input) =>
-      fromChatCompletionStream(openai, input),
+      fromChatCompletionStream(openai, agentSettings, input),
   };
 
-  return obj as any;
+  return agentSettings as any;
 }

package/dist/index.d.mts

@@ -1,3 +0,0 @@
-declare function helloWorld(): string;
-
-export { helloWorld };

package/dist/index.mjs

@@ -1,7 +0,0 @@
-// src/index.ts
-function helloWorld() {
-  return "Hello World!";
-}
-export {
-  helloWorld
-};