@statelyai/agent 0.0.1 → 0.0.2

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.vscode/launch.json

@@ -0,0 +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"]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @statelyai/agent
+
+## 0.0.2
+
+### Patch Changes
+
+- e125728: Added `createAgent(...)`

package/dist/index.d.ts

@@ -1,6 +1,39 @@
-import * as xstate from 'xstate';
-import { AnyEventObject } from 'xstate';
 import OpenAI from 'openai';
+import { Prop, PromiseActorLogic, ObservableActorLogic, AnyEventObject, Values } from 'xstate';
+import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
+import { FromSchema } from 'json-schema-to-ts';
+import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
+import { ChatCompletionCreateParamsBase, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
+
+type EventSchemas = {
+    [key: string]: {
+        description?: string;
+        properties?: {
+            [key: string]: JSONSchema7;
+        };
+    };
+};
+interface ContextSchema {
+    [key: string]: JSONSchema7;
+}
+type ConvertToJSONSchemas<T> = {
+    [K in keyof T]: {
+        properties: {
+            type: {
+                const: K;
+            };
+        };
+        type: 'object';
+        required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+        additionalProperties: false;
+    } & T[K];
+} & {};
+type ConvertContextToJSONSchema<T extends ContextSchema> = {
+    type: 'object';
+    properties: T;
+    readonly required: Array<keyof T & string>;
+    additionalProperties: false;
+};
 
 /**
  * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that uses the OpenAI API to generate a completion.
@@ -9,20 +42,45 @@ import OpenAI from 'openai';
  * @param inputFn A function that maps arbitrary input to OpenAI chat completion input.
  *
  */
-declare function fromChatCompletion<TInput>(openai: OpenAI, inputFn: (input: TInput) => OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): xstate.PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
+declare function fromChatCompletion<TInput>(openai: OpenAI, 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) => OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming): xstate.ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+declare function fromChatCompletionStream<TInput>(openai: OpenAI, 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, inputFn: (input: TInput) => OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): xstate.PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+declare function fromEventChoice<TInput>(openai: OpenAI, machineTypes: {
+    schemas: {
+        context: ContextSchema;
+        events: EventSchemas;
+    };
+}, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+interface CreateAgentOutput<T extends {
+    model: ChatCompletionCreateParamsBase['model'];
+    context: ContextSchema;
+    events: EventSchemas;
+}> {
+    model: T['model'];
+    schemas: T;
+    types: {
+        context: FromSchema<ConvertContextToJSONSchema<T['context']>>;
+        events: FromSchema<Values<ConvertToJSONSchemas<T['events']>>>;
+    };
+    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>;
+}
+declare function createAgent<T extends {
+    model: ChatCompletionCreateParamsBase['model'];
+    context: ContextSchema;
+    events: EventSchemas;
+}>(openai: OpenAI, settings: T): CreateAgentOutput<T>;
 
-export { fromChatCompletion, fromChatCompletionStream, fromEventChoice };
+export { createAgent, fromChatCompletion, fromChatCompletionStream, fromEventChoice };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  createAgent: () => createAgent,
   fromChatCompletion: () => fromChatCompletion,
   fromChatCompletionStream: () => fromChatCompletionStream,
   fromEventChoice: () => fromEventChoice
@@ -35,13 +36,40 @@ function getAllTransitions(state) {
   const transitions = nodes.map((node) => [...node.transitions.values()]).flat(2);
   return transitions;
 }
+function createEventSchemas(eventSchemaMap) {
+  const resolvedEventSchemaMap = {};
+  for (const [key, schema] of Object.entries(eventSchemaMap)) {
+    resolvedEventSchemaMap[key] = {
+      type: "object",
+      required: ["type"],
+      properties: {
+        type: {
+          const: key
+        },
+        ...schema.properties
+      },
+      additionalProperties: false,
+      ...schema
+    };
+  }
+  return resolvedEventSchemaMap;
+}
 
 // src/openai.ts
 function fromChatCompletion(openai, inputFn) {
   return (0, import_xstate.fromPromise)(
     async ({ input }) => {
       const openAiInput = inputFn(input);
-      const response = await openai.chat.completions.create(openAiInput);
+      const params = typeof openAiInput === "string" ? {
+        model: "gpt-3.5-turbo-1106",
+        messages: [
+          {
+            role: "user",
+            content: openAiInput
+          }
+        ]
+      } : openAiInput;
+      const response = await openai.chat.completions.create(params);
       return response;
     }
   );
@@ -52,8 +80,17 @@ function fromChatCompletionStream(openai, inputFn) {
       const observers = /* @__PURE__ */ new Set();
       (async () => {
         const openAiInput = inputFn(input);
+        const resolvedParams = typeof openAiInput === "string" ? {
+          model: "gpt-3.5-turbo-1106",
+          messages: [
+            {
+              role: "user",
+              content: openAiInput
+            }
+          ]
+        } : openAiInput;
         const stream = await openai.chat.completions.create({
-          ...openAiInput,
+          ...resolvedParams,
           stream: true
         });
         for await (const part of stream) {
@@ -76,7 +113,7 @@ function fromChatCompletionStream(openai, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, inputFn) {
+function fromEventChoice(openai, machineTypes, inputFn) {
   return (0, import_xstate.fromPromise)(
     async ({ input, self }) => {
       const transitions = getAllTransitions(self._parent.getSnapshot());
@@ -90,17 +127,26 @@ function fromEventChoice(openai, inputFn) {
           type: "function",
           function: {
             name,
-            description: t.description,
+            description: t.description ?? machineTypes.schemas.events[t.eventType]?.description,
             parameters: {
               type: "object",
-              properties: t.meta?.parameters ?? {}
+              properties: machineTypes.schemas.events[t.eventType]?.properties ?? {}
             }
           }
         };
       });
       const openAiInput = inputFn(input);
+      const completionParams = typeof openAiInput === "string" ? {
+        model: "gpt-4-1106-preview",
+        messages: [
+          {
+            role: "user",
+            content: openAiInput
+          }
+        ]
+      } : openAiInput;
       const completion = await openai.chat.completions.create({
-        ...openAiInput,
+        ...completionParams,
         tools
       });
       const toolCalls = completion.choices[0]?.message.tool_calls;
@@ -112,12 +158,31 @@ function fromEventChoice(openai, inputFn) {
           };
         });
       }
-      return toolCalls ?? void 0;
+      return void 0;
     }
   );
 }
+function createAgent(openai, settings) {
+  const obj = {
+    model: settings.model,
+    schemas: {
+      context: {
+        type: "object",
+        properties: settings.context,
+        additionalProperties: false
+      },
+      events: createEventSchemas(settings.events)
+    },
+    types: {},
+    fromEventChoice: (input) => fromEventChoice(openai, obj, input),
+    fromChatCompletion: (input) => fromChatCompletion(openai, input),
+    fromChatCompletionStream: (input) => fromChatCompletionStream(openai, input)
+  };
+  return obj;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createAgent,
   fromChatCompletion,
   fromChatCompletionStream,
   fromEventChoice

package/examples/joke.ts

@@ -1,185 +1,151 @@
 import OpenAI from 'openai';
-import { assign, fromPromise, createActor, waitFor, setup } from 'xstate';
-import { fromEventChoice } from '../src/index';
+import { assign, fromPromise, createActor, setup, log, raise } from 'xstate';
+import { createAgent } from '../src';
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
 });
 
-async function start() {
-  const promptTemplate = (topic: string) => `Tell me a joke about ${topic}.`;
-
-  const getJokeCompletion = fromPromise(
-    async ({ input }: { input: { topic: string } }) => {
-      const res = await openai.chat.completions.create({
-        messages: [
-          {
-            role: 'user',
-            content: promptTemplate(input.topic),
-          },
-        ],
-        model: 'gpt-3.5-turbo',
-        n: 1,
-      });
-
-      return res.choices[0]?.message.content;
-    }
-  );
+const agent = createAgent(openai, {
+  model: 'gpt-3.5-turbo-1106',
+  context: {
+    topic: { type: 'string' },
+    jokes: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      desire: { type: ['string', 'null'] },
+      lastRating: { type: ['string', 'null'] },
+    },
+  },
+  events: {},
+});
 
-  const rateJoke = fromPromise(
-    async ({ input }: { input: { joke: string } }) => {
-      const res = await openai.chat.completions.create({
-        messages: [
-          {
-            role: 'user',
-            content: `Rate this joke on a scale of 1 to 10: ${input.joke}`,
-          },
-        ],
-        model: 'gpt-3.5-turbo',
-        n: 1,
-      });
+const promptTemplate = (topic: string) => `Tell me a joke about ${topic}.`;
 
-      return res.choices[0]?.message.content;
-    }
-  );
+const getJokeCompletion = agent.fromChatCompletion(promptTemplate);
 
-  const getTopic = fromPromise(async () => {
-    const topic = await new Promise<string>((res) => {
-      console.log('Give me a topic: \n\n');
-      process.stdin.on('data', (data) => {
-        const eventType = data.toString().trim();
-        res(eventType);
-      });
-    });
+const rateJoke = agent.fromChatCompletion(
+  (joke: string) => `Rate this joke on a scale of 1 to 10: ${joke}`
+);
 
-    return topic;
+const getTopic = fromPromise(async () => {
+  const topic = await new Promise<string>((res) => {
+    console.log('Give me a topic: \n\n');
+    const listener = (data: Buffer) => {
+      const result = data.toString().trim();
+      process.stdin.off('data', listener);
+      res(result);
+    };
+    process.stdin.on('data', listener);
   });
 
-  const chain = setup({
-    types: {
-      context: {} as {
-        topic: string;
-        jokes: string[];
-        desire: string | null;
-        lastRating: string | null;
-      },
-      input: {} as { topic: string },
-    },
-    actors: {
-      getJokeCompletion,
-      getTopic,
-      rateJoke,
-      decide: fromEventChoice(openai, (desire: string) => ({
-        model: 'gpt-4-1106-preview',
-        messages: [
-          {
-            role: 'user',
-            content: `Execute the function that best satisfies this desire:
+  return topic;
+});
 
-${desire}
-`,
-          },
-        ],
-      })),
+const decide = agent.fromEventChoice(
+  (lastRating: string) =>
+    `Choose what to do next, given the previous rating of the joke: ${lastRating}`
+);
+
+const jokeMachine = setup({
+  types: {
+    context: {} as {
+      topic: string;
+      jokes: string[];
+      desire: string | null;
+      lastRating: string | null;
     },
-  }).createMachine({
-    context: ({ input }) => ({
-      topic: input.topic,
-      jokes: [],
-      desire: null,
-      lastRating: null,
-    }),
-    initial: 'waitingForTopic',
-    states: {
-      waitingForTopic: {
-        invoke: {
-          src: 'getTopic',
-          onDone: {
-            actions: assign({
-              topic: ({ event }) => event.output,
-            }),
-            target: 'tellingJoke',
-          },
+    input: {} as { topic: string },
+  },
+  actors: {
+    getJokeCompletion,
+    getTopic,
+    rateJoke,
+    decide,
+  },
+}).createMachine({
+  context: ({ input }) => ({
+    topic: input.topic,
+    jokes: [],
+    desire: null,
+    lastRating: null,
+  }),
+  initial: 'waitingForTopic',
+  states: {
+    waitingForTopic: {
+      invoke: {
+        src: 'getTopic',
+        onDone: {
+          actions: assign({
+            topic: ({ event }) => event.output,
+          }),
+          target: 'tellingJoke',
         },
       },
-      tellingJoke: {
-        invoke: {
-          src: 'getJokeCompletion',
-          input: ({ context }) => ({ topic: context.topic }),
-          onDone: {
-            actions: assign({
+    },
+    tellingJoke: {
+      invoke: {
+        src: 'getJokeCompletion',
+        input: ({ context }) => context.topic,
+        onDone: {
+          actions: [
+            assign({
               jokes: ({ context, event }) =>
-                context.jokes.concat(event.output as string),
+                context.jokes.concat(event.output.choices[0]!.message.content!),
             }),
-            target: 'rateJoke',
-          },
+            log((x) => x.context.jokes.at(-1)),
+          ],
+          target: 'rateJoke',
         },
       },
-      rateJoke: {
-        invoke: {
-          src: 'rateJoke',
-          input: ({ context }) => ({
-            joke: context.jokes[context.jokes.length - 1]!,
-          }),
-          onDone: {
-            actions: assign({
-              lastRating: ({ event }) => event.output as string,
+    },
+    rateJoke: {
+      invoke: {
+        src: 'rateJoke',
+        input: ({ context }) => context.jokes[context.jokes.length - 1]!,
+        onDone: {
+          actions: [
+            assign({
+              lastRating: ({ event }) =>
+                event.output.choices[0]!.message.content!,
             }),
-            target: 'joked',
-          },
+            log(({ context }) => context.lastRating),
+          ],
+          target: 'decide',
         },
       },
-      joked: {
-        invoke: {
-          src: 'getTopic',
-          onDone: {
-            actions: assign({
-              desire: ({ event }) => event.output,
-            }),
-            target: 'decide',
-          },
+    },
+    decide: {
+      invoke: {
+        src: 'decide',
+        input: ({ context }) => context.lastRating!,
+        onDone: {
+          actions: [
+            log(({ event }) => event),
+            raise(({ event }) => event.output![0]!),
+          ],
         },
       },
-      decide: {
-        invoke: {
-          src: 'decide',
-          input: ({ context }) => context.desire!,
+      on: {
+        askForTopic: {
+          target: 'waitingForTopic',
+          description:
+            'Ask for a new topic, because the last joke rated 6 or lower',
         },
-        on: {
-          askForTopic: {
-            target: 'waitingForTopic',
-            description:
-              'Ask for a new topic, because the last joke was almost perfect',
-          },
-          endJokes: {
-            target: 'end',
-            description: 'End the jokes, since the last joke was not too good',
-          },
+        endJokes: {
+          target: 'end',
+          description: 'End the jokes, since the last joke rated 7 or higher',
         },
       },
-      end: {},
     },
-  });
-
-  const actor = createActor(chain, {
-    input: {
-      topic: 'donuts',
+    end: {
+      type: 'final',
     },
-  });
-
-  actor.subscribe((st) => {
-    console.log('State: ', st.value);
-
-    if (st.context.jokes) {
-      console.log('Joke: ', st.context.jokes[st.context.jokes.length - 1]);
-    }
-  });
-
-  actor.start();
+  },
+});
 
-  await waitFor(actor, (snap) => snap.status === 'done', {
-    timeout: Infinity,
-  });
-}
+const actor = createActor(jokeMachine);
 
-start();
+actor.start();

package/examples/ticTacToe.ts

@@ -1,6 +1,6 @@
 import { assign, setup, assertEvent, createActor, raise } from 'xstate';
-import { fromChatCompletionStream, fromEventChoice } from '../src/openai';
 import OpenAI from 'openai';
+import { createAgent } from '../src/openai';
 
 const openai = new OpenAI({
   apiKey: process.env.OPENAI_API_KEY,
@@ -8,64 +8,113 @@ const openai = new OpenAI({
 
 type Player = 'x' | 'o';
 
+const agent = createAgent(openai, {
+  model: 'gpt-3.5-turbo-1106',
+  context: {
+    board: {
+      type: 'array',
+      items: {
+        type: ['null', 'string'],
+        enum: [null, 'x', 'o'],
+      },
+      minItems: 9,
+      maxItems: 9,
+      description: 'The board of the tic-tac-toe game',
+    },
+    moves: {
+      type: 'number',
+      description: 'The number of moves that have been played',
+    },
+    player: {
+      type: 'string',
+      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',
+    },
+    events: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    },
+  } as const,
+  events: {
+    'x.play': {
+      properties: {
+        index: {
+          description: 'The index of the cell to play on',
+          type: 'number',
+
+          minimum: 0,
+          maximum: 8,
+        },
+      },
+    },
+    'o.play': {
+      properties: {
+        index: {
+          description: 'The index of the cell to play on',
+          type: 'number',
+          minimum: 0,
+          maximum: 8,
+        },
+      },
+    },
+    reset: {
+      properties: {},
+    },
+  },
+});
+
 const initialContext = {
   board: Array(9).fill(null) as Array<Player | null>,
   moves: 0,
   player: 'x' as Player,
-  winner: undefined as Player | undefined,
+  winner: null as Player | null,
   gameReport: '',
-};
+  events: [],
+} satisfies typeof agent.types.context;
+
+const bot = agent.fromEventChoice(
+  ({ 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.
+
+${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(
+  ({
+    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:
 
-export const ticTacToeMachine = setup({
-  types: {} as {
-    context: typeof initialContext;
-    events:
-      | { type: 'x.play'; index: number }
-      | {
-          type: 'o.play';
-          index: number;
-        }
-      | { type: 'RESET' };
-  },
-  actors: {
-    bot: fromEventChoice(
-      openai,
-      ({ context }: { context: typeof initialContext }) => ({
-        model: 'gpt-4-1106-preview',
-        messages: [
-          {
-            role: 'system',
-            content: `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)}`,
-          },
-          {
-            role: 'user',
-            content:
-              'Execute the single best next move to try to win the game. Do not play on an existing cell.',
-          },
-        ],
-      })
-    ),
-    gameReporter: fromChatCompletionStream(
-      openai,
-      ({ context }: { context: typeof initialContext }) => ({
-        model: 'gpt-4-1106-preview',
-        messages: [
-          {
-            role: 'user',
-            content: `The tic-tac-toe game is over. The winner is ${
-              context.winner ?? 'nobody'
-            }. This was the ending board state:
-          
 ${JSON.stringify(context.board, null, 2)}
 
-Provide a game report analyzing the game.`,
-          },
-        ],
-        stream: true,
-      })
-    ),
+And here are the events that led to this game state:
+
+${context.events.join('\n')}
+
+Provide a very short game report analyzing the game.`
+);
+
+export const ticTacToeMachine = setup({
+  types: agent.types,
+  actors: {
+    bot,
+    gameReporter,
   },
   actions: {
     updateBoard: assign({
@@ -77,11 +126,19 @@ Provide a game report analyzing the game.`,
       },
       moves: ({ context }) => context.moves + 1,
       player: ({ context }) => (context.player === 'x' ? 'o' : 'x'),
+      events: ({ context, event }) => {
+        return [...context.events, JSON.stringify(event)];
+      },
     }),
     resetGame: assign(initialContext),
     setWinner: assign({
       winner: ({ context }) => (context.player === 'x' ? 'o' : 'x'),
     }),
+    recordEvent: assign({
+      events: ({ context, event }) => {
+        return [...context.events, JSON.stringify(event)];
+      },
+    }),
   },
   guards: {
     checkWin: ({ context }) => {
@@ -157,18 +214,8 @@ Provide a game report analyzing the game.`,
                 target: 'o',
                 guard: 'isValidMove',
                 actions: 'updateBoard',
-                meta: {
-                  parameters: {
-                    index: {
-                      description: 'The index of the cell to play on',
-                      type: 'number',
-                      min: 0,
-                      max: 8,
-                    },
-                  },
-                },
               },
-              { reenter: true },
+              { target: 'x', reenter: true },
             ],
           },
         },
@@ -177,10 +224,8 @@ Provide a game report analyzing the game.`,
             src: 'bot',
             input: ({ context }) => ({ context }),
             onDone: {
-              // @ts-ignore
               actions: raise(({ event }) => {
-                console.log('output', event.output);
-                return event.output![0];
+                return event.output![0]!;
               }),
             },
           },
@@ -190,18 +235,8 @@ Provide a game report analyzing the game.`,
                 target: 'x',
                 guard: 'isValidMove',
                 actions: 'updateBoard',
-                meta: {
-                  parameters: {
-                    index: {
-                      description: 'The index of the cell to play on',
-                      type: 'number',
-                      min: 0,
-                      max: 8,
-                    },
-                  },
-                },
               },
-              { reenter: true },
+              { target: 'o', reenter: true },
             ],
           },
         },
@@ -233,7 +268,7 @@ Provide a game report analyzing the game.`,
         },
       },
       on: {
-        RESET: {
+        reset: {
           target: 'playing',
           actions: 'resetGame',
         },

package/package.json

@@ -1,26 +1,30 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc",
-    "test": "vitest run",
-    "prepublishOnly": "tsup src/index.ts --dts"
-  },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "devDependencies": {
+    "@changesets/cli": "^2.27.1",
     "@types/node": "^20.10.6",
+    "json-schema-to-ts": "^3.0.0",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   },
   "dependencies": {
     "openai": "^4.24.1",
     "xstate": "^5.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "tsc",
+    "test": "vitest run"
   }
-}
+}

package/src/index.ts

@@ -2,4 +2,5 @@ export {
   fromChatCompletion,
   fromChatCompletionStream,
   fromEventChoice,
+  createAgent,
 } from './openai';

package/src/openai.ts

@@ -1,12 +1,29 @@
 import OpenAI from 'openai';
 import {
   AnyEventObject,
+  ObservableActorLogic,
   Observer,
+  PromiseActorLogic,
+  Values,
   fromObservable,
   fromPromise,
+  setup,
   toObserver,
 } from 'xstate';
 import { getAllTransitions } from './utils';
+import {
+  ContextSchema,
+  EventSchemas,
+  ConvertContextToJSONSchema,
+  ConvertToJSONSchemas,
+  createEventSchemas,
+} from './utils';
+import { FromSchema } from 'json-schema-to-ts';
+import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
+import {
+  ChatCompletionCreateParamsBase,
+  ChatCompletionCreateParamsStreaming,
+} from 'openai/resources/chat/completions';
 
 /**
  * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that uses the OpenAI API to generate a completion.
@@ -19,12 +36,24 @@ export function fromChatCompletion<TInput>(
   openai: OpenAI,
   inputFn: (
     input: TInput
-  ) => OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
 ) {
   return fromPromise<OpenAI.Chat.Completions.ChatCompletion, TInput>(
     async ({ input }) => {
       const openAiInput = inputFn(input);
-      const response = await openai.chat.completions.create(openAiInput);
+      const params: ChatCompletionCreateParamsNonStreaming =
+        typeof openAiInput === 'string'
+          ? {
+              model: 'gpt-3.5-turbo-1106',
+              messages: [
+                {
+                  role: 'user',
+                  content: openAiInput,
+                },
+              ],
+            }
+          : openAiInput;
+      const response = await openai.chat.completions.create(params);
 
       return response;
     }
@@ -41,7 +70,7 @@ export function fromChatCompletionStream<TInput>(
   openai: OpenAI,
   inputFn: (
     input: TInput
-  ) => OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming
 ) {
   return fromObservable<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>(
     ({ input }) => {
@@ -49,8 +78,20 @@ export function fromChatCompletionStream<TInput>(
 
       (async () => {
         const openAiInput = inputFn(input);
+        const resolvedParams: ChatCompletionCreateParamsBase =
+          typeof openAiInput === 'string'
+            ? {
+                model: 'gpt-3.5-turbo-1106',
+                messages: [
+                  {
+                    role: 'user',
+                    content: openAiInput,
+                  },
+                ],
+              }
+            : openAiInput;
         const stream = await openai.chat.completions.create({
-          ...openAiInput,
+          ...resolvedParams,
           stream: true,
         });
 
@@ -85,9 +126,10 @@ export function fromChatCompletionStream<TInput>(
  */
 export function fromEventChoice<TInput>(
   openai: OpenAI,
+  machineTypes: { schemas: { context: ContextSchema; events: EventSchemas } },
   inputFn: (
     input: TInput
-  ) => OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
 ) {
   return fromPromise<AnyEventObject[] | undefined, TInput>(
     async ({ input, self }) => {
@@ -104,17 +146,33 @@ export function fromEventChoice<TInput>(
             type: 'function',
             function: {
               name,
-              description: t.description,
+              description:
+                t.description ??
+                machineTypes.schemas.events[t.eventType]?.description,
               parameters: {
                 type: 'object',
-                properties: t.meta?.parameters ?? {},
+                properties:
+                  machineTypes.schemas.events[t.eventType]?.properties ?? {},
               },
             },
           } as const;
         });
+
       const openAiInput = inputFn(input);
+      const completionParams: ChatCompletionCreateParamsNonStreaming =
+        typeof openAiInput === 'string'
+          ? {
+              model: 'gpt-4-1106-preview',
+              messages: [
+                {
+                  role: 'user',
+                  content: openAiInput,
+                },
+              ],
+            }
+          : openAiInput;
       const completion = await openai.chat.completions.create({
-        ...openAiInput,
+        ...completionParams,
         tools,
       });
 
@@ -129,7 +187,64 @@ export function fromEventChoice<TInput>(
         });
       }
 
-      return toolCalls ?? undefined;
+      return undefined;
     }
   );
 }
+
+interface CreateAgentOutput<
+  T extends {
+    model: ChatCompletionCreateParamsBase['model'];
+    context: ContextSchema;
+    events: EventSchemas;
+  }
+> {
+  model: T['model'];
+  schemas: T;
+  types: {
+    context: FromSchema<ConvertContextToJSONSchema<T['context']>>;
+    events: FromSchema<Values<ConvertToJSONSchemas<T['events']>>>;
+  };
+  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
+  >;
+}
+
+export function createAgent<
+  T extends {
+    model: ChatCompletionCreateParamsBase['model'];
+    context: ContextSchema;
+    events: EventSchemas;
+  }
+>(openai: OpenAI, settings: T): CreateAgentOutput<T> {
+  const obj: CreateAgentOutput<T> = {
+    model: settings.model,
+    schemas: {
+      context: {
+        type: 'object',
+        properties: settings.context,
+        additionalProperties: false,
+      },
+      events: createEventSchemas(settings.events),
+    } as any,
+    types: {} as any,
+    fromEventChoice: (input) => fromEventChoice(openai, obj, input) as any,
+    fromChatCompletion: (input) => fromChatCompletion(openai, input),
+    fromChatCompletionStream: (input) =>
+      fromChatCompletionStream(openai, input),
+  };
+
+  return obj as any;
+}

package/src/utils.ts

@@ -1,4 +1,6 @@
-import { AnyMachineSnapshot, AnyStateNode } from 'xstate';
+import { AnyMachineSnapshot, AnyStateNode, Prop, Values } from 'xstate';
+import { FromSchema } from 'json-schema-to-ts';
+import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
 
 export function getAllTransitions(state: AnyMachineSnapshot) {
   const nodes = state._nodes;
@@ -8,3 +10,59 @@ export function getAllTransitions(state: AnyMachineSnapshot) {
 
   return transitions;
 }
+
+export type EventSchemas = {
+  [key: string]: {
+    description?: string;
+    properties?: {
+      [key: string]: JSONSchema7;
+    };
+  };
+};
+
+export interface ContextSchema {
+  [key: string]: JSONSchema7;
+}
+
+export type ConvertToJSONSchemas<T> = {
+  [K in keyof T]: {
+    properties: { type: { const: K } };
+    type: 'object';
+    required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+    additionalProperties: false;
+  } & T[K];
+} & {};
+
+export type ConvertContextToJSONSchema<T extends ContextSchema> = {
+  type: 'object';
+  properties: T;
+  readonly required: Array<keyof T & string>;
+  additionalProperties: false;
+};
+
+export function createEventSchemas<T extends EventSchemas>(
+  eventSchemaMap: T
+): ConvertToJSONSchemas<T> {
+  const resolvedEventSchemaMap = {};
+
+  for (const [key, schema] of Object.entries(eventSchemaMap)) {
+    // @ts-ignore
+    resolvedEventSchemaMap[key] = {
+      type: 'object',
+      required: ['type'],
+      properties: {
+        type: {
+          const: key,
+        },
+        ...schema.properties,
+      },
+      additionalProperties: false,
+      ...schema,
+    } as JSONSchema7;
+  }
+
+  return resolvedEventSchemaMap as ConvertToJSONSchemas<T>;
+}
+
+export type InferEventsFromSchemas<T extends ConvertToJSONSchemas<any>> =
+  FromSchema<Values<T>>;