Naming: which is which

Why this page exists#

A handful of LSD words are overloaded. The meaning is always clear from context in the code, but the words alone can be ambiguous when you are new or reading an error. Here is each one, pinned.

"View"#

A @tool.view factory returns a View — the same class you subclass yourself or get from the views façade. There is no separate wrapper: a view is the object you show().

"Panel"#

• @tool.view(..., location="sidebar") — a decorator whose factory returns a View (params
  • @action, no kind). The desktop docks it in the sidebar.
• The word "panel" in Desktop is a placement term; there is no separate Panel class in the authoring API. Viewer overlays have their own declared extension surface and do not use @tool.view(location="overlay").

So: a panel is a View with no kind. If you are authoring one, you write a View subclass.

"Table" vs "pa.Table" vs "views.table"#

• Table — the one class and constructor: an immutable, zero-copy wrapper around one Arrow table with a small verb list (with_column, filter, join, group_by, sort, print…). Build one with Table({...}), Table([{...}, …]), Table(df), or Table(pa_table); read files with Table.read_csv / Table.read_parquet.
• There is no lowercase table(...) factory — the constructor absorbed it. Two look-alikes remain and are not the LSD class: pa.table(...) is pyarrow's own constructor, and views.table(...) is the data-view façade that wraps a Table for display.
• pa.Table — raw pyarrow. .arrow on a Table is the zero-copy escape hatch out to it (and Table(pa_table) brings one back in). A step parameter annotated Table or pa.Table is an input port.

"Workspace"#

engine.workspace is the domain workspace: it owns the entity forest, identity resolution, hierarchy and event bus. Add an entity with engine.workspace.add(entity), then run it with engine.run(entity.id). Engine.add(view) attaches views; it does not add entities.

engine.artifact_workspace is the separate run / cache directory where step outputs land. This ArtifactWorkspace is path-compatible and provides .exists, .size(), .dir_for(entity) and .clean(). Engine() creates a temporary artifact directory; pass Engine(artifact_workspace="./runs") to choose one. Open a saved project with Engine.load("project.lsd"), not by passing a filename as the Engine constructor's workspace.

A participant's UI workspace is their arrangement of view tabs. It is distinct from the domain workspace, artifact directory, saved project document and Local package authoring directory.

"Entity"#

• Entity — the base class: a node that owns an ordered list of steps. You subclass it (or use @tool.entity) to define a domain type.
• @tool.entity — registers a creatable entity type (a builder function, or a hand-written Entity subclass).
• @tool.template (an EntityTemplate) — a recipe that turns dropped file(s) into a ready-wired entity in the import wizard.

Configurable → View#

A short inheritance chain underlies the authoring surface, which is why params behave the same everywhere:

• Configurable — anything with param() fields (steps, entities, the engine — all of them).
• View — a Configurable that also has @action buttons and optional data (feed / to_text / to_image). With no kind it renders as a form (a panel); with a kind (table/chart/flowchart/custom) it represents data.

Steps are Configurables, not Views — they have parameters but no @action. That they render in the same inspector as a View is because both are Configurable.

"watch" — the View↔Entity verb#

view.watch(entity) is the one verb that links a view to an entity: the view holds that entity's output and refreshes on every re-run. It is the symmetry partner of an entity's run — engine.workspace.add plus run_all() moves data, engine.add(view) plus show() presents it, and watch is the wire between them.

• It takes an Entity, a stable entity id, or an unambiguous display name. An unresolved string stays pending until that entity is added to the domain workspace. Watching can happen before or after the view is attached to the engine.
• The framework does the bus wiring — you never call bus.on(...) to feed a view.
• Watching an entity that has already run pulls its output immediately (what makes drag-and-drop and a reopened project feel instant).
• It returns the view, so views.table(title=...).watch(entity) reads as one phrase.

The desktop's drag-drop, the 3-D checkbox, and right-click "Show in ▸" are all sugar over this one verb. (Do not confuse it with on_view_event — a view-local UI observer — or the low-level event bus.)

"ViewerPayload" — what a deliver returns#

A ViewerPayload is the object a @tool.deliver step returns to show a result (symmetric to how a @tool.load step takes a src: Source). The framework writes any tables to Parquet, persists a *_payload.json sidecar, stamps entity_id / step_id, and emits the payload's topic — routing it to every view that watches the entity. You never hand-roll ctx.emit("viewer/...").

A payload return is for the terminal deliver artifact. Live, mid-run signals (progress, a training epoch) stay ctx.emit custom events. See Rendering & payloads and Deliver steps for the full story.

Related#

Learn — The Tool object · Tables & data flow · Contributing UI

Start — How an LSD package fits together