@letta-ai/letta-react 0.0.1

package/project.json

@@ -0,0 +1,20 @@
+{
+  "name": "letta-react",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/letta-react/src",
+  "projectType": "application",
+  "tags": [],
+  "targets": {
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "tsc --noEmit -p packages/letta-react/tsconfig.app.json"
+      }
+    },
+    "test": {
+      "options": {
+        "passWithNoTests": true
+      }
+    }
+  }
+}

package/src/hooks/useAgentMessages/useAgentMessages.ts

@@ -0,0 +1,329 @@
+import { LettaClient, type Letta } from '@letta-ai/letta-client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { LettaRequest } from '@letta-ai/letta-client/api/types/LettaRequest';
+import type { MessagesListRequest } from '@letta-ai/letta-client/api/resources/agents';
+import { useGlobalLettaConfig } from '../useGlobalLettaConfig/useGlobalLettaConfig';
+import type { LocalMessagesState } from '../../types';
+import { useCachedState } from '../useCachedState/useCachedState';
+import { useLettaClient } from '../useLettaClient/useLettaClient';
+
+interface UseAgentOptions {
+  client?: LettaClient.Options;
+  agentId: string;
+  limit?: number;
+  messageOptions?: Omit<MessagesListRequest, 'after' | 'before' | 'limit'>;
+  method?: 'stream' | 'basic';
+}
+
+function extendContent(
+  content: string | Letta.TextContent[],
+  nextContent: string | Letta.TextContent[]
+): string | Letta.TextContent[] {
+  if (typeof content === 'string') {
+    if (typeof nextContent === 'string') {
+      return `${content}${nextContent}`;
+    } else {
+      return `${content}${nextContent.join('')}`;
+    }
+  } else {
+    if (typeof nextContent === 'string') {
+      return [...content, { text: nextContent, type: 'text' }];
+    } else {
+      return [...content, ...nextContent];
+    }
+  }
+}
+
+interface SendMessagePayload {
+  messages: LettaRequest['messages'];
+}
+
+export function useAgentMessages(options: UseAgentOptions) {
+  const {
+    client = {},
+    method = 'stream',
+    messageOptions = {},
+    limit = 20,
+    agentId,
+  } = options;
+  const localClient = useLettaClient(client);
+
+  const [localMessages, setLocalMessages] = useCachedState<LocalMessagesState>(
+    `messages-${agentId}`,
+    {
+      messages: [],
+    }
+  );
+
+  const hasInitialLoaded = useRef<boolean>(false);
+
+  const [isLoading, setIsLoading] = useState(true);
+  const [isFetching, setIsFetching] = useState(false);
+  const [loadingError, setLoadingError] = useState<unknown | null>(null);
+
+  const [isSending, setIsSending] = useState(false);
+  const [sendingError, setSendingError] = useState<unknown | null>(null);
+
+  const sendNonStreamedMessage = useCallback(
+    async function sendNonStreamedMessage(
+      sendMessagePayload: SendMessagePayload
+    ) {
+      try {
+        setIsSending(true);
+        setSendingError(null);
+
+        const response = await localClient.agents.messages.create(agentId, {
+          ...sendMessagePayload,
+          ...messageOptions,
+        });
+
+        setLocalMessages((prevState) => ({
+          ...prevState,
+          messages: [...response.messages, ...prevState.messages],
+        }));
+      } catch (e) {
+        setSendingError(e);
+      } finally {
+        setIsSending(false);
+      }
+    },
+    [localClient]
+  );
+
+  const sendStreamedMessage = useCallback(
+    async function sendStreamedMessage(sendMessagePayload: SendMessagePayload) {
+      try {
+        setIsSending(true);
+        setSendingError(null);
+
+        const response = await localClient.agents.messages.createStream(
+          agentId,
+          {
+            ...sendMessagePayload,
+            ...messageOptions,
+            streamTokens: true,
+          }
+        );
+
+        for await (const nextMessage of response) {
+          if (nextMessage.messageType === 'usage_statistics') {
+            return;
+          }
+          // @ts-expect-error - this is a correct lookup, id does exist
+          if (!nextMessage?.id) {
+            return;
+          }
+
+          setLocalMessages((prevState) => {
+            let hasExistingMessage = false;
+            const nextMessages = prevState.messages.map((prevMessage) => {
+              if (nextMessage.messageType === 'usage_statistics') {
+                return prevMessage;
+              }
+
+              // @ts-expect-error - this is a correct lookup, id does exist
+              if (!prevMessage?.id || !nextMessage?.id) {
+                return prevMessage;
+              }
+
+              // @ts-expect-error - this is a correct lookup, id does exist
+              if (prevMessage.id !== nextMessage.id) {
+                return prevMessage;
+              }
+
+              if (
+                nextMessage.messageType === 'reasoning_message' &&
+                prevMessage.messageType === 'reasoning_message'
+              ) {
+                hasExistingMessage = true;
+
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                  reasoning: `${prevMessage.reasoning}${nextMessage.reasoning}`,
+                };
+              }
+
+              if (
+                nextMessage.messageType === 'system_message' &&
+                prevMessage.messageType === 'system_message'
+              ) {
+                hasExistingMessage = true;
+
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                  content: extendContent(
+                    prevMessage.content,
+                    nextMessage.content
+                  ),
+                };
+              }
+
+              if (
+                nextMessage.messageType === 'user_message' &&
+                prevMessage.messageType === 'user_message'
+              ) {
+                hasExistingMessage = true;
+
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                  content: extendContent(
+                    prevMessage.content,
+                    nextMessage.content
+                  ),
+                };
+              }
+
+              if (
+                nextMessage.messageType === 'assistant_message' &&
+                prevMessage.messageType === 'assistant_message'
+              ) {
+                hasExistingMessage = true;
+
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                  content: extendContent(
+                    prevMessage.content,
+                    nextMessage.content
+                  ),
+                };
+              }
+
+              if (
+                nextMessage.messageType === 'tool_call_message' &&
+                prevMessage.messageType === 'tool_call_message'
+              ) {
+                hasExistingMessage = true;
+
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                };
+              }
+
+              if (
+                nextMessage.messageType === 'tool_return_message' &&
+                prevMessage.messageType === 'tool_return_message'
+              ) {
+                hasExistingMessage = true;
+                return {
+                  ...prevMessage,
+                  ...nextMessage,
+                };
+              }
+
+              return prevMessage;
+            });
+
+            return {
+              ...prevState,
+              messages: [
+                ...nextMessages,
+                ...(!hasExistingMessage
+                  ? [
+                      {
+                        ...nextMessage,
+                      },
+                    ]
+                  : []),
+              ] as LocalMessagesState['messages'],
+            };
+          });
+        }
+      } catch (e) {
+        setSendingError(e);
+      } finally {
+        setIsSending(false);
+      }
+    },
+    [localClient]
+  );
+
+  const sendMessage = useCallback(
+    function sendMessage(payload: SendMessagePayload) {
+      if (isSending) {
+        return;
+      }
+
+      if (method === 'stream') {
+        return sendStreamedMessage(payload);
+      }
+
+      return sendNonStreamedMessage(payload);
+    },
+    [method, isSending, sendStreamedMessage, sendNonStreamedMessage]
+  );
+
+  const getMessages = useCallback(
+    async function getMessages(before?: string) {
+      try {
+        if (isFetching) {
+          return;
+        }
+
+        setLoadingError(null);
+        setIsFetching(true);
+
+        const messages = await localClient.agents.messages.list(agentId, {
+          before,
+          limit: limit + 1,
+          ...messageOptions,
+        });
+
+        const messagesToAdd = messages.slice(1, messages.length);
+        const nextCursor = messages.length > limit ? messages[0] : undefined;
+
+        setLocalMessages((prevState) => ({
+          ...prevState,
+          messages: [...messagesToAdd, ...prevState.messages],
+          nextCursor: nextCursor?.id,
+        }));
+      } catch (e) {
+        setLoadingError(e);
+      } finally {
+        setIsFetching(false);
+        setIsLoading(false);
+      }
+    },
+    [localClient, isFetching]
+  );
+
+  const fetchOlderMessages = useCallback(async () => {
+    const nextCursor = localMessages.nextCursor;
+
+    if (!nextCursor) {
+      return;
+    }
+
+    return getMessages(nextCursor);
+  }, [getMessages]);
+
+  useEffect(() => {
+    if (hasInitialLoaded.current) {
+      return;
+    }
+
+    hasInitialLoaded.current = true;
+
+    setIsLoading(true);
+
+    getMessages();
+  }, []);
+
+  return {
+    messages: localMessages.messages,
+    isLoading,
+    isFetching,
+    isLoadingError: !!loadingError,
+    loadingError,
+    sendMessage,
+    isSending,
+    sendingError,
+    isSendingError: !!sendingError,
+    fetchOlderMessages,
+    hasOlderMessages: localMessages.nextCursor,
+  };
+}

