@statelyai/agent 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @statelyai/agent
 
+## 0.0.6
+
+### Patch Changes
+
+- [#16](https://github.com/statelyai/agent/pull/16) [`3ba5fb2`](https://github.com/statelyai/agent/commit/3ba5fb2392b51dee71f2585ed662b4ee9ecd6c41) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Update to XState 5.8.0
+
 ## 0.0.5
 
 ### Patch Changes

package/dist/index.d.ts

@@ -14,36 +14,38 @@ type EventSchemas = {
         };
     };
 };
-interface ContextSchema {
-    [key: string]: JSONSchema7;
-}
+type ContextSchema = JSONSchema7 & {
+    type: 'object';
+};
 type ConvertToJSONSchemas<T> = {
     [K in keyof T]: {
         properties: {
             type: {
                 const: K;
             };
-        };
+        } & Prop<T[K], 'properties'>;
         type: 'object';
-        required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+        required: Array<(keyof Prop<T[K], 'properties'> & string) | 'type'>;
         additionalProperties: false;
-    } & T[K];
+    };
 } & {};
-type ConvertContextToJSONSchema<T extends ContextSchema> = {
-    type: 'object';
-    properties: T;
-    readonly required: Array<keyof T & string>;
-    additionalProperties: false;
-};
 
-declare function createSchemas<TContextSchema extends ContextSchema, TEventSchemas extends EventSchemas>({ context, events, }: {
+declare function createSchemas<const TContextSchema extends ContextSchema, const TEventSchemas extends EventSchemas>({ context, events, }: {
+    /**
+     * The JSON schema for the context object.
+     *
+     * Must be of `{ type: 'object' }`.
+     */
     context: TContextSchema;
+    /**
+     * An object mapping event types to each event object's JSON Schema.
+     */
     events: TEventSchemas;
 }): {
-    context: ConvertContextToJSONSchema<TContextSchema>;
+    context: TContextSchema;
     events: ConvertToJSONSchemas<TEventSchemas>;
     types: {
-        context: FromSchema<ConvertContextToJSONSchema<TContextSchema>>;
+        context: FromSchema<TContextSchema>;
         events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
     };
 };
@@ -52,29 +54,26 @@ declare function createAgent<T extends AnyStateMachine>(...args: Parameters<type
 
 interface StatelyAgentAdapter {
     model: string;
-    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, options?: {
-        /**
-         * Immediately execute sending the event to the parent actor.
-         * @default true
-         */
-        execute?: boolean;
-    }) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
     /**
-     * Creates promise actor logic that resolves with a chat completion.
+     * Creates actor logic that chooses an event from all of the
+     * possible next events of the parent state machine
+     * and sends it to the parent actor.
+     */
+    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+    /**
+     * Creates actor logic that resolves with a chat completion.
      */
     fromChat: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
     /**
-     * Creates observable actor logic that emits a chat completion stream.
+     * Creates actor logic that emits a chat completion stream.
      */
     fromChatStream: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming) => ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+    /**
+     * Creates actor logic that chooses a tool from the provided
+     * tools and runs that tool.
+     */
     fromTool: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, tools: {
         [key: string]: Tool<any, any>;
-    }, options?: {
-        /**
-         * Immediately execute sending the event to the parent actor.
-         * @default true
-         */
-        execute?: boolean;
     }) => PromiseActorLogic<{
         result: any;
         tool: string;

package/dist/index.js

@@ -57,12 +57,7 @@ function createSchemas({
   events
 }) {
   return {
-    context: {
-      type: "object",
-      properties: context,
-      additionalProperties: false,
-      required: Object.keys(context)
-    },
+    context,
     events: createEventSchemas(events),
     types: {}
   };
@@ -134,7 +129,7 @@ function fromChatStream(openai, agentSettings, inputFn) {
     }
   );
 }
-function fromEvent(openai, agentSettings, inputFn, options) {
+function fromEvent(openai, agentSettings, inputFn) {
   return (0, import_xstate2.fromPromise)(
     async ({ input, self, system }) => {
       const parentSnapshot = self._parent?.getSnapshot();
@@ -177,26 +172,22 @@ function fromEvent(openai, agentSettings, inputFn, options) {
         tools
       });
       const toolCalls = completion.choices[0]?.message.tool_calls;
-      if (toolCalls) {
+      if (toolCalls?.length) {
         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);
-          });
-        }
+        const event = events[0];
+        system._relay(self, self._parent, event);
       }
       return void 0;
     }
   );
 }
 function fromTool(openai, agentSettings, tools, inputFn) {
-  return (0, import_xstate2.fromPromise)(async ({ input, self, system }) => {
-    const functionNameMapping = {};
+  return (0, import_xstate2.fromPromise)(async ({ input }) => {
     const resolvedTools = Object.entries(tools).map(([key, value]) => {
       return {
         type: "function",
@@ -241,10 +232,7 @@ function fromTool(openai, agentSettings, tools, inputFn) {
 function createOpenAIAdapter(openai, settings) {
   const agentSettings = {
     model: settings.model,
-    fromEvent: (input) => (
-      // @ts-ignore infinitely deep
-      fromEvent(openai, agentSettings, input, { execute: true })
-    ),
+    fromEvent: (input) => fromEvent(openai, agentSettings, input),
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
     fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
     fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input)

package/examples/joke.ts

@@ -9,15 +9,19 @@ const openai = new OpenAI({
 
 const schemas = createSchemas({
   context: {
-    topic: { type: 'string' },
-    jokes: {
-      type: 'array',
-      items: {
-        type: 'string',
+    type: 'object',
+    properties: {
+      topic: { type: 'string' },
+      jokes: {
+        type: 'array',
+        items: {
+          type: 'string',
+        },
       },
+      desire: { type: ['string', 'null'] },
+      lastRating: { type: ['string', 'null'] },
     },
-    desire: { type: ['string', 'null'] as const },
-    lastRating: { type: ['string', 'null'] as const },
+    required: ['topic', 'jokes', 'desire', 'lastRating'],
   },
   events: {
     askForTopic: {

package/examples/numberGuesser.ts

@@ -0,0 +1,128 @@
+import OpenAI from 'openai';
+import { createAgent, createOpenAIAdapter, createSchemas } from '../src';
+import { assign, setup } from 'xstate';
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const adapter = createOpenAIAdapter(openai, {
+  model: 'gpt-3.5-turbo-1106',
+});
+
+const guessLogic = adapter.fromEvent(
+  ({
+    previousGuesses,
+    lastResult,
+  }: {
+    previousGuesses: number[];
+    lastResult: string;
+  }) => `
+  Guess the number between 1 and 10. The previous guesses were ${
+    previousGuesses.length ? previousGuesses.join(', ') : 'not made yet'
+  } and the last result was ${lastResult}.
+`
+);
+
+const schemas = createSchemas({
+  context: {
+    type: 'object',
+    properties: {
+      lastGuess: {
+        type: ['number', 'null'],
+        description: 'The last guess',
+      },
+      previousGuesses: {
+        type: 'array',
+        items: {
+          type: 'number',
+        },
+        description: 'The previous guesses',
+      },
+      answer: {
+        type: 'number',
+        description: 'The answer',
+      },
+    },
+  },
+  events: {
+    guess: {
+      properties: {
+        number: {
+          // integer
+          type: 'number',
+          minimum: 1,
+          maximum: 10,
+        },
+      },
+      required: ['number'],
+    },
+  },
+});
+
+const machine = setup({
+  types: {
+    context: {} as {
+      previousGuesses: number[];
+      answer: number;
+    },
+    input: {} as { answer: number },
+    events: schemas.types.events,
+  },
+  schemas,
+  actors: {
+    guessLogic,
+  },
+}).createMachine({
+  context: ({ input }) => ({
+    answer: input.answer,
+    previousGuesses: [],
+  }),
+  initial: 'guessing',
+  states: {
+    guessing: {
+      always: {
+        guard: ({ context }) =>
+          context.answer === context.previousGuesses.at(-1),
+        target: 'winner',
+      },
+      invoke: {
+        src: 'guessLogic',
+        input: ({ context }) => ({
+          previousGuesses: context.previousGuesses,
+          lastResult:
+            context.previousGuesses.length === 0
+              ? 'not given yet'
+              : context.previousGuesses.at(-1)! - context.answer > 0
+              ? 'too high'
+              : 'too low',
+        }),
+      },
+      on: {
+        guess: {
+          actions: assign({
+            previousGuesses: ({ context, event }) => [
+              ...context.previousGuesses,
+              event.number,
+            ],
+          }),
+          target: 'guessing',
+          reenter: true,
+        },
+      },
+    },
+    winner: {
+      type: 'final',
+    },
+  },
+});
+
+const agent = createAgent(machine, {
+  input: { answer: 4 },
+  inspect: (ev) => {
+    if (ev.type === '@xstate.event') {
+      console.log(ev.event);
+    }
+  },
+});
+
+agent.start();

package/examples/ticTacToe.ts

@@ -10,36 +10,40 @@ type Player = 'x' | 'o';
 
 const schemas = createSchemas({
   context: {
-    board: {
-      type: 'array',
-      items: {
-        type: ['null', 'string'],
-        enum: [null, 'x', 'o'],
+    type: 'object',
+    properties: {
+      board: {
+        type: 'array',
+        items: {
+          type: ['null', 'string'],
+          enum: [null, 'x', 'o'],
+        },
+        minItems: 9,
+        maxItems: 9,
+        description: 'The board of the tic-tac-toe game',
       },
-      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',
-    },
-    gameReport: {
-      type: 'string',
-      description: 'The game report',
-    },
-    events: {
-      type: 'array',
-      items: {
+      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',
+      },
+      gameReport: {
+        type: 'string',
+        description: 'The game report',
+      },
+      events: {
+        type: 'array',
+        items: {
+          type: 'string',
+        },
       },
     },
-  } as const,
+    required: ['board', 'moves', 'player', 'gameReport', 'events'],
+  },
   events: {
     'x.play': {
       properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,13 +24,13 @@
     "access": "public"
   },
   "dependencies": {
-    "xstate": "^5.6.0"
+    "xstate": "^5.8.0"
   },
   "packageManager": "pnpm@8.11.0",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc",
-    "test": "vitest run",
+    "test": "vitest",
     "example": "ts-node examples/helpers/runner.ts",
     "changeset": "changeset",
     "release": "changeset publish",

package/readme.md

@@ -1,13 +1,14 @@
 # Stately Agent (alpha)
 
-🚧 Documentation in progress! Please see [the examples directory](https://github.com/statelyai/agent/tree/main/examples) for working examples.
+- Read [the documentation](https://stately.ai/docs/agents)
+- 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
+pnpm install openai @statelyai/agent
 ```
 
 ## Usage
@@ -35,7 +36,7 @@ OPENAI_API_KEY="your-openai-api-key"
 Then, install the dependencies (`npm install`) and run the examples:
 
 ```bash
-npm run example joke
+pnpm run example joke
 # or:
-# npm run example ticTacToe
+# pnpm run example ticTacToe
 ```

package/src/adapters/openai.ts

@@ -1,9 +1,7 @@
 import type OpenAI from 'openai';
 import {
   AnyEventObject,
-  ObservableActorLogic,
   Observer,
-  PromiseActorLogic,
   fromObservable,
   fromPromise,
   isMachineSnapshot,
@@ -11,10 +9,7 @@ import {
 } from 'xstate';
 import { getAllTransitions } from '../utils';
 import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
-import {
-  ChatCompletionCreateParamsBase,
-  ChatCompletionCreateParamsStreaming,
-} from 'openai/resources/chat/completions';
+import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
 import { StatelyAgentAdapter, Tool } from '../types';
 
 /**
@@ -26,7 +21,7 @@ import { StatelyAgentAdapter, Tool } from '../types';
  */
 export function fromChatCompletion<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
@@ -61,7 +56,7 @@ export function fromChatCompletion<TInput>(
  */
 export function fromChatStream<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
   ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming
@@ -120,17 +115,10 @@ export function fromChatStream<TInput>(
  */
 export function fromEvent<TInput>(
   openai: OpenAI,
-  agentSettings: OpenAIAdapterOutput<any>,
+  agentSettings: StatelyAgentAdapter,
   inputFn: (
     input: TInput
-  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming,
-  options?: {
-    /**
-     * Immediately execute sending the event to the parent actor.
-     * @default false
-     */
-    execute?: boolean;
-  }
+  ) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
 ) {
   return fromPromise<AnyEventObject[] | undefined, TInput>(
     async ({ input, self, system }) => {
@@ -186,7 +174,7 @@ export function fromEvent<TInput>(
 
       const toolCalls = completion.choices[0]?.message.tool_calls;
 
-      if (toolCalls) {
+      if (toolCalls?.length) {
         const events = toolCalls.map((tc) => {
           return {
             type: functionNameMapping[tc.function.name],
@@ -194,12 +182,10 @@ export function fromEvent<TInput>(
           };
         });
 
-        if (options?.execute) {
-          events.forEach((event) => {
-            // @ts-ignore
-            system._relay(self, self._parent, event);
-          });
-        }
+        const event = events[0]!;
+
+        // @ts-ignore
+        system._relay(self, self._parent, event);
       }
 
       return undefined;
@@ -243,8 +229,7 @@ export function fromTool<TInput>(
       }
     | undefined,
     TInput
-  >(async ({ input, self, system }) => {
-    const functionNameMapping: Record<string, string> = {};
+  >(async ({ input }) => {
     const resolvedTools = Object.entries(tools).map(([key, value]) => {
       return {
         type: 'function',
@@ -296,42 +281,6 @@ export function fromTool<TInput>(
   });
 }
 
-interface OpenAIAdapterOutput<
-  T extends {
-    model: ChatCompletionCreateParamsBase['model'];
-  }
-> {
-  model: T['model'];
-  /**
-   * Determines which event to send to the parent state machine actor based on the prompt.
-   */
-  fromEvent: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
-    options?: {
-      /**
-       * Immediately execute sending the event to the parent actor.
-       * @default true
-       */
-      execute?: boolean;
-    }
-  ) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
-  /**
-   * Creates promise actor logic that resolves with a chat completion.
-   */
-  fromChat: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
-  ) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
-  /**
-   * Creates observable actor logic that emits a chat completion stream.
-   */
-  fromChatStream: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming
-  ) => ObservableActorLogic<
-    OpenAI.Chat.Completions.ChatCompletionChunk,
-    TInput
-  >;
-}
-
 export function createOpenAIAdapter<
   T extends {
     model: ChatCompletionCreateParamsBase['model'];
@@ -339,9 +288,7 @@ export function createOpenAIAdapter<
 >(openai: OpenAI, settings: T): StatelyAgentAdapter {
   const agentSettings: StatelyAgentAdapter = {
     model: settings.model,
-    fromEvent: (input) =>
-      // @ts-ignore infinitely deep
-      fromEvent(openai, agentSettings, input, { execute: true }) as any,
+    fromEvent: (input) => fromEvent(openai, agentSettings, input),
     fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
     fromChatStream: (input) => fromChatStream(openai, agentSettings, input),
     fromTool: (input, tools) => fromTool(openai, agentSettings, tools, input),

package/src/schemas.ts

@@ -2,36 +2,38 @@ import { Values } from 'xstate';
 import {
   ContextSchema,
   EventSchemas,
-  ConvertContextToJSONSchema,
   ConvertToJSONSchemas,
   createEventSchemas,
 } from './utils';
 import { FromSchema } from 'json-schema-to-ts';
 
 export function createSchemas<
-  TContextSchema extends ContextSchema,
-  TEventSchemas extends EventSchemas
+  const TContextSchema extends ContextSchema,
+  const TEventSchemas extends EventSchemas
 >({
   context,
   events,
 }: {
+  /**
+   * The JSON schema for the context object.
+   *
+   * Must be of `{ type: 'object' }`.
+   */
   context: TContextSchema;
+  /**
+   * An object mapping event types to each event object's JSON Schema.
+   */
   events: TEventSchemas;
 }): {
-  context: ConvertContextToJSONSchema<TContextSchema>;
+  context: TContextSchema;
   events: ConvertToJSONSchemas<TEventSchemas>;
   types: {
-    context: FromSchema<ConvertContextToJSONSchema<TContextSchema>>;
+    context: FromSchema<TContextSchema>;
     events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
   };
 } {
   return {
-    context: {
-      type: 'object',
-      properties: context,
-      additionalProperties: false,
-      required: Object.keys(context),
-    },
+    context,
     events: createEventSchemas(events),
     types: {} as any,
   };

package/src/types.ts

@@ -4,8 +4,6 @@ import {
   ChatCompletionCreateParamsStreaming,
 } from 'openai/resources';
 import {
-  AnyActorLogic,
-  AnyActorRef,
   AnyEventObject,
   ObservableActorLogic,
   PromiseActorLogic,
@@ -13,24 +11,22 @@ import {
 
 export interface StatelyAgentAdapter {
   model: string;
+  /**
+   * Creates actor logic that chooses an event from all of the
+   * possible next events of the parent state machine
+   * and sends it to the parent actor.
+   */
   fromEvent: <TInput>(
-    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
-    options?: {
-      /**
-       * Immediately execute sending the event to the parent actor.
-       * @default true
-       */
-      execute?: boolean;
-    }
+    inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
   ) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
   /**
-   * Creates promise actor logic that resolves with a chat completion.
+   * Creates actor logic that resolves with a chat completion.
    */
   fromChat: <TInput>(
     inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming
   ) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
   /**
-   * Creates observable actor logic that emits a chat completion stream.
+   * Creates actor logic that emits a chat completion stream.
    */
   fromChatStream: <TInput>(
     inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming
@@ -38,18 +34,14 @@ export interface StatelyAgentAdapter {
     OpenAI.Chat.Completions.ChatCompletionChunk,
     TInput
   >;
-
+  /**
+   * Creates actor logic that chooses a tool from the provided
+   * tools and runs that tool.
+   */
   fromTool: <TInput>(
     inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming,
     tools: {
       [key: string]: Tool<any, any>;
-    },
-    options?: {
-      /**
-       * Immediately execute sending the event to the parent actor.
-       * @default true
-       */
-      execute?: boolean;
     }
   ) => PromiseActorLogic<
     | {

package/src/utils.ts

@@ -20,26 +20,17 @@ export type EventSchemas = {
   };
 };
 
-export interface ContextSchema {
-  [key: string]: JSONSchema7;
-}
+export type ContextSchema = JSONSchema7 & { type: 'object' };
 
 export type ConvertToJSONSchemas<T> = {
   [K in keyof T]: {
-    properties: { type: { const: K } };
+    properties: { type: { const: K } } & Prop<T[K], 'properties'>;
     type: 'object';
-    required: Array<keyof Prop<T[K], 'properties'> | 'type'>;
+    required: Array<(keyof Prop<T[K], 'properties'> & string) | '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> {

package/vitest.config.ts

@@ -0,0 +1,9 @@
+// vitest.config.ts
+import dotenv from 'dotenv';
+dotenv.config();
+
+export default {
+  test: {
+    testTimeout: 10000, // Global timeout of 10000ms for all tests
+  },
+};