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

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as ai from 'ai';
 import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, LanguageModelV1, CoreTool } from 'ai';
-import { EventObject, AnyStateMachine, AnyEventObject, ActorRefLike, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, StateValue, Actor, Subscription, ObservableActorLogic } from 'xstate';
+import { AnyStateMachine, AnyEventObject, ActorRefLike, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, StateValue, EventObject, Actor, Subscription, ObservableActorLogic } from 'xstate';
 import { SomeZodObject, ZodType, TypeOf } from 'zod';
 
 type ZodEventMapping = {
@@ -12,15 +12,19 @@ type ZodContextMapping = {
 
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type StreamTextOptions = Parameters<typeof streamText>[0];
-type CostFunction<TEvent extends EventObject> = (path: AgentPath<TEvent>) => number;
-type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
+type CostFunction<TAgent extends AnyAgent> = (path: AgentPath<TAgent>) => number;
+type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions<TAgent>, 'prompt' | 'tools'> & {
     /**
      * The currently observed state.
      */
-    state: ObservedState;
+    state: ObservedState<TAgent>;
+    /**
+     * The context to provide in the prompt to the agent. This overrides the `state.context`.
+     */
+    context?: Record<string, any>;
     /**
      * 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;
     /**
@@ -33,53 +37,50 @@ type AgentPlanInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions,
      * is interacting with.
      */
     machine?: AnyStateMachine;
-    /**
-     * The previous plan.
-     */
-    previousPlan?: AgentPlan<TEvent>;
     /**
      * The total cost of the path to the goal state.
      */
-    costFunction?: CostFunction<TEvent>;
+    costFunction?: CostFunction<TAgent>;
     /**
-     * The maximum number of attempts to generate a plan.
+     * The maximum number of attempts to make a decision.
      * Defaults to 2.
      */
     maxAttempts?: number;
 };
-type AgentStep<TEvent extends EventObject> = {
+type AgentStep<TAgent extends AnyAgent> = {
     /** The event to take */
-    event: TEvent;
+    event: EventFromAgent<TAgent>;
     /** The next expected state after taking the event */
-    state: ObservedState | undefined;
+    state: ObservedState<TAgent> | undefined;
 };
-type AgentPath<TEvent extends EventObject> = {
+type AgentPath<TAgent extends AnyAgent> = {
     /** The expected ending state of the path */
-    state: ObservedState | undefined;
+    state: ObservedState<TAgent> | undefined;
     /** The steps to reach the ending state */
-    steps: Array<AgentStep<TEvent>>;
+    steps: Array<AgentStep<TAgent>>;
     weight?: number;
 };
-type AgentPlan<TEvent extends EventObject> = {
+type AgentDecision<TAgent extends AnyAgent> = {
+    id: string;
     /**
-     * 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;
+    goalState: ObservedState<TAgent> | undefined;
     /**
      * The next event that the agent decided needs to occur to achieve the `goal`.
      *
      * This next event is chosen from the
      */
-    nextEvent: TEvent | undefined;
+    nextEvent: EventFromAgent<TAgent> | undefined;
     /**
      * The paths that the agent can take to achieve the goal.
      */
-    paths: AgentPath<TEvent>[];
+    paths: AgentPath<TAgent>[];
     episodeId: string;
     timestamp: number;
 };
@@ -91,17 +92,13 @@ interface TransitionData {
     };
     target?: any;
 }
-type PromptTemplate<TEvents extends EventObject> = (data: {
+type PromptTemplate<TAgent extends AnyAgent> = (data: {
     goal: string;
     /**
      * The observed state
      */
-    state?: ObservedState;
-    /**
-     * The context to provide.
-     * This overrides the observed state.context, if provided.
-     */
-    context?: any;
+    stateValue?: any;
+    context?: Record<string, any>;
     /**
      * The state machine model of the observed environment
      */
@@ -117,17 +114,25 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     observations?: AgentObservation<any>[];
     feedback?: AgentFeedback[];
     messages?: AgentMessage[];
-    plans?: AgentPlan<TEvents>[];
+    decisions?: AgentDecision<TAgent>[];
 }) => string;
-type AgentPlanner<T extends AnyAgent> = (agent: T, input: AgentPlanInput<T['types']['events']>) => Promise<AgentPlan<T['types']['events']> | undefined>;
-type AgentDecideOptions<T extends AnyAgent> = {
+type AgentStrategy<TAgent extends AnyAgent> = (agent: TAgent, input: AgentDecideInput<EventFromAgent<TAgent>>) => Promise<AgentDecision<TAgent> | undefined>;
+type AgentInteractInput<T extends AnyAgent> = Omit<AgentDecideOptions<T>, 'state'> & {
+    state?: never;
+};
+type AgentDecideOptions<TAgent extends AnyAgent> = {
     goal: string;
-    model?: LanguageModel;
-    state: ObservedState;
+    state: ObservedState<TAgent>;
+    /**
+     * The context to provide in the prompt to the agent. This overrides the `state.context`.
+     */
+    context?: Record<string, any>;
     machine?: AnyStateMachine;
+    model?: LanguageModel;
     execute?: (event: AnyEventObject) => Promise<void>;
-    planner?: AgentPlanner<T>;
+    strategy?: AgentStrategy<TAgent>;
     events?: ZodEventMapping;
+    allowedEvents?: Array<EventFromAgent<TAgent>['type']>;
     /**
      * The maximum number of times the agent will attempt to make a decision.
      * Defaults to 2.
@@ -135,22 +140,22 @@ type AgentDecideOptions<T extends AnyAgent> = {
     maxAttempts?: number;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
 interface AgentFeedback {
-    goal?: string;
-    observationId?: string;
+    observationId: string;
+    score: number;
+    comment: string | undefined;
     /**
      * The message correlation that the feedback is relevant for
      */
     attributes: Record<string, any>;
-    reward: number;
     timestamp: number;
     episodeId: string;
 }
 interface AgentFeedbackInput {
-    goal?: string;
-    observationId?: string;
+    observationId: string;
+    score: number;
+    comment?: string;
     attributes?: Record<string, any>;
     timestamp?: number;
-    reward?: number;
 }
 type AgentMessage = CoreMessage & {
     timestamp: number;
@@ -215,6 +220,7 @@ type AgentMessageInput = CoreMessage & {
 };
 interface AgentObservation<TActor extends ActorRefLike> {
     id: string;
+    goal?: string;
     prevState: SnapshotFrom<TActor> | undefined;
     event: EventFrom<TActor> | undefined;
     state: SnapshotFrom<TActor>;
@@ -222,21 +228,22 @@ interface AgentObservation<TActor extends ActorRefLike> {
     episodeId: string;
     timestamp: number;
 }
-interface AgentObservationInput {
+interface AgentObservationInput<TAgent extends AnyAgent> {
     id?: string;
-    prevState?: ObservedState;
+    prevState?: ObservedState<TAgent>;
     event?: AnyEventObject;
-    state: ObservedState;
+    state: ObservedState<TAgent>;
     machine?: AnyStateMachine;
     timestamp?: number;
+    goal: string | undefined;
 }
 type AgentDecisionInput = {
     goal: string;
     model?: LanguageModel;
     context?: Record<string, any>;
 } & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-type AgentDecisionLogic<TEvents extends EventObject> = PromiseActorLogic<AgentPlan<TEvents> | undefined, AgentDecisionInput | string>;
-type AgentEmitted<TEvents extends EventObject> = {
+type AgentDecisionLogic<TAgent extends AnyAgent> = PromiseActorLogic<AgentDecision<TAgent> | undefined, AgentDecisionInput | string>;
+type AgentEmitted<TAgent extends AnyAgent> = {
     type: 'feedback';
     feedback: AgentFeedback;
 } | {
@@ -246,10 +253,10 @@ type AgentEmitted<TEvents extends EventObject> = {
     type: 'message';
     message: AgentMessage;
 } | {
-    type: 'plan';
-    plan: AgentPlan<TEvents>;
+    type: 'decision';
+    decision: AgentDecision<TAgent>;
 };
-type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<AgentMemoryContext>, {
+type AgentLogic<TAgent extends AnyAgent> = ActorLogic<TransitionSnapshot<AgentMemoryContext<TAgent>>, {
     type: 'agent.feedback';
     feedback: AgentFeedback;
 } | {
@@ -259,30 +266,30 @@ type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<Age
     type: 'agent.message';
     message: AgentMessage;
 } | {
-    type: 'agent.plan';
-    plan: AgentPlan<TEvents>;
+    type: 'agent.decision';
+    decision: AgentDecision<TAgent>;
 }, any, // TODO: input
-any, AgentEmitted<TEvents>>;
-type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
+any, AgentEmitted<TAgent>>;
+type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Compute<Values<{
     [K in keyof TEventSchemas & string]: {
         type: K;
     } & TypeOf<TEventSchemas[K]>;
-}>;
+}>>;
 type ContextFromZodContextMapping<TContextSchema extends ZodContextMapping> = {
     [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
 type AnyAgent = Agent<any, any, any, any>;
 type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
-type CommonTextOptions = {
+type CommonTextOptions<TAgent extends AnyAgent> = {
     prompt: FromAgent<string>;
     model?: LanguageModel;
-    context?: Record<string, any>;
     messages?: FromAgent<CoreMessage[]>;
     template?: PromptTemplate<any>;
+    context?: Record<string, any>;
 };
-type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
-interface ObservedState {
+type AgentGenerateTextOptions<TAgent extends AnyAgent> = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions<TAgent>;
+type AgentStreamTextOptions<TAgent extends AnyAgent> = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions<TAgent>;
+interface ObservedState<TAgent extends AnyAgent> {
     /**
      * The current state value of the state machine, e.g.
      * `"loading"` or `"processing"` or `"ready"`
@@ -291,25 +298,32 @@ interface ObservedState {
     /**
      * Additional contextual data related to the current state
      */
-    context?: Record<string, unknown>;
+    context?: ContextFromAgent<TAgent>;
 }
 type ObservedStateFrom<TActor extends ActorRefLike> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
-type AgentMemoryContext = {
-    observations: AgentObservation<any>[];
+type AgentMemoryContext<TAgent extends AnyAgent> = {
+    observations: AgentObservation<TAgent>[];
     messages: AgentMessage[];
-    plans: AgentPlan<any>[];
+    decisions: AgentDecision<TAgent>[];
     feedback: AgentFeedback[];
 };
-interface AgentLongTermMemory {
-    get<K extends keyof AgentMemoryContext>(key: K): Promise<AgentMemoryContext[K]>;
-    append<K extends keyof AgentMemoryContext>(key: K, item: AgentMemoryContext[K][0]): Promise<void>;
-    set<K extends keyof AgentMemoryContext>(key: K, items: AgentMemoryContext[K]): Promise<void>;
+interface AgentLongTermMemory<TAgent extends AnyAgent> {
+    get<K extends keyof AgentMemoryContext<TAgent>>(key: K): Promise<AgentMemoryContext<TAgent>[K]>;
+    append<K extends keyof AgentMemoryContext<TAgent>>(key: K, item: AgentMemoryContext<TAgent>[K][0]): Promise<void>;
+    set<K extends keyof AgentMemoryContext<TAgent>>(key: K, items: AgentMemoryContext<TAgent>[K]): Promise<void>;
 }
 type Compute<A extends any> = {
     [K in keyof A]: A[K];
 } & unknown;
+type MaybePromise<T> = T | Promise<T>;
+type EventFromAgent<T extends AnyAgent> = T extends Agent<infer _, infer __, infer TEvents, infer ___> ? TEvents : never;
+type TypesFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer TEventSchema> ? {
+    context: ContextFromZodContextMapping<TContextSchema>;
+    events: EventsFromZodEventMapping<TEventSchema>;
+} : never;
+type ContextFromAgent<T extends AnyAgent> = T extends Agent<infer TContextSchema, infer _TEventSchema> ? ContextFromZodContextMapping<TContextSchema> : never;
 
-declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>>({ id, description: description, model, events, context, planner, logic, }: {
+declare function createAgent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>, TAgent extends AnyAgent = Agent<TContextSchema, TEventSchemas>>({ id, description: description, model, events, context, episodeId, strategy, logic, }: {
     /**
      * The unique identifier for the agent.
      *
@@ -335,19 +349,20 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
      */
     events: TEventSchemas;
     context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+    strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
     stringify?: typeof JSON.stringify;
     /**
      * A function that retrieves the agent's long term memory
      */
-    getMemory?: (agent: Agent<TContextSchema, TEventSchemas>) => AgentLongTermMemory;
+    getMemory?: (agent: Agent<TContextSchema, TEventSchemas>) => AgentLongTermMemory<TAgent>;
     /**
      * Agent logic
      */
-    logic?: AgentLogic<TEvents>;
+    logic?: AgentLogic<TAgent>;
     model: LanguageModel;
-} & GenerateTextOptions): Agent<TContextSchema, TEventSchemas>;
-declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>> extends Actor<AgentLogic<TEvents>> {
+    episodeId?: string;
+}): Agent<TContextSchema, TEventSchemas>;
+declare class Agent<const TContextSchema extends ZodContextMapping, const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>, TContext = ContextFromZodContextMapping<TContextSchema>> extends Actor<AgentLogic<any>> {
     /**
      * The name of the agent. All agents with the same name are related and
      * able to share experiences (observations, feedback) with each other.
@@ -360,28 +375,29 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     description?: string;
     events: TEventSchemas;
     context?: TContextSchema;
-    planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
-    types: {
-        events: TEvents;
-        context: Compute<TContext>;
-    };
+    strategy: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
     model: LanguageModel;
-    memory: AgentLongTermMemory | undefined;
+    memory: AgentLongTermMemory<this> | undefined;
     defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
-    constructor({ logic, id, name, description, model, events, context, planner, }: {
-        logic: AgentLogic<TEvents>;
+    constructor({ logic, id, name, description, model, events, context, episodeId, strategy, }: {
+        logic: AgentLogic<any>;
         id?: string;
         name?: string;
         description?: string;
         model: GenerateTextOptions['model'];
         events: TEventSchemas;
         context?: TContextSchema;
-        planner?: AgentPlanner<Agent<TContextSchema, TEventSchemas>>;
+        strategy?: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
+        episodeId?: string;
     });
     /**
      * Called whenever the agent (LLM assistant) receives or sends a message.
      */
     onMessage(fn: (message: AgentMessage) => void): Subscription;
+    /**
+     * Called whenever the agent (LLM assistant) receives some feedback.
+     */
+    onFeedback(fn: (feedback: AgentFeedback) => void): Subscription;
     /**
      * Retrieves messages from the agent's short-term (local) memory.
      */
@@ -424,29 +440,29 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     };
     getMessages(): AgentMessage[];
     addFeedback(feedbackInput: AgentFeedbackInput): {
+        comment: string | undefined;
         attributes: {
             [x: string]: any;
         };
-        reward: number;
         timestamp: number;
         episodeId: string;
-        goal?: string;
-        observationId?: string;
+        observationId: string;
+        score: number;
     };
     /**
      * Retrieves feedback from the agent's short-term (local) memory.
      */
     getFeedback(): AgentFeedback[];
-    addObservation(observationInput: AgentObservationInput): AgentObservation<any>;
+    addObservation(observationInput: AgentObservationInput<this>): AgentObservation<any>;
     /**
      * Retrieves observations from the agent's short-term (local) memory.
      */
     getObservations(): AgentObservation<any>[];
-    addPlan(plan: AgentPlan<TEvents>): void;
+    addDecision(decision: AgentDecision<this>): void;
     /**
      * Retrieves strategies from the agent's short-term (local) memory.
      */
-    getPlans(): AgentPlan<any>[];
+    getDecisions(): AgentDecision<any>[];
     /**
      * Interacts with this state machine actor by inspecting state transitions and storing them as observations.
      *
@@ -491,29 +507,29 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * actor.start();
      * ```
      */
-    interact<TActor extends ActorRefLike>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined): Subscription;
+    interact<TActor extends ActorRefLike>(actorRef: TActor, getInput: (observation: AgentObservation<TActor>) => AgentInteractInput<this> | void): Subscription;
     observe<TActor extends ActorRefLike>(actorRef: TActor): Subscription;
     wrap(modelToWrap: LanguageModelV1): LanguageModelV1;
     /**
-     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
+     * Resolves with an `AgentDecision` based on the information provided in the `options`, including:
      *
      * - The `goal` for the agent to achieve
      * - The observed current `state`
      * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
-    decide(opts: AgentDecideOptions<this>): Promise<AgentPlan<EventsFromZodEventMapping<this["events"]>> | undefined>;
+    decide(opts: AgentDecideOptions<this>): Promise<AgentDecision<this> | undefined>;
 }
 
-declare function fromTextStream<T extends AnyAgent>(agent: T, options?: AgentStreamTextOptions): ObservableActorLogic<{
+declare function fromTextStream<TAgent extends AnyAgent>(agent: TAgent, options?: AgentStreamTextOptions<TAgent>): ObservableActorLogic<{
     textDelta: string;
-}, Omit<AgentStreamTextOptions, 'context'> & {
-    context?: AgentStreamTextOptions['context'];
+}, Omit<AgentStreamTextOptions<TAgent>, 'context'> & {
+    context?: Record<string, any>;
 }>;
-declare function fromText<T extends AnyAgent>(agent: T, options?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
-    context?: AgentGenerateTextOptions['context'];
+declare function fromText<TAgent extends AnyAgent>(agent: TAgent, options?: AgentGenerateTextOptions<TAgent>): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions<TAgent>, 'context'> & {
+    context?: Record<string, any>;
 }>;
 
-declare function fromDecision(agent: AnyAgent, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
+declare function fromDecision<T extends AnyAgent>(agent: T, defaultInput?: AgentDecideInput<EventFromAgent<T>>): AgentDecisionLogic<any>;
 
-export { type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStep, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromZodContextMapping, type CostFunction, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, createAgent, fromDecision, fromText, fromTextStream };
+export { type AgentDecideInput, type AgentDecideOptions, type AgentDecision, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentInteractInput, type AgentLogic, type AgentLongTermMemory, type AgentMemoryContext, type AgentMessage, type AgentMessageInput, type AgentObservation, type AgentObservationInput, type AgentPath, type AgentStep, type AgentStrategy, type AgentStreamTextOptions, type AnyAgent, type CommonTextOptions, type Compute, type ContextFromAgent, type ContextFromZodContextMapping, type CostFunction, type EventFromAgent, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type LanguageModelV1TextPart, type LanguageModelV1ToolCallPart, type MaybePromise, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, type TypesFromAgent, createAgent, fromDecision, fromText, fromTextStream };