UI SDK

Ship AI chat UI in minutes

The Telygent UI SDK is a collection of accessible, customizable components designed to bridge the gap between your backend SDK and a polished user experience. It follows the shadcn/ui philosophy: it doesn't just install a library; it grafts the source code into your project so you have total control over the styling and behavior.

Installation & Setup

Initialize your project and pull in the core chat components using the CLI. This will scaffold the necessary providers, hooks, and UI elements into your components/ai folder.

terminal

# Initialize the UI registry
npx telygent-ui setup

# OPTIONAL: Add the chat interface components
npx telygent-ui add chat-interface

Adapter pattern

To keep the UI framework-agnostic, the ChatInterface uses a Frontend Adapter. This allows you to connect the UI to any backend endpoint whether you are using the Telygent Node.js SDK, a custom Python backend, or a serverless function.

Core responsibilities:

sendMessageStream

Use this for a premium user experience. As the AI "thinks" and types, the UI SDK renders fragments of text and status updates in real-time. This reduces "perceived latency" significantly for long-running analytical queries.

Instead of a standard function, you provide an AsyncIterable viasendMessageStream. The UI SDK iterates over the stream events.

sendMessage

Use this if you prefer a simpler backend implementation or if your AI responses are typically very short. The UI will show a "loading" state until the entire response is ready.

The adapter waits for a single Promise to resolve. Once received, the UI renders the full markdown content and any associated visualizations at once.

getHistory

Hydrates the chat window with previous messages when a user returns to a conversation.

Standard setup

ChatPage.tsx

import {ChatProvider, type SendMessageInput, type SendMessageResult, type ChatMessage} from "@/components/ai/ChatProvider";
import {ChatInterface} from "@/components/ai/ChatInterface";

const adapter = {
  async sendMessage({message, conversationId}: SendMessageInput): Promise<SendMessageResult> {
    const response = await api.send({message, conversationId});
    return {
      conversationId: response.conversationId,
      message: {
        role: "assistant",
        content: response.content,
        createdAt: new Date(),
        visualizations: response.visualizations,
      },
    };
  },
  async getHistory(conversationId: string): Promise<ChatMessage[]> {
    const history = await api.history(conversationId);
    return history.messages.map((item) => ({
      role: item.role === "assistant" ? "assistant" : "user",
      content: item.content,
      createdAt: new Date(item.timestamp),
      visualizations: item.visualizations ?? [],
    }));
  },
};

export default function Page() {
  return (
    <ChatProvider adapter={adapter}>
      <ChatInterface conversationId="conv_123" aiName="Telygent" />
    </ChatProvider>
  );
}

Streaming setup

ChatPage.tsx

 import {
    ChatProvider,
    type SendMessageInput,
    type ChatStreamEvent,
    type ChatMessage,
  } from "@/components/ai/ChatProvider";
  import {ChatInterface} from "@/components/ai/ChatInterface";

  async function* streamChat(input: SendMessageInput): AsyncIterable<ChatStreamEvent> {
    const response = await fetch("/api/chat/stream", {
      method: "POST",
      headers: {"Content-Type": "application/json"},
      body: JSON.stringify({
        question: input.message,
        conversationId: input.conversationId,
      }),
    });

    const reader = response.body!.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const {value, done} = await reader.read();
      if (done) break;

      buffer += decoder.decode(value, {stream: true});
      const lines = buffer.split("\n\n");
      buffer = lines.pop() ?? "";

      for (const line of lines) {
        if (!line.startsWith("data: ")) continue;
        const payload = JSON.parse(line.replace("data: ", "")) as ChatStreamEvent;
        yield payload;
      }
    }
  }

  const adapter = {
    sendMessageStream: streamChat,
    async getHistory(conversationId: string): Promise<ChatMessage[]> {
      const history = await api.history(conversationId);
      return history.messages.map((item) => ({
        role: item.role === "assistant" ? "assistant" : "user",
        content: item.content,
        createdAt: new Date(item.timestamp),
        visualizations: item.visualizations ?? [],
      }));
    },
  };

  export default function Page() {
    return (
      <ChatProvider adapter={adapter}>
        <ChatInterface conversationId="conv_123" aiName="Telygent" />
      </ChatProvider>
    );
  }

Adapter fields

conversationId

A unique identifier for your current conversation and to maintain context.

aiName

Optional

A brand or user friendly name you will like the AI to respond as

logo

Optional

Your AI or brand logo for personalization to your UI

description

Optional

A landing page description shown in the chat area when there is no message in the timeline

defaultPrompts

Optional

An array of default questions a user can choose from to get a conversation started with the AI

Placeholder

Optional

Customize the placeholder of the chat input text area

Styling & Markdown Rendering

The Telygent UI SDK uses a custom CSS manifest (ai-mdx.css) to handle the typography and layout of AI-generated content. Without this file, standard HTML elements (like <table> or <ul>) may appear unstyled or broken within the chat bubbles.

You have two options for integrating these styles into your project. Choose the one that best fits your existing workflow.

Option A: The CSS Global Import

Add the @import rule to the top of your main Tailwind or CSS entry point. This ensures the styles are bundled with your global CSS and are available across all routes.

globals.css

/* Ensure this path matches your local project structure after running 'npx telygent-ui add' */
@import "@/components/ai/components/ai-mdx.css";

@tailwind base;
@tailwind components;
@tailwind utilities;

Option B: The CSS Global Import

If you prefer to keep your CSS file clean, you can import the stylesheet directly into your top-level Layout or Page file.

layout.tsx or _app.tsx

import "@/components/ai/components/ai-mdx.css";
import "./globals.css";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}