Merge pull request #32 from statelyai/davidkpiano/0-1

davidkpiano · web-flow · commit 55623192b70e · 2024-06-12T11:24:24.000+02:00
Release 0.1
diff --git a/.changeset/cold-needles-smile.md b/.changeset/cold-needles-smile.md
diff --git a/.changeset/cuddly-pillows-glow.md b/.changeset/cuddly-pillows-glow.md
@@ -0,0 +1,17 @@
+---
+'@statelyai/agent': minor
+---
+
+First minor release of `@statelyai/agent`! The API has been simplified from experimental earlier versions. Here are the main methods:
+
+- `createAgent({ … })` creates an agent
+- `agent.decide({ … })` decides on a plan to achieve the goal
+- `agent.generateText({ … })` generates text based on a prompt
+- `agent.streamText({ … })` streams text based on a prompt
+- `agent.addObservation(observation)` adds an observation and returns a full observation object
+- `agent.addFeedback(feedback)` adds a feedback and returns a full feedback object
+- `agent.addMessage(message)` adds a message and returns a full message object
+- `agent.addPlan(plan)` adds a plan and returns a full plan object
+- `agent.onMessage(cb)` listens to messages
+- `agent.select(selector)` selects data from the agent context
+- `agent.interact(actorRef, getInput)` interacts with an actor and makes decisions to accomplish a goal
diff --git a/.changeset/sixty-clocks-sort.md b/.changeset/sixty-clocks-sort.md
diff --git a/.changeset/slimy-forks-exercise.md b/.changeset/slimy-forks-exercise.md
diff --git a/examples/email.ts b/examples/email.ts
@@ -50,7 +50,7 @@ const machine = setup({
             instructions: x.context.instructions,
             clarifications: x.context.clarifications,
           },
-          history: true,
+          messages: agent.select((ctx) => ctx.messages),
           goal: 'Respond to the email given the instructions and the provided clarifications. If not enough information is provided, ask for clarification. Otherwise, if you are absolutely sure that there is no ambiguous or missing information, create and submit a response email.',
         }),
       },
diff --git a/src/agent.test.ts b/src/agent.test.ts
@@ -14,26 +14,26 @@ test('an agent has the expected interface', () => {
   expect(agent.streamText).toBeDefined();
 
   expect(agent.addFeedback).toBeDefined();
-  expect(agent.addHistory).toBeDefined();
+  expect(agent.addMessage).toBeDefined();
   expect(agent.addObservation).toBeDefined();
   expect(agent.addPlan).toBeDefined();
 
   expect(agent.interact).toBeDefined();
 });
 
