@applica-software-guru/persona-sdk 0.0.1-preview0

package/src/logging.ts

@@ -0,0 +1,34 @@
+interface PersonaLogger {
+  log: (message: string, ...args: unknown[]) => void;
+  info: (message: string, ...args: unknown[]) => void;
+  warn: (message: string, ...args: unknown[]) => void;
+  error: (message: string, ...args: unknown[]) => void;
+  debug: (message: string, ...args: unknown[]) => void;
+}
+
+class PersonaConsoleLogger implements PersonaLogger {
+  prefix = '[Persona]';
+
+  log(message: string, ...args: unknown[]) {
+    console.log(`${this.prefix} - ${message}`, ...args);
+  }
+
+  info(message: string, ...args: unknown[]) {
+    console.info(`${this.prefix} - ${message}`, ...args);
+  }
+
+  warn(message: string, ...args: unknown[]) {
+    console.warn(`${this.prefix} - ${message}`, ...args);
+  }
+
+  error(message: string, ...args: unknown[]) {
+    console.error(`${this.prefix} - ${message}`, ...args);
+  }
+
+  debug(message: string, ...args: unknown[]) {
+    console.debug(`${this.prefix} - ${message}`, ...args);
+  }
+}
+
+export { PersonaConsoleLogger };
+export type { PersonaLogger };

package/src/messages.ts

@@ -0,0 +1,79 @@
+import { PersonaMessage } from './types';
+import { ThreadMessageLike } from '@assistant-ui/react';
+
+function removeEmptyMessages(messages: PersonaMessage[]): PersonaMessage[] {
+  return messages.filter((message) => {
+    if (message.finishReason === 'stop') {
+      return message.text !== null && message.text?.trim() !== '';
+    }
+    return true;
+  });
+}
+function parseMessages(messages: PersonaMessage[]): PersonaMessage[] {
+  const outputMessages: PersonaMessage[] = [];
+  let currentMessage: PersonaMessage | null = null;
+
+  for (const message of messages) {
+    if (message.type === 'reasoning') {
+      if (currentMessage != null) {
+        outputMessages.push(currentMessage);
+        currentMessage = null;
+      }
+      outputMessages.push(message);
+    } else if (message.functionCalls) {
+      if (currentMessage) {
+        outputMessages.push(currentMessage);
+      }
+      outputMessages.push(message);
+      currentMessage = null;
+    } else if (message.functionResponse) {
+      outputMessages[outputMessages.length - 1] = {
+        ...outputMessages[outputMessages.length - 1],
+        functionResponse: message.functionResponse,
+      };
+    } else if (
+      currentMessage &&
+      message.protocol === currentMessage.protocol &&
+      (currentMessage.role === message.role || message.finishReason === 'stop')
+    ) {
+      currentMessage.text += message.text;
+    } else {
+      if (currentMessage) {
+        outputMessages.push(currentMessage);
+      }
+      currentMessage = {
+        ...message,
+      };
+    }
+  }
+
+  if (currentMessage) {
+    outputMessages.push(currentMessage);
+  }
+  return removeEmptyMessages(outputMessages);
+}
+
+function convertMessage(message: PersonaMessage): ThreadMessageLike {
+  if (message.role === 'function') {
+    return {
+      id: message.id!,
+      role: 'assistant',
+      status: message?.functionResponse === null ? { type: 'running' } : { type: 'complete', reason: 'stop' },
+      content:
+        message.functionCalls?.map((call) => ({
+          type: 'tool-call',
+          toolName: call.name,
+          toolCallId: call.id,
+          args: call.args,
+          result: message.functionResponse?.result,
+        })) ?? [],
+    };
+  }
+  return {
+    id: message.id!,
+    role: message.role,
+    content: message.type === 'reasoning' ? [{ type: 'reasoning', text: message.text }] : [{ type: 'text', text: message.text }],
+  };
+}
+
+export { parseMessages, convertMessage, removeEmptyMessages };

package/src/protocol/base.ts

