@statelyai/agent 0.0.1 → 0.0.3

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/changelog-github", { "repo": "statelyai/agent" }],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

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/.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,13 @@
+# @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
+
+- 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,47 @@ 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, 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) => OpenAI.Chat.Completions.ChatCompletionCreateParamsStreaming): xstate.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, inputFn: (input: TInput) => OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming): xstate.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;
+    events: EventSchemas;
+}> {
+    model: T['model'];
+    schemas: T;
+    types: {
+        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>;
+}
+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,25 +36,61 @@ 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) {
+function fromChatCompletion(openai, agentSettings, 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: agentSettings.model,
+        messages: [
+          {
+            role: "user",
+            content: openAiInput
+          }
+        ]
+      } : openAiInput;
+      const response = await openai.chat.completions.create(params);
       return response;
     }
   );
 }
-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: agentSettings.model,
+          messages: [
+            {
+              role: "user",
+              content: openAiInput
+            }
+          ]
+        } : openAiInput;
         const stream = await openai.chat.completions.create({
-          ...openAiInput,
+          ...resolvedParams,
           stream: true
         });
         for await (const part of stream) {
@@ -76,9 +113,9 @@ function fromChatCompletionStream(openai, inputFn) {
     }
   );
 }
-function fromEventChoice(openai, 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) => {
@@ -90,34 +127,72 @@ function fromEventChoice(openai, inputFn) {
           type: "function",
           function: {
             name,
-            description: t.description,
+            description: t.description ?? agentSettings.schemas.events[t.eventType]?.description,
             parameters: {
               type: "object",
-              properties: t.meta?.parameters ?? {}
+              properties: agentSettings.schemas.events[t.eventType]?.properties ?? {}
             }
           }
         };
       });
       const openAiInput = inputFn(input);
+      const completionParams = typeof openAiInput === "string" ? {
+        model: agentSettings.model,
+        messages: [
+          {
+            role: "user",
+            content: openAiInput
+          }
+        ]
+      } : openAiInput;
       const completion = await openai.chat.completions.create({
-        ...openAiInput,
+        ...completionParams,
         tools
       });
       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 toolCalls ?? void 0;
+      return void 0;
     }
   );
 }
+function createAgent(openai, settings) {
+  const agentSettings = {
+    model: settings.model,
+    schemas: {
+      context: {
+        type: "object",
+        properties: settings.context,
+        additionalProperties: false
+      },
+      events: createEventSchemas(settings.events)
+    },
+    types: {},
+    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 agentSettings;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createAgent,
   fromChatCompletion,
   fromChatCompletionStream,
   fromEventChoice

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