UIX

Что такое UIX (и чем он не является)

UIX — это протокольный слой и движок конвертации, а не фреймворк для Chat UI.

Если вам нужен полнофункциональный React-интерфейс чата, используйте assistant-ui — он отличный и проверен в бою. UIX решает другую задачу: нормализацию вывода AI из любого источника в единый стабильный формат.

                      ┌─────────────────────────┐
Vercel AI SDK ──────→ │                         │
AgentX ─────────────→ │   UIX IR                │ ──→ assistant-ui
AG-UI (CopilotKit) ─→ │   (unified format)      │ ──→ your own renderer
A2UI (Google) ──────→ │                         │ ──→ any UI framework
                      └─────────────────────────┘

Думайте о UIX как о Babel для вывода AI — Babel нормализует JavaScript между движками; UIX нормализует вывод AI между провайдерами.

Проблема

Все AI-бэкенды используют разные форматы:

Источник	Формат сообщений	Формат вызова инструментов	Протокол стриминга
Vercel AI SDK	`UIMessage.parts[]`	`ToolInvocationPart`	Data Stream
AgentX	`Conversation.blocks[]`	`ToolBlock`	WebSocket events
AG-UI (CopilotKit)	AG-UI events	`ToolCallStart/End`	SSE events
A2UI (Google)	Declarative UI payload	Component-based	gRPC stream

Если вы строите Chat UI, вы привязаны к одному формату. Смените бэкенд — придётся переписывать UI-слой.

UIX IR устраняет эту связанность. Ваш UI знает только LucidConversation и LucidBlock — адаптеры берут на себя всё остальное.

Архитектура

┌─────────────────────────────────────────────────────────────────┐
│  AI Backends (upstream)                                         │
│  Vercel AI SDK · AgentX · AG-UI · A2UI · LangChain · ...        │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                    UIX Adapters (ACL)
                    Pure functions, zero side effects
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│  UIX IR  (@uix-ai/core)                                         │
│  LucidConversation → LucidBlock[]                               │
│  7 block types: text · tool · thinking · image · file · error · │
│  source                                                         │
│  JSON Schema + TypeScript types + type guards                   │
└──────────────────────────┬──────────────────────────────────────┘
                           │
               ┌───────────┴───────────┐
               ▼                       ▼
┌──────────────────────┐  ┌──────────────────────────────────────┐
│  assistant-ui        │  │  UIX Reference Renderer              │
│  (рекомендуется)     │  │  @uix-ai/stream (StreamMarkdown)     │
│  Полный Chat UI      │  │  @uix-ai/agent (ChatBubble, etc.)    │
│  runtime via         │  │  Лёгкий, zero-runtime                │
│  ExternalStore       │  │                                      │
└──────────────────────┘  └──────────────────────────────────────┘

Почему адаптеры, а не прямая интеграция?

В терминах DDD каждый AI-бэкенд — это отдельный Bounded Context. Адаптеры UIX — это Anti-Corruption Layer (ACL): потребитель (UI) защищает себя от изменений форматов на стороне источника.

Upstream (AgentX, Vercel и др.) владеет своими типами — никакого давления на изменения
Downstream (UI) зависит только от UIX IR — не боится смены бэкенда
Адаптеры — чистые функции: fromX(input) → LucidConversation[]

Спецификация UIX IR

Основные типы

interface LucidConversation {
  id: string
  role: 'user' | 'assistant' | 'system'
  status: 'streaming' | 'completed' | 'error'
  blocks: LucidBlock[]
  timestamp: number
}

interface LucidBlock<T extends BlockType> {
  id: string
  type: T  // 'text' | 'tool' | 'thinking' | 'image' | 'file' | 'error' | 'source'
  status: 'streaming' | 'completed' | 'error'
  content: ContentByType<T>  // условный тип, выводится из T
}

Типы блоков

Тип	Описание	Содержимое
`text`	Текстовый контент (поддерживает стриминг)	`{ text: string }`
`tool`	Вызов инструмента/функции	`{ name, input, output, status }` — жизненный цикл из 9 состояний
`thinking`	Процесс рассуждения AI	`{ reasoning: string }`
`image`	Изображение	`{ url, alt, width, height }`
`file`	Прикреплённый файл	`{ name, type, url, size }`
`error`	Сообщение об ошибке	`{ code, message, details }`
`source`	Ссылка на источник	`{ sourceId, title, url, excerpt }`

Жизненный цикл инструмента (9 состояний)

pending → streaming → ready → running → success
                                ↓
                        approval-required → approved → success
                                         → denied
                                ↓
                               error

Пакеты

Core (основная ценность)

Пакет	Описание	Статус
`@uix-ai/core`	Типы UIX IR, JSON Schema, type guards	✅ v0.0.2

Адаптеры (мост)

Пакет	Конвертирует из	Статус
(в разработке)

Установка

README