PyPI - flashruntime - Versions diffs - 0.3.0__py3-none-any.whl - Mend

flashruntime 0.3.0__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 (95) hide show

flashml_workloads/__init__.py +7 -0
flashml_workloads/fedavg_driver.py +569 -0
flashml_workloads/fedavg_weights.py +223 -0
flashml_workloads/fedavg_worker.py +166 -0
flashml_workloads/kmeans_driver.py +134 -0
flashml_workloads/kmeans_shard.py +69 -0
flashml_workloads/sgd_trainer.py +127 -0
flashml_workloads/sharded_kmeans.py +323 -0
flashml_workloads/sklearn_trial.py +89 -0
flashruntime/__init__.py +125 -0
flashruntime/artifacts/__init__.py +25 -0
flashruntime/artifacts/store.py +228 -0
flashruntime/backends/__init__.py +26 -0
flashruntime/backends/base.py +63 -0
flashruntime/backends/kuberay.py +465 -0
flashruntime/checkpoint/__init__.py +20 -0
flashruntime/checkpoint/catalog.py +198 -0
flashruntime/checkpoint/local.py +109 -0
flashruntime/checkpoint/store.py +86 -0
flashruntime/integrations/__init__.py +5 -0
flashruntime/integrations/huggingface.py +59 -0
flashruntime/integrations/pytorch.py +52 -0
flashruntime/integrations/sklearn.py +42 -0
flashruntime/launchers/__init__.py +130 -0
flashruntime/launchers/local.py +126 -0
flashruntime/leases/__init__.py +27 -0
flashruntime/leases/manager.py +365 -0
flashruntime/leases/sqlite_store.py +169 -0
flashruntime/leases/store.py +103 -0
flashruntime/monitor/__init__.py +7 -0
flashruntime/monitor/sampler.py +232 -0
flashruntime/planner/__init__.py +56 -0
flashruntime/planner/candidates.py +597 -0
flashruntime/planner/catalog.py +129 -0
flashruntime/planner/comm.py +95 -0
flashruntime/planner/explain.py +109 -0
flashruntime/planner/memory.py +166 -0
flashruntime/planner/resolve.py +120 -0
flashruntime/planner/selector.py +169 -0
flashruntime/planner/timecost.py +81 -0
flashruntime/profiling/__init__.py +113 -0
flashruntime/protocol/__init__.py +18 -0
flashruntime/protocol/plan_v1alpha1.py +320 -0
flashruntime/protocol/v1alpha1.py +465 -0
flashruntime/providers/__init__.py +138 -0
flashruntime/py.typed +0 -0
flashruntime/recipes/__init__.py +135 -0
flashruntime/recipes/command.py +166 -0
flashruntime/recovery/__init__.py +21 -0
flashruntime/recovery/policy.py +170 -0
flashruntime/recovery/signals.py +135 -0
flashruntime/recovery/taxonomy.py +91 -0
flashruntime/scheduler/__init__.py +170 -0
flashruntime/sdk.py +402 -0
flashruntime/service/__init__.py +3 -0
flashruntime/service/app.py +391 -0
flashruntime/service/auth.py +180 -0
flashruntime/service/checkpoints.py +90 -0
flashruntime/service/cli.py +167 -0
flashruntime/service/dashboard.py +193 -0
flashruntime/service/ledger.py +101 -0
flashruntime/service/modea.py +821 -0
flashruntime/strategies/__init__.py +156 -0
flashruntime/strategies/command.py +56 -0
flashruntime/torch/__init__.py +274 -0
flashruntime/viewer/__init__.py +20 -0
flashruntime/viewer/_docs/benchmarks.html +771 -0
flashruntime/viewer/_docs/concepts/architecture.html +302 -0
flashruntime/viewer/_docs/get-started.html +263 -0
flashruntime/viewer/_docs/guides/federated-averaging.html +363 -0
flashruntime/viewer/_docs/guides/huggingface.html +223 -0
flashruntime/viewer/_docs/guides/jobspec-and-isolation.html +271 -0
flashruntime/viewer/_docs/guides/pytorch.html +313 -0
flashruntime/viewer/_docs/guides/sklearn.html +232 -0
flashruntime/viewer/_docs/index.html +251 -0
flashruntime/viewer/_docs/reference/cli.html +254 -0
flashruntime/viewer/_docs/reference/integrations.html +240 -0
flashruntime/viewer/_docs/reference/sdk.html +341 -0
flashruntime/viewer/_docs/reference/torch-helper.html +244 -0
flashruntime/viewer/_docs/search-index.json +1 -0
flashruntime/viewer/_docs/tutorials/convnet.html +571 -0
flashruntime/viewer/_docs/tutorials/fault-tolerance.html +375 -0
flashruntime/viewer/_docs/tutorials/sklearn-sweeps.html +278 -0
flashruntime/viewer/flowmap.py +307 -0
flashruntime/viewer/page.py +594 -0
flashruntime/viewer/server.py +134 -0
flashruntime/viewer/state.py +250 -0
flashruntime/workloads/__init__.py +6 -0
flashruntime/workloads/command.py +127 -0
flashruntime-0.3.0.dist-info/METADATA +365 -0
flashruntime-0.3.0.dist-info/RECORD +95 -0
flashruntime-0.3.0.dist-info/WHEEL +5 -0
flashruntime-0.3.0.dist-info/entry_points.txt +2 -0
flashruntime-0.3.0.dist-info/licenses/LICENSE +202 -0
flashruntime-0.3.0.dist-info/top_level.txt +2 -0

