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

3lc_compute_plugin_sdk-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_call:   # reused as the gate by release.yml
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-type-test:
+    name: ruff · mypy · pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install dependencies
+        run: uv sync --python 3.12 --dev --locked
+
+      - name: Ruff lint
+        run: uv run --python 3.12 ruff check .
+
+      - name: Ruff format check
+        run: uv run --python 3.12 ruff format --check .
+
+      - name: mypy (strict)
+        run: uv run --python 3.12 mypy src/
+
+      - name: pytest
+        run: uv run --python 3.12 pytest -q
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci

3lc_compute_plugin_sdk-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,68 @@
+name: docs
+
+# Build the Sphinx docs and publish to GitHub Pages.
+# Manual-only by choice: run from the Actions tab (or `gh workflow run docs`)
+# when the docs should go out — pushes to main do NOT redeploy.
+# One-time setup: repo Settings -> Pages -> Source = "GitHub Actions".
+on:
+  workflow_dispatch:
+
+# Least-privilege token for the Pages deploy.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Serialize deploys; don't cancel an in-flight one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build-deploy:
+    name: build & deploy
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      # sphinx-js drives TypeDoc to document the browser contract (.d.ts);
+      # both are Node tools pinned in docs/package.json.
+      - name: Install Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install docs Node toolchain (TypeDoc)
+        run: npm --prefix docs ci
+
+      # Install the package + deps so autodoc can import tlc_plugin_sdk,
+      # then overlay the docs toolchain and build.
+      - name: Install dependencies
+        run: uv sync --python 3.12 --locked
+
+      - name: Build docs
+        run: >
+          uv run --python 3.12 --with-requirements docs/requirements.txt
+          sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

