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

package/src/runtime.tsx

@@ -0,0 +1,214 @@
+import { useState, useEffect, useCallback, PropsWithChildren, createContext, useContext, useMemo, useRef } from 'react';
+import { useExternalStoreRuntime, AppendMessage, AssistantRuntimeProvider } from '@assistant-ui/react';
+import {
+  PersonaConfig,
+  PersonaMessage,
+  PersonaProtocol,
+  PersonaProtocolBaseConfig,
+  PersonaResponse,
+  ProtocolStatus,
+  Session,
+} from './types';
+import { parseMessages, convertMessage } from './messages';
+import {
+  PersonaRESTProtocol,
+  PersonaRESTProtocolConfig,
+  PersonaWebRTCProtocol,
+  PersonaWebRTCProtocolConfig,
+  PersonaWebSocketProtocol,
+  PersonaWebSocketProtocolConfig,
+} from './protocol';
+
+type PersonaRuntimeContextType = {
+  protocols: PersonaProtocol[];
+  protocolsStatus: Map<string, ProtocolStatus>;
+};
+
+const PersonaRuntimeContext = createContext<PersonaRuntimeContextType | undefined>(undefined);
+
+function PersonaRuntimeProviderInner({
+  dev = false,
+  protocols: _protocols,
+  logger,
+  children,
+  session: defaultSession = 'new',
+  ...config
+}: Readonly<PersonaConfig>) {
+  const [isRunning, setIsRunning] = useState(false);
+  const [messages, setMessages] = useState<PersonaMessage[]>([]);
+  const [session, setSession] = useState<Session>(defaultSession);
+  const [protocolsStatus, setProtocolsStatus] = useState<Map<string, ProtocolStatus>>(new Map());
+  const didMount = useRef(false);
+
+  const protocols = useMemo<PersonaProtocol[]>(() => {
+    if (Array.isArray(_protocols)) {
+      return _protocols;
+    }
+
+    if (typeof _protocols === 'object' && _protocols !== null) {
+      const baseEndpoint = dev ? 'localhost:8000' : 'persona.applica.guru/api';
+      const baseEndpointProtocol = dev ? 'http' : 'https';
+      const baseWebSocketProtocol = dev ? 'ws' : 'wss';
+      const availableProtocols = Object.keys(_protocols).map((key) => {
+        switch (key) {
+          case 'rest':
+            const restConfig: PersonaProtocolBaseConfig | true | undefined = _protocols[key];
+            if (restConfig === true) {
+              return new PersonaRESTProtocol({
+                apiUrl: `${baseEndpointProtocol}://${baseEndpoint}`,
+                apiKey: config.apiKey,
+                agentId: config.agentId,
+                logger,
+              });
+            }
+            return new PersonaRESTProtocol(restConfig as PersonaRESTProtocolConfig);
+          case 'webrtc':
+            const webrtcConfig: PersonaProtocolBaseConfig | true | undefined = _protocols[key];
+            if (webrtcConfig === true) {
+              return new PersonaWebRTCProtocol({
+                webrtcUrl: `${baseWebSocketProtocol}://${baseEndpoint}/webrtc`,
+                apiKey: config.apiKey,
+                agentId: config.agentId,
+                logger,
+              });
+            }
+            return new PersonaWebRTCProtocol(webrtcConfig as PersonaWebRTCProtocolConfig);
+          case 'websocket':
+            const websocketConfig: PersonaProtocolBaseConfig | true | undefined = _protocols[key];
+            if (websocketConfig === true) {
+              return new PersonaWebSocketProtocol({
+                webSocketUrl: `${baseWebSocketProtocol}://${baseEndpoint}/websocket`,
+                apiKey: config.apiKey,
+                agentId: config.agentId,
+                logger,
+              });
+            }
+            return new PersonaWebSocketProtocol(websocketConfig as PersonaWebSocketProtocolConfig);
+          default:
+            throw new Error(`Unknown protocol: ${key}`);
+        }
+      });
+      return availableProtocols;
+    }
+    throw new Error('Invalid protocols configuration');
+  }, []);
+
+  useEffect(() => {
+    if (didMount.current) return;
+
+    didMount.current = true;
+    logger?.debug(
+      'Initializing protocols: ',
+      protocols.map((protocol) => protocol.getName()),
+    );
+    protocols.forEach((protocol) => {
+      protocol.setSession(session);
+      protocol.clearListeners();
+      protocol.addStatusChangeListener((status: ProtocolStatus) => {
+        logger?.debug(`${protocol.getName()} has notified new status: ${status}`);
+        protocolsStatus.set(protocol.getName(), status);
+        setProtocolsStatus(new Map(protocolsStatus));
+      });
+      protocol.addMessageListener((message: PersonaMessage) => {
+        setMessages((currentConversation) => parseMessages([...currentConversation, ...[{ ...message, protocol: protocol.getName() }]]));
+      });
+      if (protocol.autostart && protocol.status === 'disconnected') {
+        logger?.debug(`Connecting to protocol: ${protocol.getName()}`);
+        protocol.connect(session);
+      }
+    });
+  }, [session, protocols, logger, protocolsStatus]);
+
+  const onNew = async (message: AppendMessage) => {
+    if (message.content[0]?.type !== 'text') throw new Error('Only text messages are supported');
+
+    const input = message.content[0].text;
+    setMessages((currentConversation) => [...currentConversation, { role: 'user', type: 'text', text: input }]);
+    setIsRunning(true);
+
+    const protocol = protocols.sort((a, b) => b.getPriority() - a.getPriority()).find((protocol) => protocol.status === 'connected');
+
+    await protocol?.send(input);
+
+    setIsRunning(false);
+  };
+
+  const onCancel = useCallback(() => {
+    setIsRunning(false);
+    setMessages([]);
+    setSession('new');
+    return Promise.resolve();
+  }, []);
+
+  const onReload = useCallback(() => {
+    return Promise.resolve();
+  }, []);
+
+  const runtime = useExternalStoreRuntime({
+    isRunning,
+    messages,
+    convertMessage,
+    onNew,
+    onCancel,
+    onReload,
+  });
+
+  return (
+    <PersonaRuntimeContext.Provider value={{ protocols, protocolsStatus }}>
+      <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>
+    </PersonaRuntimeContext.Provider>
+  );
+}
+
+function PersonaRuntimeProvider({ children, ...config }: PropsWithChildren<PersonaConfig>) {
+  return <PersonaRuntimeProviderInner {...config}>{children}</PersonaRuntimeProviderInner>;
+}
+
+function usePersonaRuntime(): PersonaRuntimeContextType {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntime must be used within a PersonaRuntimeProvider');
+  }
+  return context;
+}
+
+/**
+ * Retrieves a specific protocol instance from the PersonaRuntimeContext.
+ *
+ * @param protocol - The name of the protocol to use.
+ * @returns {PersonaProtocol | null} - The protocol instance or null if not found.
+ * @throws {Error} - If the hook is used outside of a PersonaRuntimeProvider.
+ */
+function usePersonaRuntimeProtocol(protocol: string): PersonaProtocol | null {
+  const context = useContext(PersonaRuntimeContext);
+  if (!context) {
+    throw new Error('usePersonaRuntimeProtocol must be used within a PersonaRuntimeProvider');
+  }
+
+  const protocolInstance = context.protocols.find((p) => p.getName() === protocol);
+  if (!protocolInstance) {
+    return null;
+  }
+
+  const status = context.protocolsStatus.get(protocolInstance.getName());
+
+  return {
+    ...protocolInstance,
+    connect: protocolInstance.connect.bind(protocolInstance),
+    disconnect: protocolInstance.disconnect.bind(protocolInstance),
+    send: protocolInstance.send.bind(protocolInstance),
+    setSession: protocolInstance.setSession.bind(protocolInstance),
+    addStatusChangeListener: protocolInstance.addStatusChangeListener.bind(protocolInstance),
+    addMessageListener: protocolInstance.addMessageListener.bind(protocolInstance),
+    getName: protocolInstance.getName.bind(protocolInstance),
+    getPriority: protocolInstance.getPriority.bind(protocolInstance),
+    status: status || protocolInstance.status,
+  };
+}
+
+function usePersonaRuntimeWebRTCProtocol(): PersonaWebRTCProtocol | null {
+  return usePersonaRuntimeProtocol('webrtc') as PersonaWebRTCProtocol;
+}
+
+export { PersonaRuntimeProvider, usePersonaRuntime, usePersonaRuntimeProtocol, usePersonaRuntimeWebRTCProtocol };
+export type { PersonaMessage, PersonaResponse };

