3lc-compute-plugin-sdk

Plugins are how you extend the 3LC Hub — your own importers, exporters, training jobs, and data tools, appearing in the Hub right next to the built-ins. This SDK is everything a plugin needs: one small Python package to program against, while the Hub takes care of discovery, isolation, serving, and job orchestration.

pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk

Distribution 3lc-compute-plugin-sdk · import tlc_plugin_sdk.

What it gives you

• ComputePlugin — the base class you subclass. Implement get_ui_fragment (and compute if you expose a synchronous endpoint); job and lifecycle hooks ship as safe defaults. There is no register() to call — a plugin's metadata lives in its plugin.toml manifest (or a [tool.tlc-compute] table in pyproject.toml), and the Hub discovers it from there.
• JobContext — the surface a long-running job programs against: progress / metric / log / result for the generic job panel, emit for your plugin's own rich UI, and cooperative cancelled.
• The worker (python -m tlc_plugin_sdk.worker) — serves your plugin's Litestar route handlers + the generic reserved routes as an ASGI app, out-of-process in the plugin's own venv.
• tlc_plugin_sdk.shared.* — batteries the heavy plugins share: URL-alias registration, config storage/UI, the generic-job helpers, image/label/modality utilities, script injection.

Quickstart

See docs/plugin-guide.md for the full author guide (manifest format, custom routes, the job model, UI fragment, checklist).

The contract version

tlc_plugin_sdk.SDK_CONTRACT_VERSION is this package's own version — one source of truth, one contract axis (both the Python and the browser surface). A plugin pins the SDK (3lc-compute-plugin-sdk>=X,<Y); the compute service and frontend implement a range and compare compatibility on MAJOR.MINOR. Versions are SemVer; see Status below for the 0.x stability stance.

How it fits

This SDK sits at the root of the plugin dependency graph. Its only required dependencies are uvicorn and litestar; the 3lc data plane is an optional extra (3lc-compute-plugin-sdk[shared]), pulled in only by the shared.* helpers. It never depends on the compute service itself or on any plugin. A plugin built against tlc_plugin_sdk alone is therefore portable across service versions and runs in its own isolated environment.

Status

0.3 is the current contract line. Within 0.x the contract still evolves — mostly additively, but a coordinated breaking change may land on a MINOR bump while the fleet re-pins in lockstep (0.3 did: JobContext.result took a positional url, and the PY_CONTRACT/JS_CONTRACT axes collapsed into SDK_CONTRACT_VERSION). Anything reshaping the core still waits for a major bump. In the browser bridge, PLUGIN_API.libs.io is a stable part of the contract; the other bundled libs are best-effort (see the guide).