@statelyai/agent 0.0.7 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -10,26 +10,33 @@
   "license": "MIT",
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.0",
-    "@changesets/cli": "^2.27.1",
-    "@types/node": "^20.10.6",
-    "dotenv": "^16.3.1",
-    "json-schema-to-ts": "^3.0.0",
-    "openai": "^4.24.1",
+    "@changesets/cli": "^2.27.5",
+    "@langchain/community": "^0.0.53",
+    "@langchain/core": "^0.1.63",
+    "@langchain/openai": "^0.0.28",
+    "@types/node": "^20.14.2",
+    "dotenv": "^16.4.5",
+    "json-schema-to-ts": "^3.1.0",
     "ts-node": "^10.9.2",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^1.2.2"
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0",
+    "wikipedia": "^2.1.2",
+    "zod": "^3.23.8"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "xstate": "^5.8.0"
+    "@ai-sdk/openai": "^0.0.13",
+    "@xstate/graph": "^2.0.0",
+    "ai": "^3.1.32",
+    "xstate": "^5.13.2"
   },
   "packageManager": "pnpm@8.11.0",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc",
+    "lint": "tsc --noEmit",
     "test": "vitest",
     "example": "ts-node examples/helpers/runner.ts",
     "changeset": "changeset",

package/readme.md

@@ -1,42 +1,13 @@
-# Stately Agent (alpha)
+# Stately Agent
 
