Metadata-Version: 2.5
Name: limescape-plugin-sdk
Version: 0.2.0
Summary: Contract between the Limescape AI Platform and node-type plugins
Author-email: Mohamed Ikhlaf <mohamed.ikhlaf@truelime.nl>, Rodger Blom <rodger.blom@truelime.nl>, Hans van der Linden <hans.vanderlinden@truelime.nl>
Requires-Python: >=3.11
Requires-Dist: packaging>=23
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6
Description-Content-Type: text/markdown

# limescape-plugin-sdk

The only contract between the Limescape AI Platform and node-type plugins in
[`limescape-ai-plugins`](https://github.com/TrueLimeNL/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
```

```python
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.
