3lc-compute-plugin-sdk 0.2.2__tar.gz → 0.3.0__tar.gz

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: release
     permissions:
-      contents: read
+      contents: write # create the GitHub Release (step below)
       id-token: write # OIDC token for PyPI Trusted Publishing
     steps:
       - uses: actions/checkout@v4
@@ -53,6 +53,32 @@ jobs:
       - name: Publish to PyPI
         run: uv publish --trusted-publishing always
 
+      # Publish the tagged version's changelog section as a GitHub Release (curated notes,
+      # not GitHub's commit list). The Release stays editable after publish for touch-up.
+      - name: Extract changelog section
+        id: changelog
+        run: |
+          VER="${GITHUB_REF_NAME#v}"
+          awk -v v="$VER" '$0 ~ "^## \\[" v "\\]" {f=1; next} /^## \[/ && f {exit} f' \
+            CHANGELOG.md > notes.md
+          echo "ver=$VER" >> "$GITHUB_OUTPUT"
+          { echo "notes<<EOF"; cat notes.md; echo EOF; } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body: |
+            ${{ steps.changelog.outputs.notes }}
+
+            ## Installation
+            ```bash
+            pip install 3lc-compute-plugin-sdk==${{ steps.changelog.outputs.ver }}
+            ```
+          draft: false
+          generate_release_notes: false
+
   # Manual (workflow_dispatch) runs → build-numbered prereleases to the legacy CloudRepo index.
   publish-cloudrepo-prerelease:
     if: github.event_name == 'workflow_dispatch'