@@ -0,0 +1,55 @@
+import { Message, MessageListenerCallback, PersonaMessage, PersonaProtocol, ProtocolStatus, Session, StatusChangeCallback } from '../types';
+
+abstract class PersonaProtocolBase implements PersonaProtocol {
+  abstract status: ProtocolStatus;
+  abstract session: Session;
+  abstract autostart: boolean;
+
+  private statusChangeCallbacks: StatusChangeCallback[] = [];
+  private messageCallbacks: MessageListenerCallback[] = [];
+
+  public addStatusChangeListener(callback: StatusChangeCallback) {
+    this.statusChangeCallbacks.push(callback);
+  }
+
+  public addMessageListener(callback: MessageListenerCallback) {
+    this.messageCallbacks.push(callback);
+  }
+  public async syncSession(session: Session): Promise<void> {
+    this.session = session;
+  }
+
+  public async notifyMessage(message: PersonaMessage): Promise<void> {
+    this.messageCallbacks.forEach((callback) => callback(message));
+  }
+  public async notifyMessages(messages: PersonaMessage[]): Promise<void> {
+    messages.forEach((message) => {
+      this.messageCallbacks.forEach((callback) => callback(message));
+    });
+  }
+
+  public async setSession(session: Session): Promise<void> {
+    this.session = session;
+  }
+  public async setStatus(status: ProtocolStatus): Promise<void> {
+    const notify = this.status !== status;
+    this.status = status;
+    if (!notify) {
+      return;
+    }
+    this.statusChangeCallbacks.forEach((callback) => callback(status));
+  }
+
+  public clearListeners(): void {
+    this.statusChangeCallbacks = [];
+    this.messageCallbacks = [];
+  }
+
+  abstract getName(): string;
+  abstract getPriority(): number;
+  abstract connect(session?: Session): Promise<Session>;
+  abstract disconnect(): Promise<void>;
+  abstract send(message: Message): Promise<void>;
+}
+
+export { PersonaProtocolBase };

package/src/protocol/index.ts

@@ -0,0 +1,4 @@
+export * from './rest';
+export * from './base';
+export * from './websocket';
+export * from './webrtc';

package/src/protocol/rest.ts

@@ -0,0 +1,64 @@
+import { PersonaProtocolBase } from './base';
+import { Message, PersonaResponse, Session, ProtocolStatus, PersonaProtocolBaseConfig } from '../types';
+
+type PersonaRESTProtocolConfig = PersonaProtocolBaseConfig & {
+  apiUrl: string;
+};
+
+class PersonaRESTProtocol extends PersonaProtocolBase {
+  status: ProtocolStatus;
+  autostart: boolean;
+  session: Session;
+  config: PersonaRESTProtocolConfig;
+  notify: boolean = true;
+
+  constructor(config: PersonaRESTProtocolConfig) {
+    super();
+    this.config = config;
+    this.status = 'disconnected';
+    this.autostart = true;
+  }
+
+  public getName(): string {
+    return 'rest';
+  }
+
+  public getPriority(): number {
+    return 0;
+  }
+
+  public async connect(session: Session): Promise<Session> {
+    this.setStatus('connected');
+    return session;
+  }
+
+  public async disconnect(): Promise<void> {
+    this.setStatus('disconnected');
+    this.session = null;
+  }
+
+  public async syncSession(session: Session): Promise<void> {
+    this.session = session;
+  }
+
+  public async send(message: Message): Promise<void> {
+    const { apiUrl, apiKey, agentId } = this.config;
+    const sessionId = this.session ?? 'new';
+    const input = message;
+
+    const response = await fetch(`${apiUrl}/agents/${agentId}/sessions/${sessionId}/messages`, {
+      body: JSON.stringify({ userMessage: input }),
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-fox-apikey': apiKey,
+        'x-persona-apikey': apiKey,
+      },
+    });
+    const personaResponse = (await response.json()) as PersonaResponse;
+    this.notifyMessages(personaResponse.response.messages);
+  }
+}
+
+export { PersonaRESTProtocol };
+export type { PersonaRESTProtocolConfig };

package/src/protocol/webrtc.ts

