# lsdtools API reference
URL: https://lsd.tools/docs/api-index
Updated: 2026-07-18

> lsdtools is the small, stable public API you author LSD tools against — about three dozen names, one rule (import only lsdtools). This page routes you to a reference for every public class, grouped by what you are doing.

`lsdtools` is the small, stable public API you author LSD tools against. It has about three dozen
names and one rule: **import only `lsdtools`**. Everything under `lsd.*` is private engine internals
that may change between releases.

## Usage

```python
from lsdtools import Tool, Table, Engine, API_VERSION

API_VERSION
# → "2.1"
```

Everything you author with lives in that one namespace. This page routes you to a reference for each
public class; for the narrative versions, start at [What is LSD?](/docs/start-overview).

## The public surface

`from lsdtools import ...`:

- **Authoring** — `Tool` · `Context` · `StepContext`
- **Views (params + actions + data)** — `View` · `action` · `param` · `validators` · `views`
- **Domain** — `EntityAction` · `EntityTemplate` · `FileRole` · `columnmap_param` ·
 `parse_column_map` · `resolve_column_map` · `apply_column_map` · `parse_source` ·
 `autoselect_largecsv_source` · `Events`
- **Data** — `Table` · `Source`
- **Runtime / interop** — `Entity` · `Engine` · `RunResult` · `Runtime` · `find_runtime` · `API_VERSION`
- **Errors** — `ValidationError` · `SchemaError`
- **Meta** — `describe_api` · `advanced` · `generate_step`

Reach past this line — into `lsd.*` — only through [`lsdtools.advanced`](/docs/api-advanced), and
only for the few things it documents.

## Authoring

- [Tool](/docs/api-tool) — the one object per package; its `@tool.*` decorators turn functions into
 nodes, commands, and views.
- [Context](/docs/api-context) — `StepContext` (progress, cancel, outputs) and `Context` (host,
 engine, project, UI) that LSD injects into your functions.
- [Source](/docs/api-source) — the input a load step reads: files, folders, or a SQL query.

## Data

- [Table](/docs/api-table) — the immutable, zero-copy Arrow wrapper that flows between steps, plus
 its `Column` expressions and its `Table(...)` constructor.

## Runtime

- [Engine](/docs/api-engine) — run pipelines in Python; returns a `RunResult`.
- [Runtime](/docs/api-runtime) — locate the installed LSD product; `find_runtime()` and `API_VERSION`.

## Views

- [View](/docs/api-view) — the one presentable surface: `param()` fields + `@action` + optional data,
 with the [`watch`](/docs/api-view-watch) verb that links it to an entity's output.
- [ViewerPayload](/docs/api-viewerpayload) — what a viewer-delivering `@tool.deliver` returns
 (`LayerPayload` / `ChartPayload` / `LegendPayload`); the framework routes it to whatever view watches
 the entity. See [Rendering & payloads](/docs/tools-rendering).
- [UI overview](/docs/ui-overview) — the one `View` model (params + `@action` + optional data), and
 how it shows: a window with the desktop, console text when headless.
- [A View of params and actions](/docs/ui-panels) — `@tool.view` returns a `View` with no kind:
 `param()` fields plus `@action` buttons. `location=` (sidebar / overlay / editor) only sets where it shows.
- [Data views](/docs/ui-widgets) — `@tool.view` returns a data `View`: a `table`, `chart`, or
 `flowchart` from `lsdtools.views`, or a custom `View` subclass.
- [Custom views](/docs/ui-custom-views) — a hand-written `View` whose GTK shell registers through
 `lsdtools.views`.

## Packaging

- [PackageManager](/docs/api-package-manager) — the desktop-side API behind the Package Manager.
- [lsd_package.json](/docs/api-manifest) — the manifest that makes a folder a package.
- [CLI commands](/docs/api-cli) — `lsd package`, `lsd <tool> <cmd>`, `lsd api`.

## Meta

- [Errors](/docs/api-errors) — `ValidationError` and `SchemaError` and when each is raised.
- [describe_api](/docs/api-describe) — machine-readable JSON of every registered step.
- [lsdtools.advanced](/docs/api-advanced) — the escape hatch to `lsd` internals.

## Related

**Learn** — [What is LSD?](/docs/start-overview) · [The Tool object](/docs/tools-tool-object) · [Params vs ports](/docs/tools-params-ports)

**API** — [Tool](/docs/api-tool) · [Table](/docs/api-table) · [Engine](/docs/api-engine)

**Examples** — [Your first tool](/docs/ex-hello-tool)