# @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.
- **Prompt templates** — A searchable picker in the chat input lists the agent's prompt templates; selecting one prefills the prompt or, when the template defines a form schema, opens a form (built-in, or host-rendered via `renderPromptTemplateForm`) whose values fill the template's `{{placeholders}}`.
- **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

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

### Peer dependencies

```bash
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

```css
/* 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:

```css
/* 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](https://ui.shadcn.com/docs/theming) for the full block.

## Quick start

```tsx
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: "ada@example.com",
      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

```tsx
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](#setup)) |

### Exported symbols

```ts
// 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,
  SelectedAssistantMessage,
  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>`.

```tsx
<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 |
| `promptTemplatesEndpoint` | `string \| ((agentId: string) => string)` | No | Endpoint (relative to `apiBaseUrl`) the chat calls to list an agent's prompt templates. A string may contain a `:agentId` placeholder; the function form lets a host route different agents to different endpoints. Defaults to the end-user route `/ai/agents/:agentId/prompt-templates` (not the admin-only `/dev/...` studio route) |
| `renderPromptTemplateForm` | `(args: { template: PromptTemplateInfo; onSubmit: (prompt: string) => void; onCancel: () => void }) => ReactNode` | No | Render slot for a selected prompt template's form. When set, the chat input delegates form rendering to the host (e.g. rendered with the host's own dynamic-form engine); on submit the host hands back the built prompt string. Falls back to the built-in form renderer when omitted |

`PromptTemplateInfo` is `{ id: string; title: string; content?: string \| null; promptFormSchema?: unknown }`.

#### `AssistantUser`

```ts
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 |
| `initialDeploymentId` | `string` | — | Opens the assistant directly on a deployed agent: seeds the pinned tab with this deployment so its name, welcome message, model and tools come from the deployment (`/ai/agent-deployments/:id`) instead of the base 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 |
| `enableMessageSelection` | `boolean` | `false` | When true, each assistant (agent) message renders a selection checkbox and a Send/Cancel footer appears below the thread. Lets the host pick agent replies and forward them elsewhere (e.g. a Microsoft Teams chat) via `onSendSelectedMessages` |

> **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.

Set `enableAgentTabs={false}` to hide the tab strip entirely (e.g. a single-agent "try this agent" surface) while keeping the rest of the header. The header's own controls (`showHeader`) are unaffected.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `enableAgentTabs` | `boolean` | `true` | Show the header agent-tabs strip (pinned tab + "add agent"). Set `false` to hide it |
| `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 <app>" 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 |
| `onSendSelectedMessages` | `(messages: SelectedAssistantMessage[]) => void \| Promise<void>` | Called with the picked assistant messages when the user presses **Send** in the selection footer (requires `enableMessageSelection`). The selection is cleared afterward |
| `onCancelSelection` | `() => void` | Called when the user presses **Cancel** in the selection footer (requires `enableMessageSelection`) |

#### Initial prompt

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `initialPrompt` | `string` | — | Staged into the composer for the user to review and send — never submitted automatically. Re-staged whenever the value changes, so no remount is needed to hand over a new prompt. Useful when launching the assistant from an agent trigger widget or deep link |
| `initialModelId` | `string` | — | Model pre-selected in the composer alongside the staged prompt |
| `initialFeatures` | `InitialFeatureFlags` | — | Feature flags pre-enabled in the composer alongside the staged prompt |
| `initialFiles` | `File[]` | — | Files staged as composer attachments alongside the staged 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.

```tsx
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`:

```ts
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:

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

#### Combining with DocyAssistant

```tsx
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>
  );
}
```

The widget's prompt lands in the assistant's composer, pre-filled and ready — the user still presses send. If a caller needs the message to go out on its own, it has to drive `onSubmit` itself.

---

### `useAssistantConfig()`

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

```tsx
const { apiBaseUrl, getAuthToken } = useAssistantConfig();
```

---

### `useAssistantTranslation()`

Returns the `t` function for translating assistant UI strings.

```tsx
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.

```ts
// 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`:

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

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

## Types

### `SelectedAssistantMessage`

An assistant (agent) reply the user picked while `enableMessageSelection` is on. Passed to `onSendSelectedMessages`.

```ts
interface SelectedAssistantMessage {
  id: string;
  text: string;   // concatenated text parts (empty for tool-only turns)
  parts: unknown[]; // raw AI SDK message parts (text, reasoning, tool calls, …),
                    // passed through untouched so hosts can extract tool outputs
}
```

### `Project`

```ts
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`

```ts
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`

```ts
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`:

```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](#setup). The package itself ships no compiled utilities.

## License

MIT
