@letta-ai/letta-react 0.0.1

package/README.md

@@ -0,0 +1,117 @@
+# Letta React
+
+A Letta react library full of the hooks you need to talk to Letta instantly
+
+## Documentation
+
+📚[Letta React Documentation](https://docs.letta.com/guides/letta-react)
+
+### Minimal Example
+
+#### Server-side configuration
+
+##### Local Letta Instance
+
+First setup Letta server, [instructions here](https://docs.letta.com/quickstart)
+
+Add the following environment variable to your environment to avoid CORS errors
+
+```bash
+export ACCEPTABLE_ORIGINS=your server url
+```
+
+Then start your server.
+
+##### Cloud/Secure Setups
+
+Setup a proxy server, below we are using [`express`](https://www.npmjs.com/package/express), [`http-proxy-middleware`](https://www.npmjs.com/package/http-proxy-middleware) and [`cors`](https://www.npmjs.com/package/cors)
+
+```
+// typescript
+
+import * as express from 'express';
+import type { Request, Response, NextFunction } from 'express';
+import cors from 'cors';
+
+import { createProxyMiddleware } from 'http-proxy-middleware';
+import type { Filter, Options, RequestHandler } from 'http-proxy-middleware';
+
+const app = express();
+
+
+app.use(cors({
+    origin: process.env.YOUR_WEBSITE_URL
+}))
+
+const lettaProxy = createProxyMiddleware<Request, Response>({
+    target: 'https://api.letta.com', // or your hosted url
+    changeOrigin: true,
+    headers: {
+        Authorization: 'Bearer ${process.env.LETTA_API_KEY}'
+    }
+  }),
+
+app.use(lettaProxy);
+
+app.listen(3000);
+```
+
+#### Client Side Usage
+
+##### Set up the `<LettaProvider />`
+
+Add the `<LettaProvider />` to the root of your application
+
+```typescript jsx
+import React from 'react';
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import { LettaProvider } from '../../src';
+
+const domNode = document.getElementById('root');
+const root = createRoot(domNode);
+
+root.render(
+  <StrictMode>
+    <LettaProvider
+      options={{
+        baseUrl: `your-letta-api-server-location`,
+      }}
+    >
+      <App />
+    </LettaProvider>
+  </StrictMode>
+);
+```
+
+##### Sending and Reading Messages `useAgentMessages`
+
+Check out [this example](./examples/view-and-send-messages) for more detailed usage.
+
+```typescript jsx
+const {
+  messages,
+  isLoading,
+  isFetching,
+  isLoadingError,
+  sendMessage,
+  isSending,
+  sendingError,
+  isSendingError,
+  fetchOlderMessages,
+  hasOlderMessages,
+} = useAgentMessages({
+  agentId: `your-agent-id`,
+});
+```
+
+##### Getting Agent State
+
+Check out [this example](./examples/view-and-send-messages) for more detailed usage.
+
+```typescript jsx
+const { agentState, error, isLoading, refresh } = agentState({
+  agentId: `your-agent-id`,
+});
+```

package/dist/hooks/useAgentMessages/useAgentMessages.d.ts

@@ -0,0 +1,27 @@
+import { LettaClient, type Letta } from '@letta-ai/letta-client';
+import type { LettaRequest } from '@letta-ai/letta-client/api/types/LettaRequest';
+import type { MessagesListRequest } from '@letta-ai/letta-client/api/resources/agents';
+interface UseAgentOptions {
+    client?: LettaClient.Options;
+    agentId: string;
+    limit?: number;
+    messageOptions?: Omit<MessagesListRequest, 'after' | 'before' | 'limit'>;
+    method?: 'stream' | 'basic';
+}
+interface SendMessagePayload {
+    messages: LettaRequest['messages'];
+}
+export declare function useAgentMessages(options: UseAgentOptions): {
+    messages: Letta.LettaMessageUnion[];
+    isLoading: boolean;
+    isFetching: boolean;
+    isLoadingError: boolean;
+    loadingError: unknown;
+    sendMessage: (payload: SendMessagePayload) => Promise<void> | undefined;
+    isSending: boolean;
+    sendingError: unknown;
+    isSendingError: boolean;
+    fetchOlderMessages: () => Promise<void>;
+    hasOlderMessages: string | undefined;
+};
+export {};

package/dist/hooks/useAgentMessages/useAgentMessages.js

@@ -0,0 +1,217 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCachedState } from '../useCachedState/useCachedState';
+import { useLettaClient } from '../useLettaClient/useLettaClient';
+function extendContent(content, nextContent) {
+    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];
+        }
+    }
+}
+export function useAgentMessages(options) {
+    const { client = {}, method = 'stream', messageOptions = {}, limit = 20, agentId, } = options;
+    const localClient = useLettaClient(client);
+    const [localMessages, setLocalMessages] = useCachedState(`messages-${agentId}`, {
+        messages: [],
+    });
+    const hasInitialLoaded = useRef(false);
+    const [isLoading, setIsLoading] = useState(true);
+    const [isFetching, setIsFetching] = useState(false);
+    const [loadingError, setLoadingError] = useState(null);
+    const [isSending, setIsSending] = useState(false);
+    const [sendingError, setSendingError] = useState(null);
+    const sendNonStreamedMessage = useCallback(function sendNonStreamedMessage(sendMessagePayload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                setIsSending(true);
+                setSendingError(null);
+                const response = yield localClient.agents.messages.create(agentId, Object.assign(Object.assign({}, sendMessagePayload), messageOptions));
+                setLocalMessages((prevState) => (Object.assign(Object.assign({}, prevState), { messages: [...response.messages, ...prevState.messages] })));
+            }
+            catch (e) {
+                setSendingError(e);
+            }
+            finally {
+                setIsSending(false);
+            }
+        });
+    }, [localClient]);
+    const sendStreamedMessage = useCallback(function sendStreamedMessage(sendMessagePayload) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, e_1, _b, _c;
+            try {
+                setIsSending(true);
+                setSendingError(null);
+                const response = yield localClient.agents.messages.createStream(agentId, Object.assign(Object.assign(Object.assign({}, sendMessagePayload), messageOptions), { streamTokens: true }));
+                try {
+                    for (var _d = true, response_1 = __asyncValues(response), response_1_1; response_1_1 = yield response_1.next(), _a = response_1_1.done, !_a; _d = true) {
+                        _c = response_1_1.value;
+                        _d = false;
+                        const nextMessage = _c;
+                        if (nextMessage.messageType === 'usage_statistics') {
+                            return;
+                        }
+                        // @ts-expect-error - this is a correct lookup, id does exist
+                        if (!(nextMessage === null || nextMessage === void 0 ? void 0 : 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 === null || prevMessage === void 0 ? void 0 : prevMessage.id) || !(nextMessage === null || nextMessage === void 0 ? void 0 : 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 Object.assign(Object.assign(Object.assign({}, prevMessage), nextMessage), { reasoning: `${prevMessage.reasoning}${nextMessage.reasoning}` });
+                                }
+                                if (nextMessage.messageType === 'system_message' &&
+                                    prevMessage.messageType === 'system_message') {
+                                    hasExistingMessage = true;
+                                    return Object.assign(Object.assign(Object.assign({}, prevMessage), nextMessage), { content: extendContent(prevMessage.content, nextMessage.content) });
+                                }
+                                if (nextMessage.messageType === 'user_message' &&
+                                    prevMessage.messageType === 'user_message') {
+                                    hasExistingMessage = true;
+                                    return Object.assign(Object.assign(Object.assign({}, prevMessage), nextMessage), { content: extendContent(prevMessage.content, nextMessage.content) });
+                                }
+                                if (nextMessage.messageType === 'assistant_message' &&
+                                    prevMessage.messageType === 'assistant_message') {
+                                    hasExistingMessage = true;
+                                    return Object.assign(Object.assign(Object.assign({}, prevMessage), nextMessage), { content: extendContent(prevMessage.content, nextMessage.content) });
+                                }
+                                if (nextMessage.messageType === 'tool_call_message' &&
+                                    prevMessage.messageType === 'tool_call_message') {
+                                    hasExistingMessage = true;
+                                    return Object.assign(Object.assign({}, prevMessage), nextMessage);
+                                }
+                                if (nextMessage.messageType === 'tool_return_message' &&
+                                    prevMessage.messageType === 'tool_return_message') {
+                                    hasExistingMessage = true;
+                                    return Object.assign(Object.assign({}, prevMessage), nextMessage);
+                                }
+                                return prevMessage;
+                            });
+                            return Object.assign(Object.assign({}, prevState), { messages: [
+                                    ...nextMessages,
+                                    ...(!hasExistingMessage
+                                        ? [
+                                            Object.assign({}, nextMessage),
+                                        ]
+                                        : []),
+                                ] });
+                        });
+                    }
+                }
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = response_1.return)) yield _b.call(response_1);
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+            }
+            catch (e) {
+                setSendingError(e);
+            }
+            finally {
+                setIsSending(false);
+            }
+        });
+    }, [localClient]);
+    const sendMessage = useCallback(function sendMessage(payload) {
+        if (isSending) {
+            return;
+        }
+        if (method === 'stream') {
+            return sendStreamedMessage(payload);
+        }
+        return sendNonStreamedMessage(payload);
+    }, [method, isSending, sendStreamedMessage, sendNonStreamedMessage]);
+    const getMessages = useCallback(function getMessages(before) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                if (isFetching) {
+                    return;
+                }
+                setLoadingError(null);
+                setIsFetching(true);
+                const messages = yield localClient.agents.messages.list(agentId, Object.assign({ before, limit: limit + 1 }, messageOptions));
+                const messagesToAdd = messages.slice(1, messages.length);
+                const nextCursor = messages.length > limit ? messages[0] : undefined;
+                setLocalMessages((prevState) => (Object.assign(Object.assign({}, prevState), { messages: [...messagesToAdd, ...prevState.messages], nextCursor: nextCursor === null || nextCursor === void 0 ? void 0 : nextCursor.id })));
+            }
+            catch (e) {
+                setLoadingError(e);
+            }
+            finally {
+                setIsFetching(false);
+                setIsLoading(false);
+            }
+        });
+    }, [localClient, isFetching]);
+    const fetchOlderMessages = useCallback(() => __awaiter(this, void 0, void 0, function* () {
+        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/dist/hooks/useAgentState/useAgentState.d.ts

@@ -0,0 +1,13 @@
+import type { LettaClient } from '@letta-ai/letta-client';
+import type { AgentState } from '@letta-ai/letta-client/api';
+interface UseAgentStateOptions {
+    client?: LettaClient.Options;
+    agentId: string;
+}
+export declare function useAgentState(options: UseAgentStateOptions): {
+    isLoading: boolean;
+    error: unknown;
+    agentState: AgentState | undefined;
+    refresh: () => Promise<void>;
+};
+export {};

package/dist/hooks/useAgentState/useAgentState.js

@@ -0,0 +1,46 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { useLettaClient } from '../useLettaClient/useLettaClient';
+import { useCachedState } from '../useCachedState/useCachedState';
+import { useCallback, useEffect, useRef, useState } from 'react';
+export function useAgentState(options) {
+    const { client, agentId } = options;
+    const localClient = useLettaClient(client);
+    const [localState, setLocalState] = useCachedState(`agent-state-${agentId}`, undefined);
+    const [isLoading, setIsLoading] = useState(true);
+    const [loadingError, setLoadingError] = useState(null);
+    const hasInitialLoaded = useRef(false);
+    const getAgentState = useCallback(() => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const state = yield 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/dist/hooks/useCachedState/useCachedState.d.ts

@@ -0,0 +1,2 @@
+import { Dispatch, SetStateAction } from 'react';
+export declare function useCachedState<T>(key: string, defaultValue: T): [T, Dispatch<SetStateAction<T>>];

package/dist/hooks/useCachedState/useCachedState.js

@@ -0,0 +1,19 @@
+import { useGlobalLettaConfig } from '../useGlobalLettaConfig/useGlobalLettaConfig';
+import { useState } from 'react';
+export function useCachedState(key, defaultValue) {
+    const { isProviderSet, cachedData, updateCache } = useGlobalLettaConfig();
+    const [localState, setLocalState] = useState(defaultValue);
+    if (!isProviderSet) {
+        return [localState, setLocalState];
+    }
+    return [
+        (cachedData === null || cachedData === void 0 ? void 0 : cachedData[key]) || defaultValue,
+        (value) => {
+            updateCache((prevState) => {
+                return Object.assign(Object.assign({}, prevState), { [key]: typeof value === 'function'
+                        ? value((prevState === null || prevState === void 0 ? void 0 : prevState[key]) || defaultValue)
+                        : value });
+            });
+        },
+    ];
+}

package/dist/hooks/useGlobalLettaConfig/useGlobalLettaConfig.d.ts

@@ -0,0 +1,17 @@
+import React, { Dispatch, SetStateAction } from 'react';
+import { LettaClient } from '@letta-ai/letta-client';
+import { type ReactNode } from 'react';
+type CachedData = Record<string, any>;
+interface LettaProviderState {
+    isProviderSet?: boolean;
+    state: LettaClient.Options;
+    cachedData: CachedData;
+    updateCache: Dispatch<SetStateAction<CachedData>>;
+}
+interface LettaProviderProps {
+    options: LettaClient.Options;
+    children: ReactNode;
+}
+export declare function LettaProvider(props: LettaProviderProps): React.JSX.Element;
+export declare function useGlobalLettaConfig(): LettaProviderState;
+export {};

package/dist/hooks/useGlobalLettaConfig/useGlobalLettaConfig.js

@@ -0,0 +1,22 @@
+import React, { useState } from 'react';
+import { createContext, useMemo, useContext } from 'react';
+const LettaContext = createContext({
+    state: {},
+    cachedData: {},
+    updateCache: () => {
+        return;
+    },
+});
+export function LettaProvider(props) {
+    const [cachedData, updateCache] = useState({});
+    const state = useMemo(() => ({
+        state: props.options,
+        cachedData,
+        updateCache,
+        isProviderSet: true,
+    }), [props.options, updateCache, cachedData]);
+    return (React.createElement(LettaContext.Provider, { value: state }, props.children));
+}
+export function useGlobalLettaConfig() {
+    return useContext(LettaContext);
+}

package/dist/hooks/useLettaClient/useLettaClient.d.ts

@@ -0,0 +1,2 @@
+import { LettaClient } from '@letta-ai/letta-client';
+export declare function useLettaClient(localOptions?: LettaClient.Options): LettaClient;

package/dist/hooks/useLettaClient/useLettaClient.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/types.d.ts

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

package/dist/types.js

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

package/eslint.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from '../../eslint.config.mjs';
+
+export default [...baseConfig];