The Open Standard for Generative UI
docs: the Autofix library travels as a system turn (#1175)
ankur-mittal955a6681ed29de
diff --git a/docs/content/docs/gateway/api/autofix.mdx b/docs/content/docs/gateway/api/autofix.mdxindex c52286cad..575b730e6 100644--- a/docs/content/docs/gateway/api/autofix.mdx+++ b/docs/content/docs/gateway/api/autofix.mdx@@ -9,50 +9,84 @@ The Autofix API repairs invalid OpenUI Lang after a model has generated it. Send**OpenAI compatible.** The request and the answer use the OpenAI chat completion shape. Point an OpenAI SDK at the base URL `https://api.thesys.dev/v1/autofix` and it posts to `/v1/autofix/chat/completions`. Both paths take the same body and answer the same way.+<Mermaid+ chart={`+flowchart LR+ Model[Model deltas] --> Acc[Accumulate] --> Parse{Valid?}+ Parse -- yes --> Render[Render]+ Parse -- no --> Autofix[POST /v1/autofix]+ Autofix -- already_valid / fixed --> Render+ Autofix -- fix_failed --> Fallback[Fallback]+`}+/>+## Detect an invalid generationParse the generation with `@openuidev/lang-core` before you call the API. It is the same check the API runs first, so a generation that passes here would come back as `already_valid`. Skip the call when nothing is wrong.```ts title="lib/detect.ts"-import { createParser } from "@openuidev/lang-core";-import library from "./openui.spec.json";--const parser = createParser(library.schema, library.root);--/** Everything that stops the generation from rendering. Empty means valid. */-export function findErrors(generation: string): string[] {- const { root, meta } = parser.parse(generation);- return [- ...meta.errors.map((e) => `${e.code} ${e.component}${e.path}: ${e.message}`),- ...meta.unresolved.map((name) => `unresolved: "${name}" is used but never defined`),- ...meta.orphaned.map((name) => `orphaned: "${name}" is defined but never used`),- ...(meta.incomplete ? ["incomplete: the generation ends mid-statement"] : []),- ...(root === null ? ["missing-root: no root element"] : []),- ];+import type { ParseResult } from "@openuidev/lang-core";++/** The API's own rule: a generation renders only when all five hold. */+export function isValid({ root, meta }: ParseResult): boolean {+ return (+ !meta.incomplete &&+ meta.errors.length === 0 &&+ meta.unresolved.length === 0 &&+ meta.orphaned.length === 0 &&+ root !== null+ );}```+Judge the generation once, after the stream ends. While it streams, `incomplete` and `unresolved` are normal: the parser has not seen the rest yet.+```ts title="server.ts"-import { findErrors } from "./lib/detect";--const errors = findErrors(generation);-if (errors.length === 0) {- render(generation);-} else {- console.warn("invalid generation", errors);- // Send it to the Autofix API, below.+import { createStreamingParser } from "@openuidev/lang-core";+import OpenAI from "openai";+import { autofix } from "./lib/autofix";+import { isValid } from "./lib/detect";+import library from "./openui.spec.json";++const model = new OpenAI(); // any provider that returns OpenUI Lang++export async function generate(messages: OpenAI.ChatCompletionMessageParam[]) {+ const parser = createStreamingParser(library.schema, library.root);+ let generation = "";+ let result = parser.getResult();++ const stream = await model.chat.completions.create({ model: "gpt-5", messages, stream: true });+ for await (const chunk of stream) {+ const delta = chunk.choices[0]?.delta?.content ?? "";+ if (!delta) continue;+ generation += delta;+ result = parser.push(delta);+ send(delta); // the browser renders as the text arrives+ }++ if (isValid(result)) return;++ const completion = await autofix(messages, generation);+ if (completion.fix_summary.status === "fix_failed") {+ sendFallback(completion.fix_summary.unfixed_errors);+ } else {+ replace(completion.choices[0].message.content); // the whole valid generation+ }}```-`parse` never throws. It takes fenced or bare OpenUI Lang and reports prop errors in `meta.errors`, with the codes listed under [Error codes](#error-codes).+`send`, `replace`, and `sendFallback` stand for your own transport to the browser: forward a delta, swap the rendered generation for the fixed one, and show a fallback.++`parse` and `push` never throw. They take fenced or bare OpenUI Lang and report prop errors in `meta.errors`, with the codes listed under [Error codes](#error-codes). For a generation you already hold in full, `createParser(library.schema, library.root).parse(generation)` gives the same result.## Fix an invalid generation-Point the OpenAI client at `/v1/autofix` and send the generation as the last assistant turn. Fenced or bare OpenUI Lang both work, and text outside the fence is ignored.+Point the OpenAI client at `/v1/autofix`. Your component library goes first, as a system turn written by `generateSystemPrompt({ cloud: true, library })`; the generation goes last, as an assistant turn. Fenced or bare OpenUI Lang both work, and text outside the fence is ignored.The API adds `fix_summary` to the chat completion, which the OpenAI types do not know about, so the example casts the request and the answer.```ts title="lib/autofix.ts"+import { generateSystemPrompt } from "@openuidev/lang-core";import OpenAI from "openai";import type { ChatCompletion } from "openai/resources/chat/completions";import library from "./openui.spec.json";@@ -62,6 +96,12 @@ const client = new OpenAI({baseURL: "https://api.thesys.dev/v1/autofix",});+// The library, in the form the API reads it: a system turn carrying the spec.+const libraryTurn = {+ role: "system",+ content: generateSystemPrompt({ cloud: true, library }),+} as const;+type FixError = { code: string; message: string; statementId?: string };type FixSummary = {status: "already_valid" | "fixed" | "fix_failed";@@ -73,26 +113,12 @@ type AutofixCompletion = ChatCompletion & { fix_summary: FixSummary };export async function autofix(messages: OpenAI.ChatCompletionMessageParam[], generation: string) {return (await client.chat.completions.create({model: "openui/autofix",- messages: [...messages, { role: "assistant", content: generation }],- library,+ messages: [libraryTurn, ...messages, { role: "assistant", content: generation }],} as OpenAI.ChatCompletionCreateParamsNonStreaming)) as AutofixCompletion;}```-```ts title="server.ts"-import { autofix } from "./lib/autofix";--// Pass the same messages you sent to your model.-const completion = await autofix(messages, generation);--if (completion.fix_summary.status === "fix_failed") {- renderFallback(generation);-} else {- render(completion.choices[0].message.content);-}-```--`openui.spec.json` is the library spec that `openui generate --spec` writes for your components. See [Generate OpenUI Lang](/docs/gateway/generate-openui-lang) for how it is created. Omit `library` to check the generation against the built-in OpenUI chat library.+`openui.spec.json` is the library spec that `openui generate --spec` writes for your components. See [Generate OpenUI Lang](/docs/gateway/generate-openui-lang) for how it is created. `generateSystemPrompt({ cloud: true, library })` turns it into a two-line `]]>openui:config` block, the same one the Gateway reads; the API reads the library from the first message only, and counts no config block as conversation. The API always needs the library: a generation is only valid against the components your app renders, so there is no built-in default.`model` is accepted so that an SDK client has something to send, and it is ignored: the fix always runs on the same correction model.@@ -101,10 +127,16 @@ if (completion.fix_summary.status === "fix_failed") {The plain path takes the same body. Server calls use the API key described in [Authentication](/docs/gateway/authentication).```ts title="lib/autofix-fetch.ts"+import { generateSystemPrompt } from "@openuidev/lang-core";import library from "./openui.spec.json";type Message = { role: string; content: string | unknown[] };+const libraryTurn: Message = {+ role: "system",+ content: generateSystemPrompt({ cloud: true, library }),+};+export async function autofix(messages: Message[], generation: string) {const response = await fetch("https://api.thesys.dev/v1/autofix", {method: "POST",@@ -113,8 +145,7 @@ export async function autofix(messages: Message[], generation: string) {"Content-Type": "application/json",},body: JSON.stringify({- messages: [...messages, { role: "assistant", content: generation }],- library,+ messages: [libraryTurn, ...messages, { role: "assistant", content: generation }],}),});@@ -130,8 +161,7 @@ export async function autofix(messages: Message[], generation: string) {| Field | Type | Required | Purpose || ---------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `messages` | array | Yes | The conversation, in the OpenAI chat message shape. The last turn must be an `assistant` turn whose text is the generation to fix, up to 100,000 characters. The turns before it are the context: only the text of `user`, `assistant`, `system`, and `developer` turns is read, and tool turns and non-text parts are dropped. |-| `library` | object | No | Your library spec, as written by `openui generate --spec`. Without it, the built-in chat library is used. |+| `messages` | array | Yes | The conversation, in the OpenAI chat message shape. The first message is a `system` turn that carries your library as the `]]>openui:config` block that `generateSystemPrompt({ cloud: true, library })` writes; it is read as the library, not as conversation. The last turn must be an `assistant` turn whose text is the generation to fix, up to 100,000 characters. The turns in between are the context: only the text of `user`, `assistant`, `system`, and `developer` turns is read, and tool turns and non-text parts are dropped. || `model` | string | No | Accepted so that an SDK client can name a model, and ignored. The answer always reports `openui/autofix`. || `stream` | bool | No | Streaming is not supported. A fix has nothing to send until it is finished, so `stream: true` is a `400`. |@@ -235,6 +265,10 @@ Each entry in `fixed_errors` or `unfixed_errors` names one problem. `code` is alThese are the same codes the OpenUI SDK reports in the browser, so an application can handle both with one path. See [Observability](/docs/observability) for how they appear in the Thesys Console.+## Framing++The generation may be bare OpenUI Lang, a fenced code block, or an assistant turn as the OpenUI SDK stores it after the user has touched a form inside it: `]]>openui:content`, the program, `]]>openui:context` with the form state, `]]>openui:end`. Only the program inside is checked and repaired. A fixed generation comes back in the same wrapping it arrived in, header line, context section and end marker unchanged, so the SDK reads the answer the way it reads history.+## Limits- The generation can be up to 100,000 characters.@@ -259,7 +293,7 @@ The endpoint returns the same error shape as the Chat Completions and Responses| Status | Type | When || ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |-| `400` | `invalid_request_error` | The last turn is not an assistant turn with a generation, a limit is passed, `library` is malformed, or `stream` is `true`. |+| `400` | `invalid_request_error` | The first message is not a library turn, or its block is malformed; the last turn is not an assistant turn with a generation; a limit is passed; or `stream` is `true`. || `401` | `authentication_error` | The API key is missing or invalid. || `429` | `rate_limit_error` | The organization has no credits, or billing is suspended. || `500` | `internal_server_error` | The fixing model could not be reached. Nothing is charged. |