# Tool.deliver
URL: https://lsd.tools/docs/api-tool-deliver
Updated: 2026-07-17

## Parameters

| name | type | default | description |
|---|---|---|---|
| `outputs` | `list[str]` | `None` | named output ports for a delivery that also forwards data |
| `graph_outputs` | `dict` | `None` | `{name: type}` read-only scalars set via `ctx.set_output(...)`, excluded from the cache key |
| `overrides` | `str` | `None` | make this a drop-in variant of another package's node |
| `override_mode` | `str` | `"replace"` | `"replace"` wins the overridden identity by default; `"coexist"` keeps both addable |

## Contract

A deliver takes a `Table` input port and either performs a **side effect** (returns `None`) or
**returns a [`ViewerPayload`](/docs/api-viewerpayload)** to show a result. The **return annotation**
decides which: `-> None` is a pure side effect; `-> ViewerPayload` (or a subclass — `LayerPayload` /
`ChartPayload` / `LegendPayload`) makes it a viewer-delivering step. A `ViewerPayload` return is only
valid on `@tool.deliver`.

## Example

Write a file — a side effect that returns nothing:

```python
@tool.deliver
def to_csv(t: Table, path: str) -> None:
    t.write_csv(path)
```

Show a result — return a payload; the framework persists it, stamps `entity_id` / `step_id`, and
emits its topic to every `View` that `watch`es the entity:

```python
@tool.deliver
def points(t: Table) -> LayerPayload:
    return LayerPayload(kind="points", tables={"path": t}, style={"color": "grade"})
```

## Notes

On a returned payload the framework writes each of the payload's tables to Parquet, persists a
`*_payload.json` sidecar (reconstructed generically on reopen), and emits the payload's `topic` — you
never hand-roll `ctx.emit("viewer/...")`. A viewer-delivering step also gains three optional `"Viewer"`
routing parameters (`layer` / `view` / `target`). A `StepContext` parameter may be injected for
`ctx.output_dir` / `ctx.emit`; a `Context` parameter is rejected. `override_mode` is `"replace"`
(default) or `"coexist"`.

## See also

**API:** [load](/docs/api-tool-load) · [shape](/docs/api-tool-shape) · [ViewerPayload](/docs/api-viewerpayload) · [Context](/docs/api-context)

**Guides:** [Deliver steps](/docs/tools-deliver) · [Rendering & payloads](/docs/tools-rendering)