@docyrus/ui-pro-ai-assistant

@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. Session list shows creation date and author on hover.
• Multi-model & multi-agent — Let users switch between AI models and agent deployments on the fly. Agent avatars display in the header and message list.
• Deep research — Extended research mode with live progress streaming.
• AI memories — Persistent memory management across sessions.
• Edit & resend prompts — Hover any user message to edit it; subsequent assistant replies are archived server-side and the conversation regenerates from that point.
• Voice input — Browser-native speech-to-text.
• File uploads — Attach files to messages with configurable format restrictions.
• Agent trigger widget — Standalone agent carousel with prompt input, per-agent capabilities, model/reasoning selection, and suggestion chips. Decoupled from the chat UI — wire it to any destination.
• Chromeless mode — Optionally hide the header and/or border for seamless embedding.
• 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,
    user: {
      id: "current-user-id",
      firstname: "Ada",
      lastname: "Lovelace",
      email: "[e-mail]",
      photo: "https://example.com/avatar.png",
    },
  }), [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, AgentTriggerWidget } 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,
  AgentTriggerWidgetProps,
  InitialFeatureFlags,
  PromptFeatureFlags,
  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	Yes	Current authenticated user. Used to filter sessions/projects to the active user and to display name and avatar in the chat
getDataSourceSchema	(id: string) => Promise<DataSourceSchema | null>	No	Resolver for data source schemas

AssistantUser

interface AssistantUser {
  id: string;       // required — used for server-side filtering
  email?: string;   // optional — shown as fallback display name
  firstname?: string;
  lastname?: string;
  photo?: string;   // optional — avatar in chat messages
}

Note: user.id must be the authenticated user's UUID as stored in Docyrus. Without it, the session list will not be filtered and all tenant users' threads will be visible.

<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
enableWelcomePage	boolean	true	Show a welcome landing page on first open with agent greeting, inline prompt input, and recent sessions. Sidebar and header are hidden in this view. Dismissed on interaction (new chat, session click, or message send)
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
hideBorder	boolean	false	Hide the outer border and shadow of the assistant container
showHeader	boolean	true	Show the header bar; when false the agent selector moves to the top of the sidebar
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 (also read from agent config supportMultipleModels)
supportWorkCanvas	boolean	true	Work canvas panel
supportedFileFormats	string[]	—	Allowed upload MIME types / extensions
enableVoice	boolean	false	Voice input mode
enableMicrophone	boolean	true	Microphone button
enableSharing	boolean	false	Show share button on thread headers

Note: Feature props serve as defaults. When the agent deployment is loaded, the API response capabilities (supportWebSearch, documentSearch, supportDeepResearch, supportThinking, featureWorks, supportFiles, supportMultipleModels, promptOptimizationChoice) take precedence over prop values.

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)
hostEnvironment	string	—	Host environment identifier sent to the chat endpoint as hostEnvironment. The backend uses this to filter the tool list bound to the agent so only tools available in the current environment are exposed. Common values: "web", "desktop", "chrome", "word", "excel", "powerpoint", "outlook"
appId	string	—	ID of the host app currently open in the page. Forwarded to the chat endpoint as appId so the agent can scope its behavior/tools to it. Renders a dismissable "Talking about " chip above the input; once the user clears it, the id stops being sent
appName	string	—	Display name for the current host app, shown in the context chip
appIcon	string	—	Docyrus icon identifier (e.g. "fas inbox") for the current host app. Rendered via <DocyrusIcon> in the context chip

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
onShare	(info: { dataSourceId: string; recordId: string }) => void	Custom share handler. When provided, the thread header share button calls this instead of the built-in sharing editor

Initial prompt

Prop	Type	Default	Description
initialPrompt	string	—	When provided, the assistant auto-sends this message on mount. Useful when launching the assistant from an agent trigger widget or deep link
initialModelId	string	—	Model ID to pre-select when auto-sending the initial prompt
initialFeatures	InitialFeatureFlags	—	Feature flags to enable when auto-sending the initial prompt
initialFiles	File[]	—	Files to attach when auto-sending the initial prompt

<AgentTriggerWidget>

A standalone agent discovery and prompt input component. Displays agents in a carousel with per-agent capabilities, model selection, reasoning levels, and suggestion chips. Fully decoupled from DocyAssistant — the consumer decides what happens on submit.

import { AssistantProvider, AgentTriggerWidget } from "@docyrus/ui-pro-ai-assistant";

<AssistantProvider config={config}>
  <AgentTriggerWidget
    agentIds={["agent-id-1", "agent-id-2"]}
    onSubmit={(agentId, prompt, features, modelId) => {
      // Open DocyAssistant, navigate to a chat page, call an API, etc.
    }}
  />
</AssistantProvider>

Props

Prop	Type	Default	Description
agentIds	string[]	—	Required. Agent IDs to display in the carousel
className	string	—	CSS class on the root element
placeholder	string	—	Prompt input placeholder text
onSubmit	(agentId, prompt, features, modelId?) => void	—	Fires when the user submits a prompt. Receives the selected agent ID, prompt text, feature flags, and optional model ID

PromptFeatureFlags

The features object passed to onSubmit:

interface PromptFeatureFlags {
  webSearch: boolean;
  thinking: boolean;
  deepResearch: boolean;
  documentSearch: boolean;
  workCanvas: boolean;
}

InitialFeatureFlags

Used by DocyAssistant.initialFeatures — all fields are optional since you only need to set the ones you want enabled:

interface InitialFeatureFlags {
  webSearch?: boolean;
  thinking?: boolean;
  deepResearch?: boolean;
  documentSearch?: boolean;
  workCanvas?: boolean;
}

Combining with DocyAssistant

function MyPage() {
  const [assistantOpen, setAssistantOpen] = useState(false);
  const [agentId, setAgentId] = useState<string | null>(null);
  const [initialPrompt, setInitialPrompt] = useState<string>();

  return (
    <AssistantProvider config={config}>
      <AgentTriggerWidget
        agentIds={agentIds}
        onSubmit={(id, prompt) => {
          setAgentId(id);
          setInitialPrompt(prompt);
          setAssistantOpen(true);
        }}
      />
      {assistantOpen && agentId && (
        <DocyAssistant
          isOpen
          onClose={() => setAssistantOpen(false)}
          tenantAiAgentId={agentId}
          initialPrompt={initialPrompt}
          renderMode="modal"
        />
      )}
    </AssistantProvider>
  );
}

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