@docyrus/ui-pro-ai-assistant

A full-featured, drop-in AI assistant chat UI for React. Ships with multi-turn conversations, a work canvas, project management, multi-model and multi-agent support, voice input, file uploads, deep research, and built-in i18n for 9 languages.

Highlights

• Plug-and-play chat interface — Modal or inline rendering with a single component.
• Work canvas — AI-generated outputs (text, code, spreadsheets, images, charts, documents) are rendered in type-specific viewers side-by-side with the conversation.
• Projects & sessions — Organize conversations into projects, manage threads, and persist context.
• Multi-model & multi-agent — Let users switch between AI models and agent deployments on the fly.
• Deep research — Extended research mode with live progress streaming.
• AI memories — Persistent memory management across sessions.
• Voice input — Browser-native speech-to-text.
• File uploads — Attach files to messages with configurable format restrictions.
• i18n — English, German, Spanish, French, Italian, Portuguese, Greek, Slovenian, Turkish.
• Vite plugin — Optional dev-server middleware for Plate editor AI commands.

Installation

npm install @docyrus/ui-pro-ai-assistant

Peer dependencies

npm install @docyrus/api-client @docyrus/ui-pro-shared react react-dom

| Peer | Version | |------|---------| | @docyrus/api-client | >= 0.1.0 | | @docyrus/ui-pro-shared | >= 0.0.1 | | react | ^19 | | react-dom | ^19 | | vite | >= 5.0.0 (optional) |

Quick start

import "@docyrus/ui-pro-ai-assistant/styles.css";

import { useCallback, useMemo } from "react";
import { useDocyrusAuth } from "@docyrus/signin";
import { AssistantProvider, DocyAssistant } from "@docyrus/ui-pro-ai-assistant";

function App() {
  const { client, status } = useDocyrusAuth();

  const getAuthToken = useCallback(async () => {
    const token = await client?.getAccessToken();
    if (!token) throw new Error("No access token available");
    return token;
  }, [client]);

  const config = useMemo(() => ({
    apiBaseUrl: "https://api.docyrus.com/v1",
    getAuthToken,
  }), [getAuthToken]);

  if (status !== "authenticated" || !client) {
    return <p>Authenticating...</p>;
  }

  return (
    <AssistantProvider config={config}>
      <DocyAssistant
        tenantAiAgentId="your-agent-id"
        renderMode="inline"
        enableSidebar
        enableNavDropdown
        className="h-full w-full"
      />
    </AssistantProvider>
  );
}

Modal mode

function ModalExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Assistant</button>
      <AssistantProvider config={config}>
        <DocyAssistant
          tenantAiAgentId="your-agent-id"
          renderMode="modal"
          isOpen={open}
          onClose={() => setOpen(false)}
        />
      </AssistantProvider>
    </>
  );
}

Exports

| Entry point | Import path | Description | |-------------|-------------|-------------| | Main | @docyrus/ui-pro-ai-assistant | Components, provider, hooks, and types | | Vite plugin | @docyrus/ui-pro-ai-assistant/vite | Dev-server middleware for Plate AI | | Web worker | @docyrus/ui-pro-ai-assistant/worker | Worker entry for AI command handlers | | Stylesheet | @docyrus/ui-pro-ai-assistant/styles.css | Required CSS — import once at app root |

Exported symbols

// Components
import { DocyAssistant } from "@docyrus/ui-pro-ai-assistant";

// Provider & config
import {
  AssistantProvider,
  useAssistantConfig,
} from "@docyrus/ui-pro-ai-assistant";

// i18n
import {
  AssistantI18nProvider,
  useAssistantTranslation,
} from "@docyrus/ui-pro-ai-assistant";

// Types
import type {
  AssistantConfig,
  AssistantUser,
  Project,
  Work,
  WorkTypes,
} from "@docyrus/ui-pro-ai-assistant";

// Vite plugin (separate entry)
import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";

API reference

<AssistantProvider>

Wraps your component tree to provide API configuration context. Must be an ancestor of <DocyAssistant>.

<AssistantProvider config={config}>
  {children}
</AssistantProvider>

AssistantConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | apiBaseUrl | string | Yes | Base API URL, e.g. "https://api.docyrus.com/v1" | | getAuthToken | () => Promise<string> | Yes | Async callback returning a valid Bearer token | | user | AssistantUser \| null | No | Current user info for display | | getDataSourceSchema | (id: string) => Promise<DataSourceSchema \| null> | No | Resolver for data source schemas |

AssistantUser

interface AssistantUser {
  id: string;
  email?: string;
  firstname?: string;
  lastname?: string;
  photo?: string;
}

<DocyAssistant>

The main chat interface component.

Core

| Prop | Type | Default | Description | |------|------|---------|-------------| | tenantAiAgentId | string | — | Required. ID of the tenant AI agent | | renderMode | "modal" \| "inline" | "modal" | Render as overlay dialog or embedded inline | | isOpen | boolean | — | Modal visibility (modal mode only) | | onClose | () => void | — | Called when the modal closes | | className | string | — | CSS class on the root element |

Appearance

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | — | Header title | | description | string | — | Subtitle below the title | | placeholder | string | — | Chat input placeholder | | logo | string | — | Logo image URL | | footerText | string | — | Footer text | | theme | "auto" \| "light" \| "dark" | "auto" | Color theme | | variant | "default" \| "docked" \| "expanded" | "default" | Layout variant | | size | "default" \| "large" | "default" | Component size |

Layout

