@statelyai/agent 0.0.7 → 0.1.0

package/.vscode/launch.json

@@ -7,11 +7,22 @@
       "request": "launch",
       "name": "Debug Current Test File",
       "autoAttachChildProcesses": true,
-      "skipFiles": ["<node_internals>/**", "**/node_modules/**"],
+      "skipFiles": ["<node_internals>/**", "**/node_modules/**", "examples/**"],
       "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
       "args": ["run", "${relativeFile}"],
       "smartStep": true,
       "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug Current File",
+      "program": "${file}",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ts-node",
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "sourceMaps": true,
+      "console": "integratedTerminal"
     }
   ]
 }

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @statelyai/agent
 
+## 0.1.0
+
+### Minor Changes
+
+- [#32](https://github.com/statelyai/agent/pull/32) [`537f501`](https://github.com/statelyai/agent/commit/537f50111b5f8edc1a309d1abb8fffcdddddbc03) Thanks [@davidkpiano](https://github.com/davidkpiano)! - 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
+
+## 0.0.8
+
+### Patch Changes
+
+- [#22](https://github.com/statelyai/agent/pull/22) [`8a2c34b`](https://github.com/statelyai/agent/commit/8a2c34b8a99161bf47c72df8eed3f5d3b6a19f5f) Thanks [@davidkpiano](https://github.com/davidkpiano)! - The `createSchemas(…)` function has been removed. The `defineEvents(…)` function should be used instead, as it is a simpler way of defining events and event schemas using Zod:
+
+  ```ts
+  import { defineEvents } from "@statelyai/agent";
+  import { z } from "zod";
+  import { setup } from "xstate";
+
+  const events = defineEvents({
+    inc: z.object({
+      by: z.number().describe("Increment amount"),
+    }),
+  });
+
+  const machine = setup({
+    types: {
+      events: events.types,
+    },
+    schema: {
+      events: events.schemas,
+    },
+  }).createMachine({
+    // ...
+  });
+  ```
+
 ## 0.0.7
 
 ### Patch Changes

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+declare function helloWorld(): string;
+
+export { helloWorld };

package/dist/index.d.ts

@@ -1,93 +1,304 @@
-import * as xstate from 'xstate';
-import { Prop, Values, AnyStateMachine, createActor, PromiseActorLogic, AnyEventObject, ObservableActorLogic } from 'xstate';
-import { JSONSchema7 } from 'json-schema-to-ts/lib/types/definitions';
-import { FromSchema } from 'json-schema-to-ts';
-import OpenAI from 'openai';
-import { ChatCompletionCreateParamsBase } from 'openai/resources/chat/completions';
-import { ChatCompletionCreateParamsNonStreaming, ChatCompletionCreateParamsStreaming } from 'openai/resources';
+import { EventObject, AnyStateMachine, AnyEventObject, AnyActorRef, SnapshotFrom, EventFrom, PromiseActorLogic, ActorLogic, TransitionSnapshot, Values, ActorRefFrom, Subscription, StateValue, ObservableActorLogic } from 'xstate';
+import { TypeOf, SomeZodObject } from 'zod';
+import { generateText, streamText, LanguageModel, CoreMessage, GenerateTextResult, StreamTextResult, CoreTool } from 'ai';
 
-type EventSchemas = {
-    [key: string]: {
-        description?: string;
-        properties?: {
-            [key: string]: JSONSchema7;
-        };
-    };
+type GenerateTextOptions = Parameters<typeof generateText>[0];
+type StreamTextOptions = Parameters<typeof streamText>[0];
+type AgentPlanInput<TEvent extends EventObject> = {
+    model: LanguageModel;
+    state: ObservedState;
+    goal: string;
+    events: ZodEventMapping;
+    machine?: AnyStateMachine;
+    /**
+     * The previous plan
+     */
+    previousPlan?: AgentPlan<TEvent>;
 };
-type ContextSchema = JSONSchema7 & {
-    type: 'object';
+type AgentPlan<TEvent extends EventObject> = {
+    goal: string;
+    state: ObservedState;
+    content?: string;
+    steps?: Array<{
+        event: TEvent;
+        state?: ObservedState;
+    }>;
+    nextEvent: TEvent | undefined;
+    sessionId: string;
+    timestamp: number;
 };
-type ConvertToJSONSchemas<T> = {
-    [K in keyof T]: {
-        properties: {
-            type: {
-                const: K;
-            };
-        } & Prop<T[K], 'properties'>;
-        type: 'object';
-        required: Array<(keyof Prop<T[K], 'properties'> & string) | 'type'>;
-        additionalProperties: false;
+interface TransitionData {
+    eventType: string;
+    description?: string;
+    guard?: {
+        type: string;
     };
-} & {};
-
-declare function createSchemas<const TContextSchema extends ContextSchema, const TEventSchemas extends EventSchemas>({ context, events, }: {
+    target?: any;
+}
+type PromptTemplate<TEvents extends EventObject> = (data: {
+    goal: string;
+    /**
+     * The observed state
+     */
+    state?: ObservedState;
+    /**
+     * The context to provide.
+     * This overrides the observed state.context, if provided.
+     */
+    context?: any;
+    /**
+     * The state machine model of the observed environment
+     */
+    machine?: unknown;
+    /**
+     * The potential next transitions that can be taken
+     * in the state machine
+     */
+    transitions?: TransitionData[];
+    /**
+     * Past observations
+     */
+    observations?: AgentObservation<any>[];
+    feedback?: AgentFeedback[];
+    messages?: AgentMessageHistory[];
+    plans?: AgentPlan<TEvents>[];
+}) => string;
+type AgentPlanner<T extends Agent<any>> = (agent: T['eventTypes'], options: AgentPlanInput<T['eventTypes']>) => Promise<AgentPlan<T['eventTypes']> | undefined>;
+type AgentDecideOptions = {
+    goal: string;
+    model?: LanguageModel;
+    context?: any;
+    state: ObservedState;
+    machine: AnyStateMachine;
+    execute?: (event: AnyEventObject) => Promise<void>;
+    planner?: AgentPlanner<any>;
+    events?: ZodEventMapping;
+} & Omit<Parameters<typeof generateText>[0], 'model' | 'tools' | 'prompt' | 'messages'>;
+interface AgentFeedback {
+    goal: string;
+    observationId: string;
+    attributes: Record<string, any>;
+    timestamp: number;
+    sessionId: string;
+}
+interface AgentFeedbackInput {
+    goal: string;
+    observationId: string;
+    attributes: Record<string, any>;
+    timestamp?: number;
+}
+type AgentMessageHistory = 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>;
+    sessionId: string;
+};
+type AgentMessageHistoryInput = 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>;
+};
+interface AgentObservation<TActor extends AnyActorRef> {
+    id: string;
+    prevState: SnapshotFrom<TActor> | undefined;
+    event: EventFrom<TActor>;
+    state: SnapshotFrom<TActor>;
+    sessionId: string;
+    timestamp: number;
+}
+interface AgentObservationInput {
+    id?: string;
+    prevState: ObservedState | undefined;
+    event: AnyEventObject;
+    state: ObservedState;
+    timestamp?: number;
+}
+type AgentDecisionInput = {
+    goal: string;
+    model?: LanguageModel;
+    context?: 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: 'feedback';
+    feedback: AgentFeedback;
+} | {
+    type: 'observation';
+    observation: AgentObservation<any>;
+} | {
+    type: 'message';
+    message: AgentMessageHistory;
+} | {
+    type: 'plan';
+    plan: AgentPlan<TEvents>;
+};
+type AgentLogic<TEvents extends EventObject> = ActorLogic<TransitionSnapshot<AgentMemoryContext>, {
+    type: 'agent.feedback';
+    feedback: AgentFeedback;
+} | {
+    type: 'agent.observe';
+    observation: AgentObservation<any>;
+} | {
+    type: 'agent.message';
+    message: AgentMessageHistory;
+} | {
+    type: 'agent.plan';
+    plan: AgentPlan<TEvents>;
+}, any, // TODO: input
+any, AgentEmitted<TEvents>>;
+type EventsFromZodEventMapping<TEventSchemas extends ZodEventMapping> = Values<{
+    [K in keyof TEventSchemas & string]: {
+        type: K;
+    } & TypeOf<TEventSchemas[K]>;
+}>;
+type Agent<TEvents extends EventObject> = ActorRefFrom<AgentLogic<TEvents>> & {
+    /**
+     * The general name of the agent. All agents with the same name are related and
+     * able to share experiences (observations, feedback) with each other.
+     */
+    name: string;
     /**
-     * The JSON schema for the context object.
+     * The unique id of the agent. This is used to partition message history.
+     */
+    id?: string;
+    description?: string;
+    events: ZodEventMapping;
+    eventTypes: TEvents;
+    model: LanguageModel;
+    defaultOptions: GenerateTextOptions;
+    memory: AgentLongTermMemory | undefined;
+    /**
+     * The adapter used to perform LLM actions such as
+     * `.generateText(…)` and `.streamText(…)`.
      *
-     * Must be of `{ type: 'object' }`.
+     * Defaults to the Vercel AI SDK.
      */
-    context?: TContextSchema;
+    adapter: AIAdapter;
     /**
-     * An object mapping event types to each event object's JSON Schema.
+     * Resolves with an `AgentPlan` based on the information provided in the `options`, including:
+     *
+     * - The `goal` for the agent to achieve
+     * - The observed current `state`
+     * - The `logic` (e.g. a state machine) that specifies what can happen next
+     * - Additional `context`
      */
-    events: TEventSchemas;
-}): {
-    context: TContextSchema | undefined;
-    events: ConvertToJSONSchemas<TEventSchemas>;
-    types: {
-        context: FromSchema<TContextSchema>;
-        events: FromSchema<Values<ConvertToJSONSchemas<TEventSchemas>>>;
-    };
+    decide: (options: AgentDecideOptions) => Promise<AgentPlan<TEvents> | undefined>;
+    generateText: (options: AgentGenerateTextOptions) => Promise<GenerateTextResult<Record<string, any>>>;
+    streamText: (options: AgentStreamTextOptions) => Promise<StreamTextResult<Record<string, CoreTool<any, any>>>>;
+    addObservation: (observation: AgentObservationInput) => AgentObservation<any>;
+    addMessage: (history: AgentMessageHistoryInput) => AgentMessageHistory;
+    addFeedback: (feedbackItem: AgentFeedbackInput) => AgentFeedback;
+    addPlan: (plan: AgentPlan<TEvents>) => void;
+    /**
+     * Called whenever the agent (LLM assistant) receives or sends a message.
+     */
+    onMessage: (callback: (message: AgentMessageHistory) => void) => void;
+    /**
+     * Selects agent data from its context.
+     */
+    select: <T>(selector: (context: AgentMemoryContext) => T) => T;
+    /**
+     * Inspects state machine actor transitions and automatically observes
+     * (prevState, event, state) tuples.
+     */
+    interact: <TActor extends AnyActorRef>(actorRef: TActor, getInput?: (observation: AgentObservation<TActor>) => AgentDecisionInput | undefined) => Subscription;
+};
+type AnyAgent = Agent<any>;
+type FromAgent<T> = T | ((self: AnyAgent) => T | Promise<T>);
+interface CommonTextOptions {
+    prompt: FromAgent<string>;
+    model?: LanguageModel;
+    context?: Record<string, any>;
+    messages?: FromAgent<CoreMessage[]> | true;
+    template?: PromptTemplate<any>;
+}
+type AgentGenerateTextOptions = Omit<GenerateTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
+type AgentStreamTextOptions = Omit<StreamTextOptions, 'model' | 'prompt' | 'messages'> & CommonTextOptions;
+interface ObservedState {
+    /**
+     * The current state value of the state machine, e.g.
+     * `"loading"` or `"processing"` or `"ready"`
+     */
+    value: StateValue;
+    /**
+     * Additional contextual data related to the current state
+     */
+    context: Record<string, unknown>;
+}
+type ObservedStateFrom<TActor extends AnyActorRef> = Pick<SnapshotFrom<TActor>, 'value' | 'context'>;
+type AgentMemoryContext = {
+    observations: AgentObservation<any>[];
+    messages: AgentMessageHistory[];
+    plans: AgentPlan<any>[];
+    feedback: AgentFeedback[];
 };
+type AgentMemory = AppendOnlyStorage<AgentMemoryContext>;
+interface AppendOnlyStorage<T extends Record<string, any[]>> {
+    append<K extends keyof T>(sessionId: string, key: K, item: T[K][0]): Promise<void>;
+    getAll<K extends keyof T>(sessionId: string, key: K): Promise<T[K] | undefined>;
+}
+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 AIAdapter {
+    generateText: typeof generateText;
+    streamText: typeof streamText;
+}
 
-declare function createAgent<T extends AnyStateMachine>(...args: Parameters<typeof createActor<T>>): xstate.Actor<T>;
+type ZodEventMapping = {
+    [eventType: string]: SomeZodObject;
+};
 
-interface StatelyAgentAdapter {
-    model: string;
+declare function createAgent<const TEventSchemas extends ZodEventMapping, TEvents extends EventObject = EventsFromZodEventMapping<TEventSchemas>>({ name, description, model, events, planner, stringify, getMemory, logic, adapter, ...generateTextOptions }: {
     /**
-     * Creates actor logic that chooses an event from all of the
-     * possible next events of the parent state machine
-     * and sends it to the parent actor.
+     * The name of the agent
      */
-    fromEvent: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<AnyEventObject[] | undefined, TInput>;
+    name: string;
     /**
-     * Creates actor logic that resolves with a chat completion.
+     * A description of the role of the agent
      */
-    fromChat: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming) => PromiseActorLogic<OpenAI.Chat.Completions.ChatCompletion, TInput>;
+    description?: string;
     /**
-     * Creates actor logic that emits a chat completion stream.
+     * Events that the agent can cause (send) in an environment
+     * that the agent knows about.
      */
-    fromChatStream: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsStreaming) => ObservableActorLogic<OpenAI.Chat.Completions.ChatCompletionChunk, TInput>;
+    events: TEventSchemas;
+    planner?: AgentPlanner<Agent<TEvents>>;
+    stringify?: typeof JSON.stringify;
     /**
-     * Creates actor logic that chooses a tool from the provided
-     * tools and runs that tool.
+     * A function that retrieves the agent's long term memory
      */
-    fromTool: <TInput>(inputFn: (input: TInput) => string | ChatCompletionCreateParamsNonStreaming, tools: {
-        [key: string]: Tool<any, any>;
-    }) => PromiseActorLogic<{
-        result: any;
-        tool: string;
-        toolCall: OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
-    } | undefined, TInput>;
-}
-interface Tool<TInput, TOutput> {
-    description: string;
-    inputSchema: any;
-    run: (input: TInput) => TOutput;
-}
+    getMemory?: (agent: Agent<any>) => AgentLongTermMemory;
+    /**
+     * Agent logic
+     */
+    logic?: AgentLogic<TEvents>;
+    adapter?: AIAdapter;
+} & GenerateTextOptions): Agent<TEvents>;
+
+declare function agentGenerateText<T extends Agent<any>>(agent: T, options: AgentGenerateTextOptions): Promise<GenerateTextResult<Record<string, CoreTool<any, any>>>>;
+declare function fromTextStream<T extends Agent<any>>(agent: T, defaultOptions?: AgentStreamTextOptions): ObservableActorLogic<{
+    textDelta: string;
+}, Omit<AgentStreamTextOptions, 'context'> & {
+    context?: AgentStreamTextOptions['context'] | boolean;
+}>;
+declare function fromText<T extends Agent<any>>(agent: T, defaultOptions?: AgentGenerateTextOptions): PromiseActorLogic<GenerateTextResult<Record<string, CoreTool<any, any>>>, Omit<AgentGenerateTextOptions, 'context'> & {
+    context?: AgentGenerateTextOptions['context'] | boolean;
+}>;
 
-declare function createOpenAIAdapter<T extends {
-    model: ChatCompletionCreateParamsBase['model'];
-}>(openai: OpenAI, settings: T): StatelyAgentAdapter;
+declare function agentDecide<T extends Agent<any>>(agent: T, options: AgentDecideOptions): Promise<AgentPlan<any> | undefined>;
+declare function fromDecision(agent: Agent<any>, defaultInput?: AgentDecisionInput): AgentDecisionLogic<any>;
 
-export { createAgent, createOpenAIAdapter, createSchemas };
+export { type AIAdapter, type Agent, type AgentDecideOptions, type AgentDecisionInput, type AgentDecisionLogic, type AgentEmitted, type AgentFeedback, type AgentFeedbackInput, type AgentGenerateTextOptions, type AgentLogic, type AgentLongTermMemory, type AgentMemory, type AgentMemoryContext, type AgentMessageHistory, type AgentMessageHistoryInput, type AgentObservation, type AgentObservationInput, type AgentPlan, type AgentPlanInput, type AgentPlanner, type AgentStreamTextOptions, type AnyAgent, type AppendOnlyStorage, type CommonTextOptions, type EventsFromZodEventMapping, type FromAgent, type GenerateTextOptions, type ObservedState, type ObservedStateFrom, type PromptTemplate, type StreamTextOptions, type TransitionData, agentDecide, agentGenerateText, createAgent, fromDecision, fromText, fromTextStream };