@imiobe/omnia-assistant-ui

AI chat assistant widget that integrates iMio's Omnia API for conversational AI interactions. Features a draggable/resizable chat panel, streaming responses via SSE, page content injection, and keyboard shortcuts.

Installation

npm install @imiobe/omnia-assistant-ui preact

Preact (>=10) is a peer dependency and must be installed separately.

Quick start

import { mount } from '@imiobe/omnia-assistant-ui';
import '@imiobe/omnia-assistant-ui/dist/omnia-assistant-ui.css';

// Configure via window global
window.assistant_settings = {
  api_service_url: 'https://example.be/api',
  api_key: 'your-bearer-token',
  model: 'your-model-name',
  base_prompt: 'You are a helpful assistant.',
};

mount('app'); // mount into element with id="app"

Or pass configuration directly:

import { mount } from '@imiobe/omnia-assistant-ui';
import '@imiobe/omnia-assistant-ui/dist/omnia-assistant-ui.css';

mount('app', {
  apiServiceUrl: 'https://example.be/api',
  apiKey: 'your-bearer-token',
  model: 'your-model-name',
  basePrompt: 'You are a helpful assistant.',
  mode: 'floating',
  initialWidth: 380,
  initialHeight: 520,
});

You can also import the Preact component directly:

import { AIAssistant } from '@imiobe/omnia-assistant-ui';
import '@imiobe/omnia-assistant-ui/dist/omnia-assistant-ui.css';

function App() {
  return <AIAssistant config={{ apiServiceUrl: '...', apiKey: '...' }} />;
}

Configuration

Settings can be provided via the config prop / mount() argument (camelCase) or via window.assistant_settings (snake_case). The config prop takes precedence.

API settings

| config prop | window.assistant_settings | Default | Description | |---|---|---|---| | apiServiceUrl | api_service_url | — | Required. Base URL of the OpenAI-compatible chat API. | | apiKey | api_key | — | Required. Bearer token for authentication. | | model | model | — | Required. Model name sent in the completions request. | | basePrompt | base_prompt | — | System prompt prepended to every conversation. |

Page context settings

| config prop | window.assistant_settings | Default | Description | |---|---|---|---| | includePageContent | include_page_content | true | Inject the host page content as a system message. | | pageContentSelector | page_content_selector | '#content' | CSS selector(s) to extract page content from. Can be a string or array of strings. | | pageContentClean | page_content_clean | false | Use innerText instead of innerHTML for cleaner extraction. | | maxContextChars | — | 20000 | Max characters for page context. When exceeded, the user can select text on the page to provide a smaller context. |

UI settings

| config prop | Default | Description | |---|---|---| | mode | 'floating' | 'floating' for a draggable/resizable panel, 'fixed' for a stationary panel. | | initialWidth | 380 | Initial panel width in pixels. | | initialHeight | 520 | Initial panel height in pixels. | | disclaimer | French AI disclaimer | Disclaimer text shown at the bottom of the panel. Set to null to hide. |

API endpoint

The API endpoint must serve OpenAI-compatible SSE streaming responses at {apiServiceUrl}/chat/completions.

Request:

{
  "model": "model-name",
  "messages": [
    { "role": "system", "content": "System prompt..." },
    { "role": "system", "content": "Page content..." },
    { "role": "user", "content": "User message" }
  ],
  "stream": true
}

Response: SSE stream in OpenAI chat completions format:

data: {"choices":[{"delta":{"content":"Hello "}}]}

data: {"choices":[{"delta":{"content":"world."}}]}

data: [DONE]

Keyboard shortcuts

| Shortcut | Action | |----------|--------| | Alt+I | Toggle the chat panel open/closed |

Development

make install   # npm install
make dev       # Storybook on port 6006
make build     # Build to dist/
make lint      # ESLint

Copy .env.example to .env for the Storybook live API stories:

VITE_OMNIA_BASE_URL=https://ipa.imio.be/imio/omnia/openai
VITE_OMNIA_API_KEY=your-key
VITE_OMNIA_MODEL=your-model

When VITE_OMNIA_BASE_URL is a full URL, Storybook automatically proxies requests to avoid CORS.

Available commands

| Command | Description | |---------|-------------| | make install | Install dependencies | | make dev | Start Storybook dev server (port 6006) | | make build | Build library to dist/ (ES + UMD + CSS) | | make build-storybook | Build static Storybook site | | make lint | Run ESLint | | make lint-fix | Run ESLint with auto-fix | | make clean | Remove dist/ and storybook-static/ | | make publish | Build and publish to npm |

Build output

The library builds to dist/ in two formats:

• omnia-assistant-ui.js -- ES module
• omnia-assistant-ui.umd.cjs -- UMD (global: OmniaAssistantUI)
• omnia-assistant-ui.css -- Styles (Tailwind + @assistant-ui + theme)

Preact is not bundled -- it must be provided by the host application.

Stack

• Preact for UI (with preact/compat aliasing for React libraries)
• @assistant-ui/react for chat thread, composer, and markdown rendering
• Vite for builds (library mode)
• Tailwind CSS v3 with @assistant-ui plugins
• Framer Motion for panel animations (drag, resize, open/close)
• Mousetrap for keyboard shortcuts (Alt+I)
• Storybook 10 for component development

License

Proprietary -- (c) iMio