limescape-plugin-sdk

The only contract between the Limescape AI Platform and node-type plugins in limescape-ai-plugins. Plugins import this package (plus their own declared dependencies) and never the platform itself.

A node type

src/node-types/<code>/
├── node-type.yaml     # manifest: the single source of metadata
├── node.py            # async def execute(ctx, inp)
├── i18n/nl.json       # translations (nl and en are required)
├── i18n/en.json
├── icon.svg           # optional; otherwise a Lucide name in the manifest
├── README.md
└── tests/
    ├── test_node.py
    └── golden/*.yaml  # required when the plugin takes over a builtin type

from limescape_plugin_sdk import NodeContext, NodeInput


async def execute(ctx: NodeContext, inp: NodeInput):
    response = await ctx.http.request("GET", inp.require_param("endpoint_url"))
    response.raise_for_status()
    yield {inp.output_key: response.json()}

• inp.params is flattened and {{ variables }} are resolved; keys are the field names from the manifest. A field with resolve_variables: false keeps its original value after variable validation, for plugins applying their own template renderer.
• Yield a dict or a list of dicts; everything must be JSON-serialisable.
• Raising an exception produces [{"error": "<message>"}], exactly like the builtin node types.
• Only capabilities declared under capabilities: are granted (log and trace always are).

Tooling

limescape-plugin validate [--check-imports]   # manifests, code, i18n, icons
limescape-plugin compat [--against <previous meta archive>]
limescape-plugin requirements                 # merged requirements for the lock
limescape-plugin build --version 1.4.2 --lock bundle.lock --wheels wheels/
limescape-plugin golden                       # replay golden cases
limescape-plugin schema                       # JSON Schema of node-type.yaml

limescape_plugin_sdk.testing provides FakeContext, run_node and the golden-case runner for unit tests.

Versioning

Independent semver, not tied to the platform version. While the SDK is 0.x a platform only runs bundles locked to the same minor version and not newer than its own SDK (versioning.is_bundle_sdk_supported).

SDK 0.2 additions

Declare capabilities: [websearch] to call await ctx.websearch.search(query, parameters={"num": 5}). The platform returns the Google Custom Search JSON response and supplies its configured credentials; plugins never receive the platform search key. FakeContext(websearch_responses=[...]) and golden cassettes support the same contract.

io.input_keys_validation defaults to platform. Set it to plugin only when the node must choose between alternative legacy inputs; the plugin then checks its selected keys. Required io.input_data keys are always platform-validated. Switching this field back to platform is a breaking manifest change.

ctx.trace.event(name, data) creates a child event in the current node trace. input_keys is available in inp.params; output routing remains in inp.output_key.

SDK 0.1 bundles do not run on an SDK 0.2 platform. Upgrade the platform and build all node types against 0.2 together before the first publication.

Licence

To be decided before the package is published.