3lc-compute-plugin-sdk 0.2.3__tar.gz → 0.3.1__tar.gz

{3lc_compute_plugin_sdk-0.2.3 → 3lc_compute_plugin_sdk-0.3.1}/.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.1/CHANGELOG.md

@@ -0,0 +1,189 @@
+# 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]
+
+## [0.3.1] - 2026-08-27
+
+A patch on the 0.3 line, additive and pin-compatible (`>=0.3.0,<0.4.0` resolves it). The SDK now
+brings the `3lc` data plane as a base dependency, and the shared data-source browse widget gains an
+input/output picker split.
+
+### Added
+- The shared data-source browse widget shows a small caption ("Showing files matching:
+  `<glob>`") when a field declares an `accept` glob, so users understand why some files in a
+  listed folder don't appear as selectable — folders themselves are never glob-filtered.
+
+### Changed
+- **`3lc[pandas]` is now a base dependency.** Installing `3lc-compute-plugin-sdk` brings the 3LC
+  data plane, so a plugin pins the SDK alone and gets `tlc` and every `shared.*` helper with it.
+  The former `[shared]` extra is kept as an empty, deprecated alias — existing
+  `3lc-compute-plugin-sdk[shared]` pins keep resolving — and will be removed at 1.0. Drop the
+  suffix when you raise your floor to a release carrying this change. Nothing changes at import
+  time: `tlc` is still loaded lazily, only by the helpers that use it.
+- **Docs:** clarified `runtime.provision_extra` in the plugin guide — it names the
+  optional-dependency group the host installs into your plugin's venv (keeping the base light for
+  discovery and letting one distribution carry several plugins), not an "umbrella-only, required"
+  key. Restated that isolation is venv-only: every plugin runs from a host-built managed venv,
+  with no in-process/host mode and no `.venv` beside the source. No contract or code change.
+- **Data-source browse widget:** the widget now takes a `purpose` config axis (`'input'`, the
+  default, or `'output'`), mirrored by a `purpose` query param on `/browse`. Input pickers now
+  **hide** folders the compute process cannot open (rather than showing them disabled), so the
+  listing only offers places you can actually descend into. Output pickers show **all** folders
+  and instead flag the ones that are not writable — dimmed with a lock glyph and a tooltip, but
+  still navigable so you can descend to a writable subdirectory — and disable "Select This
+  Folder" when the current directory is not writable. In output mode `/browse` returns a
+  `writable` flag on each directory entry and for the listed directory itself (computed only in
+  output mode; an older host that omits the flag is treated as writable).
+
+### Fixed
+- **Data-source browse widget:** folders the compute process cannot actually open (e.g. macOS
+  TCC-protected packages like `Photos Library.photoslibrary`) are now marked inaccessible and
+  rendered disabled — dimmed, with a lock glyph and a tooltip — instead of listed as navigable
+  and then failing with a red "Permission denied" panel when clicked. The `/browse` route probes
+  each directory's openability with `os.scandir` (not `os.access`, which TCC packages spuriously
+  pass) and tags directory entries with an `accessible` flag; an older host that omits the flag
+  keeps working (entries are treated as accessible).
+
+## [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.3 → 3lc_compute_plugin_sdk-0.3.1}/CLAUDE.md

@@ -18,16 +18,16 @@ in a separate repository and is **not** a dependency of this SDK.
    host-side). The SDK is the root of the dependency graph; the host depends on the SDK, never the
    reverse. The whole point — a plugin built against just this wheel runs in its own isolated venv.
 2. **Import-light.** Importing `tlc_plugin_sdk` must not eagerly pull the server stack *or the data