-- Read [the documentation](https://stately.ai/docs/agents)
-- See [the examples directory](https://github.com/statelyai/agent/tree/main/examples) for working examples.
+> [!WARNING]  
+> Alpha software! Not ready for production yet.
 
-## Installation
+Stately Agent is a flexible framework for building AI agents using state machines. Stately agents go beyond normal LLM-based AI agents by:
 
-Install `openai`, and `@statelyai/agent`:
+- Using state machines to guide the agent's behavior, powered by [XState](https://stately.ai/docs/xstate)
+- Incorporating **observations**, **message history**, and **feedback** to the agent decision-making and text-generation processes, as needed
+- Enabling custom **planning** abilities for agents to achieve specific goals based on state machine logic, observations, and feedback
+- Wrapping the [Vercel AI SDK](https://sdk.vercel.ai/) to easily support multiple model providers, such as OpenAI, Anthropic, Google, Mistral, Groq, Perplexity, and more
 
-```bash
-pnpm install openai @statelyai/agent
-```
-
-## Usage
-
-Work in progress. For now, see the examples:
-
-- [Joke generator](https://github.com/statelyai/agent/tree/main/examples/joke.ts)
-  - Demonstrates `agent.fromChatCompletion(...)` to generate a joke and provide a joke rating
-  - Demonstrates `agent.fromEvent(...)` to choose whether to keep generating jokes or stop
-- [Tic-tac-toe](https://github.com/statelyai/agent/tree/main/examples/ticTacToe.ts)
-  - Demonstrates `agent.fromEvent(...)` to have an agent play itself in a game of tic-tac-toe with precise events
-  - Demonstrates `agent.fromChatCompletionStream(...)` to produce a game report at the end of the game
-- [Weather](https://github.com/statelyai/agent/tree/main/examples/weather.ts)
-  - Demonstrates using [Tavily](https://tavily.com/) as an external API
-  - Demonstrates `agent.fromEvent(...)` to only use Tavily to get the weather if the user provides a valid location
-
-## Examples
-
-First, clone this repo locally. To run the examples in this repo, create a `.env` file at the root of the repo with the following contents:
-
-```bash
-OPENAI_API_KEY="your-openai-api-key"
-```
-
-Then, install the dependencies (`npm install`) and run the examples:
-
-```bash
-pnpm run example joke
-# or:
-# pnpm run example ticTacToe
-```
+_Documentation coming soon_

package/src/adapters/vercel.ts

@@ -0,0 +1,7 @@
+import { generateText, streamText } from 'ai';
+import { AIAdapter } from '../types';
+
+export const vercelAdapter: AIAdapter = {
+  generateText,
+  streamText,
+};

package/src/agent-experimental.ts

@@ -0,0 +1,221 @@
+// //  type AgentExperiences<TState, TReward> = Record<
+// //   string, // serialized state
+// //   Record<
+// //     string, // serialized event
+// //     {
+// //       state: TState;
+// //       reward: TReward;
+// //     }
+// //   >
+
+// import OpenAI from 'openai';
+// import {
+//   AnyEventObject,
+//   EventObject,
+//   AnyActorLogic,
+//   AnyMachineSnapshot,
+//   ActorRef,
+//   AnyActorRef,
+//   SnapshotFrom,
+//   EventFrom,
+// } from 'xstate';
+// import { getToolCalls } from './adapters/openai';
+// import { ZodEventMapping } from './schemas';
+
+// // >;
+// interface AgentExperience<TState, TEvent extends AnyEventObject> {
+//   prevState: TState | undefined;
+//   event: TEvent;
+//   nextState: TState;
+// }
+
+// type AgentPlan<TState, TEvent extends EventObject> = Array<{
+//   /**
+//    * The current state
+//    */
+//   state: TState;
+//   /**
+//    * The event to execute
+//    */
+//   event: TEvent;
+//   /**
+//    * The expected next state
+//    */
+//   nextState?: TState;
+// }>;
+
+// interface AgentModel<
+//   // TLogic extends AnyActorLogic,
+//   TReward,
+//   TState,
+//   TEvent extends EventObject
+// > {
+//   // policy: ({
+//   //   logic,
+//   //   state,
+//   //   goal,
+//   // }: {
+//   //   logic: TLogic;
+//   //   state: TState;
+//   //   goal: string;
+//   // }) => Promise<AgentPlan<TState>>;
+//   getExperiences: () => Promise<Array<AgentExperience<TState, TEvent>>>; // TODO: TLogic instead?
+//   addExperience: (experience: AgentExperience<TState, TEvent>) => void;
+//   getLogic: ({
+//     experiences,
+//   }: {
+//     experiences: Array<AgentExperience<TState, TEvent>>; // TODO: TLogic instead?
+//   }) => Promise<AnyActorLogic>;
+//   getNextEvents: ({
+//     logic,
+//     state,
+//   }: {
+//     logic: AnyActorLogic;
+//     state: TState;
+//   }) => Promise<AnyEventObject[]>;
+//   getPlans: ({
+//     logic,
+//     state,
+//     goals,
+//   }: {
+//     logic: AnyActorLogic;
+//     state: TState;
+//     goals: string[];
+//   }) => Promise<Array<AgentPlan<TState, TEvent>>>;
+//   getReward: ({
+//     logic,
+//     state,
+//     goals,
+//     action,
+//   }: {
+//     logic: AnyActorLogic;
+//     state: TState;
+//     goals: string[];
+//     action: EventObject;
+//   }) => Promise<TReward>;
+// }
+
+// interface AgentLogic<T> {
+//   /**
+//    * The next possible actions (represented by events) that the agent can take
+//    * based on the current state of the environment
+//    */
+//   getActions(state: T): Promise<AnyEventObject[]>;
+//   getPlan(state: T, goal: any): Promise<Array<[T, EventObject]>>;
+// }
+
+// interface Agent<TState extends AnyMachineSnapshot, TEvent extends EventObject> {
+//   act: (env: ActorRef<TState, TEvent>) => Promise<void>;
+// }
+
+// function createAgent2<TEnvironment extends AnyActorRef>(
+//   openai: OpenAI,
+//   // logic: AnyActorLogic,
+//   // input: InputFrom<TLogic>,
+//   getGoals: (state: SnapshotFrom<TEnvironment>) => string | string[],
+//   schemas: ZodEventMapping
+// ): Agent<SnapshotFrom<TEnvironment>, EventFrom<TEnvironment>> {
+//   const experiences: Array<AgentExperience<any, any>> = [];
+
+//   const agentModel: AgentModel<
+//     any,
+//     SnapshotFrom<TEnvironment>,
+//     EventFrom<TEnvironment>
+//   > = {
+//     // policy: async ({ logic, state, goal }) => {
+//     //   const toolEvents = await getToolCalls(
+//     //     openai,
+//     //     goal,
+//     //     state,
+//     //     'gpt-4-1106-preview',
+//     //     (eventType) => eventType.startsWith('agent.'),
+//     //     schemas
+//     //   );
+//     //   console.log(toolEvents);
+//     //   return toolEvents.map((te) => ({
+//     //     state,
+//     //     event: te as EventFromLogic<TLogic>,
+//     //   }));
+//     // },
+//     addExperience: (experience) => {
+//       experiences.push(experience);
+//     },
+//     getExperiences: async () => experiences,
+//     getLogic: async ({ experiences }) => {
+//       return null as any; // TODO
+//     },
+//     getNextEvents: async ({ logic, state }) => {
+//       return [];
+//     },
+//     getReward: async ({ logic, state, goals, action }) => {
+//       return 0;
+//     },
+//     getPlans: async ({ logic, state, goals }) => {
+//       if (!goals[0]) {
+//         return [];
+//       }
+
+//       const toolEvents = await getToolCalls(
+//         openai,
+//         goals[0] + '\nOnly make a single tool call.',
+//         state as any,
+//         'gpt-3.5-turbo-16k-0613',
+//         (eventType) => eventType.startsWith('agent.'),
+//         schemas
+//       );
+
+//       console.log(toolEvents);
+
+//       return [
+//         toolEvents.map((toolEvent) => ({
+//           state,
+//           event: toolEvent as EventFrom<TEnvironment>,
+//         })),
+//       ];
+//     },
+//   };
+
+//   // const actor = createActor(logic, {
+//   //   input,
+//   //   inspect: (inspEv) => {
+//   //     if (inspEv.type === '@xstate.snapshot') {
+//   //       agentModel.addExperience({
+//   //         prevState: experiences[experiences.length - 1]?.nextState,
+//   //         nextState: (inspEv.snapshot as AnyMachineSnapshot).value,
+//   //         event: inspEv.event as EventFromLogic<TLogic>,
+//   //       });
+//   //     }
+//   //   },
+//   // });
+
+//   return {
+//     act: async (actorRef) => {
+//       const state = actorRef.getSnapshot();
+//       // @ts-ignore
+//       console.log(state.value, state.context);
+//       const experiences = await agentModel.getExperiences();
+//       const goals = toArray(getGoals(state));
+//       console.log('Goal:', goals);
+
+//       const nextPlans = await agentModel.getPlans({
+//         logic: await agentModel.getLogic({ experiences }),
+//         goals,
+//         state,
+//       });
+
+//       const nextStep = nextPlans?.[0]?.[0];
+
+//       // TODO: race conditions!
+//       if (nextStep) {
+//         console.log('nextStep', nextStep?.event);
+//         actorRef.send(nextStep.event);
+//       } else {
+//         console.log('No next step');
+//       }
+//     },
+//   } satisfies Agent<SnapshotFrom<TEnvironment>, EventFrom<TEnvironment>>; // TODO: fix types
+// }
+
+// function toArray<T>(value: T | T[]): T[] {
+//   return Array.isArray(value) ? value : [value];
+// }

package/src/agent.test.ts

@@ -0,0 +1,187 @@
+import { test, expect } from 'vitest';
+import { createAgent, type AIAdapter } from './';
+import { createActor, createMachine } from 'xstate';
+
+test('an agent has the expected interface', () => {
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  expect(agent.decide).toBeDefined();
+  expect(agent.generateText).toBeDefined();
+  expect(agent.streamText).toBeDefined();
+
+  expect(agent.addFeedback).toBeDefined();
+  expect(agent.addMessage).toBeDefined();
+  expect(agent.addObservation).toBeDefined();
+  expect(agent.addPlan).toBeDefined();
+
+  expect(agent.interact).toBeDefined();
+});
+
+test('agent.addMessage() adds to message history', () => {
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  agent.addMessage({
+    content: 'msg 1',
+    role: 'user',
+  });
+
+  const messageHistory = agent.addMessage({
+    content: 'response 1',
+    role: 'assistant',
+  });
+
+  expect(messageHistory.sessionId).toEqual(agent.sessionId);
+
+  expect(agent.select((c) => c.messages)).toContainEqual(
+    expect.objectContaining({
+      content: 'msg 1',
+    })
+  );
+
+  expect(agent.select((c) => c.messages)).toContainEqual(
+    expect.objectContaining({
+      content: 'response 1',
+      sessionId: expect.any(String),
+      timestamp: expect.any(Number),
+    })
+  );
+});
+
+test('agent.addFeedback() adds to feedback', () => {
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const feedback = agent.addFeedback({
+    attributes: {
+      score: -1,
+    },
+    goal: 'Win the game',
+    observationId: 'obs-1',
+  });
+
+  expect(feedback.sessionId).toEqual(agent.sessionId);
+
+  expect(agent.select((c) => c.feedback)).toContainEqual(
+    expect.objectContaining({
+      attributes: {
+        score: -1,
+      },
+      goal: 'Win the game',
+      observationId: 'obs-1',
+      sessionId: expect.any(String),
+      timestamp: expect.any(Number),
+    })
+  );
+});
+
+test('agent.addObservation() adds to observations', () => {
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const observation = agent.addObservation({
+    prevState: { value: 'playing', context: {} },
+    event: { type: 'play', position: 3 },
+    state: { value: 'lost', context: {} },
+  });
+
+  expect(observation.sessionId).toEqual(agent.sessionId);
+
+  expect(agent.select((c) => c.observations)).toContainEqual(
+    expect.objectContaining({
+      prevState: { value: 'playing', context: {} },
+      event: { type: 'play', position: 3 },
+      state: { value: 'lost', context: {} },
+      sessionId: expect.any(String),
+      timestamp: expect.any(Number),
+    })
+  );
+});
+
+test('agent.interact() observes machine actors (no 2nd arg)', () => {
+  const machine = createMachine({
+    initial: 'a',
+    states: {
+      a: {
+        on: { NEXT: 'b' },
+      },
+      b: {},
+    },
+  });
+
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    model: {} as any,
+  });
+
+  const actor = createActor(machine);
+
+  agent.interact(actor);
+
+  actor.start();
+
+  expect(agent.select((c) => c.observations)).toContainEqual(
+    expect.objectContaining({
+      prevState: undefined,
+      state: expect.objectContaining({ value: 'a' }),
+    })
+  );
+
+  actor.send({ type: 'NEXT' });
+
+  expect(agent.select((c) => c.observations)).toContainEqual(
+    expect.objectContaining({
+      prevState: expect.objectContaining({ value: 'a' }),
+      event: { type: 'NEXT' },
+      state: expect.objectContaining({ value: 'b' }),
+    })
+  );
+});
+
+test('Agents can use a custom adapter', async () => {
+  const adapter = {
+    generateText: async () => {
+      return {
+        text: 'Response',
+      } as any;
+    },
+  } as unknown as AIAdapter;
+
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    adapter,
+    model: {} as any,
+  });
+
+  const res = await agent.generateText({
+    prompt: 'Question?',
+  });
+
+  expect(res.text).toEqual('Response');
+});
+
+test.skip('You can listen for emitted agent events', () => {
+  const agent = createAgent({
+    name: 'test',
+    events: {},
+    adapter: {} as any,
+    model: {} as any,
+  });
+
+  agent.on('feedback', (x) => {});
+});