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

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, ActorRefLike, SnapshotFrom, EventFrom, AnyEventObject, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, StateValue, EventObject, Actor, Subscription, ObservableActorLogic } from 'xstate';
 import { SomeZodObject, ZodType, TypeOf } from 'zod';
 
 type ZodEventMapping = {
@@ -12,12 +12,17 @@ type ZodContextMapping = {
 
 type GenerateTextOptions = Parameters<typeof generateText>[0];
 type StreamTextOptions = Parameters<typeof streamText>[0];
-type CostFunction<TEvent extends EventObject> = (path: AgentPath<TEvent>) => number;
-type AgentDecideInput<TEvent extends EventObject> = Omit<AgentGenerateTextOptions, 'prompt' | 'tools'> & {
+type CostFunction<TAgent extends AnyAgent> = (path: AgentPath<TAgent>) => number;
+type AgentDecideInput<TAgent extends AnyAgent> = Omit<AgentGenerateTextOptions<TAgent>, 'model' | 'prompt' | 'tools'> & {
+    episodeId?: string;
     /**
      * 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 make a decision based on this goal.
@@ -27,40 +32,40 @@ type AgentDecideInput<TEvent extends EventObject> = Omit<AgentGenerateTextOption
      * The events that the agent can trigger. This is a mapping of
      * event types to Zod event schemas.
      */
-    events: ZodEventMapping;
+    events?: ZodEventMapping;
+    allowedEvents?: Array<EventFromAgent<TAgent>['type']>;
     /**
      * The state machine that represents the environment the agent
      * is interacting with.
      */
     machine?: AnyStateMachine;
-    /**
-     * The previous decision made by the agent.
-     */
-    prevDecision?: AgentDecision<TEvent>;
     /**
      * The total cost of the path to the goal state.
      */
-    costFunction?: CostFunction<TEvent>;
+    costFunction?: CostFunction<TAgent>;
     /**
      * The maximum number of attempts to make a decision.
      * Defaults to 2.
      */
     maxAttempts?: number;
+    strategy?: AgentStrategy<TAgent>;
+    model?: LanguageModel;
 };
-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 AgentDecision<TEvent extends EventObject> = {
+type AgentDecision<TAgent extends AnyAgent> = {
+    id: string;
     /**
      * The strategy used to generate the decision
      */
@@ -69,17 +74,17 @@ type AgentDecision<TEvent extends EventObject> = {
     /**
      * 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 +96,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,42 +118,38 @@ type PromptTemplate<TEvents extends EventObject> = (data: {
     observations?: AgentObservation<any>[];
     feedback?: AgentFeedback[];
     messages?: AgentMessage[];
-    decisions?: AgentDecision<TEvents>[];
+    decisions?: AgentDecision<TAgent>[];
 }) => string;
-type AgentStrategy<T extends AnyAgent> = (agent: T, input: AgentDecideInput<EventsFromAgent<T>>) => Promise<AgentDecision<EventsFromAgent<T>> | undefined>;
-type AgentInteractInput<T extends AnyAgent> = Omit<AgentDecideOptions<T>, 'state'>;
-type AgentDecideOptions<T extends AnyAgent> = {
-    goal: string;
-    state: ObservedState;
-    context?: Record<string, any>;
-    machine?: AnyStateMachine;
-    model?: LanguageModel;
-    execute?: (event: AnyEventObject) => Promise<void>;
-    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'>;
-interface AgentFeedback {
-    goal: string;
-    observationId: string;
-    /**
-     * The message correlation that the feedback is relevant for
-     */
+type AgentStrategy<TAgent extends AnyAgent> = (agent: TAgent, input: AgentDecideInput<EventFromAgent<TAgent>>) => Promise<AgentDecision<TAgent> | undefined>;
+type AgentInteractInput<T extends AnyAgent> = Omit<AgentDecideInput<T>, 'state'> & {
+    state?: never;
+};
+type AgentFeedback = {
+    score: number;
+    comment: string | undefined;
     attributes: Record<string, any>;
     timestamp: number;
     episodeId: string;
-}
-interface AgentFeedbackInput {
-    goal: string;
+} & ({
     observationId: string;
-    attributes: Record<string, any>;
+    decisionId?: never;
+} | {
+    decisionId: string;
+    observationId?: never;
+});
+type AgentFeedbackInput = {
+    episodeId?: string;
+    score: number;
+    comment?: string;
+    attributes?: Record<string, any>;
     timestamp?: number;
-}
+} & ({
+    observationId: string;
+    decisionId?: never;
+} | {
+    decisionId: string;
+    observationId?: never;
+});
 type AgentMessage = CoreMessage & {
     timestamp: number;
     id: string;
@@ -216,28 +213,34 @@ type AgentMessageInput = CoreMessage & {
 };
 interface AgentObservation<TActor extends ActorRefLike> {
     id: string;
+    decisionId?: string | undefined;
+    goal?: string;
     prevState: SnapshotFrom<TActor> | undefined;
     event: EventFrom<TActor> | undefined;
     state: SnapshotFrom<TActor>;
-    machineHash: string | undefined;
     episodeId: string;
     timestamp: number;
 }
-interface AgentObservationInput {
+interface AgentObservationInput<TAgent extends AnyAgent> {
     id?: string;
-    prevState?: ObservedState;
+    episodeId?: string;
+    /**
+     * The agent decision that the observation is relevant for
+     */
+    decisionId?: string | undefined;
+    prevState?: ObservedState<TAgent>;
     event?: AnyEventObject;
-    state: ObservedState;
-    machine?: AnyStateMachine;
+    state: ObservedState<TAgent>;
     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<AgentDecision<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;
 } | {
@@ -248,9 +251,9 @@ type AgentEmitted<TEvents extends EventObject> = {
     message: AgentMessage;
 } | {
     type: 'decision';
-    decision: AgentDecision<TEvents>;
+    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;
 } | {
@@ -261,29 +264,29 @@ type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<Age
     message: AgentMessage;
 } | {
     type: 'agent.decision';
-    decision: AgentDecision<TEvents>;
+    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"`
@@ -292,32 +295,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[];
-    decisions: AgentDecision<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 EventsFromAgent<T extends AnyAgent> = T extends Agent<infer _, infer __, infer TEvents, infer ___> ? TEvents : never;
+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, episodeId, strategy, 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.
      *
@@ -348,15 +351,15 @@ declare function createAgent<const TContextSchema extends ZodContextMapping, con
     /**
      * 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;
     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<TEvents>> {
+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.
@@ -371,10 +374,9 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     context?: TContextSchema;
     strategy: AgentStrategy<Agent<TContextSchema, TEventSchemas>>;
     model: LanguageModel;
-    memory: AgentLongTermMemory | undefined;
-    defaultOptions: AgentDecideOptions<AnyAgent> | undefined;
+    memory: AgentLongTermMemory<this> | undefined;
     constructor({ logic, id, name, description, model, events, context, episodeId, strategy, }: {
-        logic: AgentLogic<TEvents>;
+        logic: AgentLogic<any>;
         id?: string;
         name?: string;
         description?: string;
@@ -434,24 +436,36 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
     };
     getMessages(): AgentMessage[];
     addFeedback(feedbackInput: AgentFeedbackInput): {
+        comment: string | undefined;
         attributes: {
             [x: string]: any;
         };
         timestamp: number;
         episodeId: string;
-        goal: string;
+        score: number;
         observationId: string;
+        decisionId?: never;
+    } | {
+        comment: string | undefined;
+        attributes: {
+            [x: string]: any;
+        };
+        timestamp: number;
+        episodeId: string;
+        score: number;
+        decisionId: string;
+        observationId?: never;
     };
     /**
      * 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>[];
-    addDecision(decision: AgentDecision<TEvents>): void;
+    addDecision(decision: AgentDecision<this>): void;
     /**
      * Retrieves strategies from the agent's short-term (local) memory.
      */
@@ -511,18 +525,18 @@ declare class Agent<const TContextSchema extends ZodContextMapping, const TEvent
      * - The `machine` (e.g. a state machine) that specifies what can happen next
      * - Additional `context`
      */
-    decide(opts: AgentDecideOptions<this>): Promise<AgentDecision<EventsFromAgent<this>> | undefined>;
+    decide(input: AgentDecideInput<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<T extends AnyAgent>(agent: T, defaultInput?: AgentDecideInput<EventsFromAgent<T>>): AgentDecisionLogic<any>;
+declare function fromDecision<T extends AnyAgent>(agent: T, defaultInput?: AgentDecideInput<EventFromAgent<T>>): AgentDecisionLogic<any>;
 
-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 EventsFromAgent, 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 };
+export { type AgentDecideInput, 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 };