Every extension point

The contribution model Available

A package is plain Python. Two mechanisms cover almost everything:

• Auto-registration — define a Step or Entity subclass (or a decorated function) and importing the module registers it. No boilerplate.
• register(host) — an optional function in your package's __init__.py. It receives a PackageHost and pushes contributions (CLI commands, menus, views) via contribute(...).

from lsdtools import contribute, CliCommand, MenuItem, ViewContribution

def register(host):
    contribute(
        CliCommand("hello", "say hi", run=lambda a: print("hi")),
        MenuItem("Do it", callback=do_it, menu="run"),
        ViewContribution("my.panel", "My Panel", make_widget, location="sidebar"),
    )

Core (lsd) holds contributions in a registry; each front-end renders what it supports — the desktop renders views/menus, the CLI wires commands — so lsd itself imports neither GTK nor argparse.

1 · Steps Available

The unit of work. Decorate a function or subclass a base; both auto-register and appear in the Add step picker. (Full walkthrough in the Quickstart.)

Advanced step features

class Join(ShapeStep):
    input_ports  = ["main", "lookup"]
    output_ports = ["joined"]
    key = param(str, default="id")
    def run(self, inputs):
        return inputs.main.join(inputs["lookup"], keys=self.key)

2 · Entities Available

Entities are the nodes in the project tree that hold steps. Subclass Entity to add a new creatable type — it appears in the desktop's Add entity menu and lsd entity add automatically.

from lsdtools import Entity, param

class Dataset(Entity):
    create_label = "Dataset"            # menu label (defaults to class name)
    source_url   = param(str, required=True, label="Source URL")
    icon         = param(str, default="lsd-folder-symbolic")

from lsdtools import EntityAction

class Dataset(Entity):
    def get_actions(self):
        return [EntityAction("Refresh", callback=self._refresh, icon="lsd-refresh-symbolic")]

3 · Parameters & widgets Available

param() declares an input on a step or entity. The desktop renders an appropriate control; the CLI renders a flag. One declaration, both front-ends.

amount  = param(float, default=1.0, min=0, max=10, label="Amount", group="Tuning")
mode    = param(str, choices=["fast", "accurate"], default="fast")
notes   = param(str, widget="textarea", visibility="advanced")
secret  = param(str, widget="password")
folder  = param(str, widget="dir")

Built-in form controls Available

The desktop maps each parameter to one of: text, multiline, numeric, checkbox, combo, file, directory, plus action controls (button, split-button, menu-button).

4 · CLI commands Available

Add a lsd <name> subcommand. configure(parser) adds arguments; run(args) executes and returns an exit code. Available to both lsd and the installed LSDCli.

from lsdtools import CliCommand, contribute

def _configure(p): p.add_argument("model", help="path to a .onnx file")
def _run(args): print("inspecting", args.model); return 0

def register(host):
    contribute(CliCommand("inspect-model", "summarise an ONNX graph",
                          configure=_configure, run=_run))
# → lsd inspect-model model.onnx

5 · Desktop menus & actions Available

MenuItem — a labelled action

Contributed items appear under the desktop's Extensions menu.

contribute(MenuItem("Export report…", callback=export, menu="run", icon="lsd-save-symbolic"))

EngineAction — context-aware menu/CLI action

Returned from a desktop/menu/build handler (with the live engine in the payload), so the action can depend on the current project. menu places it in file / run / edit; supports an icon, a keyboard shortcut, and a create spec for “add entity” flows.

from lsdtools import EngineAction

async def on_menu_build(event):
    engine = event.data.get("engine")
    if engine is None: return []
    return [EngineAction("Run & Export", callback=lambda: run_export(engine),
                         menu="run", shortcut="<Control>e")]

def register(host):
    host.on("desktop/menu/build", on_menu_build)

EntityAction — entity context menu

See Entities — get_actions() adds right-click items per entity.

6 · Custom UI panels Available

Add a panel to the desktop — an editor tab or a sidebar section. The common way is declarative: describe fields + actions as data and LSD renders them with its own controls — no GTK import in your package. Action callbacks receive the panel's current field values.

from lsdtools import Panel, Field, Action, panel_view, contribute

def _greet(values):                # {field name → current value}
    print("hello", values["name"], values["times"])

def register(host):
    panel = Panel(
        title="Greeter",
        fields=[Field("name", default="world"),
                Field("times", kind="int", default=1, min=1, max=10)],
        actions=[Action("Greet", _greet, style="suggested-action")],
    )
    contribute(panel_view("my.greeter", "Greeter", panel, location="sidebar"))

Field kinds: text, password, textarea, int, float, bool, file, dir, or any field with choices=[…] (a dropdown). Same controls the inspector uses.

Escape hatch — a raw widget Available

Need something the declarative panel can't express? Contribute a factory() that returns any GTK 4 widget. Full power; couples that package to GTK (as the built-in DL viewer does).

from lsdtools import ViewContribution, contribute

def make_panel():
    import gi; gi.require_version("Gtk", "4.0")
    from gi.repository import Gtk
    return Gtk.Label(label="Anything you can build in GTK")

def register(host):
    contribute(ViewContribution("my.custom", "Custom", make_panel, location="editor"))

7 · Events Available

Subscribe to the app's lifecycle with host.on(event, handler) inside register. Handlers are async-capable and receive Event(type, data).

Pipeline & engine events

Desktop events

8 · Host services Available

register(host) receives a PackageHost. It transparently proxies the event bus (host.on/emit) and exposes optional services so a package can act on the app without importing the desktop:

def register(host):
    eng = host.engine                 # current project's engine (or None)
    host.notify("Indexing finished", "info")
    host.open_in_editor("steps.py")    # open a file in the code editor
    host.request_reload()             # ask the app to reload project scripts

9 · Step hooks & agents Available

The lsd-agent package wraps pipeline execution with hooks — for human-in-the-loop approval, auditing, or AI assistance — without changing your steps.

from lsd_agent import run_with_hooks, HITLHook, AuditHook

run_with_hooks(engine, "sales", hooks=[HITLHook(), AuditHook()])
# HITLHook pauses for approval before each step; AuditHook records what ran.

Write your own by subclassing BaseHook (pre/post-step callbacks with a StepContext).

AI step generation Available

Describe a step in plain English and have it written for you. The public lsdtools.generate_step bridges to the private lsd-agent engine, which calls Claude with your project's live API context (the same cheat-sheet from §10) so the output uses exactly the steps and params available here. The generated step lands in your steps.py and hot-reloads.

from lsdtools import generate_step
generate_step("a deliver step that writes inputs.main to a parquet file", project_dir=".")

In the desktop: Develop → Generate Step with AI…. From the terminal: lsd ai "keep the top 100 rows by value". Needs an ANTHROPIC_API_KEY (or pass a custom completer=).

10 · Packaging & lifecycle Available

Roadmap — what's proposed Proposed

The plan, distilled from the gaps above. Review and we'll prioritize, then implement.

← Back to the Quickstart · Create an account →