package/src/hooks/useAgentState/useAgentState.ts

@@ -0,0 +1,55 @@
+import { useLettaClient } from '../useLettaClient/useLettaClient';
+import type { LettaClient } from '@letta-ai/letta-client';
+import { useCachedState } from '../useCachedState/useCachedState';
+import type { AgentState } from '@letta-ai/letta-client/api';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface UseAgentStateOptions {
+  client?: LettaClient.Options;
+  agentId: string;
+}
+
+export function useAgentState(options: UseAgentStateOptions) {
+  const { client, agentId } = options;
+  const localClient = useLettaClient(client);
+
+  const [localState, setLocalState] = useCachedState<AgentState | undefined>(
+    `agent-state-${agentId}`,
+    undefined
+  );
+
+  const [isLoading, setIsLoading] = useState(true);
+  const [loadingError, setLoadingError] = useState<unknown | null>(null);
+  const hasInitialLoaded = useRef<boolean>(false);
+
+  const getAgentState = useCallback(async () => {
+    try {
+      const state = await localClient.agents.retrieve(agentId);
+
+      setLocalState(state);
+    } catch (error) {
+      setLoadingError(error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [agentId, localClient, setLocalState]);
+
+  useEffect(() => {
+    if (hasInitialLoaded.current) {
+      return;
+    }
+
+    hasInitialLoaded.current = true;
+
+    setIsLoading(true);
+
+    getAgentState();
+  }, []);
+
+  return {
+    isLoading,
+    error: loadingError,
+    agentState: localState,
+    refresh: getAgentState,
+  };
+}

package/src/hooks/useCachedState/useCachedState.ts

@@ -0,0 +1,30 @@
+import { useGlobalLettaConfig } from '../useGlobalLettaConfig/useGlobalLettaConfig';
+import { Dispatch, SetStateAction, useState } from 'react';
+
+export function useCachedState<T>(
+  key: string,
+  defaultValue: T
+): [T, Dispatch<SetStateAction<T>>] {
+  const { isProviderSet, cachedData, updateCache } = useGlobalLettaConfig();
+
+  const [localState, setLocalState] = useState<T>(defaultValue);
+
+  if (!isProviderSet) {
+    return [localState, setLocalState];
+  }
+
+  return [
+    cachedData?.[key] || defaultValue,
+    (value: T) => {
+      updateCache((prevState) => {
+        return {
+          ...prevState,
+          [key]:
+            typeof value === 'function'
+              ? value(prevState?.[key] || defaultValue)
+              : value,
+        };
+      });
+    },
+  ] as [T, Dispatch<SetStateAction<T>>];
+}

package/src/hooks/useGlobalLettaConfig/useGlobalLettaConfig.tsx

@@ -0,0 +1,49 @@
+import React, { Dispatch, SetStateAction, useState } from 'react';
+import { LettaClient } from '@letta-ai/letta-client';
+import { createContext, useMemo, type ReactNode, useContext } from 'react';
+
+type CachedData = Record<string, any>;
+
+interface LettaProviderState {
+  isProviderSet?: boolean;
+  state: LettaClient.Options;
+  cachedData: CachedData;
+  updateCache: Dispatch<SetStateAction<CachedData>>;
+}
+
+const LettaContext = createContext<LettaProviderState>({
+  state: {},
+  cachedData: {},
+  updateCache: () => {
+    return;
+  },
+});
+
+interface LettaProviderProps {
+  options: LettaClient.Options;
+  children: ReactNode;
+}
+
+export function LettaProvider(props: LettaProviderProps) {
+  const [cachedData, updateCache] = useState({});
+
+  const state = useMemo(
+    () => ({
+      state: props.options,
+      cachedData,
+      updateCache,
+      isProviderSet: true,
+    }),
+    [props.options, updateCache, cachedData]
+  );
+
+  return (
+    <LettaContext.Provider value={state}>
+      {props.children}
+    </LettaContext.Provider>
+  );
+}
+
+export function useGlobalLettaConfig() {
+  return useContext(LettaContext);
+}

package/src/hooks/useLettaClient/useLettaClient.ts

@@ -0,0 +1,17 @@
+import { useState } from 'react';
+import { LettaClient } from '@letta-ai/letta-client';
+import { useGlobalLettaConfig } from '../useGlobalLettaConfig/useGlobalLettaConfig';
+
+export function useLettaClient(localOptions: LettaClient.Options = {}) {
+  const globalClient = useGlobalLettaConfig();
+
+  const [localClient] = useState(
+    () =>
+      new LettaClient({
+        ...globalClient.state,
+        ...localOptions,
+      })
+  );
+
+  return localClient;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { LettaProvider } from './hooks/useGlobalLettaConfig/useGlobalLettaConfig';
+export { useAgentMessages } from './hooks/useAgentMessages/useAgentMessages';
+export { useAgentState } from './hooks/useAgentState/useAgentState';

package/src/types.ts

@@ -0,0 +1,6 @@
+import type { Letta } from '@letta-ai/letta-client';
+
+export interface LocalMessagesState {
+  messages: Letta.LettaMessageUnion[];
+  nextCursor?: string;
+}

package/tsconfig.app.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "include": ["src"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "jsx": "react",
+    "extendedDiagnostics": true,
+    "strict": true,
+    "target": "ES6",
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "declaration": true,
+    "esModuleInterop": true
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../dist/out-tsc",
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "types": ["jest", "node"]
+  },
+  "include": [
+    "jest.config.ts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ]
+}

package/types.d.ts

@@ -0,0 +1,5 @@
+import type { Letta } from '@letta-ai/letta-client';
+export interface LocalMessagesState {
+    messages: Letta.LettaMessageUnion[];
+    nextCursor?: string;
+}

package/types.js

@@ -0,0 +1 @@
+export {};