@statelyai/agent 0.0.2 → 0.0.4

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,19 @@
 # @statelyai/agent
 
+## 0.0.4
+
+### Patch Changes
+
+- [#5](https://github.com/statelyai/agent/pull/5) [`ae473d7`](https://github.com/statelyai/agent/commit/ae473d73399a15ac3199d77d00eb44a0ea5626db) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Simplify API (WIP)
+
+- [#5](https://github.com/statelyai/agent/pull/5) [`687bed8`](https://github.com/statelyai/agent/commit/687bed87f29bd1d13447cc53b5154da0fe6fdcab) Thanks [@davidkpiano](https://github.com/davidkpiano)! - Add `createSchemas`, `createOpenAIAdapter`, and change `createAgent`
+
+## 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

@@ -1,7 +1,8 @@
-import OpenAI from 'openai';
-import { Prop, PromiseActorLogic, ObservableActorLogic, AnyEventObject, Values } from 'xstate';
+import * as xstate from 'xstate';
+import { Prop, Values, AnyStateMachine, createActor, PromiseActorLogic, AnyEventObject, ObservableActorLogic } from 'xstate';
 import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
 import { FromSchema } from 'json-schema-to-ts';
+import OpenAI from 'openai';
 import { ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
 import { ChatCompletionCreateParamsBase, ChatCompletionCreateParamsStreaming } from 'openai/resources/chat/completions';
 
@@ -35,52 +36,45 @@ type ConvertContextToJSONSchema<T extends ContextSchema> = {
     additionalProperties: false;
 };
 
-/**
- * Creates [promise actor logic](https://stately.ai/docs/promise-actors) that uses the OpenAI API to generate a completion.
- *
- * @param openai The OpenAI instance.
- * @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>;
-/**
- * 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>;
-/**
- * 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;
+declare function createSchemas<TContextSchema extends ContextSchema, TEventSchemas extends EventSchemas>({ context, events, }: {
+    context: TContextSchema;
+    events: TEventSchemas;
+}): {
+    context: ConvertContextToJSONSchema<TContextSchema>;
+    events: ConvertToJSONSchemas<TEventSchemas>;
+    types: {
+        context: FromSchema<ConvertContextToJSONSchema<TContextSchema>>;
+        events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
     };
-}, inputFn: (input: TInput) => string | OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
-interface CreateAgentOutput<T extends {
+};
+
+declare function createAgent<T extends AnyStateMachine>(...args: Parameters<typeof createActor<T>>): xstate.Actor<T>;
+
+interface OpenAIAdapterOutput<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>;
+    /**
+     * Determines which event to send to the parent state machine actor based on the prompt.
+     */
+    fromEventChoice: <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>;
 }
-declare function createAgent<T extends {
+declare function createOpenAIAdapter<T extends {
     model: ChatCompletionCreateParamsBase['model'];
-    context: ContextSchema;
-    events: EventSchemas;
-}>(openai: OpenAI, settings: T): CreateAgentOutput<T>;
+}>(openai: OpenAI, settings: T): OpenAIAdapterOutput<T>;
 
-export { createAgent, fromChatCompletion, fromChatCompletionStream, fromEventChoice };
+export { createAgent, createOpenAIAdapter, createSchemas };

package/dist/index.js

@@ -21,15 +21,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   createAgent: () => createAgent,
-  fromChatCompletion: () => fromChatCompletion,
-  fromChatCompletionStream: () => fromChatCompletionStream,
-  fromEventChoice: () => fromEventChoice
+  createOpenAIAdapter: () => createOpenAIAdapter,
+  createSchemas: () => createSchemas
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/openai.ts
-var import_xstate = require("xstate");
-
 // src/utils.ts
 function getAllTransitions(state) {
   const nodes = state._nodes;
@@ -55,13 +51,38 @@ function createEventSchemas(eventSchemaMap) {
   return resolvedEventSchemaMap;
 }
 
-// src/openai.ts
-function fromChatCompletion(openai, inputFn) {
-  return (0, import_xstate.fromPromise)(
+// src/schemas.ts
+function createSchemas({
+  context,
+  events
+}) {
+  return {
+    context: {
+      type: "object",
+      properties: context,
+      additionalProperties: false,
+      required: Object.keys(context)
+    },
+    events: createEventSchemas(events),
+    types: {}
+  };
+}
+
+// src/agent.ts
+var import_xstate = require("xstate");
+function createAgent(...args) {
+  const [machine, options] = args;
+  return (0, import_xstate.createActor)(machine, options);
+}
+
+// src/adapters/openai.ts
+var import_xstate2 = require("xstate");
+function fromChatCompletion(openai, agentSettings, inputFn) {
+  return (0, import_xstate2.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 +95,14 @@ function fromChatCompletion(openai, inputFn) {
     }
   );
 }
-function fromChatCompletionStream(openai, inputFn) {
-  return (0, import_xstate.fromObservable)(
+function fromChatStream(openai, agentSettings, inputFn) {
+  return (0, import_xstate2.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",
@@ -101,7 +122,7 @@ function fromChatCompletionStream(openai, inputFn) {
       })();
       return {
         subscribe: (...args) => {
-          const observer = (0, import_xstate.toObserver)(...args);
+          const observer = (0, import_xstate2.toObserver)(...args);
           observers.add(observer);
           return {
             unsubscribe: () => {
@@ -113,9 +134,15 @@ function fromChatCompletionStream(openai, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, machineTypes, inputFn) {
-  return (0, import_xstate.fromPromise)(
-    async ({ input, self }) => {
+function fromEventChoice(openai, agentSettings, inputFn, options) {
+  return (0, import_xstate2.fromPromise)(
+    async ({ input, self, system }) => {
+      const parentSnapshot = self._parent?.getSnapshot();
+      if (!parentSnapshot || !(0, import_xstate2.isMachineSnapshot)(parentSnapshot)) {
+        return void 0;
+      }
+      const schemas = parentSnapshot.machine.schemas;
+      const eventSchemaMap = schemas.events ?? {};
       const transitions = getAllTransitions(self._parent.getSnapshot());
       const functionNameMapping = {};
       const tools = transitions.filter((t) => {
@@ -127,17 +154,17 @@ function fromEventChoice(openai, machineTypes, inputFn) {
           type: "function",
           function: {
             name,
-            description: t.description ?? machineTypes.schemas.events[t.eventType]?.description,
+            description: t.description ?? eventSchemaMap[t.eventType]?.description,
             parameters: {
               type: "object",
-              properties: machineTypes.schemas.events[t.eventType]?.properties ?? {}
+              properties: eventSchemaMap[t.eventType]?.properties ?? {}
             }
           }
         };
       });
       const openAiInput = inputFn(input);
       const completionParams = typeof openAiInput === "string" ? {
-        model: "gpt-4-1106-preview",
+        model: agentSettings.model,
         messages: [
           {
             role: "user",
@@ -151,39 +178,37 @@ 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 = {
+function createOpenAIAdapter(openai, settings) {
+  const agentSettings = {
     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)
+    fromEventChoice: (input) => (
+      // @ts-ignore infinitely deep
+      fromEventChoice(openai, agentSettings, input, { execute: true })
+    ),
+    fromChat: (input) => fromChatCompletion(openai, agentSettings, input),
+    fromChatStream: (input) => fromChatStream(openai, agentSettings, input)
   };
-  return obj;
+  return agentSettings;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAgent,
-  fromChatCompletion,
-  fromChatCompletionStream,
-  fromEventChoice
+  createOpenAIAdapter,
+  createSchemas
 });

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 + '\n');
+      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();
+}