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

package/src/strategies/shortestPath.ts

@@ -0,0 +1,173 @@
+import { generateObject } from 'ai';
+import {
+  AgentDecision,
+  AgentDecideInput,
+  AgentStrategy,
+  AgentStep,
+  AnyAgent,
+  CostFunction,
+  ObservedState,
+} from '../types';
+import { getShortestPaths } from '@xstate/graph';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import Ajv from 'ajv';
+import { AnyMachineSnapshot } from 'xstate';
+
+const ajv = new Ajv();
+
+function observedStatesEqual(state1: ObservedState, state2: ObservedState) {
+  // check state value && state context
+  return (
+    JSON.stringify(state1.value) === JSON.stringify(state2.value) &&
+    JSON.stringify(state1.context) === JSON.stringify(state2.context)
+  );
+}
+
+function trimSteps(steps: AgentStep<any>[], currentState: ObservedState) {
+  const index = steps.findIndex(
+    (step) => step.state && observedStatesEqual(step.state, currentState)
+  );
+
+  if (index === -1) {
+    return undefined;
+  }
+
+  return steps.slice(index + 1, steps.length);
+}
+
+export async function experimental_shortestPathStrategy<T extends AnyAgent>(
+  agent: T,
+  input: AgentDecideInput<any>
+): Promise<AgentDecision<any> | undefined> {
+  const costFunction: CostFunction<any> =
+    input.costFunction ?? ((path) => path.weight ?? Infinity);
+  const existingDecision = agent
+    .getDecisions()
+    .find((p) => p.strategy === 'shortestPath' && p.goal === input.goal);
+
+  let paths = existingDecision?.paths;
+
+  if (existingDecision) {
+    console.log('Existing decision found');
+  }
+
+  if (!input.machine && !existingDecision) {
+    return;
+  }
+
+  if (input.machine && !existingDecision) {
+    const contextSchema = zodToJsonSchema(z.object(agent.context));
+    const result = await generateObject({
+      model: agent.model,
+      system: input.system ?? agent.description,
+      prompt: `
+<goal>
+${input.goal}
+</goal>
+<contextSchema>
+${contextSchema}
+</contextSchema>
+
+
+Update the context JSON schema so that it validates the context to determine that it reaches the goal. Return the result as a diff.
+
+The contextSchema properties must not change. Do not add or remove properties, or modify the name of the properties.
+Use "const" for exact required values and define ranges/types for flexible conditions.
+
+Examples:
+1. For "user is logged in with admin role":
+{
+  "contextSchema": "{"type": "object", "properties": {"role": {"const": "admin"}, "lastLogin": {"type": "string"}}, "required": ["role"]}"
+}
+
+2. For "score is above 100":
+{
+  "contextSchema": "{"type": "object", "properties": {"score": {"type": "number", "minimum": 100}}, "required": ["score"]}"
+}
+
+3. For "fruits contain apple, orange, banana":
+{
+  "type": "array",
+  "allOf": [
+    { "contains": { "const": "apple" } },
+    { "contains": { "const": "orange" } },
+    { "contains": { "const": "banana" } }
+  ]
+}
+    `.trim(),
+      schema: z.object({
+        // valueSchema: z
+        //   .string()
+        //   .describe('The JSON Schema representing the goal state value'),
+        contextSchema: z
+          .object({
+            type: z.literal('object'),
+            properties: z.object(
+              Object.keys((contextSchema as any).properties).reduce(
+                (acc, key) => {
+                  acc[key] = z.any();
+                  return acc;
+                },
+                {} as any
+              )
+            ),
+            required: z.array(z.string()).optional(),
+          })
+          .describe('The JSON Schema representing the goal state context'),
+      }),
+    });
+
+    console.log(result.object);
+    const validateContext = ajv.compile(result.object.contextSchema);
+
+    const stateFilter = (state: AnyMachineSnapshot) => {
+      return validateContext(state.context);
+    };
+
+    const resolvedState = input.machine.resolveState({
+      ...input.state,
+      context: input.state.context ?? {},
+    });
+
+    paths = getShortestPaths(input.machine, {
+      fromState: resolvedState,
+      toState: stateFilter,
+    });
+  }
+
+  if (!paths) {
+    return undefined;
+  }
+
+  const trimmedPaths = paths
+    .map((path) => {
+      const trimmedSteps = trimSteps(path.steps, input.state);
+      if (!trimmedSteps) {
+        return undefined;
+      }
+      return {
+        ...path,
+        steps: trimmedSteps,
+      };
+    })
+    .filter((p): p is NonNullable<typeof p> => p !== undefined);
+
+  // Sort paths from least weight to most weight
+  const sortedPaths = trimmedPaths.sort(
+    (a, b) => costFunction(a) - costFunction(b)
+  );
+
+  const leastWeightPath = sortedPaths[0];
+  const nextStep = leastWeightPath?.steps[0];
+
+  return {
+    strategy: 'shortestPath',
+    episodeId: agent.episodeId,
+    goal: input.goal,
+    goalState: paths[0]?.state,
+    nextEvent: nextStep?.event,
+    paths,
+    timestamp: Date.now(),
+  };
+}

