@statelyai/agent 0.1.0 → 0.1.2

package/dist/index.mjs

@@ -1,7 +1,518 @@
-// src/index.ts
-function helloWorld() {
-  return "Hello World!";
+// src/agent.ts
+import {
+  createActor,
+  fromTransition,
+  toObserver as toObserver2
+} from "xstate";
+
+// src/planners/simplePlanner.ts
+import { tool } from "ai";
+
+// src/utils.ts
+function getAllTransitions(state) {
+  const nodes = state._nodes;
+  const transitions = nodes.map((node) => [...node.transitions.values()]).flat(2).map((transition) => ({
+    ...transition,
+    guard: typeof transition.guard === "string" ? { type: transition.guard } : transition.guard
+    // TODO: fix
+  }));
+  return transitions;
+}
+function wrapInXml(tagName, content) {
+  return `<${tagName}>${content}</${tagName}>`;
+}
+
+// src/templates/defaultText.ts
+var defaultTextTemplate = (data) => {
+  const preamble = [
+    data.context ? wrapInXml("context", JSON.stringify(data.context)) : void 0
+  ].filter(Boolean).join("\n");
+  return `
+${preamble}
+
+${data.goal}
+  `.trim();
+};
+
+// src/planners/simplePlanner.ts
+function getTransitions(state, machine) {
+  if (!machine) {
+    return [];
+  }
+  const resolvedState = machine.resolveState(state);
+  return getAllTransitions(resolvedState);
+}
+var simplePlannerPromptTemplate = (data) => {
+  return `
+${defaultTextTemplate(data)}
+
+Only make a single tool call to achieve the above goal.
+  `.trim();
+};
+async function simplePlanner(agent, input) {
+  const transitions = input.machine ? getTransitions(input.state, input.machine) : Object.entries(input.events).map(([eventType, { description }]) => ({
+    eventType,
+    description
+  }));
+  const filter = (eventType) => Object.keys(input.events).includes(eventType);
+  const functionNameMapping = {};
+  const toolTransitions = transitions.filter((t) => {
+    return filter(t.eventType);
+  }).map((t) => {
+    const name = t.eventType.replace(/\./g, "_");
+    functionNameMapping[name] = t.eventType;
+    return {
+      type: "function",
+      eventType: t.eventType,
+      description: t.description,
+      name
+    };
+  });
+  const toolMap = {};
+  for (const toolTransitionData of toolTransitions) {
+    const toolZodType = input.events?.[toolTransitionData.eventType];
+    if (!toolZodType) {
+      continue;
+    }
+    toolMap[toolTransitionData.name] = tool({
+      description: toolZodType?.description ?? toolTransitionData.description,
+      parameters: toolZodType,
+      execute: async (params) => {
+        const event = {
+          type: toolTransitionData.eventType,
+          ...params
+        };
+        return event;
+      }
+    });
+  }
+  const prompt = simplePlannerPromptTemplate({
+    context: input.state.context,
+    goal: input.goal
+  });
+  const result = await agent.generateText({
+    prompt,
+    tools: toolMap,
+    toolChoice: "required",
+    ...input
+  });
+  const singleResult = result.toolResults[0];
+  if (!singleResult) {
+    console.warn("No tool call results returned");
+    return void 0;
+  }
+  return {
+    goal: input.goal,
+    state: input.state,
+    steps: [
+      {
+        event: singleResult.result
+      }
+    ],
+    nextEvent: singleResult.result,
+    sessionId: agent.sessionId,
+    timestamp: Date.now()
+  };
+}
+
+// src/agent.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/text.ts
+import { randomUUID } from "crypto";
+import {
+  fromObservable,
+  fromPromise,
+  toObserver
+} from "xstate";
+async function getMessages(agent, prompt, options) {
+  let messages = [];
+  if (options.messages === true) {
+    messages = agent.select((s) => s.messages);
+  } else if (typeof options.messages === "function") {
+    messages = await options.messages(agent);
+  } else if (options.messages) {
+    messages = options.messages;
+  }
+  messages = messages.concat({
+    role: "user",
+    content: prompt
+  });
+  return messages;
+}
+async function agentGenerateText(agent, options) {
+  const resolvedOptions = {
+    ...agent.defaultOptions,
+    ...options
+  };
+  const template = resolvedOptions.template ?? defaultTextTemplate;
+  const id = randomUUID();
+  const goal = typeof resolvedOptions.prompt === "string" ? resolvedOptions.prompt : await resolvedOptions.prompt(agent);
+  const promptWithContext = template({
+    goal,
+    context: resolvedOptions.context
+  });
+  const messages = await getMessages(agent, promptWithContext, resolvedOptions);
+  agent.addMessage({
+    id,
+    role: "user",
+    content: promptWithContext,
+    timestamp: Date.now()
+  });
+  const result = await agent.adapter.generateText({
+    ...resolvedOptions,
+    prompt: void 0,
+    messages
+  });
+  agent.addMessage({
+    content: result.text,
+    id,
+    role: "assistant",
+    timestamp: Date.now(),
+    responseId: id,
+    result
+  });
+  return result;
+}
+async function agentStreamText(agent, options) {
+  const resolvedOptions = {
+    ...agent.defaultOptions,
+    ...options
+  };
+  const template = resolvedOptions.template ?? defaultTextTemplate;
+  const id = randomUUID();
+  const goal = typeof resolvedOptions.prompt === "string" ? resolvedOptions.prompt : await resolvedOptions.prompt(agent);
+  const promptWithContext = template({
+    goal,
+    context: resolvedOptions.context
+  });
+  const messages = await getMessages(agent, promptWithContext, resolvedOptions);
+  agent.addMessage({
+    role: "user",
+    content: promptWithContext,
+    id,
+    timestamp: Date.now()
+  });
+  const result = await agent.adapter.streamText({
+    ...resolvedOptions,
+    prompt: void 0,
+    messages,
+    onFinish: async (res) => {
+      agent.addMessage({
+        role: "assistant",
+        result: {
+          text: res.text,
+          finishReason: res.finishReason,
+          logprobs: void 0,
+          responseMessages: [],
+          toolCalls: [],
+          toolResults: [],
+          usage: res.usage,
+          warnings: res.warnings,
+          rawResponse: res.rawResponse
+        },
+        content: res.text,
+        id: randomUUID(),
+        timestamp: Date.now(),
+        responseId: id
+      });
+    }
+  });
+  return result;
+}
+function fromTextStream(agent, defaultOptions) {
+  return fromObservable(({ input, self }) => {
+    const context = input.context === true ? (self._parent?.getSnapshot()).context : input.context;
+    const observers = /* @__PURE__ */ new Set();
+    (async () => {
+      const result = await agentStreamText(agent, {
+        ...defaultOptions,
+        ...input,
+        context
+      });
+      for await (const part of result.fullStream) {
+        if (part.type === "text-delta") {
+          observers.forEach((observer) => {
+            observer.next?.(part);
+          });
+        }
+      }
+    })();
+    return {
+      subscribe: (...args) => {
+        const observer = toObserver(...args);
+        observers.add(observer);
+        return {
+          unsubscribe: () => {
+            observers.delete(observer);
+          }
+        };
+      }
+    };
+  });
+}
+function fromText(agent, defaultOptions) {
+  return fromPromise(async ({ input, self }) => {
+    const context = input.context === true ? (self._parent?.getSnapshot()).context : input.context;
+    return await agentGenerateText(agent, {
+      ...input,
+      ...defaultOptions,
+      context
+    });
+  });
+}
+
+// src/decision.ts
+import { fromPromise as fromPromise2 } from "xstate";
+async function agentDecide(agent, options) {
+  const resolvedOptions = {
+    ...agent.defaultOptions,
+    ...options
+  };
+  const {
+    planner = simplePlanner,
+    goal,
+    events = agent.events,
+    state,
+    machine,
+    model = agent.model,
+    ...otherPlanInput
+  } = resolvedOptions;
+  const plan = await planner(agent, {
+    model,
+    goal,
+    events,
+    state,
+    machine,
+    ...otherPlanInput
+  });
+  if (plan?.nextEvent) {
+    agent.addPlan(plan);
+    await resolvedOptions.execute?.(plan.nextEvent);
+  }
+  return plan;
+}
+function fromDecision(agent, defaultInput) {
+  return fromPromise2(async ({ input, self }) => {
+    const parentRef = self._parent;
+    if (!parentRef) {
+      return;
+    }
+    const snapshot = parentRef.getSnapshot();
+    const inputObject = typeof input === "string" ? { goal: input } : input;
+    const resolvedInput = {
+      ...defaultInput,
+      ...inputObject
+    };
+    const contextToInclude = resolvedInput.context === true ? (
+      // include entire context
+      parentRef.getSnapshot().context
+    ) : resolvedInput.context;
+    const state = {
+      value: snapshot.value,
+      context: contextToInclude
+    };
+    const plan = await agentDecide(agent, {
+      machine: parentRef.src,
+      state,
+      execute: async (event) => {
+        parentRef.send(event);
+      },
+      ...resolvedInput
+    });
+    return plan;
+  });
+}
+
+// src/adapters/vercel.ts
+import { generateText, streamText } from "ai";
+var vercelAdapter = {
+  generateText,
+  streamText
+};
+
+// src/agent.ts
+var agentLogic = fromTransition(
+  (state, event, { emit }) => {
+    switch (event.type) {
+      case "agent.feedback": {
+        state.feedback.push(event.feedback);
+        emit({
+          type: "feedback",
+          // @ts-ignore TODO: fix types in XState
+          feedback: event.feedback
+        });
+        break;
+      }
+      case "agent.observe": {
+        state.observations.push(event.observation);
+        emit({
+          type: "observation",
+          // @ts-ignore TODO: fix types in XState
+          observation: event.observation
+        });
+        break;
+      }
+      case "agent.message": {
+        state.messages.push(event.message);
+        emit({
+          type: "message",
+          // @ts-ignore TODO: fix types in XState
+          message: event.message
+        });
+        break;
+      }
+      case "agent.plan": {
+        state.plans.push(event.plan);
+        emit({
+          type: "plan",
+          // @ts-ignore TODO: fix types in XState
+          plan: event.plan
+        });
+        break;
+      }
+      default:
+        break;
+    }
+    return state;
+  },
+  {
+    feedback: [],
+    messages: [],
+    observations: [],
+    plans: []
+  }
+);
+function createAgent({
+  name,
+  description,
+  model,
+  events,
+  planner = simplePlanner,
+  stringify = JSON.stringify,
+  getMemory,
+  logic = agentLogic,
+  adapter = vercelAdapter,
+  ...generateTextOptions
+}) {
+  const messageHistoryListeners = [];
+  const agent = createActor(logic);
+  agent.events = events;
+  agent.model = model;
+  agent.name = name;
+  agent.description = description;
+  agent.adapter = adapter;
+  agent.defaultOptions = { ...generateTextOptions, model };
+  agent.select = (selector) => {
+    return selector(agent.getSnapshot().context);
+  };
+  agent.memory = getMemory ? getMemory(agent) : void 0;
+  agent.onMessage = (callback) => {
+    messageHistoryListeners.push(toObserver2(callback));
+  };
+  agent.decide = (opts) => {
+    return agentDecide(agent, opts);
+  };
+  agent.addMessage = (messageInput) => {
+    const message = {
+      ...messageInput,
+      id: messageInput.id ?? randomUUID2(),
+      timestamp: messageInput.timestamp ?? Date.now(),
+      sessionId: agent.sessionId
+    };
+    agent.send({
+      type: "agent.message",
+      message
+    });
+    return message;
+  };
+  agent.generateText = (opts) => agentGenerateText(agent, opts);
+  agent.streamText = (opts) => agentStreamText(agent, opts);
+  agent.addFeedback = (feedbackInput) => {
+    const feedback = {
+      ...feedbackInput,
+      timestamp: feedbackInput.timestamp ?? Date.now(),
+      sessionId: agent.sessionId
+    };
+    agent.send({
+      type: "agent.feedback",
+      feedback
+    });
+    return feedback;
+  };
+  agent.addObservation = (observationInput) => {
+    const observation = {
+      ...observationInput,
+      id: observationInput.id ?? randomUUID2(),
+      sessionId: agent.sessionId,
+      timestamp: observationInput.timestamp ?? Date.now()
+    };
+    agent.send({
+      type: "agent.observe",
+      observation
+    });
+    return observation;
+  };
+  agent.addPlan = (plan) => {
+    agent.send({
+      type: "agent.plan",
+      plan
+    });
+  };
+  agent.interact = (actorRef, getInput) => {
+    let prevState = void 0;
+    let subscribed = true;
+    async function handleObservation(observationInput) {
+      const observation = agent.addObservation(observationInput);
+      const input = getInput?.(observation);
+      if (input) {
+        await agentDecide(agent, {
+          machine: actorRef.src,
+          state: observation.state,
+          execute: async (event) => {
+            actorRef.send(event);
+          },
+          ...input
+        });
+      }
+      prevState = observationInput.state;
+    }
+    actorRef.system.inspect({
+      next: async (inspEvent) => {
+        if (!subscribed || inspEvent.actorRef !== actorRef || inspEvent.type !== "@xstate.snapshot") {
+          return;
+        }
+        const observationInput = {
+          event: inspEvent.event,
+          prevState,
+          state: inspEvent.snapshot
+        };
+        await handleObservation(observationInput);
+      }
+    });
+    if (actorRef._processingStatus === 1) {
+      handleObservation({
+        prevState: void 0,
+        event: { type: "" },
+        // TODO: unknown events?
+        state: actorRef.getSnapshot()
+      });
+    }
+    return {
+      unsubscribe: () => {
+        subscribed = false;
+      }
+      // TODO: make this actually unsubscribe
+    };
+  };
+  agent.start();
+  return agent;
 }
 export {
-  helloWorld
+  agentDecide,
+  agentGenerateText,
+  createAgent,
+  fromDecision,
+  fromText,
+  fromTextStream
 };

package/examples/todo.ts

@@ -9,7 +9,8 @@ const agent = createAgent({
   model: openai('gpt-4o'),
   events: {
     addTodo: z.object({
-      message: z.string().min(1).max(100).describe('The message of the todo'),
+      title: z.string().min(1).max(100).describe('The title of the todo'),
+      content: z.string().min(1).max(100).describe('The content of the todo'),
     }),
     deleteTodo: z.object({
       index: z.number().describe('The index of the todo to delete'),
@@ -24,7 +25,8 @@ const agent = createAgent({
 });
 
 interface Todo {
-  message: string;
+  title: string;
+  content: string;
   done: boolean;
 }
 
@@ -48,7 +50,8 @@ const machine = setup({
         todos: ({ context, event }) => [
           ...context.todos,
           {
-            message: event.message,
+            title: event.title,
+            content: event.content,
             done: false,
           },
         ],

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@statelyai/agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "lint": "tsc --noEmit",
+    "test": "vitest",
+    "example": "ts-node examples/helpers/runner.ts",
+    "prepublishOnly": "tsup src/index.ts --format cjs,esm --dts",
+    "changeset": "changeset",
+    "release": "changeset publish",
+    "version": "changeset version"
+  },
   "keywords": [],
   "author": "",
   "license": "MIT",
@@ -33,14 +43,5 @@
     "ai": "^3.1.32",
     "xstate": "^5.13.2"
   },
-  "packageManager": "pnpm@8.11.0",
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "lint": "tsc --noEmit",
-    "test": "vitest",
-    "example": "ts-node examples/helpers/runner.ts",
-    "changeset": "changeset",
-    "release": "changeset publish",
-    "version": "changeset version"
-  }
-}
+  "packageManager": "pnpm@8.11.0"
+}

package/src/planners/simplePlanner.ts

@@ -9,7 +9,6 @@ import {
 } from '../types';
 import { getAllTransitions } from '../utils';
 import { AnyStateMachine } from 'xstate';
-import { z } from 'zod';
 import { defaultTextTemplate } from '../templates/defaultText';
 
 function getTransitions(
@@ -75,9 +74,13 @@ export async function simplePlanner<T extends Agent<any>>(
   for (const toolTransitionData of toolTransitions) {
     const toolZodType = input.events?.[toolTransitionData.eventType];
 
+    if (!toolZodType) {
+      continue;
+    }
+
     toolMap[toolTransitionData.name] = tool({
       description: toolZodType?.description ?? toolTransitionData.description,
-      parameters: toolZodType ?? z.object({}),
+      parameters: toolZodType,
       execute: async (params) => {
         const event = {
           type: toolTransitionData.eventType,

package/src/schemas.ts

@@ -1,4 +1,4 @@
-import { SomeZodObject } from 'zod';
+import type { SomeZodObject } from 'zod';
 import { AnyEventObject } from 'xstate';
 import { ObservedState } from './types';