flashruntime/viewer/_docs/reference/sdk.html ADDED Viewed

@@ -0,0 +1,341 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Reference: SDK (`flashruntime`) — flashruntime docs</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; margin: 0; }
+  body { font: 14px/1.65 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: #0d1117; color: #c9d1d9; }
+  a { color: oklch(0.80 0.16 200); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  .layout { display: flex; align-items: flex-start; min-height: 100vh; }
+  /* sidebar — PyTorch-docs-like: sections from _nav.yml, current page active */
+  .sidebar { flex: 0 0 264px; position: sticky; top: 0; height: 100vh; overflow-y: auto;
+             border-right: 1px solid #21262d; background: #0d1117; padding: 20px 16px; }
+  .brand { color: #e6edf3; font-size: 15px; letter-spacing: .04em; }
+  .brand small { display: block; margin-top: 2px; color: #8b949e; font-size: 10px;
+                 text-transform: uppercase; letter-spacing: .14em; }
+  .search { position: relative; margin: 16px 0; }
+  #q { width: 100%; background: #010409; border: 1px solid #21262d; border-radius: 6px;
+       color: #c9d1d9; font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; padding: 7px 9px; }
+  #q:focus { outline: 1px solid oklch(0.80 0.16 200); }
+  #results { position: absolute; left: 0; right: 0; top: 112%; z-index: 5; display: none;
+             background: #161b22; border: 1px solid #21262d; border-radius: 6px; overflow: hidden; }
+  #results.open { display: block; }
+  #results a { display: block; padding: 7px 9px; border-bottom: 1px solid #21262d; color: #c9d1d9; }
+  #results a:last-child { border-bottom: 0; }
+  #results a:hover { background: #010409; text-decoration: none; }
+  #results a b { color: #e6edf3; font-weight: 600; }
+  #results a span { display: block; margin-top: 2px; color: #8b949e; font-size: 11px; }
+  #results .nohit { padding: 7px 9px; color: #8b949e; }
+  .nav-section { margin: 16px 0 6px; color: #8b949e; font-size: 10px; font-weight: 600;
+                 text-transform: uppercase; letter-spacing: .14em; }
+  .nav-link { display: block; padding: 4px 8px; border-radius: 5px; color: #c9d1d9; font-size: 13px; }
+  .nav-link:hover { background: #161b22; text-decoration: none; }
+  .nav-link.active { background: #161b22; color: #e6edf3; box-shadow: inset 2px 0 0 oklch(0.80 0.16 200); }
+  /* content */
+  .content { flex: 1 1 auto; max-width: 840px; min-width: 0; padding: 34px 40px 80px; }
+  .content h1 { color: #e6edf3; font-size: 26px; margin: 0 0 16px; }
+  .content h2 { color: #e6edf3; font-size: 18px; margin: 30px 0 10px;
+                padding-top: 10px; border-top: 1px solid #21262d; }
+  .content h3 { color: #e6edf3; font-size: 15px; margin: 22px 0 8px; }
+  .content p, .content li { color: #c9d1d9; }
+  .content ul, .content ol { padding-left: 22px; margin: 10px 0; }
+  .content li { margin: 4px 0; }
+  .content blockquote { margin: 14px 0; padding: 2px 14px; border-left: 3px solid oklch(0.80 0.18 60);
+                        background: #161b22; border-radius: 0 6px 6px 0; color: #8b949e; }
+  .content :not(pre) > code { background: #010409; border: 1px solid #21262d;
+                              border-radius: 4px; padding: 1px 5px; font-size: 12.5px; }
+  .content table { border-collapse: collapse; margin: 14px 0; display: block; overflow-x: auto; }
+  .content th, .content td { border: 1px solid #21262d; padding: 6px 10px; text-align: left; }
+  .content th { color: #e6edf3; background: #161b22; }
+  /* code blocks + copy button */
+  .codeblock { position: relative; margin: 14px 0; }
+  .codeblock pre { background: #010409; border: 1px solid #21262d; border-radius: 8px;
+                   padding: 14px 16px; overflow-x: auto; }
+  .codeblock pre code { padding: 0; border: 0; background: none; font-size: 12.5px; color: #c9d1d9; }
+  .copybtn { position: absolute; top: 8px; right: 8px; padding: 3px 8px; cursor: pointer;
+             background: #161b22; border: 1px solid #21262d; border-radius: 5px;
+             color: #8b949e; font: 11px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  .copybtn:hover { color: #e6edf3; border-color: oklch(0.80 0.16 200); }
+  @media (max-width: 800px) {
+    .layout { flex-direction: column; }
+    .sidebar { position: static; height: auto; width: 100%; flex-basis: auto;
+               border-right: 0; border-bottom: 1px solid #21262d; }
+    .content { padding: 24px 18px 60px; }
+  }
+</style>
+</head>
+<body>
+<div class="layout">
+  <aside class="sidebar">
+    <a class="brand" href="../index.html">flashruntime<small>documentation</small></a>
+    <div class="search">
+      <input id="q" type="search" placeholder="Search docs  (press /)" autocomplete="off" spellcheck="false">
+      <div id="results"></div>
+    </div>
+    <nav><div class="nav-section">Getting started</div>
+<a class="nav-link" href="../index.html">FlashRuntime</a>
+<a class="nav-link" href="../get-started.html">Get started</a>
+<div class="nav-section">Tutorials</div>
+<a class="nav-link" href="../tutorials/convnet.html">Tutorial: make a ConvNet fault-tolerant</a>
+<a class="nav-link" href="../tutorials/sklearn-sweeps.html">Tutorial: parallel scikit-learn sweeps</a>
+<a class="nav-link" href="../tutorials/fault-tolerance.html">Tutorial: automatic recovery, explained</a>
+<div class="nav-section">Guides</div>
+<a class="nav-link" href="../guides/pytorch.html">PyTorch guide</a>
+<a class="nav-link" href="../guides/sklearn.html">scikit-learn guide</a>
+<a class="nav-link" href="../guides/huggingface.html">Hugging Face guide</a>
+<a class="nav-link" href="../guides/jobspec-and-isolation.html">JobSpec &amp; isolation guide</a>
+<a class="nav-link" href="../guides/federated-averaging.html">Federated averaging</a>
+<div class="nav-section">Concepts</div>
+<a class="nav-link" href="../concepts/architecture.html">Architecture</a>
+<div class="nav-section">Reference</div>
+<a class="nav-link active" href="sdk.html">Reference: SDK (`flashruntime`)</a>
+<a class="nav-link" href="integrations.html">Reference: integrations (`flashruntime.integrations`)</a>
+<a class="nav-link" href="torch-helper.html">Reference: torch helper (`flashruntime.torch`)</a>
+<a class="nav-link" href="cli.html">Reference: CLI (`flashruntime`)</a>
+<div class="nav-section">Benchmarks</div>
+<a class="nav-link" href="../benchmarks.html">Benchmarks</a></nav>
+  </aside>
+  <main class="content"><h1 id="reference-sdk-flashruntime">Reference: SDK (<code>flashruntime</code>)</h1>
+<p>The <code>flashruntime</code> top-level package. The core is pydantic-only — <code>import
+flashruntime</code> pulls in <strong>only pydantic</strong>; the bring-your-own-code helpers
+(<code>submit</code>, <code>CommandWorkload</code>, <code>integrations</code>) resolve lazily so the planner
+stays a minimal import.</p>
+<p>Signatures below are exact. Each entry says, in one line, <em>why it exists</em>.</p>
+<hr />
+<h2 id="running-a-workload">Running a workload</h2>
+<h3 id="flashsubmit"><code>flash.submit</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">def submit(workload, output_dir=None, wait=True, max_restarts=0, watch=None) -&gt; Run: ...
+</code></pre></div>
+<p>The local entry point — compiles a <code>CommandWorkload</code> into a launch spec, runs
+it as a real subprocess (once per param set), collects artifacts, and returns a
+<code>Run</code>.</p>
+<ul>
+<li><code>output_dir</code> — where <code>run.json</code> and artifacts land; a temp dir if <code>None</code>.
+  Reusing the <strong>same</strong> dir reuses the job id, so a checkpointed script resumes.</li>
+<li><code>wait</code> — <code>True</code> drives the launch loop inline and returns a finished <code>Run</code>;
+  <code>False</code> returns immediately and drives it on a daemon thread (watch it live).</li>
+<li><code>max_restarts</code> — the automatic fault-tolerance budget (default <code>0</code> = no
+  retry). A FAILED attempt is classified and run against the versioned recovery
+  policy; a deterministic app error fails fast, anything else relaunches from
+  the job-scoped checkpoint up to this many times.</li>
+<li><code>watch</code> — open the live viewer and record its URL on <code>run.viewer_url</code>;
+  <code>None</code> (default) auto-decides (on at an interactive terminal, off in
+  pipes/CI).</li>
+</ul>
+<h3 id="run"><code>Run</code></h3>
+<p>The result handle, fully populated by the time a <code>wait=True</code> <code>submit()</code> returns.</p>
+<table>
+<thead>
+<tr>
+<th>Attribute / method</th>
+<th>Meaning</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>run.state</code></td>
+<td><code>LaunchState</code> — <code>SUCCEEDED</code> if every task succeeded, else <code>FAILED</code></td>
+</tr>
+<tr>
+<td><code>run.trials</code></td>
+<td>list of parsed <code>metrics.json</code> dicts (one per task; fan-out merges its <code>params</code>)</td>
+</tr>
+<tr>
+<td><code>run.artifacts</code></td>
+<td>list of collected file <code>Path</code>s</td>
+</tr>
+<tr>
+<td><code>run.output_dir</code></td>
+<td>root the run wrote under</td>
+</tr>
+<tr>
+<td><code>run.viewer_url</code></td>
+<td>live-page URL if <code>watch</code> opened one, else <code>None</code></td>
+</tr>
+<tr>
+<td><code>run.events</code></td>
+<td>snapshot copy of the append-only event log</td>
+</tr>
+<tr>
+<td><code>run.attempts</code></td>
+<td>snapshot copy of the per-launch attempt rows</td>
+</tr>
+<tr>
+<td><code>run.run_json_path</code></td>
+<td>path to the <code>viewer_v1</code> <code>run.json</code> the Run mirrors itself to</td>
+</tr>
+<tr>
+<td><code>run.wait(timeout=None)</code></td>
+<td>block until terminal (event-based, no poll); returns the state</td>
+</tr>
+<tr>
+<td><code>run.logs(tail_lines=200)</code></td>
+<td>captured stdout+stderr (tail)</td>
+</tr>
+<tr>
+<td><code>run.best_trial(metric=None, maximize=None)</code></td>
+<td>best trial by <code>metric</code> (defaults from the workload's <code>OutputSpec</code>); <code>None</code> if none reported it</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="describing-a-workload">Describing a workload</h2>
+<h3 id="flashcommandworkload"><code>flash.CommandWorkload</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">class CommandWorkload(BaseModel):
+    command: str | list[str]                 # shlex-split (NO shell) or an argv list
+    source: Source = Source()                # where the user's code lives
+    image: ImageSpec | None = None           # pinned image (required only for the service path)
+    env: dict[str, str] = {}
+    inputs: dict[str, str] = {}              # each value must be an artifact:// URI
+    outputs: OutputSpec = OutputSpec()
+    resources: Requirements = Requirements() # resource hints (dormant locally; for future providers)
+    isolation: IsolationSpec = IsolationSpec()
+    mode: str = &quot;auto&quot;                       # auto | local | independent_tasks | coordinated
+    checkpoint: CheckpointPolicy | None = None
+    task_params: list[dict] | None = None    # {name} placeholders filled per entry (Mode A fan-out)
+</code></pre></div>
+<p>The user-facing description of a "bring your own code" workload — <em>what</em> to run
+and what FlashRuntime should do around it. It never describes <em>how</em> distributed
+math happens; that belongs to your code. <code>command</code> is <code>shlex</code>-split (there is no
+shell — pipes need an explicit <code>command="bash -c '...'"</code>).</p>
+<h3 id="flashsource"><code>flash.Source</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">class Source(BaseModel):
+    path: str = &quot;.&quot;                          # local dir; ~ is expanded
+    git_revision: str | None = None          # reserved for remote packaging (later slice)
+</code></pre></div>
+<p>Where the user's code lives — a <code>flash.Source</code>, not a bare string.</p>
+<h3 id="flashoutputspec"><code>flash.OutputSpec</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">class OutputSpec(BaseModel):
+    prefix: str = &quot;artifact://jobs/{job_id}/&quot;
+    collect: list[str] = [&quot;metrics.json&quot;]    # globs resolved against the script's cwd
+    primary_metric: str | None = None        # the metrics.json key best_trial() ranks by
+    maximize: bool = True
+</code></pre></div>
+<p>What to keep after a run, and how to rank trials. <code>metrics.json</code> in <code>collect</code>
+(the default) is what populates <code>run.trials</code>.</p>
+<hr />
+<h2 id="planning-a-job">Planning a job</h2>
+<h3 id="flashplan"><code>flash.plan</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">def plan(request: PlanRequest) -&gt; PlanReport: ...
+</code></pre></div>
+<p>Deterministic, explainable strategy selection — turns model + hardware +
+objective into a ranked, explained <code>PlanReport</code> (no cluster required). The
+closed-form arithmetic is framework-import-free.</p>
+<h3 id="flashrender"><code>flash.render</code></h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">def render(report: PlanReport) -&gt; str: ...
+</code></pre></div>
+<p>Renders a <code>PlanReport</code> as human-readable text (the numbers, the chosen plan,
+and the rejected alternatives with their reasons).</p>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">import flashruntime as flash
+report = flash.plan(flash.PlanRequest(
+    workload=flash.TransformerFineTune(model=&quot;Qwen/Qwen2.5-7B&quot;, method=&quot;lora&quot;),
+    resources=flash.Resources(gpus=4, gpu_type=&quot;RTX4090&quot;),
+    objective=flash.Objective(mode=&quot;balanced&quot;, deadline_minutes=240),
+))
+print(flash.render(report))
+</code></pre></div>
+<h3 id="plan-inputs">Plan inputs</h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">class Resources(BaseModel):
+    gpus: int = 0                            # 0 = CPU-only
+    gpu_type: str | None = None              # 'A100-40GB', 'L40S', 'RTX4090', ...
+    vram_gb: float | None = None             # per-GPU VRAM override
+    hosts: int = 1
+    cpu_ram_gb: float = 32.0
+    cpu_cores: int = 8
+    hourly_cost_usd_per_gpu: float | None = None
+class Objective(BaseModel):
+    mode: str = &quot;balanced&quot;                   # cheapest | fastest | balanced | reliable
+    max_cost_usd: float | None = None
+    deadline_minutes: float | None = None
+    allow_quantization: bool = True
+    allow_cpu_offload: bool = True
+    allow_nvme_offload: bool = False
+</code></pre></div>
+<p>Workload intents: <code>TransformerFineTune</code>, <code>PyTorchTraining</code>, <code>ClassicalML</code>,
+<code>IndependentTasks</code>. See the planner walkthrough (in the repo under
+<code>docs/planner/</code>) for the estimator arithmetic.</p>
+<h3 id="flashrun-designed-not-yet-built"><code>flash.run</code> — designed, not yet built</h3>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">def run(plan, coordinator_url=None): ...     # raises NotImplementedError
+</code></pre></div>
+<p>The plan-to-execution bridge. It is designed (the docstring describes the
+intended pipeline) but not implemented, so it raises <code>NotImplementedError</code>
+rather than half-running. Today you <code>flash.plan()</code> and submit the JobSpec
+yourself.</p>
+<hr />
+<h2 id="related-references">Related references</h2>
+<ul>
+<li><a href="integrations.html">Integrations</a> — the <code>fr_torch</code> / <code>fr_sklearn</code> / <code>fr_hf</code>
+  adapters that build a <code>CommandWorkload</code> for you.</li>
+<li><a href="torch-helper.html">torch helper</a> — the <code>flashruntime.torch</code> surface (three verbs + read-only accessors).</li>
+<li><a href="cli.html">CLI</a> — the <code>flashruntime</code> command.</li>
+</ul></main>
+</div>
+<script>
+// ---- client-side search: fetch the builder's index, filter as you type -----
+// (<=60 lines, vanilla JS, no external anything — the index is a sibling file.)
+let INDEX = [];
+// Path from THIS page back to the site root. The index stores root-relative
+// URLs (e.g. "tutorials/deep.html"); we fetch it and build result links
+// against ROOT so a page in a subdir resolves them too (see build_docs.py).
+const ROOT = "../";
+const q = document.getElementById("q");
+const results = document.getElementById("results");
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) =>
+  ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+fetch(ROOT + "search-index.json").then((r) => r.json()).then((d) => { INDEX = d; }).catch(() => {});
+// A short context window around the first match, so a hit shows WHY it matched.
+function snippet(text, needle) {
+  const i = text.toLowerCase().indexOf(needle);
+  if (i < 0) return "";
+  const start = Math.max(0, i - 32);
+  return (start > 0 ? "…" : "") + text.slice(start, i + needle.length + 44).trim() + "…";
+}
+function runSearch() {
+  const needle = q.value.trim().toLowerCase();
+  if (!needle) { results.className = ""; results.innerHTML = ""; return; }
+  const hits = INDEX.map((p) => {
+    const inTitle = p.title.toLowerCase().includes(needle);
+    const inText = p.text.toLowerCase().includes(needle);
+    if (!inTitle && !inText) return null;
+    return { url: p.url, title: p.title, snip: inText ? snippet(p.text, needle) : "" };
+  }).filter(Boolean).slice(0, 20);
+  results.className = "open";
+  results.innerHTML = hits.length
+    ? hits.map((h) => '<a href="' + ROOT + h.url + '"><b>' + esc(h.title) + "</b>" +
+        (h.snip ? "<span>" + esc(h.snip) + "</span>" : "") + "</a>").join("")
+    : '<div class="nohit">no matches</div>';
+}
+q.addEventListener("input", runSearch);
+q.addEventListener("focus", runSearch);
+document.addEventListener("click", (e) => {
+  if (!e.target.closest(".search")) { results.className = ""; }  // dismiss on outside click
+});
+document.addEventListener("keydown", (e) => {  // "/" focuses search, like PyTorch docs
+  if (e.key === "/" && document.activeElement !== q) { e.preventDefault(); q.focus(); }
+});
+// ---- copy buttons: read the <pre>'s own text into the clipboard ------------
+document.querySelectorAll(".copybtn").forEach((btn) => {
+  btn.addEventListener("click", () => {
+    const code = btn.parentElement.querySelector("pre").innerText;
+    navigator.clipboard.writeText(code).then(() => {
+      const was = btn.textContent; btn.textContent = "Copied";
+      setTimeout(() => { btn.textContent = was; }, 1200);
+    }).catch(() => {});
+  });
+});
+</script>
+</body>
+</html>

flashruntime/viewer/_docs/reference/torch-helper.html ADDED Viewed

@@ -0,0 +1,244 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Reference: torch helper (`flashruntime.torch`) — flashruntime docs</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; margin: 0; }
+  body { font: 14px/1.65 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: #0d1117; color: #c9d1d9; }
+  a { color: oklch(0.80 0.16 200); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  .layout { display: flex; align-items: flex-start; min-height: 100vh; }
+  /* sidebar — PyTorch-docs-like: sections from _nav.yml, current page active */
+  .sidebar { flex: 0 0 264px; position: sticky; top: 0; height: 100vh; overflow-y: auto;
+             border-right: 1px solid #21262d; background: #0d1117; padding: 20px 16px; }
+  .brand { color: #e6edf3; font-size: 15px; letter-spacing: .04em; }
+  .brand small { display: block; margin-top: 2px; color: #8b949e; font-size: 10px;
+                 text-transform: uppercase; letter-spacing: .14em; }
+  .search { position: relative; margin: 16px 0; }
+  #q { width: 100%; background: #010409; border: 1px solid #21262d; border-radius: 6px;
+       color: #c9d1d9; font: 12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; padding: 7px 9px; }
+  #q:focus { outline: 1px solid oklch(0.80 0.16 200); }
+  #results { position: absolute; left: 0; right: 0; top: 112%; z-index: 5; display: none;
+             background: #161b22; border: 1px solid #21262d; border-radius: 6px; overflow: hidden; }
+  #results.open { display: block; }
+  #results a { display: block; padding: 7px 9px; border-bottom: 1px solid #21262d; color: #c9d1d9; }
+  #results a:last-child { border-bottom: 0; }
+  #results a:hover { background: #010409; text-decoration: none; }
+  #results a b { color: #e6edf3; font-weight: 600; }
+  #results a span { display: block; margin-top: 2px; color: #8b949e; font-size: 11px; }
+  #results .nohit { padding: 7px 9px; color: #8b949e; }
+  .nav-section { margin: 16px 0 6px; color: #8b949e; font-size: 10px; font-weight: 600;
+                 text-transform: uppercase; letter-spacing: .14em; }
+  .nav-link { display: block; padding: 4px 8px; border-radius: 5px; color: #c9d1d9; font-size: 13px; }
+  .nav-link:hover { background: #161b22; text-decoration: none; }
+  .nav-link.active { background: #161b22; color: #e6edf3; box-shadow: inset 2px 0 0 oklch(0.80 0.16 200); }
+  /* content */
+  .content { flex: 1 1 auto; max-width: 840px; min-width: 0; padding: 34px 40px 80px; }
+  .content h1 { color: #e6edf3; font-size: 26px; margin: 0 0 16px; }
+  .content h2 { color: #e6edf3; font-size: 18px; margin: 30px 0 10px;
+                padding-top: 10px; border-top: 1px solid #21262d; }
+  .content h3 { color: #e6edf3; font-size: 15px; margin: 22px 0 8px; }
+  .content p, .content li { color: #c9d1d9; }
+  .content ul, .content ol { padding-left: 22px; margin: 10px 0; }
+  .content li { margin: 4px 0; }
+  .content blockquote { margin: 14px 0; padding: 2px 14px; border-left: 3px solid oklch(0.80 0.18 60);
+                        background: #161b22; border-radius: 0 6px 6px 0; color: #8b949e; }
+  .content :not(pre) > code { background: #010409; border: 1px solid #21262d;
+                              border-radius: 4px; padding: 1px 5px; font-size: 12.5px; }
+  .content table { border-collapse: collapse; margin: 14px 0; display: block; overflow-x: auto; }
+  .content th, .content td { border: 1px solid #21262d; padding: 6px 10px; text-align: left; }
+  .content th { color: #e6edf3; background: #161b22; }
+  /* code blocks + copy button */
+  .codeblock { position: relative; margin: 14px 0; }
+  .codeblock pre { background: #010409; border: 1px solid #21262d; border-radius: 8px;
+                   padding: 14px 16px; overflow-x: auto; }
+  .codeblock pre code { padding: 0; border: 0; background: none; font-size: 12.5px; color: #c9d1d9; }
+  .copybtn { position: absolute; top: 8px; right: 8px; padding: 3px 8px; cursor: pointer;
+             background: #161b22; border: 1px solid #21262d; border-radius: 5px;
+             color: #8b949e; font: 11px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  .copybtn:hover { color: #e6edf3; border-color: oklch(0.80 0.16 200); }
+  @media (max-width: 800px) {
+    .layout { flex-direction: column; }
+    .sidebar { position: static; height: auto; width: 100%; flex-basis: auto;
+               border-right: 0; border-bottom: 1px solid #21262d; }
+    .content { padding: 24px 18px 60px; }
+  }
+</style>
+</head>
+<body>
+<div class="layout">
+  <aside class="sidebar">
+    <a class="brand" href="../index.html">flashruntime<small>documentation</small></a>
+    <div class="search">
+      <input id="q" type="search" placeholder="Search docs  (press /)" autocomplete="off" spellcheck="false">
+      <div id="results"></div>
+    </div>
+    <nav><div class="nav-section">Getting started</div>
+<a class="nav-link" href="../index.html">FlashRuntime</a>
+<a class="nav-link" href="../get-started.html">Get started</a>
+<div class="nav-section">Tutorials</div>
+<a class="nav-link" href="../tutorials/convnet.html">Tutorial: make a ConvNet fault-tolerant</a>
+<a class="nav-link" href="../tutorials/sklearn-sweeps.html">Tutorial: parallel scikit-learn sweeps</a>
+<a class="nav-link" href="../tutorials/fault-tolerance.html">Tutorial: automatic recovery, explained</a>
+<div class="nav-section">Guides</div>
+<a class="nav-link" href="../guides/pytorch.html">PyTorch guide</a>
+<a class="nav-link" href="../guides/sklearn.html">scikit-learn guide</a>
+<a class="nav-link" href="../guides/huggingface.html">Hugging Face guide</a>
+<a class="nav-link" href="../guides/jobspec-and-isolation.html">JobSpec &amp; isolation guide</a>
+<a class="nav-link" href="../guides/federated-averaging.html">Federated averaging</a>
+<div class="nav-section">Concepts</div>
+<a class="nav-link" href="../concepts/architecture.html">Architecture</a>
+<div class="nav-section">Reference</div>
+<a class="nav-link" href="sdk.html">Reference: SDK (`flashruntime`)</a>
+<a class="nav-link" href="integrations.html">Reference: integrations (`flashruntime.integrations`)</a>
+<a class="nav-link active" href="torch-helper.html">Reference: torch helper (`flashruntime.torch`)</a>
+<a class="nav-link" href="cli.html">Reference: CLI (`flashruntime`)</a>
+<div class="nav-section">Benchmarks</div>
+<a class="nav-link" href="../benchmarks.html">Benchmarks</a></nav>
+  </aside>
+  <main class="content"><h1 id="reference-torch-helper-flashruntimetorch">Reference: torch helper (<code>flashruntime.torch</code>)</h1>
+<p>The optional in-training-script helper: one import
+(<code>import flashruntime.torch as ft</code>) makes a PyTorch script both
+launch-anywhere and fault-tolerant. <code>torch</code> is imported <strong>inside</strong> these
+functions only — FlashRuntime's core never depends on it.</p>
+<p>The surface is three verbs plus read-only launch-fact accessors — a
+deliberate guardrail (ADR-0003: do not rebuild Accelerate). The boundary is
+<em>capability</em>, not count: there are no FSDP policies, no autocast, no
+DeepSpeed config here, and there never will be. Signatures are exact; each
+says, in one line, <em>why it exists</em>.</p>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">def prepare(model, optimizer=None, dataloader=None): ...
+def checkpoint(model, optimizer=None, *, step, every=None) -&gt; None: ...
+def log_metrics(metrics: dict) -&gt; None: ...
+def start_step() -&gt; int: ...
+def rank() -&gt; int: ...
+def world_size() -&gt; int: ...
+def is_main() -&gt; bool: ...
+def device() -&gt; str: ...          # &quot;cpu&quot; or &quot;cuda:N&quot; — where prepare() put the model
+def backend() -&gt; str | None: ...  # &quot;gloo&quot;/&quot;nccl&quot;, None when single-process
+</code></pre></div>
+<hr />
+<h3 id="preparemodel-optimizernone-dataloadernone"><code>prepare(model, optimizer=None, dataloader=None)</code></h3>
+<p>Wires distributed execution and restores the newest valid checkpoint; returns
+the possibly-wrapped <code>(model, optimizer, dataloader)</code> triple.</p>
+<ul>
+<li>Launched distributed (<code>WORLD_SIZE &gt; 1</code>): initializes torch's own process
+  group (<code>nccl</code> on GPU, <code>gloo</code> on CPU), wraps the model in
+  <code>DistributedDataParallel</code>, and swaps the DataLoader's sampler for a seed-0
+  <code>DistributedSampler</code> (each rank sees a disjoint, deterministic shard).</li>
+<li>On CUDA: selects <code>nccl</code>, moves the model onto this rank's GPU <strong>before</strong> the
+  DDP wrap, and binds <code>device_ids</code> / <code>output_device</code> — you no longer call
+  <code>model.to(device)</code>.</li>
+<li>Restores the newest <strong>valid</strong> checkpoint manifest if one exists, setting the
+  resume step (read it with <code>start_step()</code>).</li>
+<li>Launched as plain <code>python train.py</code>: a no-op passthrough.</li>
+</ul>
+<blockquote>
+<p>The rebuilt DataLoader carries over <code>batch_size</code>, <code>collate_fn</code>,
+<code>num_workers</code>, and <code>drop_last</code>. <strong><code>shuffle</code> and <code>pin_memory</code> are not carried
+over</strong> — the seed-0 <code>DistributedSampler</code> owns shuffling.</p>
+</blockquote>
+<h3 id="checkpointmodel-optimizernone-step-everynone"><code>checkpoint(model, optimizer=None, *, step, every=None)</code></h3>
+<p>rank 0 writes a resumable checkpoint under the <strong>parts-first / manifest-last</strong>
+contract (the manifest is written last, so a half-written checkpoint is never
+<code>latest_valid</code>). <code>every=N</code> no-ops except on multiples of N. Every rank
+synchronizes on a barrier so no one races past a partial write.</p>
+<h3 id="log_metricsmetrics-dict"><code>log_metrics(metrics: dict)</code></h3>
+<p>rank 0 appends one JSON record per call to <code>metrics.jsonl</code> — the streaming
+history the live page draws as a loss curve. <strong>Never raises</strong> (metrics must
+never kill training). Separate from the final <code>metrics.json</code> your script writes
+for <code>run.trials</code>.</p>
+<h3 id="start_step-int"><code>start_step() -&gt; int</code></h3>
+<p>The first step the loop should run: <code>0</code> fresh, <code>&gt;0</code> after a resume (set by
+<code>prepare()</code> when it restores a checkpoint). Start your loop from it.</p>
+<h3 id="rank-world_size-is_main"><code>rank()</code> / <code>world_size()</code> / <code>is_main()</code></h3>
+<p>The small positional helpers, read from the launch environment: <code>rank()</code> is
+this process's <code>RANK</code> (default <code>0</code>), <code>world_size()</code> is <code>WORLD_SIZE</code> (default
+<code>1</code>), and <code>is_main()</code> is <code>rank() == 0</code> — guard rank-0-only work (writing the
+final <code>metrics.json</code>, printing) with it.</p>
+<hr />
+<h2 id="usage-shape">Usage shape</h2>
+<div class="codeblock"><button class="copybtn" type="button" aria-label="Copy code to clipboard">Copy</button><pre><code class="language-python">import flashruntime.torch as ft
+model, optimizer, loader = ft.prepare(model, optimizer, loader)
+start = ft.start_step()
+step = start
+while step &lt; total_steps:
+    for x, y in loader:
+        ...
+        step += 1
+        ft.checkpoint(model, optimizer, step=step, every=100)
+        ft.log_metrics({&quot;step&quot;: step, &quot;loss&quot;: float(loss)})
+if ft.is_main():
+    ...   # write the final metrics.json
+</code></pre></div>
+<p>The full worked example is the <a href="../tutorials/convnet.html">ConvNet tutorial</a>; the
+launch side is the <a href="../guides/pytorch.html">PyTorch guide</a>.</p></main>
+</div>
+<script>
+// ---- client-side search: fetch the builder's index, filter as you type -----
+// (<=60 lines, vanilla JS, no external anything — the index is a sibling file.)
+let INDEX = [];
+// Path from THIS page back to the site root. The index stores root-relative
+// URLs (e.g. "tutorials/deep.html"); we fetch it and build result links
+// against ROOT so a page in a subdir resolves them too (see build_docs.py).
+const ROOT = "../";
+const q = document.getElementById("q");
+const results = document.getElementById("results");
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) =>
+  ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+fetch(ROOT + "search-index.json").then((r) => r.json()).then((d) => { INDEX = d; }).catch(() => {});
+// A short context window around the first match, so a hit shows WHY it matched.
+function snippet(text, needle) {
+  const i = text.toLowerCase().indexOf(needle);
+  if (i < 0) return "";
+  const start = Math.max(0, i - 32);
+  return (start > 0 ? "…" : "") + text.slice(start, i + needle.length + 44).trim() + "…";
+}
+function runSearch() {
+  const needle = q.value.trim().toLowerCase();
+  if (!needle) { results.className = ""; results.innerHTML = ""; return; }
+  const hits = INDEX.map((p) => {
+    const inTitle = p.title.toLowerCase().includes(needle);
+    const inText = p.text.toLowerCase().includes(needle);
+    if (!inTitle && !inText) return null;
+    return { url: p.url, title: p.title, snip: inText ? snippet(p.text, needle) : "" };
+  }).filter(Boolean).slice(0, 20);
+  results.className = "open";
+  results.innerHTML = hits.length
+    ? hits.map((h) => '<a href="' + ROOT + h.url + '"><b>' + esc(h.title) + "</b>" +
+        (h.snip ? "<span>" + esc(h.snip) + "</span>" : "") + "</a>").join("")
+    : '<div class="nohit">no matches</div>';
+}
+q.addEventListener("input", runSearch);
+q.addEventListener("focus", runSearch);
+document.addEventListener("click", (e) => {
+  if (!e.target.closest(".search")) { results.className = ""; }  // dismiss on outside click
+});
+document.addEventListener("keydown", (e) => {  // "/" focuses search, like PyTorch docs
+  if (e.key === "/" && document.activeElement !== q) { e.preventDefault(); q.focus(); }
+});
+// ---- copy buttons: read the <pre>'s own text into the clipboard ------------
+document.querySelectorAll(".copybtn").forEach((btn) => {
+  btn.addEventListener("click", () => {
+    const code = btn.parentElement.querySelector("pre").innerText;
+    navigator.clipboard.writeText(code).then(() => {
+      const was = btn.textContent; btn.textContent = "Copied";
+      setTimeout(() => { btn.textContent = was; }, 1200);
+    }).catch(() => {});
+  });
+});
+</script>
+</body>
+</html>