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

package/src/types.ts

@@ -4,8 +4,6 @@ import {
   AnyEventObject,
   AnyStateMachine,
   EventFrom,
-  EventObject,
-  PromiseActorLogic,
   SnapshotFrom,
   StateValue,
   TransitionSnapshot,
@@ -13,7 +11,6 @@ import {
 } from 'xstate';
 import {
   CoreMessage,
-  GenerateObjectResult,
   generateText,
   GenerateTextResult,
   LanguageModel,
@@ -32,9 +29,13 @@ export type CostFunction<TAgent extends AnyAgent> = (
 ) => number;
 
 export type AgentDecideInput<TAgent extends AnyAgent> = Omit<
-  AgentGenerateTextOptions<TAgent>,
-  'prompt' | 'tools'
+  AgentGenerateTextOptions,
+  'model' | 'prompt' | 'tools' | 'toolChoice'
 > & {
+  /**
+   * The parent decision that this decision is a part of.
+   */
+  decisionId?: string;
   /**
    * The currently observed state.
    */
@@ -52,7 +53,8 @@ export type AgentDecideInput<TAgent extends AnyAgent> = Omit<
    * 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.
@@ -60,7 +62,7 @@ export type AgentDecideInput<TAgent extends AnyAgent> = Omit<
   machine?: AnyStateMachine;
 
   /**
-   * The total cost of the path to the goal state.
+   * A function that calculates the total cost of the path to the goal state.
    */
   costFunction?: CostFunction<TAgent>;
 
@@ -69,48 +71,80 @@ export type AgentDecideInput<TAgent extends AnyAgent> = Omit<
    * Defaults to 2.
    */
   maxAttempts?: number;
-};
+  /**
+   * The policy to use for making a decision.
+   */
+  policy?: AgentPolicy<TAgent>;
+  model?: LanguageModel;
+  /**
+   * The previous relevant feedback from the agent.
+   */
+  feedback?: AgentFeedback[];
+  /**
+   * The previous relevant observations from the agent.
+   */
+  observations?: AgentObservation<any>[];
+  /**
+   * The previous relevant decisions from the agent.
+   */
+  decisions?: AgentDecision<TAgent>[];
+  /**
+   * The previous relevant insights from the agent.
+   */
+  insights?: AgentInsight[];
+  toolChoice?: 'auto' | 'none' | 'required';
+} & BaseInput;
 
 export type AgentStep<TAgent extends AnyAgent> = {
   /** The event to take */
   event: EventFromAgent<TAgent>;
   /** The next expected state after taking the event */
-  state: ObservedState<TAgent> | undefined;
+  state: ObservedState<TAgent> | null;
 };
 
 export type AgentPath<TAgent extends AnyAgent> = {
   /** The expected ending state of the path */
-  state: ObservedState<TAgent> | undefined;
+  state: ObservedState<TAgent> | null;
   /** The steps to reach the ending state */
   steps: Array<AgentStep<TAgent>>;
   weight?: number;
 };
 
-export type AgentDecision<TAgent extends AnyAgent> = {
-  id: string;
+export interface AgentDecisionInput<TAgent extends AnyAgent> extends BaseInput {
+  goal: string;
+  decisionId?: string | null;
+  policy?: string | null;
+  goalState?: ObservedState<TAgent> | null;
+  nextEvent?: EventFromAgent<TAgent> | null;
+  paths?: AgentPath<TAgent>[];
+}
+
+export interface AgentDecision<TAgent extends AnyAgent = AnyAgent>
+  extends BaseProperties {
+  /**
+   * The parent decision that this decision is a part of.
+   */
+  decisionId: string | null;
   /**
-   * The strategy used to generate the decision
+   * The policy used to generate the decision
    */
-  strategy: string;
+  policy: string | null;
   goal: string;
   /**
    * The ending state of the decision.
    */
-  goalState: ObservedState<TAgent> | undefined;
+  goalState: ObservedState<TAgent> | null;
   /**
    * The next event that the agent decided needs to occur to achieve the `goal`.
    *
    * This next event is chosen from the
    */
-  nextEvent: EventFromAgent<TAgent> | undefined;
+  nextEvent: EventFromAgent<TAgent> | null;
   /**
    * The paths that the agent can take to achieve the goal.
    */
   paths: AgentPath<TAgent>[];
-  episodeId: string;
-  timestamp: number;
-  // result: GenerateObjectResult<any>;
-};
+}
 
 export interface TransitionData {
   eventType: string;
@@ -136,77 +170,77 @@ export type PromptTemplate<TAgent extends AnyAgent> = (data: {
    */
   transitions?: TransitionData[];
   /**
-   * Past observations
+   * Relevant past observations
    */
   observations?: AgentObservation<any>[]; // TODO
+  /**
+   * Relevant feedback
+   */
   feedback?: AgentFeedback[];
+  /**
+   * Relevant messages
+   */
   messages?: AgentMessage[];
+  /**
+   * Relevant past decisions
+   */
   decisions?: AgentDecision<TAgent>[];
+  /**
+   * Relevant past insights
+   */
+  insights?: AgentInsight[];
 }) => string;
 
-export type AgentStrategy<TAgent extends AnyAgent> = (
+export type AgentPolicy<TAgent extends AnyAgent = AnyAgent> = (
   agent: TAgent,
-  input: AgentDecideInput<EventFromAgent<TAgent>>
+  input: AgentDecideInput<TAgent>
 ) => Promise<AgentDecision<TAgent> | undefined>;
 
 export type AgentInteractInput<T extends AnyAgent> = Omit<
-  AgentDecideOptions<T>,
+  AgentDecideInput<T>,
   'state'
 > & {
   state?: never;
 };
 
-export type AgentDecideOptions<TAgent extends AnyAgent> = {
-  goal: string;
-  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>;
-  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.
-   */
-  maxAttempts?: number;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-
-export interface AgentFeedback {
-  observationId: string;
-  score: number;
+export interface AgentFeedback extends BaseProperties {
+  decisionId: string;
+  reward: number;
   comment: string | undefined;
-  /**
-   * The message correlation that the feedback is relevant for
-   */
   attributes: Record<string, any>;
-  timestamp: number;
+}
+
+interface BaseProperties {
+  id: string;
   episodeId: string;
+  timestamp: number;
 }
 
-export interface AgentFeedbackInput {
-  observationId: string;
-  score: number;
+type BaseInput = Partial<BaseProperties>;
+
+export interface AgentFeedbackInput extends BaseInput {
+  /**
+   * The decision ID that this feedback is relevant for.
+   */
+  decisionId: string;
+  reward: number;
   comment?: string;
   attributes?: Record<string, any>;
-  timestamp?: number;
 }
 
-export type AgentMessage = CoreMessage & {
-  timestamp: number;
-  id: string;
-  /**
-   * The response ID of the message, which references
-   * which message this message is responding to, if any.
-   */
-  responseId?: string;
-  result?: GenerateTextResult<any>;
-  episodeId: string;
-};
+export type AgentMessage = BaseProperties &
+  CoreMessage & {
+    /**
+     * The parent decision that this message is a part of.
+     */
+    decisionId?: string;
+    /**
+     * The response ID of the message, which references
+     * which message this message is responding to, if any.
+     */
+    responseId?: string;
+    result?: GenerateTextResult<any, any>;
+  };
 
 type JSONObject = {
   [key: string]: JSONValue;
@@ -219,24 +253,6 @@ type LanguageModelV1ProviderMetadata = Record<
   Record<string, JSONValue>
 >;
 
-interface LanguageModelV1ImagePart {
-  type: 'image';
-  /**
-Image data as a Uint8Array (e.g. from a Blob or Buffer) or a URL.
-   */
-  image: Uint8Array | URL;
-  /**
-Optional mime type of the image.
-   */
-  mimeType?: string;
-  /**
-   * Additional provider-specific metadata. They are passed through
-   * to the provider from the AI SDK and enable provider-specific
-   * functionality that can be fully encapsulated in the provider.
-   */
-  providerMetadata?: LanguageModelV1ProviderMetadata;
-}
-
 export interface LanguageModelV1TextPart {
   type: 'text';
   /**
@@ -272,56 +288,6 @@ Arguments of the tool call. This is a JSON-serializable object that matches the
    */
   providerMetadata?: LanguageModelV1ProviderMetadata;
 }
-interface LanguageModelV1ToolResultPart {
-  type: 'tool-result';
-  /**
-ID of the tool call that this result is associated with.
- */
-  toolCallId: string;
-  /**
-Name of the tool that generated this result.
-  */
-  toolName: string;
-  /**
-Result of the tool call. This is a JSON-serializable object.
-   */
-  result: unknown;
-  /**
-Optional flag if the result is an error or an error message.
-   */
-  isError?: boolean;
-  /**
-   * Additional provider-specific metadata. They are passed through
-   * to the provider from the AI SDK and enable provider-specific
-   * functionality that can be fully encapsulated in the provider.
-   */
-  providerMetadata?: LanguageModelV1ProviderMetadata;
-}
-type LanguageModelV1Message = (
-  | {
-      role: 'system';
-      content: string;
-    }
-  | {
-      role: 'user';
-      content: Array<LanguageModelV1TextPart | LanguageModelV1ImagePart>;
-    }
-  | {
-      role: 'assistant';
-      content: Array<LanguageModelV1TextPart | LanguageModelV1ToolCallPart>;
-    }
-  | {
-      role: 'tool';
-      content: Array<LanguageModelV1ToolResultPart>;
-    }
-) & {
-  /**
-   * Additional provider-specific metadata. They are passed through
-   * to the provider from the AI SDK and enable provider-specific
-   * functionality that can be fully encapsulated in the provider.
-   */
-  providerMetadata?: LanguageModelV1ProviderMetadata;
-};
 
 export type AgentMessageInput = CoreMessage & {
   timestamp?: number;
@@ -331,41 +297,36 @@ export type AgentMessageInput = CoreMessage & {
    * which message this message is responding to, if any.
    */
   responseId?: string;
-  result?: GenerateTextResult<any>;
+  result?: GenerateTextResult<any, any>;
 };
 
 export interface AgentObservation<TActor extends ActorRefLike> {
   id: string;
+  episodeId: string;
+  /**
+   * The decision that this observation is relevant for
+   */
+  decisionId?: string | undefined;
   goal?: string;
   prevState: SnapshotFrom<TActor> | undefined;
   event: EventFrom<TActor> | undefined;
   state: SnapshotFrom<TActor>;
-  machineHash: string | undefined;
-  episodeId: string;
+  // machineHash: string | undefined;
   timestamp: number;
 }
 
-export interface AgentObservationInput<TAgent extends AnyAgent> {
-  id?: string;
+export interface AgentObservationInput<TAgent extends AnyAgent>
+  extends BaseInput {
+  state: ObservedState<TAgent>;
+  /**
+   * The agent decision that the observation is relevant for
+   */
+  decisionId?: string | undefined;
   prevState?: ObservedState<TAgent>;
   event?: AnyEventObject;
-  state: ObservedState<TAgent>;
-  machine?: AnyStateMachine;
-  timestamp?: number;
-  goal: string | undefined;
+  goal?: string | undefined;
 }
 
-export type AgentDecisionInput = {
-  goal: string;
-  model?: LanguageModel;
-  context?: Record<string, any>;
-} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt'>;
-
-export type AgentDecisionLogic<TAgent extends AnyAgent> = PromiseActorLogic<
-  AgentDecision<TAgent> | undefined,
-  AgentDecisionInput | string
->;
-
 export type AgentEmitted<TAgent extends AnyAgent> =
   | {
       type: 'feedback';
@@ -382,6 +343,10 @@ export type AgentEmitted<TAgent extends AnyAgent> =
   | {
       type: 'decision';
       decision: AgentDecision<TAgent>;
+    }
+  | {
+      type: 'insight';
+      insight: AgentInsight;
     };
 
 export type AgentLogic<TAgent extends AnyAgent> = ActorLogic<
@@ -401,6 +366,10 @@ export type AgentLogic<TAgent extends AnyAgent> = ActorLogic<
   | {
       type: 'agent.decision';
       decision: AgentDecision<TAgent>;
+    }
+  | {
+      type: 'agent.insight';
+      insight: AgentInsight;
     },
   any, // TODO: input
   any,
@@ -422,29 +391,29 @@ export type ContextFromZodContextMapping<
   [K in keyof TContextSchema & string]: TypeOf<TContextSchema[K]>;
 };
 
-export type AnyAgent = Agent<any, any, any, any>;
+export type AnyAgent = Agent<any, any>;
 
 export type FromAgent<T> = T | ((agent: AnyAgent) => T | Promise<T>);
 
-export type CommonTextOptions<TAgent extends AnyAgent> = {
+export type CommonTextOptions = {
   prompt: FromAgent<string>;
   model?: LanguageModel;
-  messages?: FromAgent<CoreMessage[]>;
+  messages?: CoreMessage[];
   template?: PromptTemplate<any>;
   context?: Record<string, any>;
 };
 
-export type AgentGenerateTextOptions<TAgent extends AnyAgent> = Omit<
+export type AgentGenerateTextOptions = Omit<
   GenerateTextOptions,
   'model' | 'prompt' | 'messages'
 > &
-  CommonTextOptions<TAgent>;
+  CommonTextOptions;
 
-export type AgentStreamTextOptions<TAgent extends AnyAgent> = Omit<
+export type AgentStreamTextOptions = Omit<
   StreamTextOptions,
   'model' | 'prompt' | 'messages'
 > &
-  CommonTextOptions<TAgent>;
+  CommonTextOptions;
 
 export interface ObservedState<TAgent extends AnyAgent> {
   /**
@@ -464,10 +433,11 @@ export type ObservedStateFrom<TActor extends ActorRefLike> = Pick<
 >;
 
 export type AgentMemoryContext<TAgent extends AnyAgent> = {
-  observations: AgentObservation<TAgent>[]; // TODO
+  observations: AgentObservation<any>[]; // TODO
   messages: AgentMessage[];
   decisions: AgentDecision<TAgent>[];
   feedback: AgentFeedback[];
+  insights: AgentInsight[];
 };
 
 export interface AgentLongTermMemory<TAgent extends AnyAgent> {
@@ -490,11 +460,9 @@ export type MaybePromise<T> = T | Promise<T>;
 
 export type EventFromAgent<T extends AnyAgent> = T extends Agent<
   infer _,
-  infer __,
-  infer TEvents,
-  infer ___
+  infer TEventSchemas
 >
-  ? TEvents
+  ? EventsFromZodEventMapping<TEventSchemas>
   : never;
 
 export type TypesFromAgent<T extends AnyAgent> = T extends Agent<
@@ -513,3 +481,31 @@ export type ContextFromAgent<T extends AnyAgent> = T extends Agent<
 >
   ? ContextFromZodContextMapping<TContextSchema>
   : never;
+
+export interface StorageAdapter<TAgent extends AnyAgent, TQuery> {
+  addObservation(
+    observationInput: AgentObservationInput<TAgent>
+  ): Promise<AgentObservation<any>>;
+  getObservations(queryObject?: TQuery): Promise<AgentObservation<any>[]>;
+  addFeedback(feedbackInput: AgentFeedbackInput): Promise<AgentFeedback>;
+  getFeedback(queryObject?: TQuery): Promise<AgentFeedback[]>;
+  addMessage(messageInput: AgentMessageInput): Promise<AgentMessage>;
+  getMessages(queryObject?: TQuery): Promise<AgentMessage[]>;
+  addDecision(
+    decisionInput: AgentDecideInput<TAgent>
+  ): Promise<AgentDecision<TAgent>>;
+  getDecisions(queryObject?: TQuery): Promise<AgentDecision<TAgent>[]>;
+}
+
+export type StorageAdapterQuery<T extends StorageAdapter<any, any>> =
+  T extends StorageAdapter<infer _, infer TQuery> ? TQuery : never;
+
+export interface AgentInsightInput extends BaseInput {
+  observationId: string;
+  attributes: Record<string, any>;
+}
+
+export interface AgentInsight extends BaseProperties {
+  observationId: string;
+  attributes: Record<string, any>;
+}