@statelyai/agent 2.0.0-next.0 → 2.0.0-next.2

package/src/types.ts

@@ -31,8 +31,8 @@ export type CostFunction<TEvent extends EventObject> = (
   path: AgentPath<TEvent>
 ) => number;
 
-export type AgentPlanInput<TEvent extends EventObject> = Omit<
-  GenerateTextOptions,
+export type AgentDecideInput<TEvent extends EventObject> = Omit<
+  AgentGenerateTextOptions,
   'prompt' | 'tools'
 > & {
   /**
@@ -41,7 +41,7 @@ export type AgentPlanInput<TEvent extends EventObject> = Omit<
   state: ObservedState;
   /**
    * The goal for the agent to accomplish.
-   * The agent will create a plan based on this goal.
+   * The agent will make a decision based on this goal.
    */
   goal: string;
   /**
@@ -55,14 +55,20 @@ export type AgentPlanInput<TEvent extends EventObject> = Omit<
    */
   machine?: AnyStateMachine;
   /**
-   * The previous plan.
+   * The previous decision made by the agent.
    */
-  previousPlan?: AgentPlan<TEvent>;
+  prevDecision?: AgentDecision<TEvent>;
 
   /**
    * The total cost of the path to the goal state.
    */
   costFunction?: CostFunction<TEvent>;
+
+  /**
+   * The maximum number of attempts to make a decision.
+   * Defaults to 2.
+   */
+  maxAttempts?: number;
 };
 
 export type AgentStep<TEvent extends EventObject> = {
@@ -80,14 +86,14 @@ export type AgentPath<TEvent extends EventObject> = {
   weight?: number;
 };
 
-export type AgentPlan<TEvent extends EventObject> = {
+export type AgentDecision<TEvent extends EventObject> = {
   /**
-   * The planner used to generate the plan
+   * The strategy used to generate the decision
    */
-  planner: string;
+  strategy: string;
   goal: string;
   /**
-   * The ending state of the plan.
+   * The ending state of the decision.
    */
   goalState: ObservedState | undefined;
   /**
@@ -138,44 +144,52 @@ export type PromptTemplate<TEvents extends EventObject> = (data: {
   observations?: AgentObservation<any>[]; // TODO
   feedback?: AgentFeedback[];
   messages?: AgentMessage[];
-  plans?: AgentPlan<TEvents>[];
+  decisions?: AgentDecision<TEvents>[];
 }) => string;
 
-export type AgentPlanner<T extends AnyAgent> = (
+export type AgentStrategy<T extends AnyAgent> = (
   agent: T,
-  input: AgentPlanInput<T['types']['events']>
-) => Promise<AgentPlan<T['types']['events']> | undefined>;
+  input: AgentDecideInput<EventsFromAgent<T>>
+) => Promise<AgentDecision<EventsFromAgent<T>> | undefined>;
 
-export type AgentDecideOptions = {
+export type AgentInteractInput<T extends AnyAgent> = Omit<
+  AgentDecideOptions<T>,
+  'state'
+>;
+
+export type AgentDecideOptions<T extends AnyAgent> = {
   goal: string;
-  model?: LanguageModel;
   state: ObservedState;
+  context?: Record<string, any>;
   machine?: AnyStateMachine;
+  model?: LanguageModel;
   execute?: (event: AnyEventObject) => Promise<void>;
-  planner?: AgentPlanner<any>;
+  strategy?: AgentStrategy<T>;
   events?: ZodEventMapping;
+  allowedEvents?: Array<EventsFromAgent<T>['type']>;
+  /**
+   * The maximum number of times the agent will attempt to make a decision.
+   * Defaults to 2.
+   */
+  maxAttempts?: number;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 
 export interface AgentFeedback {
-  goal?: string;
-  observationId?: string;
+  goal: string;
+  observationId: string;
   /**
    * The message correlation that the feedback is relevant for
    */
-  correlationId?: string;
   attributes: Record<string, any>;
-  reward: number;
   timestamp: number;
   episodeId: string;
 }
 
 export interface AgentFeedbackInput {
-  goal?: string;
-  observationId?: string;
-  correlationId?: string;
-  attributes?: Record<string, any>;
+  goal: string;
+  observationId: string;
+  attributes: Record<string, any>;
   timestamp?: number;
-  reward?: number;
 }
 
 export type AgentMessage = CoreMessage & {
@@ -313,13 +327,12 @@ export type AgentMessageInput = CoreMessage & {
    * which message this message is responding to, if any.
    */
   responseId?: string;
-  correlationId?: string;
-  parentCorrelationId?: string;
   result?: GenerateTextResult<any>;
 };
 
 export interface AgentObservation<TActor extends ActorRefLike> {
   id: string;
+  // TODO: goal
   prevState: SnapshotFrom<TActor> | undefined;
   event: EventFrom<TActor> | undefined;
   state: SnapshotFrom<TActor>;
@@ -344,7 +357,7 @@ export type AgentDecisionInput = {
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 
 export type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<
-  AgentPlan<TEvents> | undefined,
+  AgentDecision<TEvents> | undefined,
   AgentDecisionInput | string
 >;
 
@@ -362,8 +375,8 @@ export type AgentEmitted<TEvents extends EventObject> =
       message: AgentMessage;
     }
   | {
-      type: 'plan';
-      plan: AgentPlan<TEvents>;
+      type: 'decision';
+      decision: AgentDecision<TEvents>;
     };
 
 export type AgentLogic<TEvents extends EventObject> = ActorLogic<
@@ -381,8 +394,8 @@ export type AgentLogic<TEvents extends EventObject> = ActorLogic<
       message: AgentMessage;
     }
   | {
-      type: 'agent.plan';
-      plan: AgentPlan<TEvents>;
+      type: 'agent.decision';
+      decision: AgentDecision<TEvents>;
     },
   any, // TODO: input
   any,
@@ -402,7 +415,7 @@ export type ContextFromZodContextMapping<
   [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
 
-export type AnyAgent = Agent<any, any>;
+export type AnyAgent = Agent<any, any, any, any>;
 
 export type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
 
@@ -446,7 +459,7 @@ export type ObservedStateFrom<TActor extends ActorRefLike> = Pick<
 export type AgentMemoryContext = {
   observations: AgentObservation<any>[]; // TODO
   messages: AgentMessage[];
-  plans: AgentPlan<any>[];
+  decisions: AgentDecision<any>[];
   feedback: AgentFeedback[];
 };
 
@@ -465,3 +478,31 @@ export interface AgentLongTermMemory {
 }
 
 export type Compute<A extends any> = { [K in keyof A]: A[K] } & unknown;
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type EventsFromAgent<T extends AnyAgent> = T extends Agent<
+  infer _,
+  infer __,
+  infer TEvents,
+  infer ___
+>
+  ? TEvents
+  : never;
+
+export type TypesFromAgent<T extends AnyAgent> = T extends Agent<
+  infer TContextSchema,
+  infer TEventSchema
+>
+  ? {
+      context: ContextFromZodContextMapping<TContextSchema>;
+      events: EventsFromZodEventMapping<TEventSchema>;
+    }
+  : never;
+
+export type ContextFromAgent<T extends AnyAgent> = T extends Agent<
+  infer TContextSchema,
+  infer _TEventSchema
+>
+  ? ContextFromZodContextMapping<TContextSchema>
+  : never;

package/src/utils.ts

@@ -59,6 +59,18 @@ export function wrapInXml(tagName: string, content: string): string {
   return `<${tagName}>${content}</${tagName}>`;
 }
 
+export function convertToXml(obj: Record<string, any>): string {
+  return Object.entries(obj)
+    .map(([key, value]) => {
+      if (typeof value === 'object' && value !== null) {
+        return wrapInXml(key, convertToXml(value));
+      } else {
+        return wrapInXml(key, value);
+      }
+    })
+    .join('');
+}
+
 export function randomId(prefix?: string): string {
   const timestamp = Date.now().toString(36);
   const random = Math.random().toString(36).substring(2, 9);
@@ -103,3 +115,14 @@ export function getTransitions(
   });
   return getAllTransitions(resolvedState);
 }
+
+export function isMachineActor(
+  actor: ActorRefLike
+): actor is typeof actor & { src: AnyStateMachine } {
+  return (
+    'src' in actor &&
+    typeof actor.src === 'object' &&
+    actor.src !== null &&
+    'definition' in actor.src
+  );
+}

package/vitest.config.ts

@@ -1,9 +1,15 @@
-// vitest.config.ts
+import { defineConfig } from 'vitest/config';
 import dotenv from 'dotenv';
 dotenv.config();
 
-export default {
+export default defineConfig({
   test: {
     testTimeout: 10000, // Global timeout of 10000ms for all tests
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['**.test.ts'],
+      include: ['src'],
+    },
   },
-};
+});

package/src/strategies/chain-of-note.ts

@@ -1,106 +0,0 @@
-import { GenerateTextResult, LanguageModel } from 'ai';
-import wiki, { wikiSearchResult, wikiSummary } from 'wikipedia';
-import { assign, fromPromise, setup } from 'xstate';
-import { AnyAgent } from '../types';
-
-const searchWiki = fromPromise(
-  async ({
-    input,
-  }: {
-    input: {
-      query: string;
-      limit?: number;
-    };
-  }) => {
-    const passages = await wiki.search(input.query, {
-      limit: input.limit ?? 5,
-    });
-    return passages;
-  }
-);
-
-const extractSummaries = fromPromise(
-  async ({
-    input,
-  }: {
-    input: {
-      searchResult: wikiSearchResult;
-    };
-  }) => {
-    const summaries = await Promise.all(
-      input.searchResult.results.map(async (result) => {
-        const summary = await wiki.summary(result.title);
-        return {
-          title: result.title,
-          summary,
-        };
-      })
-    );
-    return summaries;
-  }
-);
-
-export const chainOfNote = setup({
-  types: {
-    input: {} as {
-      model: LanguageModel;
-      agent: AnyAgent;
-      prompt: string;
-    },
-    context: {} as {
-      searchResults: wikiSearchResult | null;
-      summaries:
-        | {
-            title: any;
-            summary: wikiSummary;
-          }[]
-        | null;
-      model: LanguageModel;
-      agent: AnyAgent;
-      prompt: string;
-    },
-    output: {} as GenerateTextResult<any>,
-  },
-  actors: {
-    searchWiki,
-    extractSummaries,
-  },
-}).createMachine({
-  initial: 'searching',
-  context: ({ input }) => ({
-    ...input,
-    searchResults: null,
-    summaries: null,
-  }),
-  states: {
-    searching: {
-      invoke: {
-        src: 'searchWiki',
-        input: ({ context }) => ({
-          query: context.prompt,
-        }),
-        onDone: {
-          actions: assign({
-            searchResults: ({ event }) => event.output,
-          }),
-          target: 'extracting',
-        },
-      },
-    },
-    extracting: {
-      invoke: {
-        src: 'extractSummaries',
-        input: ({ context }) => ({
-          searchResult: context.searchResults!,
-        }),
-        onDone: {
-          actions: assign({
-            summaries: ({ event }) => event.output,
-          }),
-          target: 'generating',
-        },
-      },
-    },
-    generating: {},
-  },
-});