PyPI - flexlock - Versions diffs - 0.8.2__py3-none-any.whl - Mend

flexlock 0.8.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

flexlock/__init__.py +87 -0
flexlock/api.py +1444 -0
flexlock/backends/__init__.py +11 -0
flexlock/backends/base.py +41 -0
flexlock/backends/pbs.py +219 -0
flexlock/backends/slurm.py +333 -0
flexlock/cli.py +953 -0
flexlock/config.py +121 -0
flexlock/context.py +7 -0
flexlock/data_hash.py +310 -0
flexlock/debug.py +473 -0
flexlock/diff.py +253 -0
flexlock/diff_cli.py +155 -0
flexlock/exceptions.py +50 -0
flexlock/export.py +134 -0
flexlock/fingerprint.py +129 -0
flexlock/flexcli.py +163 -0
flexlock/freeze.py +291 -0
flexlock/git_utils.py +196 -0
flexlock/index.py +300 -0
flexlock/load_stage.py +60 -0
flexlock/mlflow.py +192 -0
flexlock/parallel.py +378 -0
flexlock/query.py +739 -0
flexlock/report.py +78 -0
flexlock/report_template.html +246 -0
flexlock/resolvers.py +248 -0
flexlock/run_cli.py +44 -0
flexlock/run_record.py +173 -0
flexlock/runner.py +571 -0
flexlock/save_dir.py +232 -0
flexlock/skills/flexlock-new-stage/SKILL.md +57 -0
flexlock/skills/flexlock-report/SKILL.md +50 -0
flexlock/skills/flexlock-run-and-watch/SKILL.md +60 -0
flexlock/skills/flexlock-survey/SKILL.md +61 -0
flexlock/snapshot.py +245 -0
flexlock/status_cli.py +299 -0
flexlock/taskdb.py +685 -0
flexlock/utils.py +710 -0
flexlock/worker.py +228 -0
flexlock/worker_cli.py +143 -0
flexlock-0.8.2.dist-info/METADATA +357 -0
flexlock-0.8.2.dist-info/RECORD +45 -0
flexlock-0.8.2.dist-info/WHEEL +4 -0
flexlock-0.8.2.dist-info/entry_points.txt +7 -0

flexlock/report.py ADDED Viewed

@@ -0,0 +1,78 @@
+"""Zero-dependency static HTML report built on the graph JSON.
+The report is a single self-contained HTML file (all CSS/JS inline, no CDN) so
+it opens offline on an HPC login node. Its stable contract is the embedded JSON
+island (``<script id="flexlock-data">``), which external tools can extract and
+parse independently of the rendering.
+"""
+import json
+from importlib.resources import files
+from pathlib import Path
+from . import query
+from .run_record import _atomic_write
+TEMPLATE_NAME = "report_template.html"
+def _load_template() -> str:
+    return files("flexlock").joinpath(TEMPLATE_NAME).read_text(encoding="utf-8")
+def _json_island(data: dict) -> str:
+    """Serialize + escape so a ``</script>`` (e.g. inside a note) can't break out.
+    ``</`` → ``<\\/`` is a valid JSON string escape (``\\/`` decodes to ``/``),
+    so ``JSON.parse`` round-trips the original text.
+    """
+    return json.dumps(data, default=str).replace("</", "<\\/")
+def generate_report(
+    results_root,
+    out_path,
+    title=None,
+    include_groups=True,
+    embed_configs=False,
+) -> Path:
+    """Render the static HTML report for ``results_root`` to ``out_path``."""
+    results_root = Path(results_root)
+    graph = query.build_graph(results_root, include_groups=include_groups)
+    if embed_configs:
+        for node in graph["nodes"]:
+            lock = query._load_lock(Path(node["id"]))
+            node["config"] = (lock or {}).get("config", {}) if lock else {}
+            # Attach the failure payload too, for the detail pane.
+            if node.get("status") == "failed":
+                st = query.run_status(Path(node["id"]))
+                if st.get("error"):
+                    node["error"] = st["error"]
+    else:
+        # Even without full configs, surface error payloads for failed nodes.
+        for node in graph["nodes"]:
+            if node.get("status") == "failed":
+                st = query.run_status(Path(node["id"]))
+                if st.get("error"):
+                    node["error"] = st["error"]
+    payload = {"graph": graph, "colors": query.STATUS_COLORS}
+    report_title = title or f"FlexLock report — {results_root}"
+    html = _load_template()
+    html = html.replace("{{TITLE}}", _html_escape(report_title))
+    html = html.replace("{{DATA}}", _json_island(payload))
+    out_path = Path(out_path)
+    _atomic_write(out_path, html)
+    return out_path
+def _html_escape(s: str) -> str:
+    return (
+        str(s)
+        .replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )

