Generative UI API¶
ui ¶
Generative UI primitives — agents that design their own surface.
The agent emits a typed :class:UIComponentSpec; the frontend resolves
a renderer by component_type and hot-loads it. Subsequent state
updates flow as :class:UIDeltaEvent records on the same SSE stream.
See :doc:/concepts/generative_ui for the full picture; this module hosts:
- :class:
UIComponentSpec[T]+ :class:UIDeltaEvent+ :data:UIDeltaOp— the protocol primitives. - :class:
ComponentRegistry— per-Workbench schema registry. - :class:
UIEmitter— convenience facade for emitting init/delta/remove events on an :class:EventBus. -
First-party components organised in three layers:
-
Compositional primitives: :class:
PlanComponent, :class:ChartComponent, :class:TableComponent, :class:FormComponent, :class:TakeoverDialogComponent, :class:LayoutComponent, :class:TextComponent, :class:MarkdownComponent, :class:ImageComponent, :class:BadgeComponent, :class:ButtonComponent, :class:InputComponent, :class:StatTileComponent, :class:ChecklistComponent, :class:TimelineComponent, :class:MapComponent, :class:MediaComponent. - Declarative grammars: :class:
VegaChartComponent, :class:MermaidComponent, :class:LatexComponent, :class:JsonViewerComponent. - Sandboxed escape hatch: :class:
SandboxedHTMLComponent.
UIDeltaOp
module-attribute
¶
Op set for partial component updates.
replace— set value atpathtovalue(RFC 6902 replace).merge— shallow-mergevalue(a dict) into the dict atpath; if value-at-path is not a dict, behaves like replace.append— appendvalueto the list atpath. Required for streaming-append components (chart series, table rows).remove— delete the field/element atpath.valueignored.
BadgeComponentData ¶
icon
class-attribute
instance-attribute
¶
lucide-react icon name. The frontend resolves the symbol; if
the icon is unknown it falls back to label-only.
ButtonComponentData ¶
event_name
class-attribute
instance-attribute
¶
The event_type the frontend POSTs back when the button is clicked. The agent subscribes to this via the SSE bus + event-loop integration.
ChartComponentData ¶
config
class-attribute
instance-attribute
¶
Free-form renderer-specific knobs (axis formatters, colour scheme, etc.). Not load-bearing for the protocol.
ChartSeries ¶
One labelled data series. Points are dicts so the renderer can
pick out the relevant axes (e.g. {"x": ..., "y": ...}).
ChecklistComponentData ¶
action
class-attribute
instance-attribute
¶
ui.action name the renderer sends when an item is ticked.
FormComponentData ¶
submit_event
class-attribute
instance-attribute
¶
The event_type the frontend should emit (back to the agent) on submission. Decoupled from the component_type so multiple forms can share a single rendering path.
FormField ¶
options
class-attribute
instance-attribute
¶
For select / multiselect — the available choices.
InputComponentData ¶
JsonViewerComponentData ¶
LatexComponentData ¶
content
instance-attribute
¶
LaTeX source rendered via KaTeX. Use display=True for block
math, False for inline.
LayoutComponentData ¶
LessonStepComponentData ¶
MarkdownComponentData ¶
content
instance-attribute
¶
GFM markdown — tables, code, links, images. Frontend uses react-markdown + remark-gfm + the existing CodeBlock renderer.
MediaComponentData ¶
MermaidComponentData ¶
diagram
instance-attribute
¶
Mermaid source. flowchart / sequence / classDiagram / erDiagram / gantt / mindmap / etc.
PathwayComponentData ¶
action
class-attribute
instance-attribute
¶
action: str | None = Field(
default=None,
description="ui.action name the renderer sends when the pathway is opened.",
)
ui.action name the renderer sends when the pathway is opened.
PlanComponentData ¶
Data payload — list of :class:PlanTask records.
SandboxedHTMLComponentData ¶
html
instance-attribute
¶
Raw HTML / SVG / restricted JS. Rendered in an iframe with sandbox="allow-scripts" and a strict CSP. No parent-document access, no network unless allowed via the iframe csp.
height_px
class-attribute
instance-attribute
¶
Fixed height in CSS pixels — iframes don't auto-size.
csp_extra
class-attribute
instance-attribute
¶
Additional CSP directives merged onto the default. Empty by default.
StatTileComponentData ¶
trend
class-attribute
instance-attribute
¶
Signed change versus the previous period.
TableColumn ¶
TakeoverDialogData ¶
choices
class-attribute
instance-attribute
¶
For choice kind — the offered options.
VegaChartComponentData ¶
spec
class-attribute
instance-attribute
¶
Full Vega-Lite spec (https://vega.github.io/vega-lite/). The frontend imports vega-embed and renders. The agent emits the JSON directly — Vega-Lite syntax is well-documented and the LLM is typically familiar with it.
UIEmitter ¶
Facade for publishing :class:UIComponentSpec and
:class:UIDeltaEvent events on a :class:EventBus.
Source code in orqest/ui/emitter.py
init
async
¶
Emit ui.<component_type>.init for a fresh component.
Returns the emitted :class:AgentEvent for the caller to log /
record, or None when no bus is configured. Bus failures
log at DEBUG and return None.
Source code in orqest/ui/emitter.py
delta
async
¶
delta(
*,
component_id: str,
component_type: str,
op: UIDeltaOp,
path: str = "",
value: Any = None,
agent_name: str | None = None,
) -> AgentEvent | None
Emit ui.<component_type>.delta with a partial update.
Source code in orqest/ui/emitter.py
remove
async
¶
remove(
*,
component_id: str,
component_type: str,
agent_name: str | None = None,
) -> AgentEvent | None
Emit ui.<component_type>.remove so the frontend
unmounts the component.
Source code in orqest/ui/emitter.py
ComponentRegistry ¶
Maps component_type → :class:UIComponentSpec subclass.
Source code in orqest/ui/registry.py
register ¶
Register a concrete :class:UIComponentSpec subclass.
Reads the component_type Literal default off spec_class;
the discriminator must be set on the class (not the instance).
Re-registering the same component_type is a no-op unless
overwrite=True (the prior class is logged at WARN).
Source code in orqest/ui/registry.py
get ¶
list_types ¶
validate_payload ¶
Hydrate a raw dict against the registered spec.
Returns None on lookup miss or validation failure (logged
at WARN). Best-effort — UI validation should never break agent
execution.
Source code in orqest/ui/registry.py
UIComponentSpec ¶
Generic init payload for a frontend-renderable component.
Subclasses MUST override component_type with a unique
:class:Literal value so the frontend resolver can pick a renderer.
The data field carries the typed payload the renderer reads.
The schema is intentionally minimal: every concrete component
inherits the same envelope (component_type, component_id,
data, metadata, created_at) so the SSE protocol and the
frontend resolver can be component-agnostic.
to_event_data ¶
UIDeltaEvent ¶
Targeted partial update to a previously-emitted :class:UIComponentSpec.
path is a dot-path into data (root = empty string). For list
operations, integer indices may appear in the path (e.g.
"tasks.0.status"). Frontend implementations apply the op
against the previously-rendered component identified by
component_id. A delta whose component_id is unknown, or whose
component_type differs from the rendered component's, means the
renderer is out of sync: it must refetch the snapshot rather than
guess. :func:orqest.ui.view.apply_deltas raises ValueError in
both cases; that is the reference form of this signal.
BindingError ¶
A binding path does not resolve in the given context.
Hints ¶
Presentation hints. Assistants never set colours, fonts or spacing.
ResolvedView ¶
A view rendered against a context.
ViewNode ¶
One node of a view tree.
Unknown keys are rejected (a typo such as props for data fails
instead of being dropped).
bindings
class-attribute
instance-attribute
¶
Top-level data field name -> binding path into the context.
ViewSpec ¶
A named, versioned screen definition.
Unknown keys are rejected. The root must be a layout, node ids must be
unique, and a view holds at most :data:MAX_VIEW_NODES nodes nested at
most :data:MAX_VIEW_DEPTH deep.
default_registry ¶
A :class:ComponentRegistry pre-loaded with first-party components.
Three layers of generative-UI primitives ship in core:
- Compositional — :class:
PlanComponent, :class:ChartComponent, :class:TableComponent, :class:FormComponent, :class:TakeoverDialogComponent, :class:LayoutComponent, :class:TextComponent, :class:MarkdownComponent, :class:ImageComponent, :class:BadgeComponent, :class:ButtonComponent, :class:InputComponent, :class:StatTileComponent, :class:ChecklistComponent, :class:TimelineComponent, :class:MapComponent, :class:MediaComponent, :class:PathwayComponent, :class:LessonStepComponent. The agent composes these to build arbitrary UI. - Declarative grammars — :class:
VegaChartComponent, :class:MermaidComponent, :class:LatexComponent, :class:JsonViewerComponent. Thin wrappers around external grammars; the agent emits the spec. - Sandboxed escape hatch — :class:
SandboxedHTMLComponent. The agent writes raw HTML/SVG; the frontend confines it in an iframe. The component registers in core unconditionally; consumers gate rendering / emission via their own config flag.
Source code in orqest/ui/registry.py
105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 | |
apply_deltas ¶
apply_deltas(
blocks: dict[str, dict[str, Any]],
deltas: list[UIDeltaEvent],
) -> dict[str, dict[str, Any]]
Reference applier for :func:diff_view output; returns a new block map.
Supports exactly the ops diff_view emits (top-level replace and
remove). An unknown op, an unknown component id or a
component_type that differs from the block's raises
:class:ValueError: the reference form of the renderer's "refetch the
snapshot" signal (see :class:orqest.ui.spec.UIDeltaEvent).
Source code in orqest/ui/view.py
diff_view ¶
Compute top-level-field deltas turning old into new.
Both resolutions must come from the same spec: diff_view ignores
child order and hints, so a caller must re-init when the spec changes (as
:class:orqest.assistants.live_views.LiveViews does). Returns None
when a full re-init is required: the view name or version differs, the
block id sets differ, or any block changed component_type (for
example a placeholder that became a real block). Otherwise returns one
replace per changed or added top-level data key and one remove per
dropped key, ordered by block id then key. Metadata is not diffed (hints
only change with the spec version).
Source code in orqest/ui/view.py
fallback_view ¶
A minimal view that shows the raw state in a JSON viewer.
Source code in orqest/ui/view.py
iter_nodes ¶
Yield node and every descendant, depth-first in child order.
node_problems ¶
node_problems(
spec: ViewSpec,
registry: ComponentRegistry,
context: dict[str, Any],
) -> list[tuple[str, str]]
Return (node id, problem) for each problem :func:resolve_view reports.
The same problems as :attr:ResolvedView.problems (rendered nodes only,
every cause), each paired with the id of the node it degraded.
Source code in orqest/ui/view.py
resolve_path ¶
Walk dict keys and integer list indices; raise :class:BindingError on a miss.
Source code in orqest/ui/view.py
resolve_view ¶
resolve_view(
spec: ViewSpec,
registry: ComponentRegistry,
context: dict[str, Any],
) -> ResolvedView
Render spec against context. Degraded nodes become placeholders; never raises.
unresolved_bindings ¶
unresolved_bindings(
spec: ViewSpec,
registry: ComponentRegistry,
context: dict[str, Any],
) -> list[str]
Return one line per binding that does not resolve in context.
These are warnings, not problems: such nodes render as placeholders until the data exists. Bindings inside a subtree that is not rendered (under a degraded layout) are included.
Source code in orqest/ui/view.py
validate_view ¶
Return structural problems only (unknown types, binding keys that are not fields of the block's data model, invalid data).
Bindings that do not resolve in context are not reported: they degrade to placeholders at render time and may resolve later. For such nodes the literal data is still checked (errors on bound fields are ignored), the type is still checked, and children are still visited.