package/src/types.ts

@@ -0,0 +1,98 @@
+import { PersonaLogger } from './logging';
+import { ReactNode } from 'react';
+
+export type ReadonlyJSONObject = {
+  readonly [key: string]: string | number | boolean | null | ReadonlyJSONObject | ReadonlyArray<ReadonlyJSONObject>;
+};
+
+export type FunctionCall = {
+  id?: string;
+  name: string;
+  args: ReadonlyJSONObject;
+};
+
+export type FunctionResponse = {
+  name: string;
+  result: unknown;
+  function_call_id: string;
+};
+
+export type PersonaMessage = {
+  id?: string | null;
+  protocol?: string;
+  text: string;
+  type: 'reasoning' | 'text';
+  role: 'user' | 'assistant' | 'function';
+  sessionId?: string;
+  finishReason?: 'stop' | 'function_call';
+  functionCalls?: FunctionCall[];
+  functionResponse?: FunctionResponse;
+};
+
+export type ModelResponse = {
+  messages: PersonaMessage[];
+};
+
+export type PersonaResponse = {
+  sessionId: string;
+  response: ModelResponse;
+};
+
+export type PersonaBaseConfig = {
+  logger?: PersonaLogger;
+};
+
+export type PersonaWebRTCConfig = PersonaBaseConfig & {
+  webrtcUrl: string;
+  iceServers?: RTCIceServer[];
+  onDataMessage?: (msg: MessageEvent) => void;
+};
+
+export type Session = string | null | undefined;
+export type Message = string;
+
+export type MessageListenerCallback = (message: PersonaMessage) => void;
+export type StatusChangeCallback = (status: ProtocolStatus) => void;
+
+export type ProtocolStatus = 'disconnected' | 'connecting' | 'connected';
+
+export type PersonaProtocolBaseConfig = {
+  logger?: PersonaLogger;
+  apiKey: string;
+  agentId: string;
+};
+
+export interface PersonaProtocol {
+  status: ProtocolStatus;
+  autostart: boolean;
+
+  getName: () => string;
+  getPriority: () => number;
+  connect: (session?: Session) => Promise<Session>;
+  disconnect: () => Promise<void>;
+
+  setSession: (session: Session) => Promise<void>;
+
+  send: (message: Message) => Promise<void>;
+  clearListeners: () => void;
+  addStatusChangeListener: (callback: StatusChangeCallback) => void;
+  addMessageListener: (callback: MessageListenerCallback) => void;
+}
+
+export type PersonaConfig = PersonaBaseConfig &
+  PersonaProtocolBaseConfig & {
+    /**
+     * In 'dev' mode the endpoint is set to localhost:8000,
+     * use it only for development purposes.
+     */
+    dev?: boolean;
+    session?: Session;
+    children: ReactNode;
+    protocols:
+      | PersonaProtocol[]
+      | {
+          rest?: PersonaProtocolBaseConfig | true;
+          webrtc?: PersonaProtocolBaseConfig | true;
+          websocket?: PersonaProtocolBaseConfig | true;
+        };
+  };

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "noEmit": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "outDir": "dist",
+    "paths": {
+      "@/*": ["playground/src/*"],
+      "@applica-software-guru/persona-sdk": ["src/index.ts"]
+    },
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ESNext",
+    "typeRoots": ["node_modules/@types", "src/assets.d.ts", "src/index.d.ts", "src/types.d.ts"],
+    "useDefineForClassFields": true
+  },
+  "include": ["src", "playground/src"],
+  "references": [
+    {
+      "path": "./jsconfig.node.json"
+    }
+  ]
+}

