API reference¶
The public surface of tlc_plugin_sdk. Everything below is generated from the
package’s own docstrings.
The contract¶
- class tlc_plugin_sdk.ComputePlugin[source]¶
Bases:
ABCBehavior-only base class for a compute-service plugin (host or venv).
Subclass and implement at least
get_ui_fragment(). The optional hooks below (compute,run_job, lifecycle, routes) ship as safe defaults, so the host can call any of them directly without probing for the method first.- Variables:
id (str) – Unique slug (e.g.
run-insights). Identity only, hydrated onto the instance from the manifest by the host; the rest of the plugin’s metadata also comes from its manifest, never from the instance.
- abstractmethod get_ui_fragment() str[source]¶
Return a self-contained HTML+JS+CSS fragment for the plugin UI.
- compute(params: dict[str, Any]) dict[str, Any][source]¶
Execute the plugin’s synchronous
GET /computecomputation.Override to expose a synchronous compute endpoint; the default returns an error dict so a plugin that only serves a UI and/or jobs need not implement it. Long-running work belongs in
run_job(), not here.- Returns:
A JSON-serializable dict. The default is
{"error": f"{id} does not implement compute()"}.
- initialise_runtime() None[source]¶
Initialise the plugin’s runtime resources (runners, stores, models).
Called once after the shared GPU queue is ready. Default is a no-op.
- shutdown_runtime() None[source]¶
Tear down the plugin’s runtime resources.
Must be safe to call on a plugin that was never initialised. Default is a no-op.
- run_job(ctx: JobContext) None[source]¶
Run a long-running job against a host-provided context.
The plugin reports progress/metrics and polls cancellation via
ctx; the code runs in the plugin’s worker and only ever touchesctx.- Raises:
NotImplementedError – The default — a plugin that streams jobs must override this.
- get_route_handlers() list[Any][source]¶
Return the plugin’s custom routes as relative Litestar route handlers.
Each handler’s path is relative to the plugin’s mount point
/api/plugins/{plugin_id}/(e.g. a@get("/models")handler servesGET /api/plugins/{plugin_id}/models). The handlers are served by the plugin’s own Litestar app in its worker, reverse-proxied by the host (seetlc_plugin_sdk/asgi_app.py); Litestar runsdefhandlers in a threadpool, so a synchronous, blocking custom route does not block the event loop. The reserved routes (/run,/health,/ui,/compute,/jobs/*, and the host admin routes/provision/reload/venv/worker/stop) are host-owned — a plugin must not define them. Empty by default.
- class tlc_plugin_sdk.JobContext(job_id: str, params: dict[str, Any], state_dir: Path, *, sink: Callable[[dict[str, Any]], None], cancel_event: threading.Event)[source]¶
Bases:
objectHost-provided context a plugin uses to drive one job.
- Parameters:
job_id – Unique id for this job.
params – Job parameters (parsed request body / query).
state_dir – Writable per-plugin scratch dir that survives a venv reinstall/reload (plugins must not write inside their package dir).
sink – Callable invoked with each emitted event dict.
cancel_event – Set by the host/worker to request cooperative cancellation.
- progress(*, percent: float, label: str = '', timing: dict[str, Any] | None = None) None[source]¶
Report progress with an optional label and timing dict.
- Parameters:
percent – Completion 0-100. Pass
-1for indeterminate — the generic panel then shows an activity indicator rather than a filled bar (use it when total work is unknown).label – Short status line for the generic progress view.
timing – Optional
{elapsed_s, eta_s, avg_step_s, step_label}dict.
- result(url: str) None[source]¶
Record the job’s result link — the thing the Open button opens.
The host stores it on the generic job record so the Queue & Progress panel can render it as an “open result” link; safe to call multiple times (last write wins). Pass the one canonical artifact the job produced — a run or a table URL. Richer per-plugin output still goes through
emit().- Parameters:
url – The URL the Open button opens (a run or a table URL).
- fail(message: str) NoReturn[source]¶
Fail the job with a clean, user-facing message.
Raises
JobFailed, which the worker reports as the terminalerrorevent carryingmessageverbatim — no exception-type prefix, unlike an ordinary exception (reported asf"{type}: {exc}"). Use it for validation / precondition failures where the message is meant for the user; let ordinary exceptions propagate for genuine faults.- Parameters:
message – The failure message shown on the job’s generic error card.
- Raises:
JobFailed – Always.
- emit(name: str, payload: dict[str, Any] | None = None) None[source]¶
Emit a custom, plugin-defined event for the plugin’s OWN rich UI.
The host relays it verbatim on the plugin’s SocketIO namespace; the generic Queue & Progress panel ignores it. Use
progress()/metric()/log()for the generic panel, and this for plugin-specific UI (e.g. a training plugin’s per-epoch loss curve) — so a plugin never opens its own SocketIO connection; the host owns the transport.- Parameters:
name – Event name the plugin’s UI listens for.
payload – JSON-serializable event body.
- Raises:
ValueError – If
namecollides with a host-reserved event (job_update) used for the generic Queue & Progress channel.
- tlc_plugin_sdk.SDK_CONTRACT_VERSION = '0.3.2'¶
str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.
SDK_CONTRACT_VERSION is the one contract axis: this package’s own version — the
dependency pin a plugin resolves against (3lc-compute-plugin-sdk>=X,<Y) and the version
of both the Python surface (ComputePlugin / JobContext) and the browser surface
(PLUGIN_API / PluginJobs / TlcData, declared in
tlc_plugin_sdk/contract/plugin-api.d.ts). The host and frontend implement a range and
compare compatibility on MAJOR.MINOR. See docs/plugin-guide.md → “Version & Compatibility”.
The .d.ts ships in the wheel at
<site-packages>/tlc_plugin_sdk/contract/plugin-api.d.ts; a plain-JS ui.html references
it with /// <reference types="3lc-compute-plugin-sdk/contract/plugin-api" />.
The browser contract¶
The browser surface a plugin’s ui.html programs against — PLUGIN_API, PluginJobs,
and the TlcData helper — is declared in plugin-api.d.ts.
- interface plugin-api.d.PluginApi¶
The single host -> fragment JS contract. The frontend injects this as window.PLUGIN_API when it mounts a plugin fragment; a fragment should reach for nothing else. Many plugins alias it:
var API = window.PLUGIN_API.exported from
plugin-api.d- PluginApi.compute¶
type:
TlcComputeServiceReference to
TlcApi.computeService(currently onlygetHealth()).
- PluginApi.container¶
type: HTMLElement
The DOM element the fragment was mounted into. Plugins scope their queries to it.
- PluginApi.context¶
type:
PluginContextLaunch context (resource type/urls + project).
- PluginApi.contractVersion¶
type: string
The SDK contract version this host implements, as “MAJOR.MINOR” (e.g. “0.3”), so a fragment can feature-detect the bridge. The frontend declares which contract it implements (its
IMPLEMENTED_SDK_CONTRACT) and surfaces it via <body data-contract-version>. ‘’ if the host predates it.
- PluginApi.data¶
type:
TlcDataReference to the global
TlcDatahelper (null ifTlcDatais undefined at mount).
- PluginApi.libs¶
type:
PluginLibsOptional vendored third-party libraries (each
nullif the host didn’t load it).
- PluginApi.location¶
type:
TlcLocationApiReference to the global
TlcLocationhelper (null if undefined at mount).
- PluginApi.objects¶
type:
TlcObjectServiceReference to
TlcApi.objectService. Plugins usually reach data viaauthFetch.
- async PluginApi.authFetch(url, options)¶
Authenticated
fetch. InjectsAuthorization(fromTlcAuth) and a default Accept: application/json; setsContent-Type: application/jsonwhen the body is a string. Aborts afteroptions.timeoutms (default 10000) unless the caller supplies asignal. Rejects non-ok responses with the parsed detail/message. The most-used bridge member.- Arguments:
url (string)
options (
PluginFetchOptions)
- Returns:
Promise<Response>
- async PluginApi.computeFetch(path, options, requiresGpu)¶
authFetch against the compute-service base URL.
pathis joined to the compute-service root; whenrequiresGpuis given and a CPU/GPU counterpart service is configured, routes to the matching service. Most plugins instead build URLs fromgetConfig('compute_service_url')and callauthFetch.- Arguments:
path (string)
options (
PluginFetchOptions)requiresGpu (boolean)
- Returns:
Promise<Response>
- PluginApi.getConfig(key)¶
Return a configured URL by key.
dashboard_urlhas its trailing slash stripped;compute_service_urlis the GPU/CPU-routed service for THIS plugin; object_service_url comes fromTlcApi. These three keys are the only ones recognized — any other key returns ‘’.- Arguments:
key (“dashboard_url” | “compute_service_url” | “object_service_url”)
- Returns:
string
- PluginApi.getIcon(id)¶
Return an SVG icon string. With no id (or the current plugin’s id) returns the plugin manifest’s
icon_svgwhen present; otherwise delegates to TlcIcons.get(id || pluginId), or ‘’ ifTlcIconsis undefined.- Arguments:
id (string)
- Returns:
string
Navigate the host to a path (sets
window.location.href = path).- Arguments:
path (string)
- PluginApi.showToast(message, type)¶
Show a host toast notification; no-op fallback if the host’s
showToastis unavailable.- Arguments:
message (string)
type (string)
- interface plugin-api.d.PluginContext¶
Launch context: what the user launched the plugin against.
exported from
plugin-api.d- PluginContext.projectName¶
type: string
Launch project name (’’ when none).
- PluginContext.resourceType¶
type: string
Selected resource kind (‘run’,’table’,…) or
nullwhen launched bare.
- PluginContext.resourceUrls¶
type: string[]
Selected 3LC object URLs (default
[]).
- interface plugin-api.d.PluginFetchOptions¶
Custom non-standard fetch options layered on top of the standard
RequestInit.exported from
plugin-api.d- Extends:
RequestInit
- PluginFetchOptions.allowErrorStatus?¶
type: boolean
When true, resolve with the
Responseon a non-ok HTTP status instead of rejecting — the caller inspectsresponse.ok/response.statusitself. Custom, non-standard option — deleted before the underlyingfetch()call.
- PluginFetchOptions.timeout?¶
type: number
Abort the request after this many milliseconds (default 10000). Custom, non-standard option — deleted before the underlying
fetch()call. Ignored when the caller supplies its ownsignal.
- interface plugin-api.d.PluginJobHandlers¶
exported from
plugin-api.d- PluginJobHandlers.onDone?(job)¶
Fires on terminal
completed/cancelled.- Arguments:
job (
PluginJobUpdate)
- PluginJobHandlers.onError?(job)¶
Fires on terminal
failed.- Arguments:
job (
PluginJobUpdate)
- PluginJobHandlers.onUpdate?(job)¶
Fires on every
job_update.- Arguments:
job (
PluginJobUpdate)
- interface plugin-api.d.PluginJobUpdate¶
The opaque generic job object delivered to
PluginJobshandlers.exported from
plugin-api.d- PluginJobUpdate.error?¶
type: string
Failure message on a failed job (host >= 0.6); empty/absent otherwise.
- PluginJobUpdate.id?¶
type: string
Job id.
- PluginJobUpdate.metrics?¶
type: { label?: string; value?: any; }[]
- PluginJobUpdate.progress?¶
type: { label?: string; percent?: number; timing?: any; }
- PluginJobUpdate.run_url?¶
type: string
- PluginJobUpdate.status?¶
type: string
‘queued’ | ‘running’ | ‘completed’ | ‘failed’ | ‘cancelled’.
- PluginJobUpdate.subtitle?¶
type: string
Secondary status line (the current progress label); NOT the failure message.
- PluginJobUpdate.title?¶
type: string
- interface plugin-api.d.PluginJobsApi¶
The job-tracker client. SHIPS FROM
3lc-compute-plugin-sdk(tlc_plugin_sdk.shared.job_tracker,JOB_TRACKER_JS) — auto-injected into every fragment by the SDK’s/uihandler (build_plugin_app); a manual inject_scripts(raw, job_tracker_script()) is harmless but no longer needed. NOT part of the hostPLUGIN_APIbridge; it is layered on top of it.exported from
plugin-api.d- async PluginJobsApi.cancel(jobId)¶
POST {compute}/api/plugins/jobs/{jobId}/cancel with body ‘{}’.
- Arguments:
jobId (string)
- Returns:
Promise<{ cancelled?: boolean; }>
- PluginJobsApi.connect(namespace)¶
Open (or reuse) the namespace socket now.
track()/on() connect lazily on first use and SocketIO does not replay server→client events to a client that was not yet connected — call this on mount when the fragment wants custom events from the first second, or starts jobs by other means thanrun()(which connects for you). Returns false whenPLUGIN_API.libs.iois unavailable.- Arguments:
namespace (string)
- Returns:
boolean
- async PluginJobsApi.list(pluginId)¶
GET {compute}/api/plugins/jobs → the host’s generic job records, resolved to PluginJobUpdate[] and optionally filtered (client-side) to one plugin by id. Use it to seed a freshly-mounted fragment from the durable job list — the fragment is torn down on navigation and
job_updateis live-only. See the guide’s “Job page is a launcher” section.- Arguments:
pluginId (string)
- Returns:
Promise<
PluginJobUpdate[]>
- PluginJobsApi.on(namespace, event, handler)¶
Subscribe to a CUSTOM
ctx.emit()event (not the genericjob_update) on the plugin’s namespace; returns an unsubscribe function. For rich per-job detail the flat generic schema can’t carry (result payloads, loss curves). Subscribe before run() so the socket is connected when the event fires.- Arguments:
namespace (string)
event (string)
handler ((payload: any) => void)
- Returns:
() => void
- async PluginJobsApi.run(pluginId, params, handlers)¶
Start a job and track it on the generic
job_updatechannel. Pre-subscribes on the default namespace'/' + pluginId(corrected toresp.namespaceif it differs) and buffers events so a job completing before its id is known still delivers a terminal callback. Defaultsparams.project_namefrom PLUGIN_API.context.projectName.onDonefires on completed/cancelled, onError on failed. Most-used member.- Arguments:
pluginId (string)
params (object)
handlers (
PluginJobHandlers)
- Returns:
Promise<
PluginRunResponse>
- async PluginJobsApi.start(pluginId, params)¶
POST {compute}/api/plugins/{pluginId}/run with
paramsas JSON. Defaults params.project_name from the launch context. Lower-level building block under run().- Arguments:
pluginId (string)
params (object)
- Returns:
Promise<
PluginRunResponse>
- PluginJobsApi.track(namespace, jobId, handlers)¶
Subscribe to
job_updatefor a singlejobIdon a known namespace; returns an unsubscribe function. Filters byjob.id, firesonDoneon completed/cancelled andonErroron failed, then auto-unsubscribes.- Arguments:
namespace (string)
jobId (string)
handlers (
PluginJobHandlers)
- Returns:
() => void
- interface plugin-api.d.PluginLibs¶
Third-party libraries pulled from
windowif the host loaded them, elsenullper key.- Stability tiers (frozen contract):
io(socket.io client) — STABLE: the job-tracker channel rides it; the onlylibsmember a plugin may depend on.Chart,cytoscape,html2canvas,PptxGenJS— BEST-EFFORT: exposed for convenience, may be swapped/removed without a contract bump. A plugin that needs one should be prepared to vendor its own.
exported from
plugin-api.d- PluginLibs.Chart¶
type: any
- PluginLibs.PptxGenJS¶
type: any
- PluginLibs.cytoscape¶
type: any
- Best-effort — and always
nullon the plugin page: the host does not load cytoscape into a plugin fragment, so a plugin that needs it must vendor its own.
- Best-effort — and always
- PluginLibs.html2canvas¶
type: any
- PluginLibs.io¶
type: any
socket.io client (STABLE).
- interface plugin-api.d.PluginRunResponse¶
The parsed response of the generic
POST /api/plugins/{id}/runroute.exported from
plugin-api.d- PluginRunResponse.error?¶
type: string
- PluginRunResponse.job_id?¶
type: string
- PluginRunResponse.namespace?¶
type: string
- PluginRunResponse.status?¶
type: string
- interface plugin-api.d.TlcApi¶
TlcApi — the frontend API client (api-client.js). Plugins normally reach it through
PLUGIN_APIrather than directly, but it is an ambient global.exported from
plugin-api.d- TlcApi.computeService¶
type:
TlcComputeService
- TlcApi.objectService¶
type:
TlcObjectService
- TlcApi.objectServiceUrl¶
type: readonly string
Resolved Object Service base URL (trailing slash stripped).
- async TlcApi.authFetch(url, options)¶
- Arguments:
url (string)
options (
PluginFetchOptions)
- Returns:
Promise<Response>
- async TlcApi.computeFetch(path, options, requiresGpu)¶
- Arguments:
path (string)
options (
PluginFetchOptions)requiresGpu (boolean)
- Returns:
Promise<Response>
- async TlcApi.waitForMode()¶
Resolves once compute-mode detection (GET /health -> mode/version) completes.
- Returns:
Promise<void>
- interface plugin-api.d.TlcComputeService¶
Compute-service method bag, exposed as
PLUGIN_API.compute. Currently onlygetHealth()(GET /health).exported from
plugin-api.d- async TlcComputeService.getHealth()¶
- Returns:
Promise<object>
- interface plugin-api.d.TlcData¶
The global
TlcDatahelper (cached indexing tables). Referenced from PLUGIN_API.data. Implemented by the frontend (data-helpers.js).exported from
plugin-api.d- TlcData.allRunRows()¶
Raw rows from the cached RunIndexingTable response.
- Returns:
object[]
- TlcData.allTableRows()¶
Raw rows from the cached TableIndexingTable response.
- Returns:
object[]
- TlcData.getLocations?()¶
All locations relevant to this install: configured roots plus roots inferred from the loaded data. Absent on hosts predating SDK 0.2.
- Returns:
- TlcData.getProjects()¶
Per-project rollup from both indexing tables, sorted by last_modified descending.
- Returns:
- TlcData.getRuns(projectName)¶
Runs (optionally filtered by project), with run_name derived from the URL and status mapped.
- Arguments:
projectName (string)
- Returns:
- TlcData.getSummary()¶
Dashboard summary counts.
- Returns:
- TlcData.getTables(projectName)¶
Tables (optionally filtered by project), with table_name derived from the URL.
- Arguments:
projectName (string)
- Returns:
- TlcData.getTablesByDataset(projectName)¶
getTables() grouped by dataset_name (‘(ungrouped)’ when none).
- Arguments:
projectName (string)
- Returns:
{ [datasetName: string]:
TlcDataTable[]; }
- TlcData.invalidate()¶
Mark the cache stale so the next
load()refetches; old data stays readable until replaced.
- async TlcData.load()¶
Fetch and cache both indexing tables; dedupes concurrent callers; refetches when stale.
- Returns:
Promise<void>
- TlcData.resolveLocation?(url, projectName)¶
Resolve which root an object URL lives under (longest-prefix match against configured roots, falling back to inference from the URL structure). Absent on hosts predating SDK 0.2 — feature-detect before calling.
- Arguments:
url (string)
projectName (string)
- Returns:
- TlcData.runStatusName(statusCode)¶
Map a run status code to a name (‘completed’,’empty’,’running’,’collecting’, ‘post_processing’,’paused’,’cancelled’, else ‘unknown’).
- Arguments:
statusCode (number)
- Returns:
string
- interface plugin-api.d.TlcDataLocation¶
The root a project lives under (the Object Service’s project root or one of its scan URLs). Resolved by the frontend from
api://Configurationplus the object URLs themselves; hosts predating SDK 0.2 never set it, so treat every location member as optional.exported from
plugin-api.d- TlcDataLocation.is_alias¶
type: boolean
True when
labelcame from a configured alias.
- TlcDataLocation.is_default¶
type: boolean
True for the Object Service’s primary project root.
- TlcDataLocation.key¶
type: string
Canonical prefix (file:// stripped, one trailing slash) — use for equality tests.
- TlcDataLocation.label¶
type: string
Short display name: alias name > bucket/last path segment > ‘Local’.
- TlcDataLocation.root¶
type: string
The root URL as configured or inferred (e.g. “s3://bucket/projects”).
- TlcDataLocation.scheme¶
type: string
URL scheme: ‘file’, ‘s3’, ‘gs’, …
- interface plugin-api.d.TlcDataProject¶
exported from
plugin-api.d- TlcDataProject.dataset_count¶
type: number
- TlcDataProject.last_modified¶
type: number
- TlcDataProject.locations?¶
type:
TlcDataProjectLocation[]Locations this project’s contents resolve to. Absent on hosts predating SDK 0.2.
- TlcDataProject.project_name¶
type: string
- TlcDataProject.run_count¶
type: number
- TlcDataProject.table_count¶
type: number
- interface plugin-api.d.TlcDataProjectLocation¶
Per-location slice of a project’s contents (a project can span several roots).
exported from
plugin-api.d- TlcDataProjectLocation.location¶
type:
TlcDataLocation
- TlcDataProjectLocation.run_count¶
type: number
- TlcDataProjectLocation.table_count¶
type: number
- interface plugin-api.d.TlcDataRun¶
exported from
plugin-api.d- TlcDataRun.constants¶
type: object
- TlcDataRun.created¶
type: string
- TlcDataRun.description¶
type: string
- TlcDataRun.is_url_writable¶
type: boolean
- TlcDataRun.last_modified¶
type: string
- TlcDataRun.location?¶
type:
TlcDataLocationRoot this run lives under; null if unresolvable. Absent on hosts predating SDK 0.2.
- TlcDataRun.metrics¶
type: any[]
- TlcDataRun.project_name¶
type: string
- TlcDataRun.run_name¶
type: string
- TlcDataRun.status¶
type: string
- TlcDataRun.status_code¶
type: number
- TlcDataRun.url¶
type: string
- interface plugin-api.d.TlcDataSummary¶
exported from
plugin-api.d- TlcDataSummary.project_count¶
type: number
- TlcDataSummary.run_count¶
type: number
- TlcDataSummary.table_count¶
type: number
- interface plugin-api.d.TlcDataTable¶
exported from
plugin-api.d- TlcDataTable.created¶
type: string
- TlcDataTable.dataset_name¶
type: string
- TlcDataTable.description¶
type: string
- TlcDataTable.input_table_urls¶
type: string[]
- TlcDataTable.is_url_writable¶
type: boolean
- TlcDataTable.location?¶
type:
TlcDataLocationRoot this table lives under; null if unresolvable. Absent on hosts predating SDK 0.2.
- TlcDataTable.project_name¶
type: string
- TlcDataTable.row_count¶
type: number
- TlcDataTable.table_name¶
type: string
- TlcDataTable.type¶
type: string
- TlcDataTable.url¶
type: string
- interface plugin-api.d.TlcLocationApi¶
The global
TlcLocationhelper: shared renderers for project locations. Referenced fromPLUGIN_API.location. Implemented by the frontend (location.js). Every renderer returns ‘’ when the install has a single root (isMultiRoot() === false), so output can be concatenated unconditionally.exported from
plugin-api.d- TlcLocationApi.chipHtml(loc)¶
Small chip (icon + label, root in tooltip) for one location; ‘’ when hidden.
- Arguments:
loc (
TlcDataLocation)
- Returns:
string
- TlcLocationApi.iconSvg(scheme)¶
Inline SVG string: folder glyph for ‘file’, cylinder for bucket schemes.
- Arguments:
scheme (string)
- Returns:
string
- TlcLocationApi.isMultiRoot()¶
True when the install has more than one known root.
- Returns:
boolean
- TlcLocationApi.pathLineHtml(project)¶
Muted mono path line for project cards; ‘’ when hidden.
- Arguments:
project (
TlcDataProject)
- Returns:
string
- TlcLocationApi.projectChipHtml(project)¶
Chip for a project rollup: its location, or “N locations”; ‘’ when hidden.
- Arguments:
project (
TlcDataProject)
- Returns:
string
- TlcLocationApi.rowsSpanLocations(rows)¶
True when the given rows (each optionally carrying
.location) span more than one root — the per-row chip rule (spread within the shown list, so a chip is hidden when every visible row lives under the same root).- Arguments:
rows ({ location?:
TlcDataLocation; }[])
- Returns:
boolean
- TlcLocationApi.shortLabel(label)¶
Display form of a location label: left-ellipsized past 20 chars so the distinctive tail survives.
- Arguments:
label (string)
- Returns:
string
- interface plugin-api.d.TlcObjectService¶
Object-service method bag, exposed as
PLUGIN_API.objects. All methods go throughauthFetchagainst the object-service URL; object URLs are encoded viaTlcApi.encodeObjectUrl.exported from
plugin-api.d- async TlcObjectService.deleteObject(objectUrl)¶
- Arguments:
objectUrl (string)
- Returns:
Promise<Response>
- async TlcObjectService.getConfiguration()¶
- Returns:
Promise<object>
- async TlcObjectService.getObject(objectUrl)¶
- Arguments:
objectUrl (string)
- Returns:
Promise<object>
- async TlcObjectService.getRunIndex()¶
- Returns:
Promise<object>
- async TlcObjectService.getStatus()¶
- Returns:
Promise<object>
- async TlcObjectService.getTableIndex()¶
- Returns:
Promise<object>
- async TlcObjectService.patchObject(objectUrl, patchData)¶
- Arguments:
objectUrl (string)
patchData (object)
- Returns:
Promise<object>
- async TlcObjectService.reindex(force)¶
- Arguments:
force (boolean)
- Returns:
Promise<object>
The worker¶
Out-of-process plugin worker — the plugin’s Litestar app served on a Unix socket.
Run by the host’s worker supervisor inside the plugin’s own venv:
python -m tlc_plugin_sdk.worker --entry pkg:PluginClass --socket /run/.../id.sock
The bind transport is selectable: --socket (Unix domain socket, the default the
supervisor uses) or --host/--port (TCP, e.g. --host 127.0.0.1 --port 9100)
for a worker reachable over the network. Exactly one of the two must be given.
The worker serves the plugin’s Litestar app
(tlc_plugin_sdk.asgi_app.build_plugin_app): the plugin’s own route handlers
plus the generic reserved routes (/health, /ui, /compute). On top of that
it adds the job channel the host supervisor drives:
POST /jobs/{job_id}/run→ runsrun_job(ctx)on a thread; the responsestreams NDJSON events (progress/metric/log) ending in a terminal
done/errorevent.
POST /jobs/{job_id}/cancel→ cooperative cancel (setsctx.cancelled).POST /reclaim→ release cached GPU memory now (see
GPU memory is reclaimed automatically after every job, before the terminal event is
emitted. /reclaim exists because only the host can see across workers: this
process cannot know that another plugin’s worker needs the card. The host decides
when; the worker is the only side that can act, because a CUDA allocator is
per-process and the supervisor’s only in-process lever is killing the worker.
Because the worker runs a real Litestar app, a plugin’s custom routes get a real
router, validation, multipart, and binary/streaming behavior —
and Litestar runs synchronous def handlers in a threadpool, so CPU-bound routes
don’t block the worker’s event loop. Litestar + uvicorn are base dependencies of
this SDK; they are imported here, not by the import-light tlc_plugin_sdk
package surface.
- tlc_plugin_sdk.worker.release_gpu_memory() bool[source]¶
Return this process’s cached-but-unused GPU memory to the driver.
PyTorch’s caching allocator keeps freed blocks for reuse instead of handing them back, so a finished job’s peak allocation stays charged to this process until it exits. A worker is long-lived and serves many jobs, so without this a completed job keeps pinning VRAM that nothing is using, and the next GPU job — here or in another plugin’s worker — can fail to allocate against it. A job that died of
OutOfMemoryErroris the worst case: it has the largest cache to release, and the natural response to that error is an immediate retry.torchis deliberately not imported. It is not an SDK dependency (only an ML plugin’s own venv brings it), and a worker whose plugin never loaded it has nothing to reclaim; the module is used only if the plugin already put it insys.modules. This keeps the SDK’s import-light invariant intact.Safe to call at any time, including while a job runs: releasing cached blocks never touches memory that is still referenced.
- Returns:
True if a CUDA cache was released; False if this worker has no loaded
torch, no usable CUDA device, or the release failed.
- tlc_plugin_sdk.worker.serve(entry: str, plugin_id: str, *, socket_path: str | None = None, host: str | None = None, port: int | None = None, state_root: str | None = None) None[source]¶
Load the plugin and serve its Litestar app (blocking).
Bind to exactly one transport:
socket_path(Unix domain socket, the supervisor’s default) orhost+port(TCP). The plugin’s identity comes fromplugin_id(passed by the supervisor from the manifest), not from a class attribute — venv plugins carry no metadata on the instance.- Raises:
ValueError – If not exactly one of
socket_pathorhost/portis given.