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

Copyright (c) 2026 TrueLime.

Licensed under the European Union Public Licence v. 1.2 (EUPL-1.2).

SDK 0.2.2 credential selection and categories

await ctx.credentials.resolve(reference, mode="team", expected_type="...", oauth2=False) adds exact type-checked selection. Modes: team for a saved team code, personal for a saved personal code shared with every caller of the configured flow, and personal_type for the executing person's active credential of the selected type. The platform binds execution team and identity (user_id, user_email, email); plugins cannot override that scope. Missing, conflicting or ambiguous selections fail without falling back to another credential. The returned Credential includes its resolved instance reference, type name and values.

oauth2=True currently supports googleTagManagerOAuth2Api only. The platform refreshes and persists Google tokens; the plugin receives only accessToken and optional accountId/containerId/workspaceId. Other providers need their own platform implementation. get() retains its legacy team-only behavior.

For tests, use FakeContext(credential_resolver=handler), where handler accepts reference, mode, expected_type, oauth2 and returns a Credential or its dictionary representation. Legacy fake credential dictionaries do not implement personal resolution. Real authorization and token lifecycle require platform tests.

Category marketing_analytics adds the Marketing & Analytics palette group. The matching platform category and frontend translation must be deployed too.

This is an additive 0.2.x update: older 0.2.x bundles remain compatible. Publish this SDK and deploy its platform implementation before activating a bundle that uses resolve(). A newer SDK wheel alone does not implement the platform handler.