@applica-software-guru/persona-sdk 0.1.70 → 0.1.72

package/README.md

@@ -14,6 +14,7 @@ Persona SDK is the official SDK for the Persona API. It provides a simple and ef
 - [Installation](#installation)
 - [Usage](#usage)
 - [Accessing Messages](#accessing-messages)
+- [Message Filtering](#message-filtering)
 - [Protocols Overview](#protocols-overview)
 - [API Reference](#api-reference)
 - [Customization](#customization)
@@ -131,6 +132,110 @@ Both approaches are useful for building custom UI components, analytics, or debu
 
 ---
 
+## 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-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;
+};
+```
+
+### Important Notes
+
+- The filter is applied to **all messages**, including both incoming messages from the assistant and outgoing messages from the user
+- The filter function should be pure (no side effects) and return a new array
+- Filters are applied every time the message list is updated
+- If no filter is provided, all messages are displayed as-is
+- Be careful with message ordering when filtering, as it may affect conversation context
+
+### Performance Considerations
+
+- Keep filter functions lightweight as they run on every message update
+- For expensive operations, consider debouncing or memoization
+- Avoid creating new filter functions on every render to prevent unnecessary re-processing
+
+For complete working examples, see the `examples/message-filter-example.tsx` file in the repository.
+
+---
+
 ## Protocols Overview
 
 The Persona 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.
@@ -175,14 +280,15 @@ This design allows the Persona SDK to adapt dynamically to the available protoco
 
 ### Props for `PersonaRuntimeProvider`
 
-| Prop        | Type     | Default Value                                   | Description                                                                  |
-| ----------- | -------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
-| `dev`       | boolean  | `false`                                         | Enable development mode for local Persona API usage.                         |
-| `logger`    | function | `console.log`                                   | Custom logger for debugging and logging messages.                            |
-| `protocols` | object   | `{ rest: true, webrtc: true, websocket: true }` | Protocols to use for the chat. Can be enabled/disabled using boolean values. |
-| `session`   | string   | `undefined`                                     | Session ID for the chat. Required for the chat to function.                  |
-| `apiKey`    | string   | `toolkit-test`                                  | API key for authentication. Required for the chat to function.               |
-| `agentId`   | string   | `default`                                       | Agent ID for the chat. Required for the chat to function.                    |
+| Prop            | Type          | Default Value                                   | Description                                                                                         |
+| --------------- | ------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `dev`           | boolean       | `false`                                         | Enable development mode for local Persona API usage.                                                |
+| `logger`        | function      | `console.log`                                   | Custom logger for debugging and logging messages.                                                   |
+| `protocols`     | object        | `{ rest: true, webrtc: true, websocket: true }` | Protocols to use for the chat. Can be enabled/disabled using boolean values.                        |
+| `session`       | string        | `undefined`                                     | Session ID for the chat. Required for the chat to function.                                         |
+| `apiKey`        | string        | `toolkit-test`                                  | API key for authentication. Required for the chat to function.                                      |
+| `agentId`       | string        | `default`                                       | Agent ID for the chat. Required for the chat to function.                                           |
+| `messageFilter` | MessageFilter | `undefined`                                     | Optional function to filter and transform messages before they are displayed in the chat interface. |
 
 ---