@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.
• Agent consent gate — Agents requiring consent show a non-closable terms dialog and block the prompt input until a super_admin approves.
• 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 | | tailwindcss | ^4.0.0 | | vite | >= 5.0.0 (optional) |

Setup

This package ships React component sources that use Tailwind v4 utility classes — it does not bundle a CSS utilities file. Your app's Tailwind build generates the utilities, which keeps the consumer in full control of theme tokens and avoids class-name collisions.

1. Import the component CSS once at app root

/* your app's globals.css */
@import "tailwindcss";
@import "@docyrus/ui-pro-ai-assistant/styles.css";

This brings in component-specific custom CSS (container queries, has-selectors, markdown styling) — roughly 100 lines.

2. Tell Tailwind to scan the package sources

Tailwind needs to see the class strings used inside the package's compiled JS (and inside its @docyrus/ui-pro-shared peer) to generate the utilities they reference. Add these @source directives next to your other source patterns:

/* your app's globals.css */
@source "../path/to/node_modules/@docyrus/ui-pro-ai-assistant/dist/**/*.js";
@source "../path/to/node_modules/@docyrus/ui-pro-shared/src/**/*.{ts,tsx}";

The relative path depends on where your globals.css lives. In a Vite app the CSS file is usually under src/styles/, so the @source paths point up to the nearest node_modules. Tailwind resolves the path relative to the CSS file.

3. Provide shadcn-style theme tokens

The package's utilities resolve --color-background, --color-foreground, --color-primary, etc. against your app's tokens. If you follow the standard shadcn convention (--background, --foreground on :root) plus a @theme inline mapping (--color-background: var(--background)), you're already set. See the shadcn theming docs for the full block.

Quick start

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: "[email protected]",
      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
        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 | Component-specific custom CSS — import once at app root. Tailwind utilities are generated by your app's Tailwind build (see Setup) |

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
  roles?: string[]; // optional — tenant roles; `'super_admin'` may approve an agent's consent terms
}

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.

Agent consent: When an agent requires consent (agent.consent is false/null), the assistant shows a non-closable "Terms & Agreement" gate and hides the prompt input until the terms are accepted. Only users whose roles include 'super_admin' can approve; everyone else sees the terms with the Approve button disabled.

<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 | | enableWelcomePage | boolean | true | Show a welcome landing page on first open with agent greeting, inline prompt input, and recent sessions. The header (with agent tabs) stays visible so users can switch agents from the welcome screen; the sidebar is hidden. Dismissed on interaction (new chat, session click, or message send) | | defaultFullscreen | boolean | false | Initial uncontrolled fullscreen state | | isFullscreen | boolean | — | Controlled fullscreen state. When provided, the package no longer manages its own fullscreen state — pair with onFullscreenChange to fully drive the expand button from the host | | hideExpand | boolean | false | Hide the fullscreen toggle | | hideCloseButton | boolean | false | Hide the close (X) button in the header | | hideBorder | boolean | false | Hide the outer border and shadow of the assistant container | | showHeader | boolean | true | Show the header bar with the agent tabs | | 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 tabs

The header renders a tab strip. The first tab is pinned to tenantAiAgentId and cannot be closed. The + button next to it opens a dropdown listing the available base agents (from agentSelectorUrl); selecting one opens a new closable tab with its own isolated thread and message history. Open tabs are persisted to localStorage.

Switching agents (either selecting an existing tab or adding a new one) resets navigation to the chat home — the previous agent's projects/works pane is dismissed and any selected project / project context is cleared, so the user lands in the new agent's chat view rather than a stale pane.

| Prop | Type | Default | Description | |------|------|---------|-------------| | agentSelectorUrl | string | "/ai/agent-deployments/base" | Endpoint listing base agents shown in the "+" dropdown | | onAgentChange | (agentId: string, agentType: "base" \| "deployment") => void | — | Fires when the user opens a new agent tab |

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 | | onFullscreenChange | (isFullscreen: boolean) => void | Intercepts the expand button. When provided, replaces the package's built-in fullscreen toggle — the host receives the intended next state and decides what to do (toggle, redirect, etc.). When omitted, the package self-toggles its fullscreen state. Pair with isFullscreen for a fully controlled expand/collapse. | | 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 package's components use Tailwind utility classes; your app's Tailwind build generates them via the @source directives shown in Setup. The package itself ships no compiled utilities.

License

MIT