thesys-generative-ui

What this skill does

# TheSys Generative UI Integration

Complete skill for building AI-powered interfaces with TheSys C1 Generative UI API. Convert LLM responses into streaming, interactive React components.

---

## What is TheSys C1?

**TheSys C1** is a Generative UI API that transforms Large Language Model (LLM) responses into live, interactive React components instead of plain text. Rather than displaying walls of text, your AI applications can stream forms, charts, tables, search results, and custom UI elements in real-time.

### Key Innovation

Traditional LLM applications return text that developers must manually convert into UI:
```
LLM → Text Response → Developer Parses → Manual UI Code → Display
```

TheSys C1 eliminates this manual step:
```
LLM → C1 API → Interactive React Components → Display
```

### Real-World Impact

- **83% more engaging** - Users prefer interactive components over text walls
- **10x faster development** - No manual text-to-UI conversion
- **80% cheaper** - Reduced development time and maintenance
- **Production-ready** - Used by teams building AI-native products

---

## When to Use This Skill

Use this skill when building:

1. **Chat Interfaces with Rich UI**
   - Conversational interfaces that need more than text
   - Customer support chatbots with forms and actions
   - AI assistants that show data visualizations

2. **Data Visualization Applications**
   - Analytics dashboards with AI-generated charts
   - Business intelligence tools with dynamic tables
   - Search interfaces with structured results

3. **Dynamic Form Generation**
   - E-commerce product configurators
   - Multi-step workflows driven by AI
   - Data collection with intelligent forms

4. **AI Copilots and Assistants**
   - Developer tools with code snippets and docs
   - Educational platforms with interactive lessons
   - Research tools with citations and references

5. **Search and Discovery**
   - Semantic search with structured results
   - Document analysis with highlighted findings
   - Knowledge bases with interactive answers

### This Skill Prevents These Errors

- ❌ Empty agent responses from incorrect streaming setup
- ❌ Models ignoring system prompts due to message array issues
- ❌ Version compatibility errors between SDK and API
- ❌ Themes not applying without ThemeProvider
- ❌ Streaming failures from improper response transformation
- ❌ Tool calling bugs from invalid Zod schemas
- ❌ Thread state loss from missing persistence
- ❌ CSS conflicts from import order issues
- ❌ TypeScript errors from outdated type definitions
- ❌ CORS failures from missing headers
- ❌ Rate limit crashes without retry logic
- ❌ Authentication token errors from environment issues

---

## Quick Start by Framework

### Vite + React Setup

**Most flexible setup for custom backends (your preferred stack).**

#### 1. Install Dependencies

```bash
npm install @thesysai/genui-sdk @crayonai/react-ui @crayonai/react-core @crayonai/stream
npm install openai zod
```

#### 2. Create Chat Component

**File**: `src/App.tsx`

```typescript
import "@crayonai/react-ui/styles/index.css";
import { ThemeProvider, C1Component } from "@thesysai/genui-sdk";
import { useState } from "react";

export default function App() {
  const [isLoading, setIsLoading] = useState(false);
  const [c1Response, setC1Response] = useState("");
  const [question, setQuestion] = useState("");

  const makeApiCall = async (query: string) => {
    setIsLoading(true);
    setC1Response("");

    try {
      const response = await fetch("/api/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ prompt: query }),
      });

      const data = await response.json();
      setC1Response(data.response);
    } catch (error) {
      console.error("Error:", error);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div className="container">
      <h1>AI Assistant</h1>

      <form onSubmit={(e) => {
        e.preventDefault();
        makeApiCall(question);
      }}>
        <input
          type="text"
          value={question}
          onChange={(e) => setQuestion(e.target.value)}
          placeholder="Ask me anything..."
        />
        <button type="submit" disabled={isLoading}>
          {isLoading ? "Processing..." : "Send"}
        </button>
      </form>

      {c1Response && (
        <ThemeProvider>
          <C1Component
            c1Response={c1Response}
            isStreaming={isLoading}
            updateMessage={(message) => setC1Response(message)}
            onAction={({ llmFriendlyMessage }) => {
              if (!isLoading) {
                makeApiCall(llmFriendlyMessage);
              }
            }}
          />
        </ThemeProvider>
      )}
    </div>
  );
}
```

#### 3. Configure Backend API (Express Example)

```typescript
import express from "express";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";

const app = express();
app.use(express.json());

const client = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/embed",
  apiKey: process.env.THESYS_API_KEY,
});

app.post("/api/chat", async (req, res) => {
  const { prompt } = req.body;

  const stream = await client.chat.completions.create({
    model: "c1/openai/gpt-5/v-20250930", // or any C1-compatible model
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: prompt },
    ],
    stream: true,
  });

  // Transform OpenAI stream to C1 response
  const c1Stream = transformStream(stream, (chunk) => {
    return chunk.choices[0]?.delta?.content || "";
  });

  res.json({ response: await streamToString(c1Stream) });
});

async function streamToString(stream: ReadableStream) {
  const reader = stream.getReader();
  let result = "";

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

  return result;
}

app.listen(3000);
```

---

### Next.js App Router Setup

**Most popular framework, full-stack with API routes.**

#### 1. Install Dependencies

```bash
npm install @thesysai/genui-sdk @crayonai/react-ui @crayonai/react-core
npm install openai
```

#### 2. Create Chat Page Component

**File**: `app/page.tsx`

```typescript
"use client";

import { C1Chat } from "@thesysai/genui-sdk";
import "@crayonai/react-ui/styles/index.css";

export default function Home() {
  return (
    <div className="min-h-screen">
      <C1Chat apiUrl="/api/chat" />
    </div>
  );
}
```

#### 3. Create API Route Handler

**File**: `app/api/chat/route.ts`

```typescript
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { transformStream } from "@crayonai/stream";

const client = new OpenAI({
  baseURL: "https://api.thesys.dev/v1/embed",
  apiKey: process.env.THESYS_API_KEY,
});

export async function POST(req: NextRequest) {
  const { prompt } = await req.json();

  const stream = await client.chat.completions.create({
    model: "c1/openai/gpt-5/v-20250930",
    messages: [
      { role: "system", content: "You are a helpful AI assistant." },
      { role: "user", content: prompt },
    ],
    stream: true,
  });

  // Transform to C1-compatible stream
  const responseStream = transformStream(stream, (chunk) => {
    return chunk.choices[0]?.delta?.content || "";
  }) as ReadableStream<string>;

  return new NextResponse(responseStream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      "Connection": "keep-alive",
    },
  });
}
```

**That's it!** You now have a working Generative UI chat interface.

---

### Cloudflare Workers + Static Assets Setup

**Your stack: Workers backend with Vite+React frontend.**

#### 1. Create Worker Backend (Hono)

**File**: `backend/src/index.ts`

```typescript
import { Hono } from "hono";
import { cors } from "hono/cors";

const app = new Hono();

app.use("/*", cors());

app.post("/api