3lc-compute-plugin-sdk 0.2.2__py3-none-any.whl

tlc_plugin_sdk/shared/data_source_ui.py

@@ -0,0 +1,365 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+r"""Shared UI component for data-source inputs (files and folders on the compute node).
+
+Generates the HTML + JS block that plugins embed in their UI fragments.
+This ensures a consistent file/folder selection experience across every plugin
+that needs to reference data on the compute node — local paths, S3 URLs, or
+browser-uploaded files all resolve to a compute-visible location.
+
+Usage in a plugin's ``get_ui_fragment()``::
+
+    from tlc_plugin_sdk.shared.data_source_ui import data_source_ui_script
+    from tlc_plugin_sdk.shared.ui_inject import inject_scripts
+
+    raw = Path("ui.html").read_text()
+    html = inject_scripts(raw, data_source_ui_script())
+
+Then in the plugin's ``ui.html`` JavaScript:
+
+.. code-block:: javascript
+
+    // Render a data-source input
+    var html = _tlcDataSourceHtml('my-field', {
+        placeholder: 'Path to dataset YAML...',
+        accept: '*.yaml,*.yml',      // glob filter for the browser
+        allowUpload: false,           // show upload toggle?
+        mode: 'file',                 // 'file' or 'folder'
+    });
+    container.innerHTML = html;
+
+    // Bind the browse/upload handlers (call AFTER inserting into DOM)
+    _tlcBindDataSource('my-field', computeUrl, pluginId);
+
+    // Read the value at submit time
+    var path = _tlcGetDataSourceValue('my-field');
+
+The widget requires the plugin to serve the ``/browse`` and (optionally)
+``/upload-temp`` routes from :mod:`~tlc_plugin_sdk.shared.data_source_routes`.
+"""
+
+from __future__ import annotations
+
+# fmt: off
+DATA_SOURCE_UI_JS = (
+    "// -- Shared Data Source UI ------\n"
+    "(function(){\n"
+    "var st=document.createElement('style');st.textContent=\n"
+    "'.tlc-ds-wrapper{position:relative}'"
+    "+'.tlc-ds-browse-panel{position:absolute;left:0;right:0;z-index:100;'"
+    "+' border:1px solid var(--border);border-radius:6px;'"
+    "+' margin-top:4px;max-height:320px;overflow-y:auto;background:var(--bg-card);'"
+    "+' font-size:12px;display:none;'"
+    "+' box-shadow:0 4px 16px rgba(0,0,0,.12)}'"
+    "+'.tlc-ds-browse-panel.open{display:block}'"
+    "+'.tlc-ds-breadcrumb{display:flex;align-items:center;gap:2px;padding:8px 10px;'"
+    "+' border-bottom:1px solid var(--border);font-size:11px;flex-wrap:wrap;'"
+    "+' background:var(--bg-secondary,rgba(0,0,0,.02))}'"
+    "+'.tlc-ds-breadcrumb span{cursor:pointer;color:var(--accent);font-weight:500}'"
+    "+'.tlc-ds-breadcrumb span:hover{text-decoration:underline}'"
+    "+'.tlc-ds-breadcrumb .sep{color:var(--text-muted);cursor:default;margin:0 1px}'"
+    "+'.tlc-ds-breadcrumb .sep:hover{text-decoration:none}'"
+    "+'.tlc-ds-entry{display:flex;align-items:center;gap:8px;padding:5px 10px;'"
+    "+' cursor:pointer;border-bottom:1px solid var(--border-light,rgba(0,0,0,.04))}'"
+    "+'.tlc-ds-entry:hover{background:var(--golden-light,rgba(217,119,6,.06))}'"
+    "+'.tlc-ds-entry:last-child{border-bottom:none}'"
+    "+'.tlc-ds-entry .ds-icon{flex-shrink:0;width:16px;text-align:center;font-size:13px}'"
+    "+'.tlc-ds-entry .ds-name{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}'"
+    "+'.tlc-ds-entry .ds-size{font-size:10px;color:var(--text-muted);flex-shrink:0}'"
+    # Scoped to the panel (not .tlc-ds-entry): the folder-mode select button renders in
+    # the BREADCRUMB — entry-scoped rules left it a naked native <button>.
+    "+'.tlc-ds-browse-panel .ds-select-btn{font-size:10px;padding:2px 8px;border:1px solid var(--border);'"
+    "+' border-radius:3px;background:var(--bg-card);cursor:pointer;color:var(--accent);font-weight:600;flex-shrink:0}'"
+    "+'.tlc-ds-browse-panel .ds-select-btn:hover{background:var(--accent);color:#fff;border-color:var(--accent)}'"
+    "+'.tlc-ds-empty{padding:16px;text-align:center;color:var(--text-muted);font-size:11px}'"
+    "+'.tlc-ds-error{padding:10px;color:var(--error,#ef4444);font-size:11px}'"
+    "+'.tlc-ds-upload-zone{position:absolute;left:0;right:0;z-index:100;'"
+    "+' border:2px dashed var(--border);border-radius:6px;padding:20px;'"
+    "+' text-align:center;cursor:pointer;transition:border-color .15s,background .15s;'"
+    "+' margin-top:4px;display:none;font-size:12px;background:var(--bg-card);'"
+    "+' box-shadow:0 4px 16px rgba(0,0,0,.12)}'"
+    "+'.tlc-ds-upload-zone.open{display:block}'"
+    "+'.tlc-ds-upload-zone:hover{border-color:var(--accent);background:var(--accent-light,rgba(42,74,97,.04))}'"
+    "+'.tlc-ds-upload-zone.dragging{border-color:var(--accent);background:var(--accent-light,rgba(42,74,97,.08))}'"
+    "+'.tlc-ds-upload-info{font-size:11px;color:var(--text-muted);margin-top:4px;display:none}'"
+    "+'.tlc-ds-actions{display:flex;gap:6px;align-items:center}';\n"
+    "document.head.appendChild(st)})();\n"
+    "\n"
+    "function _tlcDataSourceHtml(idPrefix, config) {\n"
+    "  config = config || {};\n"
+    "  var ph = config.placeholder || 'Path on compute node or URL…';\n"
+    "  var allowUpload = config.allowUpload || false;\n"
+    "  var accept = config.accept || '';\n"
+    "  var h = '';\n"
+    "  h += '<div class=\"tlc-ds-wrapper\">';\n"
+    "  h += '<div class=\"tlc-ds-actions\">';\n"
+    "  h += '<input type=\"text\" id=\"' + idPrefix + '\" class=\"form-control\"';\n"
+    "  h += ' placeholder=\"' + ph + '\" style=\"flex:1\">';\n"
+    "  h += '<button type=\"button\" class=\"btn btn-secondary btn-sm\" id=\"' + idPrefix + '-ds-browse-btn\"';\n"
+    "  h += ' style=\"white-space:nowrap\">Browse…</button>';\n"
+    "  if (allowUpload) {\n"
+    "    h += '<button type=\"button\" class=\"btn btn-secondary btn-sm\" id=\"' + idPrefix + '-ds-upload-btn\"';\n"
+    "    h += ' style=\"white-space:nowrap\">Upload</button>';\n"
+    "  }\n"
+    "  h += '</div>';\n"
+    "  // Browse panel (inline, hidden by default)\n"
+    "  h += '<div class=\"tlc-ds-browse-panel\" id=\"' + idPrefix + '-ds-panel\"></div>';\n"
+    "  // Upload zone (hidden by default)\n"
+    "  if (allowUpload) {\n"
+    "    var acceptAttr = accept ? accept.split(',').map(function(g){"
+    " return g.trim().replace('*',''); }).join(',') : '';\n"
+    "    h += '<div class=\"tlc-ds-upload-zone\" id=\"' + idPrefix + '-ds-upload-zone\">';\n"
+    "    h += '<div style=\"font-weight:600;margin-bottom:4px\">Drop file here</div>';\n"
+    "    h += '<div style=\"color:var(--text-muted)\">or click to browse';\n"
+    "    if (accept) h += ' — ' + accept;\n"
+    "    h += '</div>';\n"
+    "    h += '<input type=\"file\" id=\"' + idPrefix + '-ds-file-input\"';\n"
+    "    if (acceptAttr) h += ' accept=\"' + acceptAttr + '\"';\n"
+    "    h += ' style=\"display:none\">';\n"
+    "    h += '</div>';\n"
+    "    h += '<div class=\"tlc-ds-upload-info\" id=\"' + idPrefix + '-ds-upload-info\"></div>';\n"
+    "  }\n"
+    "  h += '</div>';  // close .tlc-ds-wrapper\n"
+    "  return h;\n"
+    "}\n"
+    "\n"
+    "function _tlcBindDataSource(idPrefix, computeUrl, pluginId, config) {\n"
+    "  config = config || {};\n"
+    "  var glob = config.accept || '';\n"
+    "  var mode = config.mode || 'file';\n"
+    "  var input = document.getElementById(idPrefix);\n"
+    "  var browseBtn = document.getElementById(idPrefix + '-ds-browse-btn');\n"
+    "  var panel = document.getElementById(idPrefix + '-ds-panel');\n"
+    "  var uploadBtn = document.getElementById(idPrefix + '-ds-upload-btn');\n"
+    "  var uploadZone = document.getElementById(idPrefix + '-ds-upload-zone');\n"
+    "  var API = window.PLUGIN_API;\n"
+    "\n"
+    "  // Format file sizes\n"
+    "  function _fmtSize(bytes) {\n"
+    "    if (bytes == null) return '';\n"
+    "    if (bytes < 1024) return bytes + ' B';\n"
+    "    if (bytes < 1048576) return (bytes / 1024).toFixed(1) + ' KB';\n"
+    "    return (bytes / 1048576).toFixed(1) + ' MB';\n"
+    "  }\n"
+    "\n"
+    "  function _esc(s) {\n"
+    "    if (!s) return '';\n"
+    "    var d = document.createElement('div');\n"
+    "    d.textContent = s;\n"
+    "    return d.innerHTML;\n"
+    "  }\n"
+    "\n"
+    "  // Browse panel\n"
+    "  var _panelOpen = false;\n"
+    "  browseBtn.addEventListener('click', function() {\n"
+    "    _panelOpen = !_panelOpen;\n"
+    "    panel.classList.toggle('open', _panelOpen);\n"
+    "    if (uploadZone) { uploadZone.classList.remove('open'); }\n"
+    "    if (_panelOpen) {\n"
+    "      var startPath = input.value.trim() || '~';\n"
+    "      // If the current value is a file path, browse its parent directory\n"
+    "      if (startPath !== '~' && startPath.indexOf('://') === -1) {\n"
+    "        var lastSlash = startPath.lastIndexOf('/');\n"
+    "        if (lastSlash > 0) startPath = startPath.substring(0, lastSlash);\n"
+    "      }\n"
+    "      _browseTo(startPath);\n"
+    "    }\n"
+    "  });\n"
+    "\n"
+    "  function _browseTo(dirPath) {\n"
+    "    panel.innerHTML = '<div class=\"tlc-ds-empty\">Loading…</div>';\n"
+    "    var url = computeUrl + '/api/plugins/' + pluginId + '/browse?path=' + encodeURIComponent(dirPath);\n"
+    "    if (glob) url += '&glob=' + encodeURIComponent(glob);\n"
+    "    API.authFetch(url)\n"
+    "      .then(function(r) { return r.json(); })\n"
+    "      .then(function(data) {\n"
+    "        if (data.error) {\n"
+    "          panel.innerHTML = '<div class=\"tlc-ds-error\">' + _esc(data.error) + '</div>';\n"
+    "          return;\n"
+    "        }\n"
+    "        _renderBrowse(data);\n"
+    "      })\n"
+    "      .catch(function(err) {\n"
+    "        panel.innerHTML = '<div class=\"tlc-ds-error\">Failed to browse: ' + _esc(String(err)) + '</div>';\n"
+    "      });\n"
+    "  }\n"
+    "\n"
+    "  function _renderBrowse(data) {\n"
+    "    var h = '';\n"
+    "    // Breadcrumb — anchored at the confinement root: segments above it are not\n"
+    "    // places this picker can go, so they aren't rendered at all. The root shows\n"
+    "    // as its basename; only the path below it gets '/'-separated segments.\n"
+    "    var rootPath = data.root || '/';\n"
+    "    h += '<div class=\"tlc-ds-breadcrumb\">';\n"
+    "    var rel, base;\n"
+    "    if (rootPath === '/') {\n"
+    "      h += '<span data-ds-nav=\"/\">/</span>';\n"
+    "      rel = data.path.split('/').filter(Boolean);\n"
+    "      base = '';\n"
+    "    } else {\n"
+    "      var rootLabel = rootPath.split('/').filter(Boolean).pop() || '/';\n"
+    "      h += '<span data-ds-nav=\"' + _esc(rootPath) + '\">' + _esc(rootLabel) + '</span>';\n"
+    "      rel = data.path.slice(rootPath.length).split('/').filter(Boolean);\n"
+    "      base = rootPath;\n"
+    "    }\n"
+    "    for (var i = 0; i < rel.length; i++) {\n"
+    "      h += '<span class=\"sep\">/</span>';\n"
+    "      base = base + '/' + rel[i];\n"
+    "      h += '<span data-ds-nav=\"' + _esc(base) + '\">' + _esc(rel[i]) + '</span>';\n"
+    "    }\n"
+    "    // Select-folder button (for mode='folder')\n"
+    "    if (mode === 'folder') {\n"
+    "      h += '<button type=\"button\" class=\"ds-select-btn\" data-ds-select-folder=\"' + _esc(data.path) + '\"'"
+    "         + ' style=\"margin-left:auto\">Select This Folder</button>';\n"
+    "    }\n"
+    "    h += '</div>';\n"
+    "    // Entries\n"
+    "    if (data.parent != null) {\n"
+    "      h += '<div class=\"tlc-ds-entry\" data-ds-nav=\"' + _esc(data.parent) + '\">';\n"
+    "      h += '<span class=\"ds-icon\">↑</span>';\n"
+    "      h += '<span class=\"ds-name\" style=\"color:var(--text-muted)\">..</span>';\n"
+    "      h += '</div>';\n"
+    "    }\n"
+    "    if (!data.entries || data.entries.length === 0) {\n"
+    "      h += '<div class=\"tlc-ds-empty\">Empty directory</div>';\n"
+    "    } else {\n"
+    "      data.entries.forEach(function(e) {\n"
+    "        h += '<div class=\"tlc-ds-entry\"';\n"
+    "        if (e.type === 'dir') {\n"
+    "          h += ' data-ds-nav=\"' + _esc(data.path.replace(/\\/$/, '') + '/' + e.name) + '\"';\n"
+    "        }\n"
+    "        h += '>';\n"
+    "        h += '<span class=\"ds-icon\">' + (e.type === 'dir' ? '📁' : '📄') + '</span>';\n"
+    "        h += '<span class=\"ds-name\">' + _esc(e.name) + (e.type === 'dir' ? '/' : '') + '</span>';\n"
+    "        if (e.size != null) h += '<span class=\"ds-size\">' + _fmtSize(e.size) + '</span>';\n"
+    "        if (e.type === 'file') {\n"
+    "          h += '<button type=\"button\" class=\"ds-select-btn\" data-ds-select=\"'"
+    "             + _esc(data.path.replace(/\\/$/, '') + '/' + e.name) + '\">Select</button>';\n"
+    "        }\n"
+    "        h += '</div>';\n"
+    "      });\n"
+    "    }\n"
+    "    panel.innerHTML = h;\n"
+    "\n"
+    "    // Bind navigation clicks\n"
+    "    panel.querySelectorAll('[data-ds-nav]').forEach(function(el) {\n"
+    "      el.addEventListener('click', function(ev) {\n"
+    "        ev.stopPropagation();\n"
+    "        _browseTo(el.getAttribute('data-ds-nav'));\n"
+    "      });\n"
+    "    });\n"
+    "    // Bind select buttons\n"
+    "    panel.querySelectorAll('[data-ds-select]').forEach(function(el) {\n"
+    "      el.addEventListener('click', function(ev) {\n"
+    "        ev.stopPropagation();\n"
+    "        input.value = el.getAttribute('data-ds-select');\n"
+    "        _panelOpen = false;\n"
+    "        panel.classList.remove('open');\n"
+    "        input.dispatchEvent(new Event('input', {bubbles: true}));\n"
+    "        input.dispatchEvent(new Event('change', {bubbles: true}));\n"
+    "      });\n"
+    "    });\n"
+    "    // Bind select-folder button\n"
+    "    panel.querySelectorAll('[data-ds-select-folder]').forEach(function(el) {\n"
+    "      el.addEventListener('click', function(ev) {\n"
+    "        ev.stopPropagation();\n"
+    "        input.value = el.getAttribute('data-ds-select-folder');\n"
+    "        _panelOpen = false;\n"
+    "        panel.classList.remove('open');\n"
+    "        input.dispatchEvent(new Event('input', {bubbles: true}));\n"
+    "        input.dispatchEvent(new Event('change', {bubbles: true}));\n"
+    "      });\n"
+    "    });\n"
+    "  }\n"
+    "\n"
+    "  // Upload zone\n"
+    "  if (uploadBtn && uploadZone) {\n"
+    "    var fileInput = document.getElementById(idPrefix + '-ds-file-input');\n"
+    "    var uploadInfo = document.getElementById(idPrefix + '-ds-upload-info');\n"
+    "\n"
+    "    uploadBtn.addEventListener('click', function() {\n"
+    "      var isOpen = uploadZone.classList.toggle('open');\n"
+    "      if (isOpen) { panel.classList.remove('open'); _panelOpen = false; }\n"
+    "    });\n"
+    "\n"
+    "    uploadZone.addEventListener('click', function() { fileInput.click(); });\n"
+    "    uploadZone.addEventListener('dragover', function(ev) {\n"
+    "      ev.preventDefault(); uploadZone.classList.add('dragging');\n"
+    "    });\n"
+    "    uploadZone.addEventListener('dragleave', function() {\n"
+    "      uploadZone.classList.remove('dragging');\n"
+    "    });\n"
+    "    uploadZone.addEventListener('drop', function(ev) {\n"
+    "      ev.preventDefault(); uploadZone.classList.remove('dragging');\n"
+    "      if (ev.dataTransfer.files.length > 0) _uploadFile(ev.dataTransfer.files[0]);\n"
+    "    });\n"
+    "    fileInput.addEventListener('change', function() {\n"
+    "      if (fileInput.files.length > 0) _uploadFile(fileInput.files[0]);\n"
+    "    });\n"
+    "\n"
+    "    function _uploadFile(file) {\n"
+    "      uploadInfo.style.display = '';\n"
+    "      uploadInfo.textContent = 'Uploading ' + file.name + '…';\n"
+    "      uploadZone.style.opacity = '0.6';\n"
+    "      uploadZone.style.pointerEvents = 'none';\n"
+    "\n"
+    "      var formData = new FormData();\n"
+    "      formData.append('data', file);\n"
+    "\n"
+    "      API.authFetch(computeUrl + '/api/plugins/' + pluginId + '/upload-temp', {\n"
+    "        method: 'POST',\n"
+    "        body: formData,\n"
+    "      })\n"
+    "      .then(function(r) { return r.json(); })\n"
+    "      .then(function(result) {\n"
+    "        input.value = result.path;\n"
+    "        uploadInfo.innerHTML = '<span style=\"color:var(--success)\">✓</span> '"
+    "          + _esc(file.name) + ' <span style=\"color:var(--text-muted)\">→ '"
+    "          + _esc(result.path) + '</span>';\n"
+    "        uploadZone.classList.remove('open');\n"
+    "        input.dispatchEvent(new Event('input', {bubbles: true}));\n"
+    "        input.dispatchEvent(new Event('change', {bubbles: true}));\n"
+    "      })\n"
+    "      .catch(function(err) {\n"
+    "        uploadInfo.innerHTML = '<span style=\"color:var(--error)\">Upload failed:</span> '"
+    "          + _esc(String(err));\n"
+    "      })\n"
+    "      .finally(function() {\n"
+    "        uploadZone.style.opacity = '';\n"
+    "        uploadZone.style.pointerEvents = '';\n"
+    "      });\n"
+    "    }\n"
+    "  }\n"
+    "\n"
+    "  // Close panel on outside click\n"
+    "  document.addEventListener('click', function(ev) {\n"
+    "    if (!_panelOpen) return;\n"
+    "    var wrapper = input.closest('.tlc-ds-wrapper');\n"
+    "    if (wrapper && !wrapper.contains(ev.target)) {\n"
+    "      _panelOpen = false;\n"
+    "      panel.classList.remove('open');\n"
+    "      if (uploadZone) uploadZone.classList.remove('open');\n"
+    "    }\n"
+    "  });\n"
+    "}\n"
+    "\n"
+    "function _tlcGetDataSourceValue(idPrefix) {\n"
+    "  var el = document.getElementById(idPrefix);\n"
+    "  return el ? el.value.trim() : '';\n"
+    "}\n"
+    "\n"
+    "function _tlcSetDataSourceValue(idPrefix, value) {\n"
+    "  var el = document.getElementById(idPrefix);\n"
+    "  if (el) {\n"
+    "    el.value = value || '';\n"
+    "    el.dispatchEvent(new Event('input', {bubbles: true}));\n"
+    "    el.dispatchEvent(new Event('change', {bubbles: true}));\n"
+    "  }\n"
+    "}\n"
+)
+# fmt: on
+
+
+def data_source_ui_script() -> str:
+    """Return the shared data-source UI JavaScript block."""
+    return DATA_SOURCE_UI_JS

