Skip to content

The Open Standard for Generative UI

Update the streaming protocol / data format documentation (#121)

Hrijul Bhatnagarfe396d72a2ea
diff --git a/docs/docs/concepts/003-data-format.mdx b/docs/docs/concepts/003-data-format.mdx
index 02658dd45..792496cf5 100644
--- a/docs/docs/concepts/003-data-format.mdx
+++ b/docs/docs/concepts/003-data-format.mdx
@@ -1,28 +1,87 @@
# Streaming Protocol
To enable streaming of both text and UI, Crayon uses a standard
-streaming protocol inspired from [AI SDK's streaming protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol) as described here. This stream defines the format of the data that is sent to the client. It is a simple text stream with a few special tokens that is agnostic of the backend language or the LLM model used.
+streaming protocol that utilizes Server-Sent Events (SSE). This protocol defines the format of the data that is sent to the client. It is a simple text stream with specific event types that is agnostic of the backend language or the LLM model used.
-You can implement this protocol in your custom backend and integrate it with Crayon to build your own. For example you can use a Python FastAPI backend that integrates with Deepseek models and use Crayon to build a UI for it.
+You can implement this protocol in your custom backend and integrate it with Crayon to build your own. For example, you can use a Python FastAPI backend that integrates with custom models and use Crayon to build a UI for it.
-### Text Part
+:::info
+All of the types referred to in this guide can be found [here](https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/types.ts).
+:::
+
+## Event Types
+
+The protocol supports several types of events as defined in the `SSEType` enum:
+
+```typescript
+export enum SSEType {
+ TextDelta = "text",
+ ResponseTemplate = "tpl",
+ ResponseTemplatePropsChunk = "tpl_props_chunk",
+ ContextAppend = "context_append",
+ MessageUpdate = "message_update",
+ Error = "error",
+}
+```
+
+### Text Delta
+
+A `TextDelta` represents a unit of text in the stream:
+
+```typescript
+event: text
+data: <text content>
```
-0:<text>
+
+Multiple consecutive text deltas are appended to the stream as they are generated to create a single text block.
+
+### Response Template
+
+A `ResponseTemplate` defines a UI component to render, with a name and optional properties:
+
+```typescript
+event: tpl
+data: {"name": "<template name>", "templateProps": <response template props>}
```
-A simple text chunk is prefixed with `0:`.
-Multiple consequtive text chunks are appended to the stream as they are generated to create a single
-text block.
-### Response Template Part
+The template name refers to a registered UI component, and the properties are passed to that component.
+
+### Response Template Properties Chunk
+
+`ResponseTemplatePropsChunk` allows for streaming of the props for a response template:
+
+```typescript
+event: tpl_props_chunk
+data: <response template props chunk>
```
-1:{name: <name>, templateProps: <templateProps>}
+
+### Context Append
+
+`ContextAppend` adds a new context item to the conversation:
+
+```typescript
+event: context_append
+data: <JSON context item>
```
-A response template is prefixed with `1:`. It contains the name of the template and the props to pass to it.
-Multiple response templates can be sent in a single stream.
-### Context Part
+### Message Update
+
+`MessageUpdate` sends an update about a specific message by ID:
+
+```typescript
+event: message_update
+data: {"id": "<message ID>"}
```
-8:{context}
+
+### Error
+
+`Error` provides information about errors during streaming:
+
+```typescript
+event: error
+data: <error message>
```
-A context is prefixed with `8:`.
-Multiple consequtive context parts can be sent in a single stream.
+
+## Encoding
+
+The protocol uses the `eventsource-encoder` package to properly encode the SSE events, ensuring they follow the correct format with appropriate event types and data fields.