@@ -0,0 +1,337 @@
+import { PersonaProtocolBase } from './base';
+import { Message, PersonaMessage, PersonaProtocolBaseConfig, ProtocolStatus, Session } from '../types';
+
+type AudioAnalysisData = {
+  localAmplitude: number;
+  remoteAmplitude: number;
+};
+
+type AudioVisualizerCallback = (data: AudioAnalysisData) => void;
+
+type PersonaWebRTCMessageCallback = (data: MessageEvent) => void;
+
+type PersonaWebRTCConfig = PersonaProtocolBaseConfig & {
+  webrtcUrl: string;
+  iceServers?: RTCIceServer[];
+};
+
+class PersonaWebRTCClient {
+  private config: PersonaWebRTCConfig;
+  private pc: RTCPeerConnection | null = null;
+  private ws: WebSocket | null = null;
+  private localStream: MediaStream | null = null;
+  private remoteStream: MediaStream = new MediaStream();
+  private audioCtx: AudioContext | null = null;
+
+  private localAnalyser: AnalyserNode | null = null;
+  private remoteAnalyser: AnalyserNode | null = null;
+  private analyzerFrame: number | null = null;
+  private dataChannel: RTCDataChannel | null = null;
+
+  private isConnected: boolean = false;
+  private visualizerCallbacks: AudioVisualizerCallback[] = [];
+  private messageCallbacks: PersonaWebRTCMessageCallback[] = [];
+
+  constructor(config: PersonaWebRTCConfig) {
+    this.config = config;
+  }
+
+  public async connect(session: Session): Promise<Session> {
+    if (this.isConnected) return;
+
+    this.isConnected = true;
+
+    try {
+      this.localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    } catch (err) {
+      this.config.logger?.error('Error accessing microphone:', err);
+      return;
+    }
+
+    this.pc = new RTCPeerConnection({
+      iceServers: this.config.iceServers || [
+        {
+          urls: 'stun:34.38.108.251:3478',
+        },
+        {
+          urls: 'turn:34.38.108.251:3478',
+          username: 'webrtc',
+          credential: 'webrtc',
+        },
+      ],
+    });
+
+    this.localStream.getTracks().forEach((track) => {
+      this.pc!.addTrack(track, this.localStream!);
+    });
+
+    this.pc.ontrack = (event) => {
+      event.streams[0].getTracks().forEach((track) => {
+        this.remoteStream.addTrack(track);
+      });
+
+      if (!this.audioCtx) {
+        this._startAnalyzers();
+      }
+
+      const remoteAudio = new Audio();
+      remoteAudio.srcObject = this.remoteStream;
+      remoteAudio.play().catch((e) => {
+        this.config.logger?.error('Error playing remote audio:', e);
+      });
+    };
+
+    this.pc.onicecandidate = (event) => {
+      if (event.candidate && this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(
+          JSON.stringify({
+            type: 'CANDIDATE',
+            src: 'client',
+            payload: { candidate: event.candidate },
+          }),
+        );
+      }
+    };
+
+    this.pc.ondatachannel = (event) => {
+      const channel = event.channel;
+      channel.onmessage = (msg) => {
+        this.messageCallbacks.forEach((callback) => {
+          callback(msg);
+        });
+      };
+    };
+
+    this.ws = new WebSocket(this.config.webrtcUrl || 'wss://persona.applica.guru/api/webrtc');
+    this.ws.onopen = async () => {
+      const offer = await this.pc!.createOffer();
+      await this.pc!.setLocalDescription(offer);
+
+      const metadata = {
+        agentId: this.config.agentId,
+        sessionCode: session as string,
+      };
+      this.config.logger?.debug('Opening connection to WebRTC server: ', metadata);
+
+      const offerMessage = {
+        type: 'OFFER',
+        src: crypto.randomUUID?.() || 'client_' + Date.now(),
+        payload: {
+          sdp: {
+            sdp: offer.sdp,
+            type: offer.type,
+          },
+          connectionId: (Date.now() % 1000000).toString(),
+          metadata,
+        },
+      };
+
+      this.ws!.send(JSON.stringify(offerMessage));
+    };
+
+    this.ws.onmessage = async (event) => {
+      const data = JSON.parse(event.data);
+      if (data.type === 'ANSWER') {
+        await this.pc!.setRemoteDescription(new RTCSessionDescription(data.payload.sdp));
+      } else if (data.type === 'CANDIDATE') {
+        try {
+          await this.pc!.addIceCandidate(new RTCIceCandidate(data.payload.candidate));
+        } catch (err) {
+          this.config.logger?.error('Error adding ICE candidate:', err);
+        }
+      }
+    };
+
+    this.ws.onclose = () => {
+      this._stopAnalyzers();
+    };
+  }
+
+  public async disconnect(): Promise<void> {
+    if (!this.isConnected) return;
+
+    this.isConnected = false;
+
+    if (this.ws?.readyState === WebSocket.OPEN) this.ws.close();
+    if (this.pc) this.pc.close();
+    if (this.localStream) {
+      this.localStream.getTracks().forEach((track) => track.stop());
+    }
+
+    this.remoteStream = new MediaStream();
+    if (this.audioCtx) {
+      await this.audioCtx.close();
+      this.audioCtx = null;
+    }
+
+    this._stopAnalyzers();
+  }
+
+  public addVisualizerCallback(callback: AudioVisualizerCallback): void {
+    this.visualizerCallbacks.push(callback);
+  }
+  public addMessageCallback(callback: PersonaWebRTCMessageCallback): void {
+    this.messageCallbacks.push(callback);
+  }
+
+  public createDataChannel(label = 'messages'): void {
+    if (!this.pc) return;
+    this.dataChannel = this.pc.createDataChannel(label);
+    this.dataChannel.onopen = () => this.config.logger?.info('Data channel opened');
+    this.dataChannel.onmessage = (msg: MessageEvent) => {
+      this.messageCallbacks.forEach((callback) => {
+        callback(msg);
+      });
+    };
+  }
+
+  public sendMessage(message: string): void {
+    if (!this.dataChannel) {
+      this.config.logger?.warn('Data channel is not open, cannot send message');
+      return;
+    }
+
+    this.dataChannel.send(message);
+    this.config.logger?.info('Sent message:', message);
+  }
+
+  private _startAnalyzers(): void {
+    if (!this.localStream || !this.remoteStream || this.visualizerCallbacks.length === 0) {
+      return;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.audioCtx = new (window.AudioContext || (window as any).webkitAudioContext)();
+
+    const localSource = this.audioCtx.createMediaStreamSource(this.localStream);
+    const remoteSource = this.audioCtx.createMediaStreamSource(this.remoteStream);
+
+    this.localAnalyser = this.audioCtx.createAnalyser();
+    this.remoteAnalyser = this.audioCtx.createAnalyser();
+    this.localAnalyser.fftSize = 256;
+    this.remoteAnalyser.fftSize = 256;
+
+    localSource.connect(this.localAnalyser);
+    remoteSource.connect(this.remoteAnalyser);
+
+    const loop = () => {
+      if (!this.localAnalyser || !this.remoteAnalyser || this.visualizerCallbacks.length === 0) {
+        return;
+      }
+
+      const localArray = new Uint8Array(this.localAnalyser.frequencyBinCount);
+      const remoteArray = new Uint8Array(this.remoteAnalyser.frequencyBinCount);
+
+      this.localAnalyser.getByteFrequencyData(localArray);
+      this.remoteAnalyser.getByteFrequencyData(remoteArray);
+
+      const localAmp = localArray.reduce((a, b) => a + b, 0) / localArray.length;
+      const remoteAmp = remoteArray.reduce((a, b) => a + b, 0) / remoteArray.length;
+
+      if (this.visualizerCallbacks.length > 0) {
+        this.visualizerCallbacks.forEach((callback) => {
+          callback({
+            localAmplitude: localAmp,
+            remoteAmplitude: remoteAmp,
+          });
+        });
+      }
+
+      this.analyzerFrame = requestAnimationFrame(loop);
+    };
+
+    this.analyzerFrame = requestAnimationFrame(loop);
+  }
+
+  private _stopAnalyzers(): void {
+    if (this.analyzerFrame) {
+      cancelAnimationFrame(this.analyzerFrame);
+      this.analyzerFrame = null;
+    }
+    this.localAnalyser = null;
+    this.remoteAnalyser = null;
+  }
+}
+
+type PersonaWebRTCProtocolConfig = PersonaWebRTCConfig & {
+  autostart?: boolean;
+};
+
+class PersonaWebRTCProtocol extends PersonaProtocolBase {
+  status: ProtocolStatus;
+  session: Session;
+  autostart: boolean;
+  config: PersonaWebRTCProtocolConfig;
+  webRTCClient: PersonaWebRTCClient;
+
+  constructor(config: PersonaWebRTCProtocolConfig) {
+    super();
+    this.config = config;
+    this.status = 'disconnected';
+    this.session = null;
+    this.autostart = config?.autostart ?? false;
+    this.webRTCClient = new PersonaWebRTCClient(config);
+    this.webRTCClient.addMessageCallback((msg: MessageEvent) => {
+      config.logger?.debug('Received data message:', msg.data);
+      const data = JSON.parse(msg.data) as { type: 'message' | unknown; payload: PersonaMessage | unknown };
+      if (data.type === 'message') {
+        this.notifyMessage(data.payload as PersonaMessage);
+      }
+    });
+  }
+
+  public getName(): string {
+    return 'webrtc';
+  }
+  public getPriority(): number {
+    return 10;
+  }
+
+  public async syncSession(session: Session): Promise<void> {
+    super.syncSession(session);
+    if (this.status === 'connected') {
+      await this.disconnect();
+      await this.connect(session);
+    }
+  }
+
+  public async connect(session?: Session): Promise<Session> {
+    if (this.status === 'connected') {
+      return Promise.resolve(this.session);
+    }
+    this.session = session || this.session || 'new';
+    this.setStatus('connecting');
+
+    this.config.logger?.debug('Connecting to WebRTC with sessionId:', this.session);
+    await this.webRTCClient.connect(this.session);
+    this.setStatus('connected');
+
+    await this.webRTCClient.createDataChannel();
+
+    return this.session;
+  }
+
+  public async disconnect(): Promise<void> {
+    if (this.status === 'disconnected') {
+      this.config.logger?.warn('Already disconnected');
+      return Promise.resolve();
+    }
+
+    await this.webRTCClient.disconnect();
+
+    this.setStatus('disconnected');
+    this.config?.logger?.debug('Disconnected from WebRTC');
+  }
+
+  public send(message: Message): Promise<void> {
+    if (this.status !== 'connected') {
+      return Promise.reject(new Error('Not connected'));
+    }
+
+    this.webRTCClient.sendMessage(message as string);
+    return Promise.resolve();
+  }
+}
+
+export { PersonaWebRTCProtocol };
+export type { PersonaWebRTCProtocolConfig, AudioVisualizerCallback, AudioAnalysisData };

package/src/protocol/websocket.ts

@@ -0,0 +1,106 @@
+import { Message, PersonaMessage, PersonaProtocolBaseConfig, ProtocolStatus, Session } from '../types';
+import { PersonaProtocolBase } from './base';
+
+type PersonaWebSocketProtocolConfig = PersonaProtocolBaseConfig & {
+  webSocketUrl: string;
+};
+
+class PersonaWebSocketProtocol extends PersonaProtocolBase {
+  status: ProtocolStatus;
+  autostart: boolean;
+  session: Session;
+  config: PersonaWebSocketProtocolConfig;
+  webSocket: WebSocket | null;
+
+  constructor(config: PersonaWebSocketProtocolConfig) {
+    super();
+    this.config = config;
+    this.status = 'disconnected';
+    this.autostart = true;
+    this.session = null;
+    this.webSocket = null;
+  }
+
+  public getName(): string {
+    return 'websocket';
+  }
+
+  public getPriority(): number {
+    return 1;
+  }
+
+  public async syncSession(session: Session): Promise<void> {
+    this.config.logger?.debug('Syncing session with WebSocket protocol:', session);
+    this.session = session;
+    if (this.webSocket && this.status === 'connected') {
+      this.disconnect();
+      this.connect(session);
+    }
+  }
+
+  public connect(session?: Session): Promise<Session> {
+    if (this.webSocket !== null && this.status === 'connected') {
+      return Promise.resolve(this.session);
+    }
+
+    const sid = session || this.session || 'new';
+
+    this.config.logger?.debug('Connecting to WebSocket with sessionId:', sid);
+
+    const apiKey = encodeURIComponent(this.config.apiKey);
+    const agentId = this.config.agentId;
+    const webSocketUrl = `${this.config.webSocketUrl}?sessionCode=${sid}&agentId=${agentId}&apiKey=${apiKey}`;
+    this.setStatus('connecting');
+    this.webSocket = new WebSocket(webSocketUrl);
+    this.webSocket.addEventListener('open', () => {
+      this.setStatus('connected');
+    });
+    this.webSocket.addEventListener('message', (event) => {
+      const data = JSON.parse(event.data) as { type: 'message' | unknown; payload: PersonaMessage | unknown };
+
+      if (data.type !== 'message') {
+        return;
+      }
+      const message = data.payload as PersonaMessage & { thought?: string };
+
+      this.notifyMessage(message?.thought ? { role: 'assistant', type: 'reasoning', text: message.thought } : message);
+    });
+    this.webSocket.addEventListener('close', () => {
+      this.setStatus('disconnected');
+      this.webSocket = null;
+      this.config.logger?.warn('WebSocket connection closed');
+    });
+
+    this.webSocket.addEventListener('error', (error) => {
+      this.setStatus('disconnected');
+      this.webSocket = null;
+      this.config.logger?.error('WebSocket error', error);
+
+      // TODO: Implement reconnection logic
+    });
+
+    return Promise.resolve(sid);
+  }
+
+  public disconnect(): Promise<void> {
+    this.config.logger?.debug('Disconnecting WebSocket');
+    if (this.webSocket && this.status === 'connected') {
+      this.webSocket.close();
+      this.setStatus('disconnected');
+      this.webSocket = null;
+    }
+    return Promise.resolve();
+  }
+
+  public send(message: Message): Promise<void> {
+    if (this.webSocket && this.status === 'connected') {
+      this.webSocket.send(JSON.stringify({ type: 'request', payload: message }));
+      return Promise.resolve();
+    } else {
+      return Promise.reject(new Error('WebSocket is not connected'));
+    }
+  }
+}
+
+export { PersonaWebSocketProtocol };
+export type { PersonaWebSocketProtocolConfig };