Docs: BYO Chat Library

docs/content/docs/agent/guides/chat-library.mdx

@@ -0,0 +1,102 @@
+---
+title: "OpenUI Cloud: Chat Library"
+description: Use OpenUI Cloud with its built-in chat library, or bring your own components.
+---
+
+## Using the built-in library
+
+Out of the box, OpenUI Cloud ships a general-purpose chat library: text, headers, tables, charts, forms, tabs, buttons, and more.
+
+```tsx
+import { chatLibrary } from "@openuidev/thesys";
+
+<AgentInterface llm={llm} componentLibrary={chatLibrary} />;
+```
+
+And the backend uses it by default when building the request instructions:
+
+```ts
+instructions: createResponsesInstructions({
+  instructions: "Optional instructions for the model.",
+});
+```
+
+OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library.
+
+## Using your own library
+
+There can be multiple reasons to use your library instead of the built-in one like if the domain calls for components the generic set can't express or when the app follows its own design system. To lift it, you can provide your own chat library.
+
+**Define the library.** One [`defineComponent`](/docs/openui-lang/defining-components) per component, in the frontend where your React components live. Prop schemas and descriptions are what the model sees; `id` is an optional free-form revision tag:
+
+```tsx title="src/lib/chat-library.tsx"
+import { createLibrary, defineComponent } from "@openuidev/react-lang";
+import { z } from "zod/v4";
+import { Metric, Panel } from "@/components";
+
+const MetricDef = defineComponent({
+  name: "Metric",
+  description: "A single KPI stat with an optional trend arrow.",
+  props: z.object({
+    label: z.string(),
+    value: z.string(),
+    trend: z.enum(["up", "down"]).optional(),
+  }),
+  component: ({ props }) => <Metric {...props} />,
+});
+
+const PanelDef = defineComponent({
+  name: "Panel",
+  description: "Top-level container. Children stack vertically.",
+  props: z.object({ children: z.array(MetricDef.ref) }),
+  component: ({ props, renderNode }) => <Panel>{renderNode(props.children)}</Panel>,
+});
+
+export const myLibrary = createLibrary({
+  id: "acme-chat@1",
+  root: "Panel",
+  components: [PanelDef, MetricDef],
+});
+```
+
+**Generate the spec handover file.** [`openui generate-spec`](/docs/api-reference/cli#openui-generate-spec) turns the library module into a self-contained JSON file for the backend:
+
+```bash tab="pnpm" tab-group="pkg"
+pnpx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json
+```
+
+```bash tab="bun" tab-group="pkg"
+bunx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json
+```
+
+```bash tab="yarn" tab-group="pkg"
+yarn dlx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json
+```
+
+```bash tab="npm" tab-group="pkg"
+npx @openuidev/cli@latest generate-spec src/lib/chat-library.tsx --out ./generated/chat-library-spec.json
+```
+
+**Declare it in the backend call.** Import the generated JSON and pass it as `chatLibrary`.
+
+```diff
++ import chatLibrarySpec from "./generated/chat-library-spec.json";
+
+- instructions: createResponsesInstructions(),
++ instructions: createResponsesInstructions({
++   chatLibrary: chatLibrarySpec,
++   systemPromptOptions: { preamble: "You build dashboards for Acme operators." },
++ }),
+```
+
+`systemPromptOptions` (only valid alongside `chatLibrary`) tunes the generated prompt: `preamble`, `additionalRules`, `examples`.
+
+**Swap the client library:**
+
+```diff
+- import { chatLibrary } from "@openuidev/thesys";
++ import { myLibrary } from "@/lib/chat-library";
+
+- <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
++ <AgentInterface llm={llm} componentLibrary={myLibrary} />;
+```

docs/content/docs/agent/meta.json

@@ -24,6 +24,7 @@
     "reference/self-hosting",
     "---Guides---",
     "guides/custom-artifacts",
-    "guides/migrating"
+    "guides/migrating",
+    "guides/chat-library"
   ]
 }