@applica-software-guru/persona-sdk 0.1.100 → 0.1.101

package/docs/transactions.md

@@ -1,121 +0,0 @@
-# Transactions and Tools
-
-The Transaction Protocol in the Persona 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-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

@@ -1,40 +0,0 @@
-# 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-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

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

package/playground/index.html

@@ -1,14 +0,0 @@
-<!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

@@ -1,10 +0,0 @@
-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

@@ -1,117 +0,0 @@
-import { Thread } from '@/components/assistant-ui/thread';
-import { PersonaRuntimeProvider, PersonaConsoleLogger, Session } from '@applica-software-guru/persona-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 };

package/playground/src/components/assistant-ui/assistant-modal.tsx

@@ -1,57 +0,0 @@
-'use client';
-
-import { BotIcon, ChevronDownIcon } from 'lucide-react';
-
-import { type FC, forwardRef } from 'react';
-import { AssistantModalPrimitive } from '@assistant-ui/react';
-
-import { Thread } from '@/components/assistant-ui/thread';
-import { TooltipIconButton } from '@/components/assistant-ui/tooltip-icon-button';
-
-export const AssistantModal: FC = () => {
-  return (
-    <AssistantModalPrimitive.Root>
-      <AssistantModalPrimitive.Anchor className="fixed bottom-4 right-4 size-11">
-        <AssistantModalPrimitive.Trigger asChild>
-          <AssistantModalButton />
-        </AssistantModalPrimitive.Trigger>
-      </AssistantModalPrimitive.Anchor>
-      <AssistantModalPrimitive.Content
-        sideOffset={16}
-        className="bg-popover text-popover-foreground z-50 h-[500px] w-[400px] overflow-clip rounded-xl border p-0 shadow-md outline-none [&>.aui-thread-root]:bg-inherit data-[state=closed]:animate-out data-[state=open]:animate-in data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out data-[state=open]:zoom-in data-[state=open]:slide-in-from-bottom-1/2 data-[state=open]:slide-in-from-right-1/2 data-[state=closed]:slide-out-to-bottom-1/2 data-[state=closed]:slide-out-to-right-1/2"
-      >
-        <Thread />
-      </AssistantModalPrimitive.Content>
-    </AssistantModalPrimitive.Root>
-  );
-};
-
-type AssistantModalButtonProps = { 'data-state'?: 'open' | 'closed' };
-
-const AssistantModalButton = forwardRef<HTMLButtonElement, AssistantModalButtonProps>(({ 'data-state': state, ...rest }, ref) => {
-  const tooltip = state === 'open' ? 'Close Assistant' : 'Open Assistant';
-
-  return (
-    <TooltipIconButton
-      variant="default"
-      tooltip={tooltip}
-      side="left"
-      {...rest}
-      className="size-full rounded-full shadow transition-transform hover:scale-110 active:scale-90"
-      ref={ref}
-    >
-      <BotIcon
-        data-state={state}
-        className="absolute size-6 transition-all data-[state=closed]:rotate-0 data-[state=open]:rotate-90 data-[state=closed]:scale-100 data-[state=open]:scale-0"
-      />
-
-      <ChevronDownIcon
-        data-state={state}
-        className="absolute size-6 transition-all data-[state=closed]:-rotate-90 data-[state=open]:rotate-0 data-[state=closed]:scale-0 data-[state=open]:scale-100"
-      />
-      <span className="sr-only">{tooltip}</span>
-    </TooltipIconButton>
-  );
-});
-
-AssistantModalButton.displayName = 'AssistantModalButton';

package/playground/src/components/assistant-ui/attachment.tsx