tlc_plugin_sdk/shared/generic_job.py

@@ -0,0 +1,58 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared helper for translating training progress into the generic progress schema.
+
+Used by training plugins inside ``run_job``: they compute an
+epoch/batch progress dict and call :func:`epoch_progress` to render the generic
+``{percent, label, timing}`` shape the frontend understands, which they then push
+through their own ``ctx.emit`` channel. (The host owns job *listing* and *cancel*;
+this module only shapes the progress payload.)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def epoch_progress(
+    progress: dict[str, Any],
+    *,
+    phase_key: str = "phase",
+    epoch_key: str = "epoch",
+    total_key: str = "total_epochs",
+    batch_frac_key: str = "batch_frac",
+    step_label: str = "epoch",
+) -> dict[str, Any] | None:
+    """Build progress dict from epoch/batch-based training progress.
+
+    Common to epoch-based training plugins.
+    """
+    if not progress:
+        return None
+
+    epoch = progress.get(epoch_key, 0)
+    total = progress.get(total_key, 0)
+    if total <= 0:
+        return None
+
+    batch_frac = progress.get(batch_frac_key, 0)
+    percent = int(((epoch - 1 + batch_frac) / total) * 100) if total > 0 else 0
+    percent = max(0, min(100, percent))
+
+    phase = progress.get(phase_key, "")
+    label = f"Epoch {epoch}/{total}" if total > 0 else ""
+    if phase:
+        label = f"{label} · {phase}" if label else phase
+
+    result: dict[str, Any] = {"percent": percent, "label": label}
+
+    timing = progress.get("timing")
+    if timing:
+        result["timing"] = {
+            "elapsed_s": timing.get("elapsed_s"),
+            "eta_s": timing.get("eta_s"),
+            "avg_step_s": timing.get("avg_epoch_s", timing.get("avg_step_s")),
+            "step_label": step_label,
+        }
+
+    return result