-   plane*. `litestar` and `uvicorn` are base deps but are imported **lazily** (only when a worker
-   actually serves); `tlc` is an optional extra imported lazily only by `shared.*`; and the
-   host-only SocketIO server must not be importable from here at all. `tests/test_import_light.py`
-   enforces this (guards `litestar`/`socketio`/`uvicorn`/`tlc`) — keep it green.
-3. **Dependencies stay minimal.** Base = `uvicorn` + `litestar` only. `3lc` is an optional extra
-   (`3lc-compute-plugin-sdk[shared]`, named for the `shared.*` module it unlocks) used solely by those
-   helpers — the contract core needs no data plane, so light consumers (e.g. the Hub frontend)
-   install the bare SDK. Adding a base dep widens what every plugin venv must install — justify it.
-   (Direction: as `shared.*` graduates into the core, `3lc` likely returns to base with `[shared]`
-   kept as a no-op alias.)
+   plane*. `litestar`, `uvicorn`, and `tlc` are all base deps but are imported **lazily** — the
+   server stack only when a worker actually serves, `tlc` only inside the `shared.*` helpers that
+   use it; and the host-only SocketIO server must not be importable from here at all.
+   `tests/test_import_light.py` enforces this (guards `litestar`/`socketio`/`uvicorn`/`tlc`) —
+   keep it green. Import-light is about worker startup time, not about what is installed.
+3. **Dependencies stay minimal.** Base = `uvicorn` + `litestar` + `3lc[pandas]`, nothing else.
+   `3lc` is deliberately a base dep, not an extra: every real plugin uses the data plane, and making
+   it optional only created a way to build a venv that imports fine and fails on first use. (The
+   `[shared]` extra it used to live behind is an empty, deprecated alias — gone at 1.0.) Adding a
+   base dep widens what every plugin venv must install — justify it.
 4. **The contract is published — every public symbol is forever-ish.** The 0.x line is
    additive-only (see README → Status): additions are the safe move; reshaping
    `JobContext`/`ComputePlugin` waits for a major bump. The version is the contract version
@@ -50,9 +50,8 @@ and how to port an existing plugin.
 
 ## Dev setup
 
-`3lc` resolves from the public 3LC releases index (`[tool.uv.index]` in `pyproject.toml`). If
-your platform lacks a prebuilt wheel there, override locally (uncommitted) with an editable
-path source.
+`3lc` resolves from public PyPI. To develop against an unreleased `3lc`, override locally
+(uncommitted) with an editable path source in `[tool.uv.sources]`.
 
 ```bash
 uv sync                 # installs the SDK + dev tools (ruff, mypy, pytest)
@@ -83,10 +82,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 +154,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.3 → 3lc_compute_plugin_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: 3lc-compute-plugin-sdk
-Version: 0.2.3
+Version: 0.3.1
 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
@@ -18,10 +18,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: 3lc[pandas]<4.0.0,>=3.0.0
 Requires-Dist: litestar<3.0.0,>=2.22.0
 Requires-Dist: uvicorn>=0.34.0
 Provides-Extra: shared
-Requires-Dist: 3lc[pandas]<4.0.0,>=3.0.0; extra == 'shared'
 Description-Content-Type: text/markdown
 
 # 3lc-compute-plugin-sdk
@@ -44,9 +44,10 @@ 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 Hub 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`.
@@ -63,23 +64,26 @@ 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 compute service implements a contract range, and the SDK version is the shared
-reference both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability
+`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.
+This SDK sits at the root of the plugin dependency graph. Its dependencies are `uvicorn`,
+`litestar`, and the `3lc` data plane (`3lc[pandas]`) — so installing the SDK is all a plugin needs
+to use `tlc` and the `shared.*` helpers built on it. All three are imported lazily; `import
+tlc_plugin_sdk` stays cheap. 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.3 → 3lc_compute_plugin_sdk-0.3.1}/README.md

@@ -18,9 +18,10 @@ 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 Hub 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`.
@@ -37,23 +38,26 @@ 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 compute service implements a contract range, and the SDK version is the shared
-reference both sides agree on. Versions are SemVer; see **Status** below for the 0.x stability
+`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.
+This SDK sits at the root of the plugin dependency graph. Its dependencies are `uvicorn`,
+`litestar`, and the `3lc` data plane (`3lc[pandas]`) — so installing the SDK is all a plugin needs
+to use `tlc` and the `shared.*` helpers built on it. All three are imported lazily; `import
+tlc_plugin_sdk` stays cheap. 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.3 → 3lc_compute_plugin_sdk-0.3.1}/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