KI-Assistent Plugin — Integration Guide

Overview

The KI-Assistent is a standalone Angular component that provides an AI-powered chat panel. It is designed to be embedded as a sidebar in your existing Angular application.

The plugin handles all chat logic internally: streaming responses, conversation history, file uploads, voice-to-text, interactive widgets, and data visualizations.

Quick Start

1. Install

npm install @augustalabs/ki-assistent

2. Import the CSS (required)

The plugin ships a stylesheet that must be loaded once. Add it to your angular.json:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "src/styles.css",
              "node_modules/@augustalabs/ki-assistent/ki-assistent.css"
            ]
          }
        }
      }
    }
  }
}

Or import it from your global styles.css:

@import '@augustalabs/ki-assistent/ki-assistent.css';

This file contains the base styles for the date picker calendar and other elements that render outside the component tree.

3. Provide Configuration

In your application's app.config.ts (or module providers):

import { provideKiAssistent } from '@augustalabs/ki-assistent';

export const appConfig: ApplicationConfig = {
  providers: [
    // ... your other providers
    provideKiAssistent({
      apiUrl: 'https://your-backend.example.com/api',
    }),
  ],
};

4. Add the Component

import { ChatPanel } from '@augustalabs/ki-assistent';

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [ChatPanel],
  template: `
    <div class="dashboard">
      <app-sidebar />
      <app-main-content />
      <ki-chat-panel (closeRequested)="togglePanel()" />
    </div>
  `,
})
export class DashboardComponent {
  togglePanel() { /* show/hide logic */ }
}

That's it. The panel renders as a self-contained sidebar.

Configuration

All configuration is done through the provideKiAssistent() function.