3lc_compute_plugin_sdk-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+name: Release
+
+# Tag (`v*`) pushes publish to public PyPI via Trusted Publishing (GitHub OIDC, no secrets).
+# To cut a release: bump `version` in pyproject.toml (regenerate uv.lock), update CHANGELOG.md,
+# commit, then push a tag `vX.Y.Z` that matches the version.
+#
+# Manual (workflow_dispatch) runs publish build-numbered prereleases to the legacy CloudRepo
+# index (pypi.3lc.ai) — kept as a grace-period fallback; retire that job (and the CLOUDREPO_*
+# secrets/vars on the "release" environment) once nothing consumes the CloudRepo index. The
+# split deliberately keeps build-numbered versions OFF PyPI: `X.Y.Z.N` sorts above `X.Y.Z`,
+# so a prerelease build would win over the real release in `>=X.Y,<X.Y+1`-style pins.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  # Gate the release on the full CI suite (ruff · mypy · pytest).
+  test:
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+
+  # Tag (`v*`) pushes → the real release, to public PyPI.
+  publish-pypi:
+    if: github.event_name == 'push'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+
+      - name: Verify tag matches pyproject version
+        run: |
+          PKG=$(uv version --output-format json | jq -r '.version')
+          TAG="${GITHUB_REF_NAME#v}"
+          echo "pyproject=$PKG tag=$TAG"
+          [ "$PKG" = "$TAG" ] || { echo "::error::tag $GITHUB_REF_NAME ($TAG) != pyproject version $PKG"; exit 1; }
+
+      # --no-sources strips [tool.uv.sources] so the released wheel never bakes in a dev
+      # index/path override (the published artifact resolves deps from PyPI).
+      - name: Build
+        run: uv build --no-sources
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always
+
+  # Manual (workflow_dispatch) runs → build-numbered prereleases to the legacy CloudRepo index.
+  publish-cloudrepo-prerelease:
+    if: github.event_name == 'workflow_dispatch'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: release
+    env:
+      UV_PUBLISH_URL: ${{ vars.CLOUDREPO_PUBLISH_URL }}
+      UV_PUBLISH_USERNAME: ${{ secrets.CLOUDREPO_USERNAME }}
+      UV_PUBLISH_PASSWORD: ${{ secrets.CLOUDREPO_PASSWORD }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+
+      - name: Verify the 'release' environment is configured
+        run: |
+          : "${UV_PUBLISH_URL:?set the CLOUDREPO_PUBLISH_URL variable on the 'release' environment}"
+          : "${UV_PUBLISH_USERNAME:?set the CLOUDREPO_USERNAME secret on the 'release' environment}"
+          : "${UV_PUBLISH_PASSWORD:?set the CLOUDREPO_PASSWORD secret on the 'release' environment}"
+
+      # A 4th version segment keeps every prerelease publish unique (CloudRepo has overwrites
+      # disabled) while sorting above the base version, so `<X.Y+1`-style pins still resolve it
+      # — unlike `.devN` (sorts below) or `+localN` (rejected on upload).
+      - name: Stamp build-numbered version
+        run: |
+          BASE=$(uv version --output-format json | jq -r '.version')
+          uv version "${BASE}.${GITHUB_RUN_NUMBER}"
+          echo "prerelease build version: ${BASE}.${GITHUB_RUN_NUMBER}"
+
+      - name: Build
+        run: uv build --no-sources
+
+      - name: Publish to CloudRepo
+        run: uv publish

3lc_compute_plugin_sdk-0.2.2/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Docs build output
+docs/_build/
+docs/node_modules/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

3lc_compute_plugin_sdk-0.2.2/CHANGELOG.md

@@ -0,0 +1,78 @@
+# 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.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/CLAUDE.md

@@ -0,0 +1,184 @@
+# 3lc-compute-plugin-sdk — agent & contributor orientation
+
+This repo is the **public Python plugin SDK** for the 3LC compute service: the import-light
+contract a plugin programs against. The compute-service host that discovers and runs plugins lives
+in a separate repository and is **not** a dependency of this SDK.
+
+## What this package is (and is not)
+
+- **Is:** the contract surface — `ComputePlugin`, `JobContext`, the worker entrypoint, and the
+  `tlc_plugin_sdk.shared.*` helpers. Distribution `3lc-compute-plugin-sdk`, import `tlc_plugin_sdk`.
+- **Is not:** the host. The compute service (`3lc-compute` / import `tlc_compute`) is a separate
+  package that *discovers and runs* plugins. It is not a dependency of this SDK and its source is
+  not here.
+
+## The invariants — do not break these
+
+1. **No back-edge to the host.** `tlc_plugin_sdk` must never import `tlc_compute` (or anything
+   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.)
+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
+   (see below).
+
+## Versioning
+
+`SDK_CONTRACT_VERSION` is read from this package's own version via `importlib.metadata` — one
+source of truth (`[project] version` in `pyproject.toml`). Bump it (SemVer) when the contract
+changes; the 0.x line is additive-only (README → Status). Plugins pin a range
+(`3lc-compute-plugin-sdk>=X,<Y`); the host implements a range. Don't reintroduce a
+separately-maintained version constant.
+
+## Where the rest of the context lives
+
+The author guide and API reference travel with this repo (`docs/plugin-guide.md`, `docs/api.md`)
+and are published at <https://3lc-ai.github.io/3lc-compute-plugin-sdk/>. That guide is the canonical,
+self-contained source for building a plugin against this contract — including how isolation works
+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.
+
+```bash
+uv sync                 # installs the SDK + dev tools (ruff, mypy, pytest)
+uv run ruff check .
+uv run mypy src/
+uv run pytest
+```
+
+## Conventions
+
+Python 3.10+, uv, Hatchling, Litestar, Ruff (line-length 120), mypy `--strict` clean (no
+`# type: ignore`, no `Any` used to silence the checker). Google-style docstrings. Copyright header
+on new files.
+
+## Building a new plugin (agent guide)
+
+Reference for building a plugin against this SDK. Read `docs/plugin-guide.md` first — this
+section is the condensed working order.
+
+### Before you start
+
+1. Read the full plugin guide (`docs/plugin-guide.md`).
+2. Read an existing plugin closest to what you're building — the open first-party plugins live
+   in [`3lc-compute-plugins`](https://github.com/3lc-ai/3lc-compute-plugins) under
+   `src/tlc_plugin_<name>/`, and the GPU training/labeling plugins in their own repos
+   (`3lc-compute-plugin-timm` / `-sam3` / `-yolo`):
+   - **Form → execute → result**: `tlc_plugin_exporter` or `tlc_plugin_importer`
+   - **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
+   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 +
+   subclass exemplar.
+
+### Step-by-step
+
+1. **Create the package**: the standalone `tlc_plugin_<name>/` shape from the guide's
+   "Create the plugin directory" section.
+2. **Create `plugin.toml`** (the manifest) with all metadata: top-level identity/version,
+   `[ui]`, and `[runtime]` (including `entrypoint = "pkg.module:ClassName"`). Copy the shape
+   from `tlc_plugin_exporter`.
+3. **Create `__init__.py`** with a `ComputePlugin` subclass:
+   - Subclass `ComputePlugin` (from `tlc_plugin_sdk`); no metadata attributes, no `register()`
+   - `get_ui_fragment()` reading from `ui.html`
+   - `get_route_handlers()` returning your route handlers (optional)
+   - Any optional hooks you need (`run_job` for long-running tasks, `initialise_runtime`,
+     `shutdown_runtime`)
+4. **Create `ui.html`** following the guide's UI Consistency section.
+5. **Create `routes.py`** if you need custom endpoints (e.g. config CRUD).
+6. **If you have a long-running task**: implement `run_job(ctx)` and set `requires_gpu` in
+   `[runtime]`. Reference: `tlc_plugin_image_metrics` (simplest), the training plugins.
+
+### Code patterns
+
+**Config store** (if the plugin has saved configurations):
+- Use the shared `PluginConfigStore` from `tlc_plugin_sdk.shared.config_store`
+  (generic over your config dataclass; JSON persistence under the plugin's config dir).
+- Pair it with `config_ui_script()` from `tlc_plugin_sdk.shared.config_ui` for the config bar
+  (inject via `inject_scripts()`). See the sam3 / timm plugins.
+
+**Long-running jobs** (training, inference, multi-step import):
+- Implement `run_job(ctx)` — the host owns the queue, GPU/CPU slot, progress fan-out,
+  listing, and cancellation.
+- Drive the generic Queue & Progress panel via `ctx.progress`/`ctx.metric`/`ctx.result`;
+  poll `ctx.cancelled` at checkpoints. The same `run_job` runs in `host` or `venv` mode.
+- Do **not** hand-roll a queue, job store, or job-schema translation — all host-provided.
+
+**Routes** (custom REST):
+- A module-level `get_route_handlers()` returning bare `@get`/`@post` handlers with
+  **relative** paths (no `Controller`, no `/api/plugins` prefix, `sync_to_thread=True` for
+  blocking work). The plugin class delegates to it. They resolve under
+  `/api/plugins/<plugin-id>/...` via the host's per-plugin app + catch-all.
+- CRUD for configs: relative `GET /configs`, `POST /configs`, `GET /configs/{id}`,
+  `POST /configs/{id}/delete`.
+- Do **not** add `GET /queue` / `POST /cancel/{id}` / a job-start route — long-running work
+  goes through the generic `POST /api/plugins/{id}/run`, `GET /api/plugins/jobs`, and
+  `POST /api/plugins/jobs/{job_id}/cancel`. Custom routes carry only genuinely
+  plugin-specific surface (config CRUD, metadata lookups, column detection, …).
+
+**Error response convention:**
+- Pre-validation errors (bad input): return `{"error": "description"}`
+- Execution results (job completed): return `{"success": true/false, "message": "..."}`
+- Not found: raise `HTTPException(status_code=404)`
+
+**URL aliases** (if the plugin creates tables from image folders):
+- `from tlc_plugin_sdk.shared.aliases import register_alias`; call
+  `register_alias(project_name, image_folder, alias_token)` after table creation.
+- Shared UI component: `from tlc_plugin_sdk.shared.alias_ui import alias_ui_script`; inject
+  into the fragment with `inject_scripts()` (never `str.replace` — see
+  `tlc_plugin_sdk/shared/ui_inject.py` for why).
+- In the UI: `_tlcAliasSettingsHtml(prefix, project, folder)` renders the form;
+  `_tlcBindAliasToggle(prefix)` + `_tlcBindAliasAutoUpdate(prefix, projectInputId,
+  folderInputId)` bind it; `_tlcGetAliasValues(prefix)` at submit time; after programmatic
+  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.
+- 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.
+
+### Common mistakes to avoid
+
+- Don't add a `register()` call or metadata class attributes — the manifest is the only
+  metadata source
+- Don't add plugin-specific logic to the frontend (templates, JS modules)
+- Don't use bare `fetch()` in the UI — always use `PLUGIN_API.authFetch()`
+- Don't hardcode colors — use CSS variables
+- Don't create new shared utilities for one-off operations
+- Don't duplicate the alias UI HTML/JS — use `tlc_plugin_sdk/shared/alias_ui.py`, injected
+  at serve time via `inject_scripts()`
+- Don't grab a GPU queue or push a closure — implement `run_job(ctx)`
+- Don't implement `get_active_jobs`/`cancel_job` or add `/queue`/`/cancel` routes — host-owned
+- Don't `async`-define `run_job` — it runs synchronously on a host/worker thread; poll
+  `ctx.cancelled`
+
+### Testing
+
+- Co-locate tests with the plugin (its own `tests/`).
+- Test both success and error paths for all endpoints.
+- For `run_job(ctx)`, drive it with a fake `JobContext` (a recording sink + a
+  `threading.Event` for cancel) and assert the emitted `progress`/`metric`/`result`
+  events — no GPU or queue needed.