@applica-software-guru/persona-sdk 0.0.1-preview6 → 0.1.37
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +237 -1
- package/bitbucket-pipelines.yml +2 -2
- package/package.json +1 -1
- package/preview.sh +7 -1
package/README.md
CHANGED
|
@@ -1,3 +1,239 @@
|
|
|
1
1
|
# Persona SDK ⚙️
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@applica-software-guru/persona-sdk)
|
|
4
|
+
[](#)
|
|
5
|
+
[](https://www.assistant-ui.com/)
|
|
6
|
+
|
|
7
|
+
Persona SDK is the official SDK for the Persona API. It provides a simple and efficient way to integrate the Persona API into your applications using [assistant-ui](https://www.assistant-ui.com/).
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Features](#features)
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Usage](#usage)
|
|
16
|
+
- [Protocols Overview](#protocols-overview)
|
|
17
|
+
- [API Reference](#api-reference)
|
|
18
|
+
- [Customization](#customization)
|
|
19
|
+
- [Contributing](#contributing)
|
|
20
|
+
- [License](#license)
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- **Custom Runtime Provider**: Easily integrate the Persona API with assistant-ui chat.
|
|
27
|
+
- **Local Runtime Support**: Run the assistant-ui chat locally using the Persona API.
|
|
28
|
+
- **Multiple Protocols**: Supports REST, WebSocket, and WebRTC protocols.
|
|
29
|
+
- **WebRTC Optimization**: Communicate with AI agents in real-time using the fastest protocol available.
|
|
30
|
+
- **Customizable**: Extend functionality with custom protocols and loggers.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Installation
|
|
35
|
+
|
|
36
|
+
To get started, install the Persona SDK using npm or yarn:
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install @applica-guru/persona-sdk
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
If you don't already have an assistant-ui-based project, you can create one using the [Assistant UI Getting Started Guide](https://www.assistant-ui.com/docs/getting-started).
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Usage
|
|
47
|
+
|
|
48
|
+
Here’s an example of how to use the Persona SDK in your chat application:
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
import { PersonaRuntimeProvider } from '@applica-guru/persona-sdk';
|
|
52
|
+
|
|
53
|
+
function Chat() {
|
|
54
|
+
return (
|
|
55
|
+
<PersonaRuntimeProvider
|
|
56
|
+
dev
|
|
57
|
+
logger={logger}
|
|
58
|
+
protocols={{
|
|
59
|
+
rest: true,
|
|
60
|
+
webrtc: true,
|
|
61
|
+
websocket: true,
|
|
62
|
+
}}
|
|
63
|
+
session={'<session-id>'}
|
|
64
|
+
apiKey="<api-key>"
|
|
65
|
+
agentId={'<agent-name>'}
|
|
66
|
+
>
|
|
67
|
+
<div className="h-dvh w-full">
|
|
68
|
+
<Thread />
|
|
69
|
+
</div>
|
|
70
|
+
</PersonaRuntimeProvider>
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Development Mode
|
|
76
|
+
|
|
77
|
+
Use the `dev` prop to enable development mode. This redirects all traffic to a local installation of Persona (e.g., `localhost:8000`).
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Protocols Overview
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
### REST
|
|
86
|
+
|
|
87
|
+
- **Description**: A simple and reliable protocol for sending and receiving data.
|
|
88
|
+
- **Use Case**: Ideal for applications where real-time communication is not critical.
|
|
89
|
+
|
|
90
|
+
### WebSocket
|
|
91
|
+
|
|
92
|
+
- **Description**: A full-duplex communication protocol that enables real-time interaction between the client and server.
|
|
93
|
+
- **Use Case**: Suitable for scenarios requiring low-latency communication, such as live chat applications.
|
|
94
|
+
|
|
95
|
+
### WebRTC (Recommended)
|
|
96
|
+
|
|
97
|
+
- **Description**: A peer-to-peer communication protocol designed for ultra-low latency and high-speed data transfer.
|
|
98
|
+
- **Use Case**: The fastest way to communicate with AI agents, making it ideal for real-time, interactive applications.
|
|
99
|
+
- **Why WebRTC?**: WebRTC bypasses traditional server-based communication, enabling direct peer-to-peer connections. This results in significantly reduced latency and improved performance, especially for high-frequency interactions with AI agents.
|
|
100
|
+
|
|
101
|
+
**Pro Tip**: If your application requires the fastest response times and seamless real-time interaction, enable WebRTC in the `protocols` configuration.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
### How Protocols Work Together
|
|
106
|
+
|
|
107
|
+
The Persona SDK runtime is designed to use multiple protocols simultaneously, ensuring flexibility and reliability. Here’s how it works:
|
|
108
|
+
|
|
109
|
+
1. **Shared Session**: All protocols share the same session and operate on the same data, ensuring consistency across communication channels.
|
|
110
|
+
2. **Protocol Selection**: The runtime automatically selects the fastest and most reliable protocol from the list of enabled protocols. For example:
|
|
111
|
+
- If WebRTC is available and started, it will be prioritized for its ultra-low latency.
|
|
112
|
+
- If WebRTC is not available, WebSocket will be used for real-time communication.
|
|
113
|
+
- REST will act as a fallback for non-real-time communication.
|
|
114
|
+
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.
|
|
115
|
+
4. **Seamless Integration**: Even if WebRTC is not started, other protocols like WebSocket and REST will continue to function, ensuring uninterrupted communication.
|
|
116
|
+
|
|
117
|
+
This design allows the Persona SDK to adapt dynamically to the available protocols, providing the best possible performance and reliability.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## API Reference
|
|
122
|
+
|
|
123
|
+
### Props for `PersonaRuntimeProvider`
|
|
124
|
+
|
|
125
|
+
| Prop | Type | Default Value | Description |
|
|
126
|
+
| ----------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
|
|
127
|
+
| `dev` | boolean | `false` | Enable development mode for local Persona API usage. |
|
|
128
|
+
| `logger` | function | `console.log` | Custom logger for debugging and logging messages. |
|
|
129
|
+
| `protocols` | object | `{ rest: true, webrtc: true, websocket: true }` | Protocols to use for the chat. Disable unused protocols for optimization. |
|
|
130
|
+
| `session` | string | `undefined` | Session ID for the chat. Required for the chat to function. |
|
|
131
|
+
| `apiKey` | string | `undefined` | API key for authentication. Required for the chat to function. |
|
|
132
|
+
| `agentId` | string | `undefined` | Agent ID for the chat. Required for the chat to function. |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## Customization
|
|
137
|
+
|
|
138
|
+
The Persona SDK allows you to extend its functionality by creating custom protocols and loggers.
|
|
139
|
+
|
|
140
|
+
### Custom Protocols
|
|
141
|
+
|
|
142
|
+
You can implement your own protocol by extending the `PersonaProtocolBase` class. For example:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
import { PersonaProtocolBase } from '@applica-guru/persona-sdk';
|
|
146
|
+
|
|
147
|
+
class CustomProtocol extends PersonaProtocolBase {
|
|
148
|
+
// Implement required methods like connect, disconnect, send, etc.
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
#### Example: Custom Protocol Implementation
|
|
153
|
+
|
|
154
|
+
Here’s an example of a custom protocol named `CustomProtocol`:
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
import { PersonaProtocolBase } from '@applica-guru/persona-sdk';
|
|
158
|
+
|
|
159
|
+
class CustomProtocol extends PersonaProtocolBase {
|
|
160
|
+
public getName(): string {
|
|
161
|
+
return 'custom';
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
public async connect(): Promise<void> {
|
|
165
|
+
console.log('[CustomProtocol] Connecting...');
|
|
166
|
+
this.setStatus('connected');
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
public async disconnect(): Promise<void> {
|
|
170
|
+
console.log('[CustomProtocol] Disconnecting...');
|
|
171
|
+
this.setStatus('disconnected');
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
public async send(message: string): Promise<void> {
|
|
175
|
+
console.log(`[CustomProtocol] Sending message: ${message}`);
|
|
176
|
+
this.notifyMessage({ role: 'assistant', type: 'text', text: `Echo: ${message}` });
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### Custom Loggers
|
|
182
|
+
|
|
183
|
+
You can create a custom logger by implementing the `PersonaLogger` interface:
|
|
184
|
+
|
|
185
|
+
```typescript
|
|
186
|
+
import { PersonaLogger } from '@applica-guru/persona-sdk';
|
|
187
|
+
|
|
188
|
+
class CustomLogger implements PersonaLogger {
|
|
189
|
+
log(message: string, ...args: unknown[]): void {
|
|
190
|
+
console.log(`[CustomLogger] ${message}`, ...args);
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
info(message: string, ...args: unknown[]): void {
|
|
194
|
+
console.info(`[CustomLogger] ${message}`, ...args);
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
warn(message: string, ...args: unknown[]): void {
|
|
198
|
+
console.warn(`[CustomLogger] ${message}`, ...args);
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
error(message: string, ...args: unknown[]): void {
|
|
202
|
+
console.error(`[CustomLogger] ${message}`, ...args);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
debug(message: string, ...args: unknown[]): void {
|
|
206
|
+
console.debug(`[CustomLogger] ${message}`, ...args);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Contributing
|
|
214
|
+
|
|
215
|
+
We welcome contributions! To get started:
|
|
216
|
+
|
|
217
|
+
1. Fork the repository.
|
|
218
|
+
2. Create a new branch for your feature or bugfix.
|
|
219
|
+
3. Submit a pull request with a detailed description of your changes.
|
|
220
|
+
|
|
221
|
+
Please ensure your code adheres to the existing style and passes all linting and testing checks.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## License
|
|
226
|
+
|
|
227
|
+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Support
|
|
232
|
+
|
|
233
|
+
For questions or support, contact us at [info@applica.guru](mailto:info@applica.guru).
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## Acknowledgments
|
|
238
|
+
|
|
239
|
+
This SDK is built on top of [assistant-ui](https://www.assistant-ui.com/), a powerful framework for building conversational interfaces.
|
package/bitbucket-pipelines.yml
CHANGED
|
@@ -2,12 +2,12 @@ image: node:18.20.4
|
|
|
2
2
|
|
|
3
3
|
pipelines:
|
|
4
4
|
branches:
|
|
5
|
-
|
|
5
|
+
feature/assistant-ui:
|
|
6
6
|
- step:
|
|
7
7
|
name: Deploy
|
|
8
8
|
deployment: Production
|
|
9
9
|
script:
|
|
10
|
-
- export VERSION=1
|
|
10
|
+
- export VERSION=0.1
|
|
11
11
|
- npm --no-git-tag-version version "$VERSION.$BITBUCKET_BUILD_NUMBER" -m "Upgrade to new version"
|
|
12
12
|
- npm install
|
|
13
13
|
- npm run build
|
package/package.json
CHANGED
package/preview.sh
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
#!/bin/bash
|
|
2
|
+
# This script automates the process of building and publishing a preview version of the npm package.
|
|
3
|
+
# When executed as ./preview.sh <tag-name>, it creates and publishes a new version of the package
|
|
4
|
+
# with the format @applica-software-guru/persona-sdk@0.1.0-<tag-name>.
|
|
5
|
+
# The script updates the package version with the specified tag, builds the project,
|
|
6
|
+
# and publishes it to the npm registry with the given preview tag.
|
|
7
|
+
# Usage: ./preview.sh <tag-name>
|
|
8
|
+
# Example: ./preview.sh beta
|
|
2
9
|
|
|
3
|
-
# Check if an argument is provided
|
|
4
10
|
if [ -z "$1" ]; then
|
|
5
11
|
echo "Usage: $0 <preview-tag>"
|
|
6
12
|
exit 1
|