KiAssistentConfig

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | apiUrl | string | Yes | — | Base URL of the backend API (e.g. https://api.example.com/api) | | locale | string | No | "de-DE" | Language for UI text and speech recognition | | title | string | No | "KI-Assistent" | Title displayed in the panel header | | placeholder | string | No | "Stelle irgendeine Frage" | Placeholder text in the chat input | | welcomeHeading | string | No | "Wie kann ich helfen?" | Welcome screen heading | | welcomeSubtitle | string | No | "Fragen Sie mich zu Kunden, Verträgen oder Workflows" | Welcome screen subtitle | | suggestions | string[] | No | ["Kunden suchen", ...] | Quick-action buttons on the welcome screen | | headers | Record<string, string> | No | {} | Extra HTTP headers sent with every API request (e.g. auth tokens) |

Full Example

provideKiAssistent({
  apiUrl: 'https://api.example.com/api',
  locale: 'de-DE',
  title: 'Mein Assistent',
  placeholder: 'Wie kann ich helfen?',
  welcomeHeading: 'Willkommen!',
  welcomeSubtitle: 'Stellen Sie eine Frage zu Ihrem Portfolio.',
  suggestions: [
    'Verträge anzeigen',
    'Neuen Kunden anlegen',
    'Dokument hochladen',
  ],
  headers: {
    'Authorization': 'Bearer eyJhbGci...',
    'X-Tenant-ID': 'acme-corp',
  },
})

Component API

<ki-chat-panel>

The main component. Place it wherever you want the chat sidebar.

Outputs

| Output | Type | Description | |--------|------|-------------| | closeRequested | void | Emitted when the user clicks the close (X) button. Use this to hide the panel. |

Example

@if (panelOpen) {
  <ki-chat-panel (closeRequested)="panelOpen = false" />
}

Theming

The plugin uses CSS custom properties (variables) for all colors. Set them on a parent element to match your brand.

Dark Mode (default)

The plugin uses a dark theme by default. Override any variable:

.my-panel-wrapper {
  --ki-accent: #FF6B00;          /* brand color */
  --ki-bg: #1a1a1a;             /* panel background */
  --ki-text-primary: #ffffff;    /* main text */
  --ki-text-secondary: #999;     /* muted text */
  --ki-border: #333;             /* borders */
  --ki-bubble-assistant: #2a2a2a; /* assistant bubble background */
  --ki-hover: rgba(255,255,255,0.05); /* hover states */
  --ki-accent-text: #ffffff;     /* text on accent-colored elements */
}

Light Mode

Add the ki-light class to the panel's parent container:

<div class="ki-light">
  <ki-chat-panel />
</div>

This switches all colors to light-mode defaults. You can still override individual variables.

Available CSS Variables

| Variable | Dark Default | Light Default | Controls | |----------|-------------|--------------|----------| | --ki-accent | #2EA8DB | #2EA8DB | Buttons, links, highlights, selected states | | --ki-accent-text | #ffffff | #ffffff | Text on accent backgrounds | | --ki-bg | #111927 | #f8f9fb | Panel background | | --ki-text-primary | #e0e6ed | #1a1a2e | Main text color | | --ki-text-secondary | #8b95a5 | #6b7280 | Muted text, timestamps, labels | | --ki-border | #2a3545 | #e0e3e8 | All borders | | --ki-bubble-assistant | #1e2a3a | transparent | Assistant message bubble background | | --ki-bubble-assistant-border | #2a3545 | #e0e3e8 | Assistant bubble border | | --ki-bubble-assistant-shadow | none | 0 1px 3px rgba(0,0,0,0.06) | Assistant bubble shadow | | --ki-hover | rgba(255,255,255,0.05) | rgba(0,0,0,0.04) | Hover state backgrounds | | --ki-font | system fonts | system fonts | Font family |

Features

Chat

• Real-time streaming responses via SSE
• Markdown rendering in assistant messages
• Message timestamps
• Typing indicator during response generation

Conversation History

• View past conversations via the history button (top-left)
• Conversations are titled from the first message
• Delete conversations from history
• Full message replay including widgets and displays

File & Image Upload

• Click the + button for file/image upload menus
• Drag and drop support
• Image preview thumbnails
• File type detection (PDF, Word, Excel, Markdown, etc.)
• 10 MB file size limit

Voice-to-Text

• Click the microphone button to start
• Live transcription appears in the text area as you speak
• Uses the browser's Web Speech API
• Language configurable via locale option

Message Feedback

• Thumbs up/down buttons on assistant messages
• Persisted to the backend via POST /api/messages/{id}/feedback

Copy Message

• Copy button on assistant messages
• Copies plain text to clipboard

Interactive Widgets

The backend can send interactive prompts that pause for user input:

| Widget | Description | |--------|-------------| | Form | Multi-field form with text, email, date (with custom date picker), and select inputs | | Choices | Multiple-choice buttons | | Confirm | Yes/No confirmation dialog | | Select | Searchable radio list with subtitles | | Plan | Step-by-step progress indicator (read-only) | | Summary | Success/error result card with key-value fields (read-only) |

Display Widgets

The backend can send data visualizations:

| Widget | Description | |--------|-------------| | Table | Data table with headers and rows | | Metric | KPI cards with value, label, and delta indicator | | Bar/Line Chart | SVG-based chart with labeled data points | | Pie Chart | SVG pie chart with legend | | Download | Download button for files |

Layout Example

The plugin fills 100% of its container's width and height. You control the size and position:

<div style="display: flex; height: 100vh;">
  <!-- Your app content -->
  <div style="flex: 1;">
    <router-outlet />
  </div>

  <!-- KI-Assistent panel -->
  <div style="width: 380px; flex-shrink: 0;">
    <ki-chat-panel (closeRequested)="hide()" />
  </div>
</div>

Backend Requirements

The plugin expects these API endpoints:

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /api/chat | Send message / resume widget (SSE streaming) | | GET | /api/conversations | List conversations | | GET | /api/conversations/:id/messages | Get messages for a conversation | | DELETE | /api/conversations/:id | Delete a conversation | | POST | /api/messages/:id/feedback | Submit message feedback |

CORS

Your backend must allow requests from the domain where the plugin is hosted. Required methods: GET, POST, DELETE, OPTIONS.

Authentication

If your API requires authentication, pass tokens via the headers config:

provideKiAssistent({
  apiUrl: 'https://api.example.com/api',
  headers: {
    'Authorization': `Bearer ${userToken}`,
  },
})

Browser Support

• Chrome 90+
• Firefox 90+
• Safari 15+
• Edge 90+

Voice-to-text requires Chrome, Edge, or Safari (Web Speech API).

Troubleshooting

Chat not connecting

• Check that apiUrl points to the correct backend
• Verify CORS is configured to allow your domain
• Check browser console for network errors

Theme not applying

• Ensure the ki-light class is on a parent of <ki-chat-panel>
• CSS variables must be set on a parent element, not on <ki-chat-panel> itself

Voice-to-text not working

• Only supported in Chrome, Edge, and Safari
• Requires HTTPS in production (browser security requirement)
• The microphone button is automatically hidden if unsupported