3lc-compute-plugin-insights 0.2.0__tar.gz

3lc_compute_plugin_insights-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+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:
+  ruff:
+    name: ruff (lint + format)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+
+      # Ruff runs STANDALONE (uvx): linting must not require resolving the per-plugin
+      # dependency stacks — that would be slow and need extra indexes. Config lives in
+      # pyproject [tool.ruff]; pin matches 3lc-compute-plugin-sdk.
+      - name: Ruff lint
+        run: uvx --from 'ruff>=0.15,<0.16' ruff check .
+
+      - name: Ruff format check
+        run: uvx --from 'ruff>=0.15,<0.16' ruff format --check .
+
+  lockfile:
+    name: lockfile check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+
+      - name: Verify lockfile is up to date
+        run: uv lock --check
+
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.15"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install base deps + dev group
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -v
+        env:
+          # The suite imports the released `3lc` wheel, which validates an API key against
+          # the account service at import time — there is no offline bypass in released
+          # wheels. CI authenticates the same way the 3lc-ultralytics suite does: the
+          # org-level testing key plus the environment-redirection pairs (secret-named env
+          # vars that point the wheel at the environment the key belongs to). The tests
+          # touch only local data.
+          TLC_API_KEY: ${{ secrets.TLC_API_KEY }}
+          ${{ secrets.DEFAULT_TESTING_RUNTIME_NAME }}: ${{ secrets.DEFAULT_TESTING_RUNTIME_VALUE }}
+          ${{ secrets.DEFAULT_TESTING_S_ENV_NAME }}: ${{ secrets.DEFAULT_TESTING_S_ENV_VALUE }}

