@nabeh/chat-widget-angular

Release Notes

Latest

• Adds document knowledge-graph support with built-in Knowledge Graph entry points and 2D/3D views.
• Shows source citation cards in both the embedded Knowledge Assistant and the floating widget.
• Keeps embedded suggestion chips clickable above the composer layer.
• Balances Recent Activity and Pinned Collections scroll areas when chat lists grow.
• Uses stream metadata IDs immediately, so feedback sends message_id without waiting for chat history reload.
• Sends feedback payloads as { "message_id": "...", "isLike": true }.
• Shows user initials when no avatar URL is configured.
• Displays No Content when a completed assistant response has no answer text.
• Improves chat-list overflow handling and active like/dislike visual states.

Install

npm install @nabeh/chat-widget-angular

Peer dependencies:

{
  "@angular/common": ">=17.3.0",
  "@angular/core": ">=17.3.0",
  "rxjs": "6.6.7"
}

Import the module where the widget is used:

import { ChatWidgetModule } from '@nabeh/chat-widget-angular';

Basic Usage

<chat-widget [config]="chatConfig"></chat-widget>

import { ChatWidgetConfig } from '@nabeh/chat-widget-angular';

chatConfig: ChatWidgetConfig = {
  apiBaseUrl: 'https://customer-proxy.example.com',
  displayMode: 'widget',
  rag: {
    loadHistoryOnOpen: true
  }
};

By default the library uses these backend paths:

{
  ask: '/my-chats/:chatId/messages',
  askStream: '/my-chats/:chatId/messages/stream',
  history: '/my-chats/:chatId/messages/history',
  listChats: '/my-chats/list',
  createChat: '/my-chats',
  updateChat: '/my-chats/:chatId',
  deleteChat: '/my-chats/:chatId/delete',
  feedback: '/my-chats/:chatId/feedback',
  upload: '/my-chats/upload',
  docs: '/my-chats/docs/:filename',
  knowledgeGraph: '/my-chats/knowledge-graph/:docUuid'
}

Knowledge Graph

The widget supports document-scoped knowledge graphs with both 2D and 3D views. Enable the feature once; the document UUID is taken from the citation the user selects.

import { ChatWidgetConfig } from '@nabeh/chat-widget-angular';

chatConfig: ChatWidgetConfig = {
  apiBaseUrl: 'https://customer-proxy.example.com',
  displayMode: 'embedded',
  knowledgeGraph: {
    enabled: true,
    defaultViewMode: '2d',
    maxNodes: 500,
    maxEdges: 1000
  }
};

There is no global Knowledge Graph tab. Each citation containing a document UUID shows a graph action next to its document-viewer action. Clicking the citation invokes onCitationClick; clicking its graph action opens the graph inside the widget without notifying the host application.

The AI citation contract must include the document UUID in streaming, non-streaming, and chat-history responses:

{
  "id": "c1",
  "document_uuid": "3c66197f-dbea-4889-9025-74849646c7fc",
  "page": 10,
  "text": "Relevant citation text"
}

The widget accepts document_uuid, documentUuid, source_uuid, or sourceUuid and normalizes them to citation.documentUuid. The graph action is hidden when no UUID is available, so citation/chunk IDs such as c1 are never used as document identifiers.

The default endpoint is /my-chats/knowledge-graph/:docUuid, resolved against apiBaseUrl. Customers using that proxy route do not need to configure an endpoint. An endpoint override remains available for deployments with a different route.

Users can then switch between:

• 2D: force-directed canvas view for fast exploration.
• 3D: Three.js-powered force graph for spatial exploration.

Hovering a node temporarily highlights its immediate neighbors and connecting edges. Clicking a node keeps that selection active and displays its details until it is reset.

For standalone document pages without citations, the existing documentUuid or documentUuidFactory options remain supported for programmatic graph opening:

chatConfig: ChatWidgetConfig = {
  displayMode: 'embedded',
  knowledgeGraph: {
    enabled: true,
    documentUuidFactory: () => this.selectedDocument?.source_uuid ?? null
  }
};

The customer proxy route forwards to the AI graph API:

GET /my-chats/knowledge-graph/{doc_uuid}?max_nodes=500&max_edges=1000

The widget expects:

• kg_status: not_yet_started, processing, ready, failed, or disabled
• nodes: entity nodes
• edges: relationships
• node_count / edge_count
• is_truncated

Recommended production flow:

chat-widget -> client Angular app -> NestJS/customer proxy -> AI backend

Recommended NestJS proxy route:

GET /my-chats/knowledge-graph/:docUuid

Example widget override:

endpoints: {
  knowledgeGraph: '/my-chats/knowledge-graph/:docUuid'
}

Recommended Auth Architecture

For customer deployments, prefer a customer proxy backend:

chat-widget -> customer proxy -> NestJS backend -> AI backend

The widget should call the customer proxy. The proxy can generate or refresh AI access tokens and forward requests to NestJS or AI services. In that setup, the widget does not need getAccessToken; auth stays server-side.

Use getAccessToken only for local testing or apps that intentionally attach a browser-side bearer token:

getAccessToken: () => localStorage.getItem('ACCESS_TOKEN')