@@ -1,197 +0,0 @@
-'use client';
-
-import { PropsWithChildren, useEffect, useState, type FC } from 'react';
-import { XIcon, PlusIcon, FileText } from 'lucide-react';
-import { AttachmentPrimitive, ComposerPrimitive, MessagePrimitive, useAssistantState, useAssistantApi } from '@assistant-ui/react';
-import { useShallow } from 'zustand/shallow';
-import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
-import { Dialog, DialogTitle, DialogContent, DialogTrigger } from '@/components/ui/dialog';
-import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar';
-import { TooltipIconButton } from '@/components/assistant-ui/tooltip-icon-button';
-import { cn } from '@/lib/utils';
-
-const useFileSrc = (file: File | undefined) => {
-  const [src, setSrc] = useState<string | undefined>(undefined);
-
-  useEffect(() => {
-    if (!file) {
-      setSrc(undefined);
-      return;
-    }
-
-    const objectUrl = URL.createObjectURL(file);
-    setSrc(objectUrl);
-
-    return () => {
-      URL.revokeObjectURL(objectUrl);
-    };
-  }, [file]);
-
-  return src;
-};
-
-const useAttachmentSrc = () => {
-  const { file, src } = useAssistantState(
-    useShallow(({ attachment }): { file?: File; src?: string } => {
-      if (attachment.type !== 'image') return {};
-      if (attachment.file) return { file: attachment.file };
-      const src = attachment.content?.filter((c) => c.type === 'image')[0]?.image;
-      if (!src) return {};
-      return { src };
-    }),
-  );
-
-  return useFileSrc(file) ?? src;
-};
-
-type AttachmentPreviewProps = {
-  src: string;
-};
-
-const AttachmentPreview: FC<AttachmentPreviewProps> = ({ src }) => {
-  const [isLoaded, setIsLoaded] = useState(false);
-  return (
-    <img
-      src={src}
-      alt="Image Preview"
-      width={1}
-      height={1}
-      className={
-        isLoaded
-          ? 'aui-attachment-preview-image-loaded block h-auto max-h-[80vh] w-auto max-w-full object-contain'
-          : 'aui-attachment-preview-image-loading hidden'
-      }
-      onLoad={() => setIsLoaded(true)}
-    />
-  );
-};
-
-const AttachmentPreviewDialog: FC<PropsWithChildren> = ({ children }) => {
-  const src = useAttachmentSrc();
-
-  if (!src) return children;
-
-  return (
-    <Dialog>
-      <DialogTrigger className="aui-attachment-preview-trigger cursor-pointer transition-colors hover:bg-accent/50" asChild>
-        {children}
-      </DialogTrigger>
-      <DialogContent className="aui-attachment-preview-dialog-content p-2 sm:max-w-3xl [&>button]:rounded-full [&>button]:bg-foreground/60 [&>button]:p-1 [&>button]:opacity-100 [&>button]:ring-0! [&_svg]:text-background [&>button]:hover:[&_svg]:text-destructive">
-        <DialogTitle className="aui-sr-only sr-only">Image Attachment Preview</DialogTitle>
-        <div className="aui-attachment-preview relative mx-auto flex max-h-[80dvh] w-full items-center justify-center overflow-hidden bg-background">
-          <AttachmentPreview src={src} />
-        </div>
-      </DialogContent>
-    </Dialog>
-  );
-};
-
-const AttachmentThumb: FC = () => {
-  const isImage = useAssistantState(({ attachment }) => attachment.type === 'image');
-  const src = useAttachmentSrc();
-
-  return (
-    <Avatar className="aui-attachment-tile-avatar h-full w-full rounded-none">
-      <AvatarImage src={src} alt="Attachment preview" className="aui-attachment-tile-image object-cover" />
-      <AvatarFallback delayMs={isImage ? 200 : 0}>
-        <FileText className="aui-attachment-tile-fallback-icon size-8 text-muted-foreground" />
-      </AvatarFallback>
-    </Avatar>
-  );
-};
-
-const AttachmentUI: FC = () => {
-  const api = useAssistantApi();
-  const isComposer = api.attachment.source === 'composer';
-
-  const isImage = useAssistantState(({ attachment }) => attachment.type === 'image');
-  const typeLabel = useAssistantState(({ attachment }) => {
-    const type = attachment.type;
-    switch (type) {
-      case 'image':
-        return 'Image';
-      case 'document':
-        return 'Document';
-      case 'file':
-        return 'File';
-      default:
-        const _exhaustiveCheck: never = type;
-        throw new Error(`Unknown attachment type: ${_exhaustiveCheck}`);
-    }
-  });
-
-  return (
-    <Tooltip>
-      <AttachmentPrimitive.Root
-        className={cn('aui-attachment-root relative', isImage && 'aui-attachment-root-composer only:[&>#attachment-tile]:size-24')}
-      >
-        <AttachmentPreviewDialog>
-          <TooltipTrigger asChild>
-            <div
-              className={cn(
-                'aui-attachment-tile size-14 cursor-pointer overflow-hidden rounded-[14px] border bg-muted transition-opacity hover:opacity-75',
-                isComposer && 'aui-attachment-tile-composer border-foreground/20',
-              )}
-              role="button"
-              id="attachment-tile"
-              aria-label={`${typeLabel} attachment`}
-            >
-              <AttachmentThumb />
-            </div>
-          </TooltipTrigger>
-        </AttachmentPreviewDialog>
-        {isComposer && <AttachmentRemove />}
-      </AttachmentPrimitive.Root>
-      <TooltipContent side="top">
-        <AttachmentPrimitive.Name />
-      </TooltipContent>
-    </Tooltip>
-  );
-};
-
-const AttachmentRemove: FC = () => {
-  return (
-    <AttachmentPrimitive.Remove asChild>
-      <TooltipIconButton
-        tooltip="Remove file"
-        className="aui-attachment-tile-remove absolute top-1.5 right-1.5 size-3.5 rounded-full bg-white text-muted-foreground opacity-100 shadow-sm hover:bg-white! [&_svg]:text-black hover:[&_svg]:text-destructive"
-        side="top"
-      >
-        <XIcon className="aui-attachment-remove-icon size-3 dark:stroke-[2.5px]" />
-      </TooltipIconButton>
-    </AttachmentPrimitive.Remove>
-  );
-};
-
-export const UserMessageAttachments: FC = () => {
-  return (
-    <div className="aui-user-message-attachments-end col-span-full col-start-1 row-start-1 flex w-full flex-row justify-end gap-2">
-      <MessagePrimitive.Attachments components={{ Attachment: AttachmentUI }} />
-    </div>
-  );
-};
-
-export const ComposerAttachments: FC = () => {
-  return (
-    <div className="aui-composer-attachments mb-2 flex w-full flex-row items-center gap-2 overflow-x-auto px-1.5 pt-0.5 pb-1 empty:hidden">
-      <ComposerPrimitive.Attachments components={{ Attachment: AttachmentUI }} />
-    </div>
-  );
-};
-
-export const ComposerAddAttachment: FC = () => {
-  return (
-    <ComposerPrimitive.AddAttachment asChild>
-      <TooltipIconButton
-        tooltip="Add Attachment"
-        side="bottom"
-        variant="ghost"
-        size="icon"
-        className="aui-composer-add-attachment size-[34px] rounded-full p-1 font-semibold text-xs hover:bg-muted-foreground/15 dark:border-muted-foreground/15 dark:hover:bg-muted-foreground/30"
-        aria-label="Add Attachment"
-      >
-        <PlusIcon className="aui-attachment-add-icon size-5 stroke-[1.5px]" />
-      </TooltipIconButton>
-    </ComposerPrimitive.AddAttachment>
-  );
-};