3lc_compute_plugin_insights-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,63 @@
+name: Release
+
+# Tag (`v*`) pushes publish to public PyPI via Trusted Publishing (GitHub OIDC, no secrets —
+# works from this private repo). To cut a release: bump `version` in pyproject.toml AND every
+# plugin's plugin.toml (they move together), regenerate uv.lock, update CHANGELOG.md, commit,
+# then push a tag `vX.Y.Z` that matches the version.
+#
+# NOTE: `uv build --no-sources` builds the WHEEL only — it does not resolve or install the
+# per-plugin dependency stacks. The wheel's metadata carries the SDK pin, resolved from PyPI
+# at install time.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  # Gate the release on the full CI suite (ruff · lockfile · pytest).
+  test:
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+
+  publish-pypi:
+    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; }
+
+      # The version a plugin card reports comes from its manifest; a tag with drifting
+      # manifests would ship plugins that misreport their own release.
+      - name: Verify plugin manifests match pyproject version
+        run: |
+          PKG=$(uv version --output-format json | jq -r '.version')
+          FAIL=0
+          for MANIFEST in src/*/plugin.toml; do
+            V=$(grep -Po '^version\s*=\s*"\K[^"]+' "$MANIFEST")
+            echo "$MANIFEST: $V"
+            [ "$V" = "$PKG" ] || { echo "::error::$MANIFEST version $V != pyproject version $PKG"; FAIL=1; }
+          done
+          exit $FAIL
+
+      # --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

3lc_compute_plugin_insights-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.vscode/
+.idea/
+.DS_Store

3lc_compute_plugin_insights-0.2.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `3lc-compute-plugin-insights` (the distribution of 3LC's insights plugins
+for the 3LC compute service) 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.0] - 2026-08-21
+
+### Added
+- Initial release: `run-insights` and `table-insights` extracted from the compute service host
+  (`3lc-compute`), where they were the last two in-tree `host`-isolation plugins. Both now ship
+  as `venv`-isolated plugins of this standalone distribution, provisioned from the
+  `[run_insights]` / `[table_insights]` extras. Plugin ids, UI metadata, and behavior are
+  unchanged; the import packages are `tlc_plugin_run_insights` / `tlc_plugin_table_insights`
+  (fleet naming), and the `python_workflow_builder` helper is vendored inside
+  `tlc_plugin_run_insights/_vendor/`.
+- The insights-domain test suite moved along with the code (keypoints/OKS, pose and
+  semantic-segmentation comparisons, metrics-delta grading, routing, and workflow-install URL
+  tests).
+- CI (ruff lint/format, `uv lock --check`, pytest) and a tag-driven PyPI Trusted Publishing
+  release workflow, following the plugin-fleet shape. Version 0.2.0 matches the fleet cadence.

3lc_compute_plugin_insights-0.2.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# 3lc-compute-plugin-insights — agent & contributor orientation
+
+This repo is 3LC's **proprietary** insights-plugin collection for the 3LC compute service,
+packaged as a single distribution `3lc-compute-plugin-insights`, built against the public
+[`3lc-compute-plugin-sdk`](https://github.com/3lc-ai/3lc-compute-plugin-sdk). It follows the
+umbrella shape of `3lc-compute-plugins` (multi-plugin, one dist) but is NOT part of the open
+fleet: the repo is private, the license is proprietary (see `LICENSE`), and source files carry
+the 3LC all-rights-reserved header — never the fleet's Apache SPDX header.
+
+## Layout
+
+```
+pyproject.toml               # the one distribution: 3lc-compute-plugin-insights
+src/
+  tlc_plugin_run_insights/   # run statistics, health scores, run comparisons
+    __init__.py              # the plugin class — behavior only
+    plugin.toml              # manifest — host reads it WITHOUT importing (id, ui, runtime.*)
+    statistics/              # modality handlers, operations, insight cards
+    workflows/               # dashboard-workflow generators + runtime install helpers
+    _vendor/                 # vendored python_workflow_builder (mirrored from tlc-ui)
+    ui.html, ...
+  tlc_plugin_table_insights/ # dataset-quality analysis; imports run_insights internals (same dist)
+tests/                       # insights-domain suite (moved from 3lc-compute with the code)
+```
+
+One `pyproject.toml` declares both plugins:
+- **base `dependencies`** = the SDK floor ONLY (`3lc-compute-plugin-sdk[shared]`). Both plugins are
+  `venv`-isolated, so NO plugin deps live in the base — this distribution is never installed into
+  the host venv.
+- **per-plugin extras** (`[run_insights]` / `[table_insights]`) = each plugin's deps, installed
+  ONLY into that plugin's provisioned venv (named by the manifest's `runtime.provision_extra`).
+- **`[project.entry-points."tlc_compute.plugins"]`** = one entry per plugin, supporting the
+  optional installed-package discovery path. The primary path is a **folder Source** pointed at
+  `src/`.
+
+## The rules — do not break these
+
+1. **Touch the host only through the SDK.** A plugin imports `tlc_plugin_sdk` and nothing from
+   `tlc_compute` (the host). The mental test: *could this build against just the SDK wheel, with
+   the host source deleted?* It must.
+2. **Every plugin's deps are its own venv, never the host venv.**
+3. **Metadata lives in `plugin.toml`, not on the class.** No `register()` at import; the class is
+   behavior-only.
+4. **Custom events / routes are plugin-private.** Use the generic job channel for anything the
+   shell renders; `ctx.emit` + your own `ui.html` for plugin-specific UI.
+5. **Proprietary headers stay.** Every source file keeps the 3LC "All rights reserved" copyright
+   block; new files get the same block with the current year. Do not add SPDX/Apache headers.
+
+## Cross-package note
+
+`tlc_plugin_table_insights` imports `tlc_plugin_run_insights` internals (comparison and
+statistics modules). That's fine within this one distribution — both packages install together —
+but it means the `table_insights` extra mirrors `run_insights`' deps.
+
+## The vendored workflow builder
+
+`tlc_plugin_run_insights/_vendor/python_workflow_builder/` is a vendored copy of the tlc-ui
+repo's helper for building dashboard `UserDefinedWorkflow` JSONs.
+`workflows/__init__.py` injects it onto `sys.path` at import. It is excluded from ruff; don't
+edit it here — re-mirror from tlc-ui if it needs updating.
+
+## Versioning
+
+The **distribution** versions as a whole (`[project] version`), and every `plugin.toml` `version`
+must match it — release.yml enforces this at tag time. SemVer; version cadence follows the
+plugin fleet. To cut a release: bump `pyproject.toml` + both manifests, `uv lock`, update
+CHANGELOG.md, commit, tag `vX.Y.Z` — CI publishes to PyPI via Trusted Publishing (the PyPI
+project is reserved; publishing works from this private repo).
+
+## Dev setup
+
+```bash
+uv sync --group dev           # SDK floor + test deps (normal uv usage is fine here — no overlays)
+uv run pytest
+uvx --from 'ruff>=0.15,<0.16' ruff check .
+uv lock --check
+```
+
+All deps resolve from public PyPI. For local SDK development, override (uncommitted) with an
+editable path source:
+
+```toml
+[tool.uv.sources]
+3lc-compute-plugin-sdk = { path = "../3lc-compute-plugin-sdk", editable = true }
+```
+
+## Where the rest of the context lives
+
+The plugin contract and the author guide live in `3lc-compute-plugin-sdk`
+(`docs/plugin-guide.md`, published at <https://3lc-ai.github.io/3lc-compute-plugin-sdk/>). Host
+internals and the *why* of the plugin architecture live in the private `3lc-compute` repo's
+`docs/`.
+
+## Conventions
+
+Python 3.10+, uv, Hatchling, Litestar route handlers (`get_route_handlers()`), Ruff (line-length
+120). Google-style docstrings. Proprietary 3LC copyright block on new files (current year).

3lc_compute_plugin_insights-0.2.0/LICENSE

@@ -0,0 +1,10 @@
+Copyright (c) 2026 3LC Inc. All rights reserved.
+
+All rights are reserved. Reproduction or transmission in whole or in part, in
+any form or by any means, electronic, mechanical or otherwise, is prohibited
+without the prior written permission of the copyright owner.
+
+This is proprietary software of 3LC Inc. It is NOT open-source software and is
+not licensed under any open-source license. Source code readability in the
+distributed artifacts does not grant any rights to use, copy, modify, or
+redistribute it.

3lc_compute_plugin_insights-0.2.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: 3lc-compute-plugin-insights
+Version: 0.2.0
+Summary: 3LC insights plugins for the 3LC compute service (run-insights, table-insights).
+Author-email: 3LC <pypi-admins@3lc.ai>
+License: Proprietary
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: 3lc-compute-plugin-sdk[shared]<0.3.0,>=0.2.2
+Provides-Extra: run-insights
+Requires-Dist: 3lc<4.0.0,>=3.2.0; extra == 'run-insights'
+Requires-Dist: numpy; extra == 'run-insights'
+Requires-Dist: pandas; extra == 'run-insights'
+Requires-Dist: scipy>=1.10; extra == 'run-insights'
+Provides-Extra: table-insights
+Requires-Dist: 3lc<4.0.0,>=3.2.0; extra == 'table-insights'
+Requires-Dist: numpy; extra == 'table-insights'
+Requires-Dist: pandas; extra == 'table-insights'
+Requires-Dist: scipy>=1.10; extra == 'table-insights'

3lc_compute_plugin_insights-0.2.0/README.md

@@ -0,0 +1,53 @@
+# 3lc-compute-plugin-insights
+
+The [3LC](https://3lc.ai) insights plugins for the 3LC compute service, packaged as a single
+distribution `3lc-compute-plugin-insights` built against the public
+[`3lc-compute-plugin-sdk`](https://github.com/3lc-ai/3lc-compute-plugin-sdk).
+
+```
+pyproject.toml         # the one distribution (SDK floor + per-plugin extras + entry-points)
+src/
+  tlc_plugin_run_insights/    # run statistics, health scores, comparisons  ([run_insights] extra)
+  tlc_plugin_table_insights/  # dataset-quality analysis for tables         ([table_insights] extra)
+```
+
+Each `src/tlc_plugin_<name>/` bundles its own `plugin.toml` manifest (the host reads it **without
+importing**) and advertises a `tlc_compute.plugins` entry point. One `pyproject.toml` declares
+them both; the host discovers by entry point (or by scanning a folder Source), not by repo shape.
+
+Unlike the open first-party fleet
+([`3lc-compute-plugins`](https://github.com/3lc-ai/3lc-compute-plugins) and the standalone
+timm/sam3/yolo repos), this distribution is **proprietary** — the insights plugins are 3LC's own
+analysis engine. See `LICENSE`.
+
+## Isolation
+
+Both plugins are **`venv`-isolated** (`runtime.isolation = "venv"` in their manifests): the host
+provisions a dedicated venv, installs the plugin's extra (e.g.
+`3lc-compute-plugin-insights[run_insights]`), and runs the plugin out-of-process. Its deps never
+touch the host venv.
+
+That's why the base `dependencies` is the **SDK floor only** (`3lc-compute-plugin-sdk[shared]`) —
+this distribution is never installed into the host venv. Each plugin's real deps ride its own
+extra and land only in that plugin's provisioned venv.
+
+## Develop
+
+```bash
+uv sync                          # SDK floor only
+uv sync --extra run_insights     # one plugin's deps (exactly what the host provisions into its venv)
+uv sync --group dev              # test deps
+uv run pytest
+uvx --from 'ruff>=0.15,<0.16' ruff check .
+```
+
+All dependencies resolve from public PyPI. For local SDK development, override with an
+uncommitted editable path source — see `CLAUDE.md`.
+
+## Workflow generators
+
+`tlc_plugin_run_insights/workflows/` holds both the runtime install helpers and the generator
+modules that produce the committed dashboard-workflow `.json` files, built via the vendored
+`python_workflow_builder` package (`tlc_plugin_run_insights/_vendor/`, mirrored from the tlc-ui
+repo). Regenerate a JSON by running its module, e.g.
+`python -m tlc_plugin_run_insights.workflows.missing_annotations`.

3lc_compute_plugin_insights-0.2.0/pyproject.toml

@@ -0,0 +1,132 @@
+# 3lc-compute-plugin-insights — 3LC's own insights plugins for the 3LC compute service, as one
+# distribution. The host discovers each plugin from its bundled `plugin.toml` (read WITHOUT
+# importing) and provisions it into its own venv: every plugin is `venv`-isolated, its deps live in
+# a per-plugin extra below and are installed only into that plugin's venv — never the host venv.
+# The base `dependencies` is the SDK floor only. (The `tlc_compute.plugins` entry points support an
+# optional pip-installed-discovery path; folder-Source discovery is the primary one.)
+#
+# Unlike the open fleet repos (3lc-compute-plugins, -timm, -sam3, -yolo), this distribution is
+# PROPRIETARY: the insights plugins are 3LC's own analysis engine. It ships like the `3lc`
+# package itself does on PyPI — proprietary metadata, all rights reserved, readable source in
+# the wheel. The GitHub repo stays private.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "3lc-compute-plugin-insights"
+version = "0.2.0"
+description = "3LC insights plugins for the 3LC compute service (run-insights, table-insights)."
+requires-python = ">=3.10"
+authors = [
+    {name = "3LC", email = "pypi-admins@3lc.ai"},
+]
+# Proprietary, matching the `3lc` package's metadata — NOT the fleet's Apache-2.0.
+license = {text = "Proprietary"}
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+]
+# Base = the SDK floor ONLY — no plugin deps live here; each plugin's deps ride its own extra
+# below and are installed only into that plugin's venv. `[shared]` adds the SDK's optional `tlc`
+# data plane (`tlc_plugin_sdk.shared.*`), which both plugins use.
+dependencies = [
+    "3lc-compute-plugin-sdk[shared]>=0.2.2,<0.3.0",
+]
+
+# Per-plugin extras — installed ONLY into that plugin's provisioned venv. Provisioning opts into
+# the extra named by the plugin manifest's runtime.provision_extra (`uv sync --extra <id>`).
+#
+# `3lc>=3.2.0`: the semantic-segmentation modality needs `tlc.metrics.semantic_segmentation`
+# (first shipped in 3.1), and 3.2 is the first release on public PyPI. `pycocotools` (RLE mask
+# IoU) and `python-dateutil` (route-side date parsing) both arrive transitively via `3lc` /
+# `pandas`, same as they do for the compute-service host.
+[project.optional-dependencies]
+run_insights = [
+    "3lc>=3.2.0,<4.0.0",
+    "numpy",
+    "pandas",
+    # Segmentation insights (scipy.ndimage — mask island-count / iou matching) and the
+    # semantic-seg calibration operation (scipy.stats).
+    "scipy>=1.10",
+]
+# table-insights imports run_insights internals (run_comparison, statistics.*) — same dist,
+# so the code is present; the extra mirrors run_insights' deps so those imports resolve.
+table_insights = [
+    "3lc>=3.2.0,<4.0.0",
+    "numpy",
+    "pandas",
+    "scipy>=1.10",
+]
+
+# Every plugin advertises itself here; the host iterates this group to discover them all.
+# Value = the import package; its bundled plugin.toml drives id/ui/runtime (and, for venv
+# plugins, the provision extra).
+[project.entry-points."tlc_compute.plugins"]
+run_insights = "tlc_plugin_run_insights"
+table_insights = "tlc_plugin_table_insights"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/tlc_plugin_run_insights",
+    "src/tlc_plugin_table_insights",
+]
+
+# Both `3lc` and `3lc-compute-plugin-sdk` resolve from public PyPI (the SDK's home since
+# 0.2.2) — no custom indexes. For local dev against an in-progress SDK/3lc checkout, add an
+# UNCOMMITTED [tool.uv.sources] override with editable path sources (a committed relative
+# `path = ...` source breaks remote consumers: uv reads it as a subdirectory of this repo).
+
+[dependency-groups]
+# The test suite exercises the plugin code directly, so it needs the per-plugin runtime deps
+# on top of the base sync (tlc/pandas/pycocotools already arrive via the SDK's [shared] extra).
+dev = [
+    "pytest>=8",
+    "numpy",
+    "pandas",
+    "scipy>=1.10",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+# Ruff config mirrors the fleet repos for a consistent house style. CI runs ruff standalone
+# (uvx) — linting must not require resolving the per-plugin dependency stacks.
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".venv",
+    "build",
+    "dist",
+    "**/_vendor/**",  # vendored code (python_workflow_builder, from tlc-ui) — not linted here
+]
+
+[tool.ruff.lint]
+select = ["A", "C4", "E", "EM", "F", "I", "N", "PIE", "RUF", "SIM", "UP", "W"]
+# The extra SIM ignores match 3lc-compute, where this code was written and linted.
+ignore = ["N806", "N818", "SIM102", "SIM103", "SIM105", "SIM108", "SIM114", "SIM118", "RUF001", "RUF002", "RUF003"]
+
+[tool.ruff.lint.per-file-ignores]
+"test_*.py" = [
+    "E402",
+    "SIM117",
+]
+
+[tool.ruff.lint.isort]
+# Pin first-party explicitly so import ordering does not depend on what's installed
+# (see 3lc-compute's pyproject for the full rationale).
+known-first-party = ["tlc_plugin_run_insights", "tlc_plugin_table_insights"]
+known-third-party = ["tlc_plugin_sdk", "python_workflow_builder"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+preview = true
+docstring-code-format = true