@applica-software-guru/persona-chat-sdk 0.1.102

package/docs/messages.md

@@ -0,0 +1,214 @@
+# Messages and Storage
+
+## Accessing Messages
+
+### usePersonaRuntimeMessages
+
+The `usePersonaRuntimeMessages` hook provides a simple way to access the current list of messages managed by the Persona Chat SDK runtime. This hook returns an array of `PersonaMessage` objects, which represent the conversation history, including user, assistant, and reasoning messages.
+
+**Usage Example:**
+
+```tsx
+import { usePersonaRuntimeMessages } from '@applica-software-guru/persona-chat-sdk';
+
+function MessageLogger() {
+  const messages = usePersonaRuntimeMessages();
+  return (
+    <div>
+      <h3>Messages</h3>
+      <pre>{JSON.stringify(messages, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+This hook must be used within a `PersonaRuntimeProvider`.
+
+### usePersonaRuntime and getMessages
+
+The `usePersonaRuntime` hook gives you access to the Persona runtime context, which now includes a `getMessages` method. This method returns the current array of `PersonaMessage` objects, allowing you to programmatically retrieve the latest messages at any time.
+
+**Usage Example:**
+
+```tsx
+import { usePersonaRuntime } from '@applica-software-guru/persona-chat-sdk';
+
+function MyComponent() {
+  const { getMessages } = usePersonaRuntime();
+  const messages = getMessages();
+  // Use messages as needed
+}
+```
+
+Both approaches are useful for building custom UI components, analytics, or debugging tools that need access to the chat history.
+
+---
+
+## Message Filtering
+
+The `messageFilter` prop allows you to process and filter messages before they are displayed in the chat interface. This provides powerful customization capabilities for controlling what messages users see and how they are presented.
+
+### Basic Usage
+
+Add a `messageFilter` function to your `PersonaRuntimeProvider`:
+
+```tsx
+import { PersonaRuntimeProvider, MessageFilter, PersonaMessage } from '@applica-software-guru/persona-chat-sdk';
+
+const myMessageFilter: MessageFilter = (messages: PersonaMessage[]) => {
+  // Process and return the filtered messages
+  return messages.filter((message) => message.type !== 'reasoning');
+};
+
+function App() {
+  return (
+    <PersonaRuntimeProvider apiKey="your-api-key" agentId="your-agent-id" protocols={{ rest: true }} messageFilter={myMessageFilter}>
+      {/* Your app content */}
+    </PersonaRuntimeProvider>
+  );
+}
+```
+
+### MessageFilter Type
+
+```typescript
+type MessageFilter = (messages: PersonaMessage[]) => PersonaMessage[];
+```
+
+The function receives an array of `PersonaMessage` objects and must return an array of `PersonaMessage` objects.
+
+### Common Use Cases
+
+#### 1. Hide Reasoning Messages
+
+```tsx
+const hideReasoningFilter: MessageFilter = (messages) => {
+  return messages.filter((message) => message.type !== 'reasoning');
+};
+```
+
+#### 2. Content Filtering
+
+```tsx
+const profanityFilter: MessageFilter = (messages) => {
+  const bannedWords = ['spam', 'inappropriate'];
+  return messages.filter((message) => {
+    const text = message.text.toLowerCase();
+    return !bannedWords.some((word) => text.includes(word));
+  });
+};
+```
+
+#### 3. Message Limit
+
+```tsx
+const messageLimitFilter: MessageFilter = (messages) => {
+  const maxMessages = 50;
+  return messages.length > maxMessages ? messages.slice(-maxMessages) : messages;
+};
+```
+
+#### 4. Text Transformation
+
+```tsx
+const transformTextFilter: MessageFilter = (messages) => {
+  return messages.map((message) => ({
+    ...message,
+    text: message.text.replace(/\b(TODO|FIXME)\b/g, '⚠️ $1'),
+  }));
+};
+```
+
+#### 5. Combining Multiple Filters
+
+```tsx
+const combinedFilter: MessageFilter = (messages) => {
+  let filtered = hideReasoningFilter(messages);
+  filtered = profanityFilter(filtered);
+  filtered = messageLimitFilter(filtered);
+  return filtered;
+};
+```
+
+---
+
+## Message Storage
+
+The Persona Chat SDK provides a flexible message storage system that allows you to persist conversation history across sessions. By default, messages are stored in memory, but you can easily switch to localStorage or implement your own custom storage solution.
+
+### Storage Implementations
+
+#### InMemoryMessageStorage (Default)
+
+Messages are stored in memory and lost on page reload. This is the default if no storage is specified.
+
+```tsx
+import { PersonaRuntimeProvider, InMemoryMessageStorage } from '@applica-software-guru/persona-chat-sdk';
+
+const storage = new InMemoryMessageStorage();
+
+<PersonaRuntimeProvider apiKey="your-api-key" agentId="your-agent-id" protocols={{ rest: true }} threads={true} messageStorage={storage}>
+  {/* Your app */}
+</PersonaRuntimeProvider>;
+```
+
+#### LocalStorageMessageStorage
+
+Messages persist across page reloads using browser localStorage.
+
+```tsx
+import { PersonaRuntimeProvider, LocalStorageMessageStorage } from '@applica-software-guru/persona-chat-sdk';
+
+const storage = new LocalStorageMessageStorage('my_app_messages_');
+
+<PersonaRuntimeProvider apiKey="your-api-key" agentId="your-agent-id" protocols={{ rest: true }} threads={true} messageStorage={storage}>
+  {/* Your app */}
+</PersonaRuntimeProvider>;
+```
+
+### Custom Storage Implementation
+
+You can implement your own storage solution by implementing the `MessageStorage` interface:
+
+```tsx
+import { MessageStorage, PersonaMessage, Session } from '@applica-software-guru/persona-chat-sdk';
+
+class CustomMessageStorage implements MessageStorage {
+  async saveMessages(sessionId: Session, messages: PersonaMessage[]): Promise<void> {
+    // Your custom save logic (e.g., IndexedDB, remote API)
+    await fetch('/api/save-messages', {
+      method: 'POST',
+      body: JSON.stringify({ sessionId, messages }),
+    });
+  }
+
+  async loadMessages(sessionId: Session): Promise<PersonaMessage[]> {
+    // Your custom load logic
+    const response = await fetch(`/api/load-messages/${sessionId}`);
+    return await response.json();
+  }
+
+  async deleteMessages(sessionId: Session): Promise<void> {
+    // Your custom delete logic
+    await fetch(`/api/delete-messages/${sessionId}`, { method: 'DELETE' });
+  }
+
+  async clearAll(): Promise<void> {
+    // Clear all messages
+    await fetch('/api/clear-all-messages', { method: 'DELETE' });
+  }
+
+  async getAllSessionIds(): Promise<Session[]> {
+    // Get all session IDs
+    const response = await fetch('/api/session-ids');
+    return await response.json();
+  }
+}
+
+const customStorage = new CustomMessageStorage();
+
+<PersonaRuntimeProvider
+  messageStorage={customStorage}
+  // ... other props
+/>;
+```

package/docs/protocols.md

@@ -0,0 +1,39 @@
+# Protocols
+
+The Persona Chat SDK supports multiple communication protocols to provide flexibility and performance. These protocols can work together, sharing the same session and data, to ensure the best possible experience.
+
+## Protocols Overview
+
+### REST
+
+- **Description**: A simple and reliable protocol for sending and receiving data.
+- **Use Case**: Ideal for applications where real-time communication is not critical.
+
+### WebSocket
+
+- **Description**: A full-duplex communication protocol that enables real-time interaction between the client and server.
+- **Use Case**: Suitable for scenarios requiring low-latency communication, such as live chat applications.
+
+### WebRTC
+
+- **Description**: A peer-to-peer communication protocol designed primarily for ultra-fast audio sessions, while also supporting high-speed messaging with minimal latency.
+- **Use Case**: Perfect for real-time, interactive applications where rapid audio communication and responsiveness are critical.
+- **Why WebRTC?**: By creating direct peer-to-peer connections, WebRTC eliminates unnecessary server delays, ensuring the fastest possible audio sessions and seamless message exchanges.
+
+**Pro Tip**: For optimal audio performance, make sure WebRTC is enabled in the `protocols` configuration of your application.
+
+---
+
+## How Protocols Work Together
+
+The Persona Chat SDK runtime is designed to use multiple protocols simultaneously, ensuring flexibility and reliability. Here’s how it works:
+
+1. **Shared Session**: All protocols share the same session and operate on the same data, ensuring consistency across communication channels.
+2. **Protocol Selection**: The runtime automatically selects the fastest and most reliable protocol from the list of enabled protocols. For example:
+   - If WebRTC is available and started, it will be prioritized for its ultra-low latency.
+   - If WebRTC is not available, WebSocket will be used for real-time communication.
+   - REST will act as a fallback for non-real-time communication.
+3. **WebRTC Startup**: WebRTC requires manual startup by the user (e.g., clicking a microphone icon to enable audio/video). Once started, WebRTC participates in the list of reliable protocols and is used for the fastest communication.
+4. **Seamless Integration**: Even if WebRTC is not started, other protocols like WebSocket and REST will continue to function, ensuring uninterrupted communication.
+
+This design allows the Persona Chat SDK to adapt dynamically to the available protocols, providing the best possible performance and reliability.

package/docs/transactions.md

@@ -0,0 +1,121 @@
+# Transactions and Tools
+
+The Transaction Protocol in the Persona Chat SDK is designed to handle structured interactions between the client and the Persona API. It allows you to define and execute specific operations (tools) in response to function calls.
+
+## How It Works
+
+1. **Transaction Handling**: The protocol listens for incoming transactions and invokes the appropriate tool based on the function call.
+2. **Session Management**: It shares the same session as other protocols, ensuring consistency.
+3. **Custom Logic**: You can define custom tools to handle specific function calls.
+
+## Usage Example
+
+To enable the Transaction Protocol, include it in the `protocols` configuration of the `PersonaRuntimeProvider`:
+
+```tsx
+<PersonaRuntimeProvider
+  dev
+  logger={logger}
+  protocols={{
+    transaction: async (transaction) => {
+      await transaction.invoke({
+        get_user_agent: () => navigator.userAgent || 'unknown',
+        get_client_date: () => ({ date: new Date().toISOString() }),
+      });
+    },
+  }}
+  session="your-session-id"
+  apiKey="your-api-key"
+  agentId="your-agent-id"
+>
+  <YourComponent />
+</PersonaRuntimeProvider>
+```
+
+---
+
+## Managing Tools
+
+### Using the `tools` Prop in PersonaRuntimeProvider
+
+The `tools` prop allows you to define custom tools that the Transaction Protocol can invoke in response to function calls.
+
+#### 1. As an Object (Legacy, Backward Compatible)
+
+> **Important:** When using the legacy object format, your agent configuration must also include the tool schema for each tool. If the schema is missing, the configured tools will not work as expected. This is not required when using the array format with `createTool`.
+
+```tsx
+<PersonaRuntimeProvider
+  tools={{
+    get_user_agent: () => navigator.userAgent || 'unknown',
+    get_client_date: () => ({ date: new Date().toISOString() }),
+  }}
+  ...otherProps
+/>
+```
+
+#### 2. As an Array of Tool Instances (Recommended)
+
+For better type safety, schema support, and documentation, you can define tools using the `createTool` utility:
+
+```tsx
+import { createTool } from '@applica-software-guru/persona-chat-sdk';
+
+const tools = [
+  createTool({
+    name: 'sum',
+    title: 'Sum two numbers',
+    description: 'Sums two numbers and returns the result.',
+    parameters: {
+      a: { type: 'number', description: 'First number to sum', required: true },
+      b: { type: 'number', description: 'Second number to sum', required: true },
+    },
+    output: {
+      result: { type: 'number', description: 'Sum of the two numbers' },
+    },
+    implementation: async (a: number, b: number) => {
+      return { result: a + b };
+    },
+  }),
+];
+
+<PersonaRuntimeProvider
+  tools={tools}
+  ...otherProps
+/>
+```
+
+---
+
+## Advanced Transaction Handling
+
+You can manage transactions manually by inspecting the function call and executing the `complete` or `fail` methods.
+
+```tsx
+<PersonaRuntimeProvider
+  protocols={{
+    transaction: async (transaction) => {
+      const { functionCall, persistable } = transaction;
+
+      try {
+        if (functionCall.name === 'get_user_agent') {
+          const result = navigator.userAgent || 'unknown';
+          await persistable.complete(result);
+        } else {
+          throw new Error(`Unknown function call: ${functionCall.name}`);
+        }
+      } catch (error) {
+        await persistable.fail({ error: error.message });
+      }
+    },
+  }}
+  ...
+/>
+```
+
+## Best Practices
+
+1. **Tool Naming**: Use descriptive names.
+2. **Error Handling**: Handle errors gracefully.
+3. **Testing**: Test tools thoroughly.
+4. **Security**: Avoid exposing sensitive data.

package/docs/usage.md

@@ -0,0 +1,40 @@
+# Usage
+
+Here’s an example of how to use the Persona SDK in your chat application:
+
+```typescript
+import dynamic from 'next/dynamic';
+
+const PersonaRuntimeProvider = dynamic(() => import('@applica-software-guru/persona-chat-sdk').then((mod) => mod.PersonaRuntimeProvider), {
+  ssr: false,
+});
+
+const logger = new PersonaConsoleLogger();
+
+function Chat() {
+  return (
+    <PersonaRuntimeProvider
+      dev
+      logger={logger}
+      protocols={{
+        rest: true,
+        webrtc: true,
+        websocket: true,
+      }}
+      session={'<session-id>'}
+      apiKey="<api-key>"
+      agentId={'<agent-name>'}
+    >
+      <div className="h-dvh w-full">
+        <Thread />
+      </div>
+    </PersonaRuntimeProvider>
+  );
+}
+```
+
+**Note**: When using WebRTC, it is recommended to import `PersonaRuntimeProvider` dynamically with `ssr: false` (as shown above) to ensure compatibility with server-side rendering frameworks like Next.js.
+
+### Development Mode
+
+Use the `dev` prop to enable development mode. This redirects all traffic to a local installation of Persona (e.g., `localhost:8000`).

package/jsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "composite": true,
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "resolveJsonModule": true
+  },
+  "include": ["vite.config.js", "package.json"]
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@applica-software-guru/persona-chat-sdk",
+  "private": false,
+  "version": "0.1.102",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --outDir dist && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "@assistant-ui/react-markdown": "^0.11.6",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@tailwindcss/vite": "^4.0.17",
+    "@types/inflection": "^1.13.2",
+    "@types/lodash": "^4.17.15",
+    "@types/node": "^20.12.13",
+    "@types/react-dom": "^19.1.1",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "eslint": "^8.25.0",
+    "eslint-config-prettier": "^8.10.0",
+    "eslint-config-react-app": "7.0.1",
+    "eslint-plugin-export": "^0.1.2",
+    "eslint-plugin-filenames": "^1.3.2",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jsx-a11y": "^6.6.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-react": "^7.31.10",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.4.19",
+    "eslint-plugin-sort-exports": "^0.9.1",
+    "husky": "^9.0.11",
+    "jsdom": "^22.1.0",
+    "lodash": "^4.17.21",
+    "lucide-react": "^0.485.0",
+    "prettier": "^2.8.8",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-markdown": "^10.0.1",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.2.0",
+    "tailwindcss": "^4.0.17",
+    "tw-animate-css": "^1.2.8",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.12",
+    "vite-plugin-compression": "^0.5.1",
+    "vite-plugin-dts": "^2.3.0",
+    "vite-plugin-linter": "^2.0.2",
+    "vitest": "^1.6.0"
+  },
+  "peerDependencies": {
+    "@assistant-ui/react": "^0.11.47",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-slot": "^1.2.4",
+    "react": "^18 || ^19 || ^19.0.0-rc",
+    "react-dom": "^18 || ^19 || ^19.0.0-rc",
+    "rehype-raw": "^7.0.0",
+    "zustand": "^5.0.9"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": false
+    }
+  },
+  "dependencies": {},
+  "keywords": [
+    "persona-chat-sdk"
+  ],
+  "main": "dist/bundle.cjs.js",
+  "module": "dist/bundle.es.js",
+  "types": "dist/index.d.ts",
+  "typings": "dist/index.d.ts"
+}

package/playground/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link href="/src/styles.css" rel="stylesheet">
+    <title>Persona SDK</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/playground/src/app.tsx

@@ -0,0 +1,10 @@
+function App() {
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
+      <h1 className="text-4xl font-bold text-gray-800">Hello, world!</h1>
+      <p className="mt-4 text-lg text-gray-600">This is a simple React app.</p>
+    </div>
+  );
+}
+
+export default App;

package/playground/src/chat.tsx

@@ -0,0 +1,117 @@
+import { Thread } from '@/components/assistant-ui/thread';
+import { PersonaRuntimeProvider, PersonaConsoleLogger, Session } from '@applica-software-guru/persona-chat-sdk';
+import { useMemo } from 'react';
+import { SidebarInset, SidebarProvider, SidebarTrigger } from '@/components/ui/sidebar';
+import { ThreadListSidebar } from '@/components/assistant-ui/threadlist-sidebar';
+import { SunIcon, MoonIcon, RefreshCcwDot } from 'lucide-react';
+import { useColorScheme } from './hooks/theme';
+
+const logger = new PersonaConsoleLogger();
+
+function generateSID() {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let sid = '';
+  for (let i = 0; i < 16; i++) {
+    sid += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return sid;
+}
+
+function getQueryParam(param: string): string | null {
+  const urlParams = new URLSearchParams(window.location.search);
+  return urlParams.get(param);
+}
+
+function Chat() {
+  const sidebar = getQueryParam('sidebar') === 'true';
+  const enableAttachments = getQueryParam('enableAttachments') !== 'false';
+  const agentId = getQueryParam('agentId');
+  const userId = getQueryParam('userId') || 'anonymous';
+  const apiKey = getQueryParam('apiKey');
+  const sid = getQueryParam('sid');
+
+  const session = useMemo((): Session => {
+    if (sid) {
+      return sid;
+    }
+    return generateSID();
+  }, [sid]);
+
+  return (
+    <PersonaRuntimeProvider
+      // dev
+      // baseUrl="http://localhost:8000"
+      logger={logger}
+      context={{
+        data: {
+          username: 'Roberto',
+          userAgent: 'Playground Client v1.0',
+        },
+      }}
+      tools={[]}
+      protocols={{
+        rest: true,
+        webrtc: false,
+        websocket: true,
+      }}
+      session={session}
+      apiKey={apiKey!}
+      userId={userId}
+      agentId={agentId!}
+      enableAttachments={enableAttachments}
+      threads={sidebar}
+      onThreadCreate={(threadId) => {
+        logger.info('Thread created:', threadId);
+      }}
+      onThreadSwitch={(threadId) => {
+        logger.info('Switched to thread:', threadId);
+      }}
+      onThreadRename={(threadId, newTitle) => {
+        logger.info('Thread renamed:', threadId, newTitle);
+      }}
+      onThreadArchive={(threadId) => {
+        logger.info('Thread archived:', threadId);
+      }}
+      onThreadDelete={(threadId) => {
+        logger.info('Thread deleted:', threadId);
+      }}
+    >
+      {sidebar ? (
+        <SidebarProvider>
+          <div className="flex h-dvh w-full">
+            <ThreadListSidebar />
+            <SidebarInset>
+              <SidebarTrigger className="absolute top-4 left-4" />
+              <ThemeToggle />
+              <Thread />
+            </SidebarInset>
+          </div>
+        </SidebarProvider>
+      ) : (
+        <div className="relative h-dvh w-full">
+          <ThemeToggle />
+          <Thread />
+        </div>
+      )}
+    </PersonaRuntimeProvider>
+  );
+}
+
+function ThemeToggle() {
+  const { theme, toggle } = useColorScheme();
+  const title = theme === 'auto' ? 'System theme (auto)' : theme === 'dark' ? 'Dark mode' : 'Light mode';
+
+  return (
+    <button
+      onClick={toggle}
+      aria-label={`Toggle theme, current: ${title}`}
+      title={`Toggle theme, current: ${title}`}
+      type="button"
+      className="absolute top-4 right-4 z-50 pointer-events-auto inline-flex h-10 w-10 items-center justify-center rounded-full border border-border bg-card p-2 text-foreground shadow-sm hover:cursor-pointer"
+    >
+      {theme === 'dark' ? <MoonIcon /> : theme === 'light' ? <SunIcon /> : <RefreshCcwDot />}
+    </button>
+  );
+}
+
+export { Chat };