flexlock/report_template.html ADDED Viewed

@@ -0,0 +1,246 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{TITLE}}</title>
+<style>
+  :root { --bg:#fafafa; --fg:#222; --line:#ddd; --panel:#fff; }
+  * { box-sizing: border-box; }
+  body { margin:0; font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+         background:var(--bg); color:var(--fg); }
+  header { padding:12px 20px; border-bottom:1px solid var(--line); background:var(--panel); }
+  h1 { font-size:18px; margin:0; }
+  .sub { color:#888; font-size:12px; margin-top:2px; }
+  .wrap { display:flex; gap:16px; padding:16px; align-items:flex-start; flex-wrap:wrap; }
+  .col { background:var(--panel); border:1px solid var(--line); border-radius:6px; padding:12px; }
+  .col.table { flex:2 1 520px; min-width:320px; }
+  .col.graph { flex:1 1 320px; min-width:280px; }
+  .col.detail { flex:1 1 320px; min-width:280px; }
+  .controls { display:flex; gap:8px; flex-wrap:wrap; margin-bottom:10px; align-items:center; }
+  input[type=text], select { padding:4px 6px; border:1px solid var(--line); border-radius:4px; font-size:13px; }
+  table { border-collapse:collapse; width:100%; font-size:13px; }
+  th, td { text-align:left; padding:5px 8px; border-bottom:1px solid var(--line); white-space:nowrap;
+           overflow:hidden; text-overflow:ellipsis; max-width:220px; }
+  th { cursor:pointer; user-select:none; }
+  tr.run { cursor:pointer; }
+  tr.run:hover { background:#f0f7ff; }
+  tr.sel { background:#e3f2fd; }
+  .badge { display:inline-block; padding:1px 7px; border-radius:10px; color:#fff; font-size:11px; }
+  .statusbox { display:inline-flex; align-items:center; gap:3px; font-size:12px; margin-right:6px; }
+  pre { background:#f5f5f5; padding:8px; border-radius:4px; overflow:auto; font-size:12px; max-height:340px; }
+  .err { color:#c62828; }
+  svg { width:100%; height:auto; border:1px solid var(--line); border-radius:4px; background:#fff; }
+  .nodeRect { cursor:pointer; }
+  .nodeLabel { font-size:10px; fill:#fff; pointer-events:none; }
+  .muted { color:#999; }
+</style>
+</head>
+<body>
+<header>
+  <h1>{{TITLE}}</h1>
+  <div class="sub" id="meta"></div>
+</header>
+<div class="wrap">
+  <div class="col table">
+    <div class="controls">
+      <input type="text" id="filter" placeholder="filter text…">
+      <select id="stageSel"><option value="">all stages</option></select>
+      <span id="statusFilters"></span>
+    </div>
+    <table>
+      <thead><tr id="head"></tr></thead>
+      <tbody id="rows"></tbody>
+    </table>
+  </div>
+  <div class="col graph">
+    <b>Lineage</b>
+    <div id="svgHost"></div>
+  </div>
+  <div class="col detail">
+    <b>Detail</b>
+    <div id="detail"><span class="muted">select a run…</span></div>
+  </div>
+</div>
+<script id="flexlock-data" type="application/json">{{DATA}}</script>
+<script>
+(function () {
+  const payload = JSON.parse(document.getElementById("flexlock-data").textContent);
+  const graph = payload.graph;
+  const nodes = graph.nodes;
+  const edges = graph.edges;
+  const byId = {};
+  nodes.forEach(n => byId[n.id] = n);
+  const COLORS = payload.colors || {};
+  function color(status){ return COLORS[status] || "#bdbdbd"; }
+  document.getElementById("meta").textContent =
+    graph.nodes.length + " runs · root " + graph.root + " · generated " + graph.generated_at;
+  // Most-frequent metric keys (up to 8) become table columns.
+  const freq = {};
+  nodes.forEach(n => Object.keys(n.metrics || {}).forEach(k => freq[k] = (freq[k]||0)+1));
+  const metricCols = Object.keys(freq).sort((a,b)=>freq[b]-freq[a]).slice(0, 8);
+  const baseCols = [["label","Stage"],["status","Status"],["timestamp","Timestamp"],["note","Note"]];
+  const head = document.getElementById("head");
+  baseCols.concat(metricCols.map(m=>[m,m])).forEach(([key,lbl]) => {
+    const th = document.createElement("th");
+    th.textContent = lbl; th.dataset.key = key;
+    th.onclick = () => sortBy(key);
+    head.appendChild(th);
+  });
+  // Status filter checkboxes.
+  const statuses = Array.from(new Set(nodes.map(n=>n.status))).sort();
+  const sf = document.getElementById("statusFilters");
+  const active = new Set(statuses);
+  statuses.forEach(s => {
+    const span = document.createElement("label");
+    span.className = "statusbox";
+    const cb = document.createElement("input");
+    cb.type = "checkbox"; cb.checked = true;
+    cb.onchange = () => { cb.checked ? active.add(s) : active.delete(s); render(); };
+    span.appendChild(cb);
+    const b = document.createElement("span");
+    b.className = "badge"; b.style.background = color(s); b.textContent = s;
+    span.appendChild(b);
+    sf.appendChild(span);
+  });
+  // Stage dropdown.
+  const stageSel = document.getElementById("stageSel");
+  Array.from(new Set(nodes.map(n=>n.label))).sort().forEach(l => {
+    const o = document.createElement("option"); o.value=l; o.textContent=l; stageSel.appendChild(o);
+  });
+  let sortKey = "timestamp", sortDir = -1, selected = null;
+  function sortBy(k){ if(sortKey===k){sortDir*=-1;}else{sortKey=k;sortDir=1;} render(); }
+  function visibleNodes(){
+    const q = document.getElementById("filter").value.toLowerCase();
+    const stage = stageSel.value;
+    return nodes.filter(n => active.has(n.status)
+      && (!stage || n.label === stage)
+      && (!q || JSON.stringify(n).toLowerCase().includes(q)));
+  }
+  function fmtVal(n, key){
+    if (["label","status","timestamp","note"].includes(key)) return n[key] == null ? "" : n[key];
+    const m = n.metrics || {}; return (key in m) ? m[key] : "";
+  }
+  function render(){
+    const rows = document.getElementById("rows");
+    rows.innerHTML = "";
+    const list = visibleNodes().slice().sort((a,b)=>{
+      const va = fmtVal(a, sortKey), vb = fmtVal(b, sortKey);
+      return (va > vb ? 1 : va < vb ? -1 : 0) * sortDir;
+    });
+    list.forEach(n => {
+      const tr = document.createElement("tr");
+      tr.className = "run" + (selected === n.id ? " sel" : "");
+      tr.onclick = () => selectNode(n.id);
+      baseCols.forEach(([key]) => {
+        const td = document.createElement("td");
+        if (key === "status"){
+          const b = document.createElement("span");
+          b.className = "badge"; b.style.background = color(n.status); b.textContent = n.status;
+          td.appendChild(b);
+        } else { td.textContent = fmtVal(n, key); td.title = fmtVal(n, key); }
+        tr.appendChild(td);
+      });
+      metricCols.forEach(m => {
+        const td = document.createElement("td"); td.textContent = fmtVal(n, m); tr.appendChild(td);
+      });
+      rows.appendChild(tr);
+    });
+    drawGraph();
+  }
+  function selectNode(id){
+    selected = id;
+    const n = byId[id];
+    const d = document.getElementById("detail");
+    let html = "<h3>"+esc(n.label)+" — <span style='color:"+color(n.status)+"'>"+esc(n.status)+"</span></h3>";
+    html += "<div class='muted' style='font-size:11px'>"+esc(n.id)+"</div>";
+    if (n.note) html += "<p><b>note:</b> "+esc(n.note)+"</p>";
+    if (n.target) html += "<p><b>target:</b> <code>"+esc(n.target)+"</code></p>";
+    if (n.tag) html += "<p><b>tag:</b> "+esc(n.tag)+"</p>";
+    if (n.metrics && Object.keys(n.metrics).length){
+      html += "<p><b>metrics:</b></p><pre>"+esc(JSON.stringify(n.metrics, null, 2))+"</pre>";
+    }
+    if (n.error){
+      html += "<p class='err'><b>error:</b> "+esc(n.error.exc_type||"")+" "+esc(n.error.exc_message||"")+"</p>";
+      if (n.error.traceback) html += "<pre class='err'>"+esc(n.error.traceback)+"</pre>";
+    }
+    if (n.config){
+      html += "<p><b>config:</b></p><pre>"+esc(JSON.stringify(n.config, null, 2))+"</pre>";
+    }
+    d.innerHTML = html;
+    render();
+  }
+  // Kahn topological layering for the SVG lineage view.
+  function layers(){
+    const indeg = {}, adj = {};
+    nodes.forEach(n => { indeg[n.id]=0; adj[n.id]=[]; });
+    edges.forEach(e => { if (byId[e.source] && byId[e.target]){ adj[e.source].push(e.target); indeg[e.target]++; } });
+    let frontier = nodes.filter(n=>indeg[n.id]===0).map(n=>n.id);
+    const layer = {}; let depth = 0; const seen = new Set();
+    while (frontier.length){
+      const next = [];
+      frontier.forEach(id => { if (seen.has(id)) return; seen.add(id); layer[id]=depth;
+        adj[id].forEach(t => { indeg[t]--; if (indeg[t]<=0) next.push(t); }); });
+      frontier = next; depth++;
+      if (depth > nodes.length + 2) break;
+    }
+    nodes.forEach(n => { if (!(n.id in layer)) layer[n.id]=0; });
+    return layer;
+  }
+  function drawGraph(){
+    const host = document.getElementById("svgHost");
+    const vis = new Set(visibleNodes().map(n=>n.id));
+    const layer = layers();
+    const cols = {};
+    nodes.forEach(n => { if (!vis.has(n.id)) return; (cols[layer[n.id]] = cols[layer[n.id]]||[]).push(n); });
+    const colKeys = Object.keys(cols).map(Number).sort((a,b)=>a-b);
+    const W = 300, rowH = 34, boxW = 120, boxH = 22;
+    const maxRows = Math.max(1, ...colKeys.map(k=>cols[k].length));
+    const H = Math.max(60, maxRows * rowH + 20);
+    const pos = {};
+    let svg = "<svg viewBox='0 0 "+W+" "+H+"'>";
+    colKeys.forEach((k, ci) => {
+      const x = colKeys.length>1 ? 10 + ci*( (W-boxW-20)/(colKeys.length-1) ) : 10;
+      cols[k].forEach((n, ri) => { pos[n.id] = { x: x, y: 12 + ri*rowH }; });
+    });
+    edges.forEach(e => {
+      const a = pos[e.source], b = pos[e.target];
+      if (!a || !b) return;
+      const dash = e.type === "sweep_item" ? " stroke-dasharray='3,3'" : "";
+      svg += "<line x1='"+(a.x+boxW)+"' y1='"+(a.y+boxH/2)+"' x2='"+b.x+"' y2='"+(b.y+boxH/2)+"' stroke='#bbb'"+dash+"/>";
+    });
+    nodes.forEach(n => {
+      const p = pos[n.id]; if (!p) return;
+      const stroke = selected === n.id ? "#000" : "none";
+      svg += "<g class='nodeRect' onclick=\"__sel('"+n.id.replace(/'/g,"")+"')\">";
+      svg += "<rect x='"+p.x+"' y='"+p.y+"' width='"+boxW+"' height='"+boxH+"' rx='3' fill='"+color(n.status)+"' stroke='"+stroke+"'/>";
+      svg += "<text class='nodeLabel' x='"+(p.x+6)+"' y='"+(p.y+15)+"'>"+esc(n.label.slice(0,16))+"</text></g>";
+    });
+    svg += "</svg>";
+    host.innerHTML = svg;
+  }
+  window.__sel = selectNode;
+  function esc(s){ return String(s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+  document.getElementById("filter").oninput = render;
+  stageSel.onchange = render;
+  render();
+})();
+</script>
+</body>
+</html>

flexlock/resolvers.py ADDED Viewed

@@ -0,0 +1,248 @@
+"""OmegaConf resolvers for FlexLock."""
+from omegaconf import OmegaConf, DictConfig
+from .data_hash import hash_data
+from .load_stage import load_stage_from_path
+from datetime import datetime
+from contextlib import contextmanager
+import re
+from pathlib import Path
+from functools import wraps
+from . import config
+# Resolvers whose evaluation is *deferred* to stage start (they read live
+# filesystem/upstream-run state that only exists on the worker, not at submit
+# time). During the submit-time freeze these are stubbed to re-emit their own
+# call string (see ``deferred_stubbed``); everything else resolves eagerly.
+DEFERRED_RESOLVERS = ("run_lock", "latest")
+# Distinct "no default supplied" sentinel so that an explicit ``null`` default
+# (e.g. ``${run_lock:${dir},key,null}``) is honoured rather than treated as
+# "raise". ``None`` cannot serve as this marker because it is a valid default.
+_MISSING = object()
+def now_resolver(fmt: str = None) -> str:
+    """
+    OmegaConf resolver that returns the current time as a formatted string.
+    Deprecated: prefer ``submit(..., save_dir_policy="timestamp")`` over
+    embedding ``${now:}`` in ``save_dir``. See
+    ``docs/resolution_simplification_plan.md``.
+    Args:
+        fmt: Format string for strftime (defaults to config.TIMESTAMP_FORMAT)
+    """
+    import warnings
+    warnings.warn(
+        "${now:} is deprecated; use save_dir_policy='timestamp' on submit()/run "
+        "instead of embedding ${now:} in save_dir.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if fmt is None:
+        fmt = config.TIMESTAMP_FORMAT
+    return datetime.now().strftime(fmt)
+def latest_resolver(path_glob: str, default=_MISSING) -> str:
+    """
+    OmegaConf resolver that returns the latest path matching the given pattern.
+    Raises ``FileNotFoundError`` when nothing matches, unless a ``default`` is
+    supplied (``${latest:pattern,fallback}``), in which case the default is
+    returned. Returning the unmatched pattern silently — the old behaviour —
+    produced a bogus path that failed far downstream.
+    """
+    from glob import glob
+    import os
+    # Expand user (~) and resolve the path
+    path_glob = os.path.expanduser(path_glob)
+    # Find all paths matching the pattern
+    matching_paths = glob(path_glob, recursive=True)
+    if not matching_paths:
+        if default is not _MISSING:
+            return default
+        raise FileNotFoundError(
+            f"latest resolver: no paths match pattern {path_glob!r}"
+        )
+    # Find the latest path by modification time
+    latest_path = max(matching_paths, key=os.path.getmtime)
+    return latest_path
+def vinc_resolver(path: str, fmt: str = "_{i:04d}") -> str:
+    """
+    OmegaConf resolver that finds the highest existing version of a folder/file
+    and returns the next versioned path as a string.
+    The value is a pure function of the current filesystem state (highest
+    existing version + 1) so that multiple references to the same ``${vinc:}``
+    within one ``submit()`` resolve idempotently to the *same* directory — the
+    counter only advances once the previous run's directory actually exists on
+    disk.
+    Concurrency note: because the claim is not taken here, two submits racing
+    from separate processes can compute the same next version and collide.
+    Deprecated: prefer ``submit(..., save_dir_policy="increment")``, which takes
+    the atomic ``mkdir(exist_ok=False)`` claim at the right layer and so fixes
+    the race this resolver could not. See ``docs/resolution_simplification_plan.md``.
+    """
+    import warnings
+    warnings.warn(
+        "${vinc:} is deprecated; use save_dir_policy='increment' on submit()/run "
+        "instead of embedding ${vinc:} in save_dir. The policy also claims the "
+        "directory atomically, fixing the concurrent-submit race.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    from .save_dir import next_versioned_path
+    return next_versioned_path(path, fmt)
+def run_lock_resolver(run_dir: str, key: str, default=_MISSING):
+    """
+    OmegaConf resolver that reads a field from an upstream run.lock.
+    Navigates a dot-separated key path into the run.lock YAML and returns
+    the value with its native type (int, float, bool, str, list, dict).
+    Usage in configs:
+        ${run_lock:path/to/run_dir,config.datamodule.stats_file}
+        ${run_lock:${run_dir},config.lit_module.regression_checkpoint_path,null}
+    """
+    from loguru import logger
+    import yaml
+    lock_path = Path(run_dir) / "run.lock"
+    if not lock_path.exists():
+        if default is not _MISSING:
+            logger.warning(f"run_lock resolver: no run.lock at {run_dir}, using default")
+            return default
+        raise FileNotFoundError(f"run_lock resolver: no run.lock found in {run_dir}")
+    with open(lock_path) as f:
+        data = yaml.safe_load(f)
+    # Navigate dot-path
+    value = data
+    for part in key.split("."):
+        if isinstance(value, dict) and part in value:
+            value = value[part]
+        else:
+            if default is not _MISSING:
+                return default
+            raise KeyError(
+                f"run_lock resolver: key '{key}' not found in {lock_path} "
+                f"(failed at '{part}')"
+            )
+    if value is None:
+        # A legitimately null value is returned as-is when no default was
+        # supplied; only substitute an explicitly provided default.
+        return None if default is _MISSING else default
+    return value
+def register_resolvers():
+    """
+    Registers the flexlock resolvers with OmegaConf.
+    """
+    OmegaConf.register_new_resolver("now", now_resolver)
+    OmegaConf.register_new_resolver("vinc", vinc_resolver)
+    OmegaConf.register_new_resolver("latest", latest_resolver, use_cache=False)
+    OmegaConf.register_new_resolver("run_lock", run_lock_resolver, use_cache=False)
+# The real resolver implementations plus their registration options, so a stub
+# context can faithfully restore them on exit.
+def _real_resolvers():
+    return {
+        "now": (now_resolver, {}),
+        "vinc": (vinc_resolver, {}),
+        "latest": (latest_resolver, {"use_cache": False}),
+        "run_lock": (run_lock_resolver, {"use_cache": False}),
+    }
+def _emit_stub_arg(value) -> str:
+    """Render a (pre-resolved) resolver argument back into interpolation text.
+    ``None`` becomes ``null`` so a real ``${run_lock:${dir},key,null}`` default
+    survives the freeze; everything else is stringified as-is.
+    """
+    if value is None:
+        return "null"
+    return str(value)
+@contextmanager
+def _stubbed(names):
+    """Temporarily replace the named resolvers with stubs that re-emit their own
+    call string, with arguments already resolved by OmegaConf.
+    OmegaConf resolves nested interpolations in a resolver's arguments *before*
+    invoking the resolver. So under this context, resolving
+    ``${run_lock:${precompute_dir},key}`` yields the frozen string
+    ``${run_lock:/data/precomputed,key}`` — every non-stubbed interpolation
+    (simple refs, cross-tree, multi-hop, mixed strings, relative refs) is
+    resolved by OmegaConf itself, while the stubbed call collapses back to a
+    self-contained call string with zero hand-rolled grammar parsing.
+    Restores the real resolvers (with their original options) on exit.
+    """
+    def _make_stub(name):
+        def _stub(*args):
+            return "${" + name + ":" + ",".join(_emit_stub_arg(a) for a in args) + "}"
+        return _stub
+    reals = _real_resolvers()
+    for name in names:
+        OmegaConf.register_new_resolver(
+            name, _make_stub(name), replace=True, use_cache=False
+        )
+    try:
+        yield
+    finally:
+        for name in names:
+            func, opts = reals[name]
+            OmegaConf.register_new_resolver(name, func, replace=True, **opts)
+def deferred_stubbed():
+    """Stub only the deferred resolvers (``run_lock``/``latest``).
+    Used by the merge-before-resolve sweep freeze, where ``vinc``/``now`` should
+    still fire (they are being retired via ``save_dir_policy``).
+    """
+    return _stubbed(DEFERRED_RESOLVERS)
+def frozen_resolvers():
+    """Stub every flexlock resolver, so all ``${name:args}`` calls are preserved
+    as frozen call strings during the submit-time node freeze.
+    """
+    return _stubbed(tuple(_real_resolvers().keys()))
+def resolve_deferred(cfg: DictConfig) -> DictConfig:
+    """Fire the deferred resolvers once, at stage start, and return a detached
+    config of concrete values.
+    This is the single point where ``run_lock``/``latest`` (and any other
+    interpolations left after the submit-time freeze) are evaluated with the
+    real resolvers. Called on the worker right after the task override is merged
+    (and on the local single-run path). Re-wrapping as a plain config detaches
+    it from any parent so downstream ``config.copy()`` cannot re-fire anything.
+    """
+    resolved = OmegaConf.to_container(cfg, resolve=True, throw_on_missing=False)
+    return OmegaConf.create(resolved)

flexlock/run_cli.py ADDED Viewed

@@ -0,0 +1,44 @@
+"""CLI entry point for FlexLock runner."""
+import os
+import sys
+from loguru import logger
+from flexlock.runner import FlexLockRunner
+def main():
+    """
+    CLI entry point for flexlock-run command.
+    This is a standalone CLI that provides direct access to FlexLockRunner
+    without requiring a Python script with @flexcli decorator.
+    Usage:
+        flexlock-run --config experiment.yml
+        flexlock-run --defaults module.config:defaults --config exp.yml
+        flexlock-run --config exp.yml --select experiments.exp1
+        flexlock-run --sweep-file sweep.yaml --n_jobs 4
+    """
+    # Make the current working directory importable so users can pass
+    # `-d mypkg.module.var` for a package in their project without having
+    # to set PYTHONPATH manually. Mirrors what `python -m mypkg` would do.
+    cwd = os.getcwd()
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    try:
+        runner = FlexLockRunner()
+        runner.run()
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user")
+        sys.exit(130)  # Standard exit code for SIGINT
+    except Exception as e:
+        logger.error(f"FlexLock run failed: {e}")
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)
+if __name__ == "__main__":
+    main()