-test('agent.addHistory() adds to history', () => {
+test('agent.addMessage() adds to message history', () => {
   const agent = createAgent({
     name: 'test',
     events: {},
     model: {} as any,
   });
 
-  agent.addHistory({
+  agent.addMessage({
     content: 'msg 1',
     role: 'user',
   });
 
-  const messageHistory = agent.addHistory({
+  const messageHistory = agent.addMessage({
     content: 'response 1',
     role: 'assistant',
   });
diff --git a/src/agent.ts b/src/agent.ts
@@ -10,7 +10,6 @@ import {
 import { ZodEventMapping } from './schemas';
 import {
   Agent,
-  AgentContext,
   AgentLogic,
   AgentMessageHistory,
   AgentPlanner,
@@ -20,6 +19,7 @@ import {
   AIAdapter,
   ObservedState,
   AgentObservationInput,
+  AgentMemoryContext,
 } from './types';
 import { simplePlanner } from './planners/simplePlanner';
 import { randomUUID } from 'crypto';
@@ -76,7 +76,7 @@ export const agentLogic: AgentLogic<AnyEventObject> = fromTransition(
     messages: [],
     observations: [],
     plans: [],
-  } as AgentContext
+  } as AgentMemoryContext
 );
 
 export function createAgent<
@@ -141,7 +141,7 @@ export function createAgent<
     return agentDecide(agent, opts);
   };
 
-  agent.addHistory = (messageInput) => {
+  agent.addMessage = (messageInput) => {
     const message = {
       ...messageInput,
       id: messageInput.id ?? randomUUID(),
diff --git a/src/memory.ts b/src/memory.ts
@@ -1,8 +1,8 @@
-import { AgentMemory, AgentMemoryData } from './types';
+import { AgentMemory, AgentMemoryContext } from './types';
 
 export function createAgentMemory(): AgentMemory {
   const storage = {
-    sessions: {} as Record<string, AgentMemoryData>,
+    sessions: {} as Record<string, AgentMemoryContext>,
   };
 
   return {
@@ -14,7 +14,7 @@ export function createAgentMemory(): AgentMemory {
           messages: [],
           plans: [],
           feedback: [],
-        } satisfies AgentMemoryData);
+        } satisfies AgentMemoryContext);
 
       storage.sessions[sessionId]![key].push(item as any);
     },
diff --git a/src/strategies/chain-of-note.ts b/src/strategies/chain-of-note.ts
@@ -118,7 +118,7 @@ export const chainOfNote = setup({
 //           return summary.extract;
 //         })
 //       );
-//       x.agent?.addHistory({
+//       x.agent?.addMessage({
 //         content: x.prompt!,
 //         id: Date.now() + '',
 //         role: 'user',
@@ -142,7 +142,7 @@ export const chainOfNote = setup({
 //         prompt: `${x.prompt!}`,
 //       });
 
-//       x.agent?.addHistory({
+//       x.agent?.addMessage({
 //         content: result.text,
 //         id: Date.now() + '',
 //         role: 'user',
diff --git a/src/text.ts b/src/text.ts
@@ -75,7 +75,7 @@ export async function agentGenerateText<T extends Agent<any>>(
 
   const messages = await getMessages(agent, promptWithContext, resolvedOptions);
 
-  agent.addHistory({
+  agent.addMessage({
     id,
     role: 'user',
     content: promptWithContext,
@@ -88,8 +88,8 @@ export async function agentGenerateText<T extends Agent<any>>(
     messages,
   });
 
-  agent.addHistory({
-    content: result.toolResults ?? result.text,
+  agent.addMessage({
+    content: result.text,
     id,
     role: 'assistant',
     timestamp: Date.now(),
@@ -123,7 +123,7 @@ export async function agentStreamText(
 
   const messages = await getMessages(agent, promptWithContext, resolvedOptions);
 
-  agent.addHistory({
+  agent.addMessage({
     role: 'user',
     content: promptWithContext,
     id,
@@ -135,7 +135,7 @@ export async function agentStreamText(
     prompt: undefined,
     messages,
     onFinish: async (res) => {
-      agent.addHistory({
+      agent.addMessage({
         role: 'assistant',
         result: {
           text: res.text,
diff --git a/src/types.ts b/src/types.ts
@@ -164,8 +164,6 @@ export interface AgentObservationInput {
   timestamp?: number;
 }
 
-export type AgentContext = AgentMemoryData;
-
 export type AgentDecisionInput = {
   goal: string;
   model?: LanguageModel;
@@ -196,7 +194,7 @@ export type AgentEmitted<TEvents extends EventObject> =
     };
 
 export type AgentLogic<TEvents extends EventObject> = ActorLogic<
-  TransitionSnapshot<AgentContext>,
+  TransitionSnapshot<AgentMemoryContext>,
   | {
       type: 'agent.feedback';
       feedback: AgentFeedback;
@@ -274,7 +272,7 @@ export type Agent<TEvents extends EventObject> = ActorRefFrom<
   ) => Promise<StreamTextResult<Record<string, CoreTool<any, any>>>>;
 
   addObservation: (observation: AgentObservationInput) => AgentObservation<any>; // TODO
-  addHistory: (history: AgentMessageHistoryInput) => AgentMessageHistory;
+  addMessage: (history: AgentMessageHistoryInput) => AgentMessageHistory;
   addFeedback: (feedbackItem: AgentFeedbackInput) => AgentFeedback;
   addPlan: (plan: AgentPlan<TEvents>) => void;
   /**
@@ -284,7 +282,7 @@ export type Agent<TEvents extends EventObject> = ActorRefFrom<
   /**
    * Selects agent data from its context.
    */
-  select: <T>(selector: (context: AgentContext) => T) => T;
+  select: <T>(selector: (context: AgentMemoryContext) => T) => T;
 
   /**
    * Inspects state machine actor transitions and automatically observes
@@ -339,14 +337,14 @@ export type ObservedStateFrom<TActor extends AnyActorRef> = Pick<
   'value' | 'context'
 >;
 
-export type AgentMemoryData = {
+export type AgentMemoryContext = {
   observations: AgentObservation<any>[]; // TODO
   messages: AgentMessageHistory[];
   plans: AgentPlan<any>[];
   feedback: AgentFeedback[];
 };
 
-export type AgentMemory = AppendOnlyStorage<AgentMemoryData>;
+export type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
 
 export interface AppendOnlyStorage<T extends Record<string, any[]>> {
   append<K extends keyof T>(
@@ -361,14 +359,16 @@ export interface AppendOnlyStorage<T extends Record<string, any[]>> {
 }
 
 export interface AgentLongTermMemory {
-  get<K extends keyof AgentMemoryData>(key: K): Promise<AgentMemoryData[K]>;
-  append<K extends keyof AgentMemoryData>(
+  get<K extends keyof AgentMemoryContext>(
+    key: K
+  ): Promise<AgentMemoryContext[K]>;
+  append<K extends keyof AgentMemoryContext>(
     key: K,
-    item: AgentMemoryData[K][0]
+    item: AgentMemoryContext[K][0]
   ): Promise<void>;
-  set<K extends keyof AgentMemoryData>(
+  set<K extends keyof AgentMemoryContext>(
     key: K,
-    items: AgentMemoryData[K]
+    items: AgentMemoryContext[K]
   ): Promise<void>;
 }
 