package/src/{planners → strategies}/simple.ts

@@ -1,23 +1,27 @@
 import { CoreMessage, generateText } from 'ai';
-import { AgentPlan, AgentPlanInput, PromptTemplate, AnyAgent } from '../types';
-import { randomId } from '../utils';
+import {
+  AgentDecision,
+  AgentDecideInput,
+  PromptTemplate,
+  AnyAgent,
+} from '../types';
+import { convertToXml, randomId } from '../utils';
 import { getNextSnapshot } from 'xstate';
-import { defaultTextTemplate } from '../templates/defaultText';
 import { getMessages } from '../text';
 import { getToolMap } from '../decide';
 
-const simplePlannerPromptTemplate: PromptTemplate<any> = (data) => {
+const simpleStrategyPromptTemplate: PromptTemplate<any> = (data) => {
   return `
-${defaultTextTemplate(data)}
+${convertToXml(data)}
 
 Make at most one tool call to achieve the above goal. If the goal cannot be achieved with any tool calls, do not make any tool call.
   `.trim();
 };
 
-export async function simplePlanner<T extends AnyAgent>(
+export async function simpleStrategy<T extends AnyAgent>(
   agent: T,
-  input: AgentPlanInput<any>
-): Promise<AgentPlan<any> | undefined> {
+  input: AgentDecideInput<any>
+): Promise<AgentDecision<any> | undefined> {
   const toolMap = getToolMap(agent, input);
 
   if (!toolMap) {
@@ -27,8 +31,8 @@ export async function simplePlanner<T extends AnyAgent>(
 
   // Create a prompt with the given context and goal.
   // The template is used to ensure that a single tool call at most is made.
-  const prompt = simplePlannerPromptTemplate({
-    context: input.state.context,
+  const prompt = simpleStrategyPromptTemplate({
+    context: input.context,
     goal: input.goal,
   });
 
@@ -38,20 +42,22 @@ export async function simplePlanner<T extends AnyAgent>(
 
   const {
     state,
+    context,
     machine,
-    previousPlan,
+    prevDecision,
     events,
     goal,
     model: _,
     ...rest
   } = input;
 
-  const machineState = input.machine
-    ? input.machine.resolveState({
-        ...input.state,
-        context: input.state.context,
-      })
-    : undefined;
+  const machineState =
+    input.machine && input.state
+      ? input.machine.resolveState({
+          ...input.state,
+          context: input.state.context ?? {},
+        })
+      : undefined;
 
   const result = await generateText({
     ...rest,
@@ -81,7 +87,7 @@ export async function simplePlanner<T extends AnyAgent>(
   }
 
   return {
-    planner: 'simple',
+    strategy: 'simple',
     goal: input.goal,
     goalState: input.state,
     nextEvent: singleResult.result,
@@ -103,3 +109,7 @@ export async function simplePlanner<T extends AnyAgent>(
     ],
   };
 }
+
+export function createSimpleStrategy<T extends AnyAgent>() {
+  return simpleStrategy;
+}

package/src/types.ts

@@ -31,7 +31,7 @@ export type CostFunction<TEvent extends EventObject> = (
   path: AgentPath<TEvent>
 ) => number;
 
-export type AgentPlanInput<TEvent extends EventObject> = Omit<
+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,9 +55,9 @@ 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.
@@ -65,7 +65,7 @@ export type AgentPlanInput<TEvent extends EventObject> = Omit<
   costFunction?: CostFunction<TEvent>;
 
   /**
-   * The maximum number of attempts to generate a plan.
+   * The maximum number of attempts to make a decision.
    * Defaults to 2.
    */
   maxAttempts?: number;
@@ -86,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;
   /**
@@ -144,22 +144,29 @@ 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 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<T>;
+  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.
@@ -168,23 +175,21 @@ export type AgentDecideOptions<T extends AnyAgent> = {
 } & 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
    */
   attributes: Record<string, any>;
-  reward: number;
   timestamp: number;
   episodeId: string;
 }
 
 export interface AgentFeedbackInput {
-  goal?: string;
-  observationId?: string;
-  attributes?: Record<string, any>;
+  goal: string;
+  observationId: string;
+  attributes: Record<string, any>;
   timestamp?: number;
-  reward?: number;
 }
 
 export type AgentMessage = CoreMessage & {
@@ -327,6 +332,7 @@ export type AgentMessageInput = CoreMessage & {
 
 export interface AgentObservation<TActor extends ActorRefLike> {
   id: string;
+  // TODO: goal
   prevState: SnapshotFrom<TActor> | undefined;
   event: EventFrom<TActor> | undefined;
   state: SnapshotFrom<TActor>;
@@ -351,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
 >;
 
@@ -369,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<
@@ -388,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,
@@ -453,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[];
 };
 
@@ -472,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);

package/src/planners/shortestPath.ts

@@ -1,177 +0,0 @@
-import { generateObject } from 'ai';
-import {
-  AgentPlan,
-  AgentPlanInput,
-  AgentPlanner,
-  AgentStep,
-  AnyAgent,
-  CostFunction,
-  ObservedState,
-} from '../types';
-import { getShortestPaths } from '@xstate/graph';
-import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
-import Ajv from 'ajv';
-import { AnyMachineSnapshot } from 'xstate';
-
-const ajv = new Ajv();
-
-function observedStatesEqual(state1: ObservedState, state2: ObservedState) {
-  // check state value && state context
-  return (
-    JSON.stringify(state1.value) === JSON.stringify(state2.value) &&
-    JSON.stringify(state1.context) === JSON.stringify(state2.context)
-  );
-}
-
-function trimSteps(steps: AgentStep<any>[], currentState: ObservedState) {
-  const index = steps.findIndex(
-    (step) => step.state && observedStatesEqual(step.state, currentState)
-  );
-
-  if (index === -1) {
-    return undefined;
-  }
-
-  return steps.slice(index + 1, steps.length);
-}
-
-export function experimental_createShortestPathPlanner<
-  T extends AnyAgent
->(): AgentPlanner<T> {
-  return async function shortestPathPlanner<T extends AnyAgent>(
-    agent: T,
-    input: AgentPlanInput<any>
-  ): Promise<AgentPlan<any> | undefined> {
-    const costFunction: CostFunction<any> =
-      input.costFunction ?? ((path) => path.weight ?? Infinity);
-    const existingPlan = agent
-      .getPlans()
-      .find((p) => p.planner === 'shortestPath' && p.goal === input.goal);
-
-    let paths = existingPlan?.paths;
-
-    if (existingPlan) {
-      console.log('Existing plan found');
-    }
-
-    if (!input.machine && !existingPlan) {
-      return;
-    }
-
-    if (input.machine && !existingPlan) {
-      const contextSchema = zodToJsonSchema(z.object(agent.context));
-      const result = await generateObject({
-        model: agent.model,
-        system: input.system ?? agent.description,
-        prompt: `
-  <goal>
-  ${input.goal}
-  </goal>
-  <contextSchema>
-  ${contextSchema}
-  </contextSchema>
-  
-  
-  Update the context JSON schema so that it validates the context to determine that it reaches the goal. Return the result as a diff.
-  
-  The contextSchema properties must not change. Do not add or remove properties, or modify the name of the properties.
-  Use "const" for exact required values and define ranges/types for flexible conditions.
-  
-  Examples:
-  1. For "user is logged in with admin role":
-  {
-    "contextSchema": "{"type": "object", "properties": {"role": {"const": "admin"}, "lastLogin": {"type": "string"}}, "required": ["role"]}"
-  }
-  
-  2. For "score is above 100":
-  {
-    "contextSchema": "{"type": "object", "properties": {"score": {"type": "number", "minimum": 100}}, "required": ["score"]}"
-  }
-
-  3. For "fruits contain apple, orange, banana":
-  {
-    "type": "array",
-    "allOf": [
-      { "contains": { "const": "apple" } },
-      { "contains": { "const": "orange" } },
-      { "contains": { "const": "banana" } }
-    ]
-  }
-      `.trim(),
-        schema: z.object({
-          // valueSchema: z
-          //   .string()
-          //   .describe('The JSON Schema representing the goal state value'),
-          contextSchema: z
-            .object({
-              type: z.literal('object'),
-              properties: z.object(
-                Object.keys((contextSchema as any).properties).reduce(
-                  (acc, key) => {
-                    acc[key] = z.any();
-                    return acc;
-                  },
-                  {} as any
-                )
-              ),
-              required: z.array(z.string()).optional(),
-            })
-            .describe('The JSON Schema representing the goal state context'),
-        }),
-      });
-
-      console.log(result.object);
-      const validateContext = ajv.compile(result.object.contextSchema);
-
-      const stateFilter = (state: AnyMachineSnapshot) => {
-        return validateContext(state.context);
-      };
-
-      const resolvedState = input.machine.resolveState({
-        ...input.state,
-        context: input.state.context ?? {},
-      });
-
-      paths = getShortestPaths(input.machine, {
-        fromState: resolvedState,
-        toState: stateFilter,
-      });
-    }
-
-    if (!paths) {
-      return undefined;
-    }
-
-    const trimmedPaths = paths
-      .map((path) => {
-        const trimmedSteps = trimSteps(path.steps, input.state);
-        if (!trimmedSteps) {
-          return undefined;
-        }
-        return {
-          ...path,
-          steps: trimmedSteps,
-        };
-      })
-      .filter((p): p is NonNullable<typeof p> => p !== undefined);
-
-    // Sort paths from least weight to most weight
-    const sortedPaths = trimmedPaths.sort(
-      (a, b) => costFunction(a) - costFunction(b)
-    );
-
-    const leastWeightPath = sortedPaths[0];
-    const nextStep = leastWeightPath?.steps[0];
-
-    return {
-      planner: 'shortestPath',
-      episodeId: agent.episodeId,
-      goal: input.goal,
-      goalState: paths[0]?.state,
-      nextEvent: nextStep?.event,
-      paths,
-      timestamp: Date.now(),
-    };
-  };
-}