The widget sends that value as:

Authorization: Bearer <token>

Streaming Responses

Streaming uses fetch() and ReadableStream.getReader() because Angular HttpClient does not expose token-by-token response chunks.

Streaming is enabled by default. Configure endpoints.askStream for the customer proxy or AI streaming route:

chatConfig: ChatWidgetConfig = {
  apiBaseUrl: 'https://customer-proxy.example.com',
  endpoints: {
    askStream: '/my-chats/:chatId/messages/stream'
  },
  rag: {
    enableThink: false
  }
};

endpoints.askStream should normally point to the customer proxy or NestJS backend. The backend should forward the request to the AI server stream endpoint. A full AI URL can be used only for isolated local testing when CORS and auth allow it:

endpoints: {
  askStream: 'http://183.82.145.33:7777/ai-server/smart_docs/ask_your_doc/stream'
}

The streaming request body is:

{
  "message": "What are the key findings in this document?",
  "chat_id": "smart-docs-session-001",
  "query": "What are the key findings in this document?",
  "enable_think": false
}

The widget does not include source_uuid in streaming chat requests. If a deployment requires document-scoped chat, the customer proxy or NestJS/AI API contract must add and authorize that field explicitly; setting rag.sourceUuid alone does not send it.

The stream parser supports concatenated JSON objects and objects split across chunks:

{"type":"metadata","content":""}
{"type":"answer","content":"The"}
{"type":"answer","content":" document"}
{"type":"references","content":{"citations":[]}}

type: "answer" appends content to the current assistant message in real time. type: "references" attaches citations to that assistant message and displays source cards.

Document Preview

Citations are displayed below assistant answers:

• in the embedded Knowledge Assistant sources panel and inline source cards
• in the floating widget as inline source cards

Clicking a source opens a document preview overlay by default.

The preview uses:

endpoints: {
  docs: '/my-chats/docs/:filename'
}

For a citation with knowledgeName: "labor-law" and pageNumber: 28, the iframe opens:

/my-chats/docs/labor-law#page=28

The backend can resolve the real file extension by matching files that start with the requested filename.

Custom Citation Navigation

If the customer app wants to open its own document page instead of the built-in preview, use onCitationClick.

chatConfig: ChatWidgetConfig = {
  apiBaseUrl: 'https://customer-proxy.example.com',
  onCitationClick: async (event) => {
    console.log('Open customer document page', {
      documentId: event.documentId,
      pageNumber: event.pageNumber,
      text: event.text
    });
  }
};

The callback receives the requested navigation fields as guaranteed values:

• documentId: string
• pageNumber: number (defaults to 1 when the citation has no page)
• text: string (defaults to an empty string)

It also includes the full normalized RagCitation fields for compatibility:

• documentUuid
• sourceDocument
• knowledgeName
• pageNumber
• text
• score

Chat Actions

The sidebar supports:

• Edit: calls updateChat with { title }.
• Pin Chat / Unpin Chat: calls updateChat with { title, pinned } and moves the chat between Recent Activity and Pinned Collections immediately.
• Delete: calls deleteChat and removes the chat from the UI.

Configuration Reference

type ChatWidgetConfig = {
  apiBaseUrl: string;
  endpoints?: Partial<ChatWidgetEndpoints>;
  displayMode?: 'widget' | 'embedded';
  position?: 'bottom-right' | 'bottom-left';
  title?: string;
  subtitle?: string;
  welcomeMessage?: string;
  inputPlaceholder?: string;
  launcherAriaLabel?: string;
  closeAriaLabel?: string;
  initialSuggestions?: string[];
  sourceApp?: string;
  locale?: string;
  customHeaders?: Record<string, string>;
  rag?: KnowledgeRagConfig;
  knowledgeGraph?: KnowledgeGraphConfig;
  getAccessToken?: () => Promise<string | null> | string | null;
  userInfo?: () => Promise<UserInfo | null> | UserInfo | null;
  onOpen?: () => void;
  onClose?: () => void;
  onError?: (error: Error) => void;
  onOpenAssistantPage?: () => Promise<void> | void;
  assistantPageUrl?: string;
  assistantAvatarUrl?: string;
  embedded?: {
    showHeader?: boolean;
  };
};

apiBaseUrl

Base URL for the customer proxy or backend.

endpoints

Override any backend path. Relative paths are resolved against apiBaseUrl. Full URLs are supported for askStream and other endpoints.

customHeaders

Static headers added to every request. Prefer proxy-side auth for production.

getAccessToken

Optional browser-side bearer token provider. Useful for testing; not required when the customer proxy adds tokens server-side.

rag

type KnowledgeRagConfig = {
  chatId?: string;
  chatIdFactory?: () => string;
  knowledgeNames?: string[];
  sourceUuid?: string;
  enableThink?: boolean;
  useStreaming?: boolean;
  enableReferences?: boolean;
  loadHistoryOnOpen?: boolean;
};

sourceUuid is retained for backward compatibility as a fallback document context when Knowledge Graph is opened programmatically without a citation UUID. It is not included in the endpoints.askStream request body. Citation-scoped graphs use the document UUID from the AI citation response instead.