package/tsconfig.node.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "composite": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES6"
+  },
+  "include": ["vite.config.ts", "package.json", "playground/src", "src/**/*"]
+}

package/vite.config.ts

@@ -0,0 +1,69 @@
+import react from '@vitejs/plugin-react';
+import * as packageJson from './package.json';
+import { resolve } from 'path';
+import { ConfigEnv, defineConfig, UserConfig } from 'vite';
+import { default as dts } from 'vite-plugin-dts';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig((configEnv: ConfigEnv) => {
+  const { mode } = configEnv;
+  const isDevelopment = mode === 'development';
+  console.log({
+    mode,
+    isDevelopment,
+    peerDependencies: packageJson.peerDependencies,
+  });
+  const config: UserConfig = {
+    build: {
+      sourcemap: true,
+      lib: {
+        entry: resolve('src', 'index.ts'),
+        name: 'personaSDK',
+        formats: ['es', 'umd', 'cjs', 'iife'],
+        fileName: (format: string) => `bundle.${format}.js`,
+      },
+      rollupOptions: {
+        external: Object.keys(packageJson.peerDependencies || {}),
+        input: resolve(__dirname, 'src', 'index.ts'),
+        output: {
+          globals: {
+            'react-dom': 'ReactDOM',
+            react: 'React',
+          },
+        },
+      },
+    },
+    resolve: {
+      dedupe: Object.keys(packageJson.peerDependencies || {}),
+      alias: {
+        '@applica-software-guru/persona-sdk': resolve(__dirname, 'src'),
+        '@': resolve(__dirname, 'playground/src'),
+        '@/*': resolve(__dirname, 'playground/src/*'),
+        '*': resolve(__dirname, 'src/*'),
+        react: resolve(__dirname, 'node_modules', 'react'),
+        'react-dom': resolve(__dirname, 'node_modules', 'react-dom'),
+        'react/jsx-runtime': resolve(__dirname, 'node_modules', 'react/jsx-runtime'),
+      },
+    },
+    plugins: [
+      dts({
+        include: ['./src/**/*.{js,jsx,ts,tsx}'],
+      }),
+      react(),
+    ],
+    define: {
+      'process.env': {
+        NODE_ENV: 'client',
+      },
+    },
+    optimizeDeps: {
+      include: Object.keys(packageJson.peerDependencies || {}),
+    },
+  };
+  if (isDevelopment) {
+    config.plugins = [react(), tailwindcss()];
+    config.root = resolve(__dirname, 'playground');
+  }
+
+  return config;
+});