| Prop | Type | Default | Description | |------|------|---------|-------------| | enableSidebar | boolean | true | Show the session list sidebar | | enableNavDropdown | boolean | false | Show navigation dropdown | | defaultFullscreen | boolean | false | Start in fullscreen | | hideExpand | boolean | false | Hide the fullscreen toggle | | hideCloseButton | boolean | false | Hide the close (X) button in the header | | hideAgentSelector | boolean | false | Hide the agent selector dropdown; shows agent name as static text instead | | maxMessages | number | — | Max messages to keep in context |

Features

| Prop | Type | Default | Description | |------|------|---------|-------------| | supportWebSearch | boolean | true | Web search | | supportThinking | boolean | true | Thinking / reasoning mode | | supportFiles | boolean | true | File uploads | | supportDocumentSearch | boolean | true | Document search | | supportDeepResearch | boolean | true | Deep research mode | | supportMultiModels | boolean | true | Model selector | | supportWorkCanvas | boolean | true | Work canvas panel | | supportedFileFormats | string[] | — | Allowed upload MIME types / extensions | | enableVoice | boolean | false | Voice input mode | | enableMicrophone | boolean | true | Microphone button |

Agent selection

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentSelectorUrl | string | "/ai/agent-deployments" | Deployment selector endpoint | | baseAgentSelectorUrl | string | "/ai/agent-deployments/base" | Base agent selector endpoint | | onAgentChange | (agentId: string, agentType: "base" \| "deployment") => void | — | Fires when the active agent changes |

API

| Prop | Type | Default | Description | |------|------|---------|-------------| | apiEndpoint | string | "/ai/agents/:agentId/chat" | Chat endpoint template (:agentId is replaced at runtime) |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onMessageSend | (message: string) => void | Fires when a message is sent | | onVoiceStart | () => void | Fires when voice recording starts | | onVoiceEnd | () => void | Fires when voice recording ends |

useAssistantConfig()

Returns the AssistantConfig from the nearest AssistantProvider. Throws if used outside the provider.

const { apiBaseUrl, getAuthToken } = useAssistantConfig();

useAssistantTranslation()

Returns the t function for translating assistant UI strings.

const { t } = useAssistantTranslation();
// t("common.untitled") → "Untitled"

plateEditorPlugin()

Vite plugin that adds dev-server middleware for Plate editor AI commands (/api/ai/command and /api/ai/copilot). Only needed if you use the Plate rich-text editor AI features.

// vite.config.ts
import { defineConfig } from "vite";
import { plateEditorPlugin } from "@docyrus/ui-pro-ai-assistant/vite";

export default defineConfig({
  plugins: [plateEditorPlugin()],
});

Work canvas types

AI-generated outputs open in a side canvas with type-specific viewers:

| WorkTypes value | Viewer | Description | |-------------------|--------|-------------| | Text | Plate.js rich editor | Editable rich text | | Code | Sandpack | Live code preview | | Data / Xlsx | Univer spreadsheet | Full spreadsheet with formulas | | Image | Image viewer | Generated images | | Chart | VChart | Interactive charts | | Html / HtmlTemplate | HTML iframe | Rendered HTML | | Docyment / Docx / Pptx | Document viewer | Office document preview | | App | App renderer | Custom applications | | Record | Record view | Structured data display | | DataSource | Data explorer | Data source output | | CustomQuerySql / CustomQueryJson | Query result | Query output display |

Internationalization

9 built-in locales: en, de, es, fr, it, pt, el, sl, tr.

The language is auto-detected. To override, wrap with AssistantI18nProvider:

import { AssistantI18nProvider } from "@docyrus/ui-pro-ai-assistant";

<AssistantI18nProvider locale="de">
  <DocyAssistant ... />
</AssistantI18nProvider>

Types

Project

interface Project {
  id: string;
  name: string;
  tenant_ai_agent_id: string;
  description?: string;
  instructions?: string;
  tenant_ai_agent_deployment_id?: string;
  color?: string;
  icon?: string;
  shared_to?: string[];
  created_by?: string;
}

Work

interface Work {
  id: string;
  title: string;
  type?: WorkTypes;
  content_json?: unknown;
  content_text?: string;
  description?: string;
  image_url?: string;
  core_ai_model_id?: string | null;
  base_message_id?: string;
  base_thread_id?: string;
  tenant_ai_agent_id?: string;
  tenant_ai_agent_deployment_id?: string;
  tenant_data_source_id?: string;
  tenant_ai_project_id?: string;
  shared_to?: string[];
  created_by?: string;
  created_on?: Date;
  last_modified_on?: Date;
}

WorkTypes

const WorkTypes = {
  Record: "record",
  Data: "data",
  Text: "text",
  Code: "code",
  Image: "image",
  Xlsx: "xlsx",
  Docx: "docx",
  Pptx: "pptx",
  Html: "html",
  Docyment: "docyment",
  Chart: "chart",
  DataSource: "data_source",
  HtmlTemplate: "html_template",
  CustomQuerySql: "custom_query_sql",
  CustomQueryJson: "custom_query_json",
  App: "app",
} as const;

Environment variables

When using with Vite, set these in your .env:

VITE_DOCYRUS_API_URL=https://api.docyrus.com
VITE_DOCYRUS_CLIENT_ID=your-client-id
VITE_DOCYRUS_AGENT_ID=your-agent-id

# Optional — for Plate editor AI plugin
VITE_DOCYRUS_EDITOR_AGENT_ID=your-editor-agent-id

Requirements

• React 19+
• ESM only ("type": "module")
• Tailwind CSS v4 (the stylesheet uses Tailwind utilities)

License

MIT