Plugin SDK

Package adapters as independent distributions with static manifests, metadata-only discovery, and explicit policy-checked loading.

PHASE 1 · PRE-1.0PYTHON 3.11+EDIT ON GITHUB ↗

Package layout

A plugin registers one factory in the lumis_sdk.plugins entry-point group and ships a strict static manifest, lumis-plugin.json, at distribution root (limited to 64 KiB). The manifest version must equal the installed distribution version, and entryPoint must equal the registered entry-point name:

json

{
  "apiVersion": "lumis.dev/v1",
  "kind": "PluginManifest",
  "metadata": { "name": "acme-evidence", "version": "1.2.0" },
  "spec": {
    "entryPoint": "acme-evidence",
    "capabilities": ["evidence_provider"],
    "supportStatus": "community",
    "sdk": { "minimum": "0.0.4", "maximumExclusive": "0.1.0" },
    "requiredAuthorities": ["network", "secrets"],
    "summary": "Collect bounded evidence from the Acme service."
  }
}

Factory contract

The entry point resolves to a zero-argument callable with a lumis_manifest attribute. Applications should normally wrap this shape in a typed callable class, as demonstrated by lumis_sdk.testkit.FakePluginFactory.

python

from lumis_sdk.domain import PluginManifest

MANIFEST = PluginManifest.model_validate_json(...)


def create_plugin() -> object:
    return AcmeEvidenceProvider(...)


create_plugin.lumis_manifest = MANIFEST

Discovery and loading

python

from lumis_sdk.adapters.plugins import ImportlibPluginCatalog
from lumis_sdk.domain import PluginAuthority, PluginLoadPolicy

catalog = ImportlibPluginCatalog()
descriptors = catalog.discover()  # metadata only; imports no plugin module

loaded = catalog.load(
    "acme-evidence",
    policy=PluginLoadPolicy(
        allowed_authorities=[PluginAuthority.NETWORK, PluginAuthority.SECRETS]
    ),
)
provider = loaded.instance

Discovery validates distribution identity, SDK compatibility, support status, capabilities, and authority requests without importing plugin modules. The default load policy allows declared capability surfaces but denies every sensitive authority—network, secrets, and the rest must be granted explicitly. Loading fails for missing or invalid manifests, incompatible SDK versions, archived plugins, duplicates, entry-point mismatches, manifest mismatches, and import or factory failures.

CLI inspection

shell

lumis plugins list
lumis plugins list --json
lumis plugins doctor
lumis plugins doctor --json

Both commands inspect static metadata only; they never load or activate plugins.

Contract testing

python

from lumis_sdk.testkit import assert_plugin_factory_contract

instance = assert_plugin_factory_contract(create_plugin, MANIFEST)

Capability-specific packages should additionally run the contract tests for the public port they implement—the evidence, report, and memory contracts all ship reusable assertions. The factory check does not prove network safety, credential handling, semantic correctness, or provider quality.