3lc_compute_plugin_sdk-0.3.0/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to `3lc-compute-plugin-sdk` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.3.0] - 2026-08-25
+
+A coordinated contract wave: breaking **for plugin authors** but **not on the wire** — the
+worker→host NDJSON events are unchanged, so a host keeps running a plugin venv still on 0.2.x
+(skew badge only). The whole first-party fleet re-pins `>=0.3.0,<0.4.0` in the same release.
+
+### Added
+- `JobContext.fail(message)` raises `JobFailed` (exported from `tlc_plugin_sdk`); the worker
+  reports it as the terminal `error` event with the **bare** message, while any other exception
+  keeps its `TypeName: …` prefix.
+- `PluginJobs.list(pluginId?)` — `GET {compute}/api/plugins/jobs`, filtered client-side by
+  `plugin_id`. Use it to **seed a fragment on mount** from the durable host job list (the
+  fragment is torn down on navigation and `job_update` is live-only). Declared in the `.d.ts`.
+- `PluginJobs.connect(namespace)` — warm the namespace socket on mount. `track()`/`on()`
+  connect lazily and SocketIO does not replay events to a not-yet-connected client, so a
+  fragment listening for custom events from the first second (or re-attaching to a job it did
+  not start) calls this first; `run()` already connects for you.
+- The host's `/ui` handler now **auto-injects** the `PluginJobs` client into every fragment; the
+  client is idempotent, so a plugin that still injects it by hand keeps working.
+- `ComputePlugin.compute()` ships a default (returns an error dict), so only `get_ui_fragment()`
+  stays abstract.
+- `.d.ts` truth pass: `PluginJobUpdate.error`, `PluginFetchOptions.allowErrorStatus`,
+  `PluginJobsApi.list`, `TlcLocationApi.rowsSpanLocations`/`shortLabel`, and a new
+  **Legacy globals** ambient block (`openTablePicker`/`closeTablePicker`/`CancelJob`/`cssVar`
+  and the injected `_tlc*` helpers).
+
+### Changed
+- **One contract axis.** `PY_CONTRACT` and `JS_CONTRACT` are removed; `SDK_CONTRACT_VERSION`
+  (the package version) is the whole contract, compared on `MAJOR.MINOR`. `/health` reports
+  `sdk_version` only (no `py_contract`/`js_contract`).
+- `JobContext.result` takes a **positional** `url` (`ctx.result(url)`); it opens the Open
+  button — a run *or* a table URL. The `run_url=` keyword is gone; the emitted `result` event
+  still carries `run_url` (wire unchanged).
+- `JobContext.progress` documents `percent=-1` as indeterminate.
+
+### Removed
+- `shared.modality.detect_modality_from_url` (zero users). `detect_modality_from_schema`,
+  `classify_metrics_columns`, `labels.candidate_label_paths`, and `labels.find_label_path`
+  are now internal (underscore-prefixed). Public alternatives: `detect_modality_from_table`
+  for modality; `get_label_map` / `get_label_names` / `find_label_column` for labels.
+  `classify_metrics_columns` was a plugin-specific column-name heuristic with no public
+  replacement — inline it (its one known user did).
+- The orphan `_ICON_SVG` constant; the dead `params.setdefault("url", "")` in the `/compute`
+  handler.
+
+### Migration
+- `ctx.result(run_url=x)` → `ctx.result(x)`.
+- Validation failures: raise, or `ctx.fail("message")` for a clean user-facing card.
+- Reading `tlc_plugin_sdk.PY_CONTRACT` / `JS_CONTRACT`, or a worker's `/health`
+  `py_contract`/`js_contract`: use `SDK_CONTRACT_VERSION` / `sdk_version` and compare on
+  `MAJOR.MINOR`.
+- `shared.modality.detect_modality_from_url(url)` → load the table yourself and call
+  `detect_modality_from_table(table)`. `classify_metrics_columns(columns)` → copy the
+  heuristic into your plugin.
+- A fragment that kept its own always-connected socket for custom events: switch to
+  `PluginJobs.on(namespace, event, handler)` and call `PluginJobs.connect(namespace)` on mount
+  so nothing emitted before the first `track()` is missed.
+- Fragments may delete their manual `inject_scripts(raw, job_tracker_script())` — the host
+  injects `PluginJobs` now (harmless to keep).
+- The manifest never declared the SocketIO namespace or `sdk_version`; both were dead and are
+  documented as such. The namespace is host-derived as `/<plugin-id>`.
+
+## [0.2.3] - 2026-08-21
+
+### Changed
+- Docs: the plugin guide and API docstrings describe the single runtime — a plugin runs in
+  its own venv behind a worker; the manifest's `isolation` key accepts only `"venv"` (the
+  default when absent). The guide's isolation table, the in-tree host exception callout, and
+  the `unload` endpoint reference are gone; the dev-workflow section now documents the
+  folder-Source + editable-venv + `worker/stop` loop. No code or contract change.
+
+## [0.2.2] - 2026-08-18
+
+### Added
+- Shared data-source picker (`shared.data_source_ui`) and its browse/upload route handlers
+  (`shared.data_source_routes`): plugins mount one consistent widget for choosing a local
+  path or uploading a file, instead of each fragment rolling its own (#11).
+
+### Changed
+- **Distribution moved to PyPI**: `3lc-compute-plugin-sdk` is now published to public
+  [PyPI](https://pypi.org/project/3lc-compute-plugin-sdk/) via Trusted Publishing; the private
+  CloudRepo index (pypi.3lc.ai) is no longer needed to install the SDK. Manual prerelease
+  builds keep publishing to CloudRepo for a grace period (#13).
+- The `[shared]` extra's `3lc` dependency resolves from public PyPI (its home since the 3.2
+  rust release), so the SDK no longer pins a custom package index (#12).
+
+### Security
+- The data-source `/browse` route is confined to operator-configured roots
+  (`TLC_DATA_SOURCE_ROOTS`, `os.pathsep`-separated; default: the service user's home).
+  Every requested path is realpath-resolved before the containment check, so `..`
+  segments and symlinks pointing outside a root are denied rather than followed, and
+  the widget's breadcrumb stops at the root instead of offering the whole filesystem (#11).
+- The data-source `/upload-temp` route strips directory components from the
+  client-supplied filename (closing a path traversal where a `../…` name chose the
+  write location), lands each upload in its own private temp directory so same-named
+  uploads never clobber each other, and rejects bodies larger than
+  `TLC_DATA_SOURCE_MAX_UPLOAD_MB` (default 512) (#11).
+
+## [0.2.1] - 2026-08-13
+
+### Added
+- Tilde expansion and local-path normalization helpers in `shared.url_utils`
+  (`normalize_local_path`, `normalize_url`): user-supplied paths expand `~` and resolve
+  to absolute form at every ingress, so exported files and stored URLs never carry a
+  user-relative path (#10).
+
+## [0.2.0] - 2026-08-05
+
+### Added
+- JS_CONTRACT 0.2: project locations (`TlcLocation`) are available to plugin UI fragments
+  through `PLUGIN_API`, so plugins can resolve and present where a project's data lives (#8).
+- The plugin worker reports the SDK contract version from its `/health` endpoint, letting the
+  host enforce compatibility floors precisely instead of guessing (#6).
+
+### Changed
+- The plugin worker releases cached GPU memory after every job, so a finished GPU job no longer
+  pins CUDA memory that other plugins need (#7).
+
+## [0.1.1] - 2026-07-03
+
+### Changed
+- **Distribution renamed**: `3lc-plugin-sdk` is now published as `3lc-compute-plugin-sdk`
+  (the import name `tlc_plugin_sdk` is unchanged). Update your dependency declarations.
+
+### Fixed
+- Regenerated `uv.lock` for the renamed distribution; release builds append the run number as a
+  build counter.
+
+## [0.1.0] - 2026-06-30
+
+First public release of the plugin SDK for the 3LC compute service.
+
+### Added
+- The plugin contract: `ComputePlugin`, `JobContext`, and the `PLUGIN_API` browser bridge
+  (JS_CONTRACT) that plugin UI fragments use to talk to the host.
+- Slim base package with a `[shared]` extra for common plugin dependencies.
+- Apache-2.0 license, public CI, and a documentation site including the plugin author guide and
+  a rendered browser-contract reference.

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/CLAUDE.md

@@ -83,10 +83,11 @@ section is the condensed working order.
    - **Config + GPU job + SocketIO**: sam3, yolo, or timm
    - **Inline data display (no standalone page)**: `tlc_plugin_table_statistics`
    - **Action on selected resources**: `tlc_plugin_merger`
-3. Read `src/tlc_plugin_sdk/contract.py` — `ComputePlugin` is an `abc.ABC` with two abstract
-   methods (`get_ui_fragment()`, `compute()`) and an `id` attribute the host stamps from the
-   manifest. The optional hooks (`run_job`, `initialise_runtime`, `shutdown_runtime`,
-   `get_route_handlers`) ship as no-op defaults, so you override only what you need. There is
+3. Read `src/tlc_plugin_sdk/contract.py` — `ComputePlugin` is an `abc.ABC` with one abstract
+   method (`get_ui_fragment()`) and an `id` attribute the host stamps from the manifest.
+   `compute()` and the other hooks (`run_job`, `initialise_runtime`, `shutdown_runtime`,
+   `get_route_handlers`) ship as defaults (`compute()` reports that the plugin doesn't
+   implement it), so you override only what you need. There is
    no `register()` and **no** `get_active_jobs`/`cancel_job` — the host owns job listing and
    cancellation.
 4. Read `tlc_plugin_exporter`'s `plugin.toml` + `__init__.py` — the canonical manifest +
@@ -154,9 +155,11 @@ section is the condensed working order.
   form fills call `_tlcSyncAliasFromForm(prefix, projectId, folderId)`.
 
 **SocketIO** (if real-time updates are needed):
-- `socketio_namespace` is optional — it defaults to `/<plugin-id>`, which the host
-  auto-registers at startup; declare it in `[runtime]` only to override.
-- Prefer the `window.PluginJobs` client over a hand-rolled socket.
+- The namespace is host-derived as `/<plugin-id>` and auto-registered at startup; the manifest
+  does not (and never did) declare it.
+- Prefer the `window.PluginJobs` client over a hand-rolled socket. It connects a namespace
+  lazily; call `PluginJobs.connect('/<plugin-id>')` on mount if the fragment needs custom
+  events from the first second (`run()` connects for you).
 - Use `ctx.emit(name, payload)` only for telemetry the generic schema can't express
   (e.g. a loss curve); never re-emit the generic lifecycle by hand.
 

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.2.2
-Summary: Public Python SDK for building 3LC compute-service plugins (the import-light plugin contract).
+Version: 0.3.0
+Summary: Public Python SDK for building 3LC compute-service plugins.
 Project-URL: Homepage, https://github.com/3lc-ai/3lc-compute-plugin-sdk
 Project-URL: Repository, https://github.com/3lc-ai/3lc-compute-plugin-sdk
 Author-email: 3LC <support@3lc.ai>
@@ -44,15 +44,16 @@ pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk
 
 ## What it gives you
 
-- **`ComputePlugin`** — the base class you subclass. Implement `compute` / `get_ui_fragment`;
-  job and lifecycle hooks ship as no-op defaults. There is no `register()` to call — a plugin's
-  metadata lives in its `[tool.tlc-compute]` manifest, and the host discovers it from there.
+- **`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, identically whether the host runs it
-  in-process or out-of-process in its own venv.
+  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.
 
@@ -63,20 +64,25 @@ 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.
-A plugin pins the SDK (`3lc-compute-plugin-sdk>=X,<Y`) and declares the contract it targets via its
-manifest. The host implements a contract range and the SDK version is the lingua franca that
-both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability stance.
+`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.
 
-## Boundary (the one rule)
+## How it fits
 
-The SDK is the **root** of the plugin dependency graph: it depends only on `3lc` + `uvicorn` +
-`litestar`, and **never** on the host (`3lc-compute`) or on any plugin. If your plugin only
-needs `tlc_plugin_sdk`, it is portable across host versions and can run in its own isolated venv.
+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.2 is the released contract line.** Within 0.x the contract evolves **additively only**:
-symbols and schemas that exist keep working, and anything breaking waits for a major bump. In
+**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).

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/README.md

@@ -18,15 +18,16 @@ pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk
 
 ## What it gives you
 
-- **`ComputePlugin`** — the base class you subclass. Implement `compute` / `get_ui_fragment`;
-  job and lifecycle hooks ship as no-op defaults. There is no `register()` to call — a plugin's
-  metadata lives in its `[tool.tlc-compute]` manifest, and the host discovers it from there.
+- **`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, identically whether the host runs it
-  in-process or out-of-process in its own venv.
+  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.
 
@@ -37,20 +38,25 @@ 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.
-A plugin pins the SDK (`3lc-compute-plugin-sdk>=X,<Y`) and declares the contract it targets via its
-manifest. The host implements a contract range and the SDK version is the lingua franca that
-both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability stance.
+`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.
 
-## Boundary (the one rule)
+## How it fits
 
-The SDK is the **root** of the plugin dependency graph: it depends only on `3lc` + `uvicorn` +
-`litestar`, and **never** on the host (`3lc-compute`) or on any plugin. If your plugin only
-needs `tlc_plugin_sdk`, it is portable across host versions and can run in its own isolated venv.
+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.2 is the released contract line.** Within 0.x the contract evolves **additively only**:
-symbols and schemas that exist keep working, and anything breaking waits for a major bump. In
+**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).

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/docs/api.md

@@ -13,29 +13,23 @@ package's own docstrings.
    :members:
 
 .. autodata:: tlc_plugin_sdk.SDK_CONTRACT_VERSION
-
-.. autodata:: tlc_plugin_sdk.PY_CONTRACT
-
-.. autodata:: tlc_plugin_sdk.JS_CONTRACT
 ```
 
-`SDK_CONTRACT_VERSION` is the wheel/SemVer — the dependency *pin* a plugin resolves
-against (`3lc-compute-plugin-sdk>=X,<Y`). `PY_CONTRACT` and `JS_CONTRACT` are finer-grained
-**capability markers** for runtime feature-detection: `PY_CONTRACT` covers the Python
-surface (`ComputePlugin` / `JobContext`), `JS_CONTRACT` the browser surface
+`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`). Both increment independently and are always
-`<=` the package version. See `docs/plugin-guide.md` → "Two version axes".
+`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 (`JS_CONTRACT`)
+## 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`, the source of truth for
-`JS_CONTRACT`.
+and the `TlcData` helper — is declared in `plugin-api.d.ts`.
 
 ```{eval-rst}
 .. automodule documents every exported symbol in the file, so new contract

{3lc_compute_plugin_sdk-0.2.2 → 3lc_compute_plugin_sdk-0.3.0}/docs/index.md

@@ -17,7 +17,7 @@ pip install 3lc-compute-plugin-sdk          # import name: tlc_plugin_sdk
   against: `progress` / `metric` / `log` / `result`, `emit` for rich UI, and
   cooperative `cancelled`.
 - **The worker** (`python -m tlc_plugin_sdk.worker`) — serves your plugin's Litestar
-  route handlers as an ASGI app, in-process or out-of-process in its own venv.
+  route handlers as an ASGI app, out-of-process in the plugin's own venv.
 
 ```{toctree}
 :maxdepth: 2