flashruntime 0.3.0__py3-none-any.whl

flashml_workloads/sgd_trainer.py

@@ -0,0 +1,127 @@
+"""Checkpointable logistic-regression SGD, runnable as a leased task.
+
+Executor contract (same CLI as the other task modules):
+
+    python -m flashml_workloads.sgd_trainer --spec spec.json --out OUTDIR
+
+`spec.json`:
+    params: steps, checkpoint_every, lr, seed,
+            kill_at_step (optional — fires only on a FRESH start, so a
+            resumed retry never re-crashes; this is the deterministic
+            kill-and-recover test hook)
+    inputs: dataset (headerless CSV, label last), resume (optional path to
+            a checkpoint json downloaded by the executor)
+
+Checkpoints go to OUTDIR/ckpt/step-NNNNNN.json ({step, weights, bias}); the
+executor's relay uploads them and commits manifests as they appear.
+
+Determinism is the contract: batches are indexed by step number (cyclic
+slices, no RNG state to carry), so resuming from step k reproduces the
+uninterrupted run bit-for-bit — recovery must never silently change the
+result. Pure stdlib; runs anywhere, including `--network none` containers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import math
+import sys
+from pathlib import Path
+
+BATCH = 4
+
+
+def _load(path: str) -> tuple[list[list[float]], list[float]]:
+    xs, ys = [], []
+    with open(path, newline="") as f:
+        for row in csv.reader(f):
+            if row:
+                xs.append([float(v) for v in row[:-1]])
+                ys.append(float(row[-1]))
+    return xs, ys
+
+
+def _loss(xs, ys, w, b) -> float:
+    total = 0.0
+    for x, y in zip(xs, ys):
+        z = sum(wi * xi for wi, xi in zip(w, x)) + b
+        p = 1.0 / (1.0 + math.exp(-z))
+        p = min(max(p, 1e-12), 1 - 1e-12)
+        total += -(y * math.log(p) + (1 - y) * math.log(1 - p))
+    return total / len(xs)
+
+
+def run_trainer(spec: dict, out: Path) -> dict:
+    params = spec.get("params", {})
+    steps = int(params["steps"])
+    every = int(params.get("checkpoint_every", 100))
+    lr = float(params.get("lr", 0.1))
+    kill_at = params.get("kill_at_step")
+
+    xs, ys = _load(spec["inputs"]["dataset"])
+    dims = len(xs[0])
+
+    resume_path = spec.get("inputs", {}).get("resume")
+    if resume_path:
+        ckpt = json.loads(Path(resume_path).read_text())
+        w, b, start = list(ckpt["weights"]), float(ckpt["bias"]), int(ckpt["step"])
+        resumed = True
+    else:
+        w, b, start = [0.0] * dims, 0.0, 0
+        resumed = False
+
+    out = Path(out)
+    ckpt_dir = out / "ckpt"
+    ckpt_dir.mkdir(parents=True, exist_ok=True)
+
+    n = len(xs)
+    for step in range(start + 1, steps + 1):
+        # batch indexed by step ⇒ no RNG state; resume is trivially exact
+        base = ((step - 1) * BATCH) % n
+        idx = [(base + i) % n for i in range(BATCH)]
+        gw, gb = [0.0] * dims, 0.0
+        for i in idx:
+            z = sum(wi * xi for wi, xi in zip(w, xs[i])) + b
+            p = 1.0 / (1.0 + math.exp(-z))
+            err = p - ys[i]
+            for d in range(dims):
+                gw[d] += err * xs[i][d]
+            gb += err
+        for d in range(dims):
+            w[d] -= lr * gw[d] / BATCH
+        b -= lr * gb / BATCH
+
+        if step % every == 0 and step < steps:
+            (ckpt_dir / f"step-{step:06d}.json").write_text(
+                json.dumps({"step": step, "weights": w, "bias": b})
+            )
+        if kill_at is not None and not resumed and step >= int(kill_at):
+            # simulated crash on a fresh run only — retries resume, not re-die
+            sys.exit(3)
+
+    metrics = {
+        "task_id": spec.get("task_id", ""),
+        "steps": steps,
+        "started_from_step": start,
+        "resumed": resumed,
+        "final_loss": round(_loss(xs, ys, w, b), 12),
+        "weights": [round(v, 12) for v in w],
+        "bias": round(b, 12),
+    }
+    (out / "metrics.json").write_text(json.dumps(metrics, sort_keys=True))
+    return metrics
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sgd_trainer")
+    parser.add_argument("--spec", required=True)
+    parser.add_argument("--out", required=True)
+    args = parser.parse_args(argv)
+    run_trainer(json.loads(Path(args.spec).read_text()), Path(args.out))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flashml_workloads/sharded_kmeans.py

@@ -0,0 +1,323 @@
+"""Iterative sharded K-Means on Ray tasks — the POC's real distributed job.
+
+Shape (per docs/SYSTEM_OVERVIEW and the POC brief):
+- deterministic synthetic dataset, generated per shard from (seed, shard_id)
+  so shards are reproducible anywhere without shipping data;
+- each iteration maps one retriable Ray task per shard (many more shards
+  than workers → dynamic scheduling), reduces partial sums on the driver,
+  updates centroids;
+- every task reports which Ray node / Kubernetes node / pod it ran on;
+- retry evidence is *measured*, not fabricated: after the run the driver
+  queries Ray's task state API for tasks whose attempt count exceeds 1 and
+  correlates in-run worker-set changes;
+- final artifacts (centroids, metrics, execution summary, node
+  contributions, recovery events) are uploaded to the configured artifact
+  store (MinIO locally, OSS on Alibaba) — durable outside any worker.
+
+Parameters (FLASHML_WORKLOAD_PARAMS JSON): samples, dimensions, clusters,
+shards, iterations, seed, task_delay_seconds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import socket
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+# `ray` is imported lazily inside the functions that need it: the pure data
+# functions (make_shard, _true_centers) must stay importable in environments
+# without Ray (unit tests, the runtime service image).
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _params() -> dict:
+    p = json.loads(os.environ.get("FLASHML_WORKLOAD_PARAMS", "{}"))
+    return {
+        "samples": int(p.get("samples", 150_000)),
+        "dimensions": int(p.get("dimensions", 24)),
+        "clusters": int(p.get("clusters", 6)),
+        "shards": int(p.get("shards", 36)),
+        "iterations": int(p.get("iterations", 12)),
+        "seed": int(p.get("seed", 42)),
+        "task_delay_seconds": float(p.get("task_delay_seconds", 0.4)),
+    }
+
+
+def _true_centers(seed: int, clusters: int, dimensions: int) -> np.ndarray:
+    return np.random.default_rng(seed).uniform(-10, 10, size=(clusters, dimensions))
+
+
+def make_shard(seed: int, shard_id: int, samples_per_shard: int,
+               clusters: int, dimensions: int) -> np.ndarray:
+    """Deterministic shard: same (seed, shard_id) always yields the same
+    points, so a retried task recomputes identical data."""
+    centers = _true_centers(seed, clusters, dimensions)
+    rng = np.random.default_rng(seed * 1_000_003 + shard_id)
+    assignment = rng.integers(0, clusters, size=samples_per_shard)
+    noise = rng.normal(0.0, 1.5, size=(samples_per_shard, dimensions))
+    return centers[assignment] + noise
+
+
+def assign_shard(shard_id: int, centroids: np.ndarray, cfg: dict) -> dict:
+    """One map task: assign a shard's points to the current centroids and
+    return partial sums/counts plus the identity of the node that did it."""
+    import ray
+
+    t0 = time.monotonic()
+    X = make_shard(cfg["seed"], shard_id, cfg["samples_per_shard"],
+                   cfg["clusters"], cfg["dimensions"])
+    if cfg["task_delay_seconds"] > 0:
+        # Only to stretch the run long enough to inject a failure reliably.
+        time.sleep(cfg["task_delay_seconds"])
+
+    # Nearest-centroid assignment.
+    d2 = ((X[:, None, :] - centroids[None, :, :]) ** 2).sum(axis=2)
+    labels = d2.argmin(axis=1)
+    inertia = float(d2[np.arange(len(X)), labels].sum())
+
+    k = centroids.shape[0]
+    sums = np.zeros_like(centroids)
+    counts = np.zeros(k, dtype=np.int64)
+    for c in range(k):
+        mask = labels == c
+        counts[c] = int(mask.sum())
+        if counts[c]:
+            sums[c] = X[mask].sum(axis=0)
+
+    ctx = ray.get_runtime_context()
+    return {
+        "shard_id": shard_id,
+        "partial_sums": sums,
+        "partial_counts": counts,
+        "inertia": inertia,
+        "n_samples": int(len(X)),
+        "duration_ms": int((time.monotonic() - t0) * 1000),
+        "ray_node_id": ctx.get_node_id(),
+        "pod": os.environ.get("K8S_POD_NAME", socket.gethostname()),
+        "k8s_node": os.environ.get("K8S_NODE_NAME", "unknown"),
+    }
+
+
+def _worker_set() -> dict[str, str]:
+    """Alive Ray nodes (node_id -> node name/ip), head included."""
+    import ray
+
+    return {n["NodeID"]: n.get("NodeManagerHostname", n.get("NodeManagerAddress", "?"))
+            for n in ray.nodes() if n["Alive"]}
+
+
+def _collect_retry_evidence(job_id: str) -> list[dict]:
+    """Real per-task attempt metadata from Ray's state API. A task with
+    attempt_number > 0 was genuinely retried by Ray."""
+    events: list[dict] = []
+    try:
+        from ray.util.state import list_tasks
+
+        tasks = list_tasks(filters=[("name", "=", "assign_shard")],
+                           limit=10_000, detail=True)
+        for t in tasks:
+            attempt = getattr(t, "attempt_number", 0) or 0
+            if attempt > 0:
+                events.append({
+                    "schema_version": "v1alpha1",
+                    "job_id": job_id,
+                    "type": "TASK_ATTEMPT_RETRIED",
+                    "timestamp": _now_iso(),
+                    "source": "ray.task-state",
+                    "message": f"task {t.task_id} retried (attempt {attempt + 1})",
+                    "data": {
+                        "task_id": t.task_id,
+                        "attempt_number": attempt,
+                        "state": str(getattr(t, "state", "")),
+                        "node_id": getattr(t, "node_id", None),
+                        "error_type": str(getattr(t, "error_type", "") or ""),
+                    },
+                })
+    except Exception as exc:  # state API is best-effort; never fake evidence
+        print(json.dumps({"msg": "could not query Ray task state API",
+                          "error": str(exc)}))
+    return events
+
+
+def run() -> None:
+    import ray
+
+    job_id = os.environ.get("FLASHML_JOB_ID", "local-dev")
+    params = _params()
+    max_attempts = int(os.environ.get("FLASHML_MAX_TASK_ATTEMPTS", "4"))
+
+    ray.init()  # inside the RayJob-managed cluster
+
+    cfg = {
+        "seed": params["seed"],
+        "clusters": params["clusters"],
+        "dimensions": params["dimensions"],
+        "samples_per_shard": max(1, params["samples"] // params["shards"]),
+        "task_delay_seconds": params["task_delay_seconds"],
+    }
+
+    # max_retries counts *re*-executions: attempts = 1 + max_retries.
+    remote_assign = ray.remote(max_retries=max_attempts - 1, num_cpus=1)(assign_shard)
+
+    rng = np.random.default_rng(params["seed"])
+    centers = _true_centers(params["seed"], params["clusters"], params["dimensions"])
+    centroids = centers + rng.normal(0, 4.0, size=centers.shape)
+
+    print(json.dumps({"msg": "kmeans starting", "job_id": job_id, **params}))
+    initial_workers = _worker_set()
+    print(json.dumps({"msg": "ray nodes online", "nodes": list(initial_workers.values()),
+                      "count": len(initial_workers)}))
+
+    metrics_history: list[dict] = []
+    recovery_events: list[dict] = []
+    node_contributions: dict[str, dict] = {}
+    seen_workers = dict(initial_workers)
+    t_start = time.monotonic()
+
+    for iteration in range(params["iterations"]):
+        it0 = time.monotonic()
+        refs = [remote_assign.remote(s, centroids, cfg) for s in range(params["shards"])]
+        results = ray.get(refs)
+
+        # Reduce.
+        sums = np.zeros_like(centroids)
+        counts = np.zeros(params["clusters"], dtype=np.int64)
+        inertia = 0.0
+        for r in results:
+            sums += r["partial_sums"]
+            counts += r["partial_counts"]
+            inertia += r["inertia"]
+            node_key = f'{r["k8s_node"]}|{r["pod"]}'
+            entry = node_contributions.setdefault(node_key, {
+                "k8s_node": r["k8s_node"], "pod": r["pod"],
+                "ray_node_id": r["ray_node_id"], "tasks": 0, "samples": 0,
+                "busy_ms": 0,
+            })
+            entry["tasks"] += 1
+            entry["samples"] += r["n_samples"]
+            entry["busy_ms"] += r["duration_ms"]
+
+        nonzero = counts > 0
+        old = centroids.copy()
+        centroids[nonzero] = sums[nonzero] / counts[nonzero, None]
+        movement = float(np.linalg.norm(centroids - old))
+
+        # Worker-set diffs are observed facts from ray.nodes().
+        current_workers = _worker_set()
+        for node_id, name in seen_workers.items():
+            if node_id not in current_workers:
+                recovery_events.append({
+                    "schema_version": "v1alpha1", "job_id": job_id,
+                    "type": "RAY_WORKER_LOST", "timestamp": _now_iso(),
+                    "source": "ray.nodes",
+                    "message": f"Ray node {name} left the cluster during iteration {iteration}",
+                    "data": {"ray_node_id": node_id, "node": name,
+                             "iteration": iteration},
+                })
+        for node_id, name in current_workers.items():
+            if node_id not in seen_workers:
+                recovery_events.append({
+                    "schema_version": "v1alpha1", "job_id": job_id,
+                    "type": "RAY_WORKER_REPLACED", "timestamp": _now_iso(),
+                    "source": "ray.nodes",
+                    "message": f"Ray node {name} joined during iteration {iteration}",
+                    "data": {"ray_node_id": node_id, "node": name,
+                             "iteration": iteration},
+                })
+        seen_workers = current_workers
+
+        entry = {
+            "iteration": iteration,
+            "inertia": inertia,
+            "movement": movement,
+            "duration_s": round(time.monotonic() - it0, 3),
+            "tasks": params["shards"],
+            "workers_online": len(current_workers),
+            "timestamp": _now_iso(),
+        }
+        metrics_history.append(entry)
+        print(json.dumps({"msg": "iteration complete", **entry}))
+        recovery_events.append({
+            "schema_version": "v1alpha1", "job_id": job_id,
+            "type": "ITERATION_COMPLETED", "timestamp": _now_iso(),
+            "source": "workload.driver",
+            "message": f"iteration {iteration} complete "
+                       f"(inertia={inertia:.1f}, movement={movement:.4f})",
+            "data": entry,
+        })
+
+    total_s = round(time.monotonic() - t_start, 2)
+    recovery_events.extend(_collect_retry_evidence(job_id))
+
+    summary = {
+        "job_id": job_id,
+        "parameters": params,
+        "total_duration_s": total_s,
+        "iterations_run": len(metrics_history),
+        "final_inertia": metrics_history[-1]["inertia"],
+        "final_movement": metrics_history[-1]["movement"],
+        "tasks_total": params["shards"] * params["iterations"],
+        "max_task_attempts": max_attempts,
+        "retried_tasks": sum(1 for e in recovery_events
+                             if e["type"] == "TASK_ATTEMPT_RETRIED"),
+        "workers_lost": sum(1 for e in recovery_events
+                            if e["type"] == "RAY_WORKER_LOST"),
+        "nodes_contributing": len(node_contributions),
+        "finished_at": _now_iso(),
+    }
+    print(json.dumps({"msg": "kmeans finished", **summary}))
+
+    _upload_artifacts(job_id, {
+        "centroids.json": {"centroids": centroids.tolist(),
+                           "clusters": params["clusters"],
+                           "dimensions": params["dimensions"]},
+        "metrics.json": {"history": metrics_history},
+        "execution-summary.json": summary,
+        "node-contributions.json": {"nodes": list(node_contributions.values())},
+        "recovery-events.json": recovery_events,
+    })
+
+
+def _upload_artifacts(job_id: str, artifacts: dict[str, object]) -> None:
+    prefix = os.environ.get("FLASHML_ARTIFACT_PREFIX", f"artifact://jobs/{job_id}/")
+    try:
+        from flashruntime.artifacts import artifact_uri_to_key, store_from_env
+
+        store = store_from_env()
+    except Exception as exc:
+        print(json.dumps({"msg": "artifact store unavailable; writing locally",
+                          "error": str(exc)}))
+        out = Path("/tmp/flashml-artifacts") / job_id
+        out.mkdir(parents=True, exist_ok=True)
+        for name, payload in artifacts.items():
+            (out / name).write_text(json.dumps(payload, indent=2))
+        return
+
+    key_prefix = artifact_uri_to_key(prefix)
+
+    async def _put_all():
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp:
+            for name, payload in artifacts.items():
+                path = Path(tmp) / name
+                path.write_text(json.dumps(payload, indent=2))
+                record = await store.put_file(path, f"{key_prefix}{name}")
+                print(json.dumps({"msg": "artifact committed", "uri": record.uri,
+                                  "etag": record.etag,
+                                  "size_bytes": record.size_bytes}))
+
+    asyncio.run(_put_all())
+
+
+if __name__ == "__main__":
+    run()

flashml_workloads/sklearn_trial.py

@@ -0,0 +1,89 @@
+"""One hyperparameter-search trial, runnable as a leased task.
+
+Executor contract (Tier-1 subprocess runner):
+
+    python -m flashml_workloads.sklearn_trial --spec spec.json --out OUTDIR
+
+`spec.json` (written by the executor from the lease payload):
+    {
+      "task_id": "trial-003",
+      "params":  {"model": "logreg", "C": 0.1},          # this trial's config
+      "inputs":  {"dataset": "/abs/path/to/dataset.csv"} # downloaded shared data
+    }
+
+The dataset is a headerless CSV, features then label in the last column —
+shared data hosted by the coordinator's local artifact endpoint, downloaded
+once per task. Output: `OUTDIR/metrics.json` with the cross-validated
+accuracy; the executor uploads it and commits its sha256.
+
+Supported params: model ∈ {logreg, rf}; logreg: C; rf: n_estimators,
+max_depth. Deterministic (fixed random_state) so retried attempts produce
+identical results — which is what makes idempotent commit meaningful.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import time
+from pathlib import Path
+
+
+def run_trial(spec: dict) -> dict:
+    from sklearn.ensemble import RandomForestClassifier
+    from sklearn.linear_model import LogisticRegression
+    from sklearn.model_selection import cross_val_score
+
+    params = spec.get("params", {})
+    dataset_path = spec["inputs"]["dataset"]
+
+    features: list[list[float]] = []
+    labels: list[float] = []
+    with open(dataset_path, newline="") as f:
+        for row in csv.reader(f):
+            if not row:
+                continue
+            features.append([float(x) for x in row[:-1]])
+            labels.append(float(row[-1]))
+
+    model_kind = params.get("model", "logreg")
+    if model_kind == "logreg":
+        model = LogisticRegression(C=float(params.get("C", 1.0)), max_iter=500, random_state=0)
+    elif model_kind == "rf":
+        model = RandomForestClassifier(
+            n_estimators=int(params.get("n_estimators", 50)),
+            max_depth=int(params["max_depth"]) if params.get("max_depth") else None,
+            random_state=0,
+        )
+    else:
+        raise ValueError(f"unsupported model {model_kind!r} (logreg|rf)")
+
+    start = time.monotonic()
+    scores = cross_val_score(model, features, labels, cv=3)
+    return {
+        "task_id": spec.get("task_id", ""),
+        "params": params,
+        "accuracy_mean": round(float(sum(scores) / len(scores)), 4),
+        "accuracy_folds": [round(float(s), 4) for s in scores],
+        "n_samples": len(labels),
+        "train_seconds": round(time.monotonic() - start, 3),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sklearn_trial")
+    parser.add_argument("--spec", required=True, help="path to spec.json")
+    parser.add_argument("--out", required=True, help="output directory")
+    args = parser.parse_args(argv)
+
+    spec = json.loads(Path(args.spec).read_text())
+    metrics = run_trial(spec)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "metrics.json").write_text(json.dumps(metrics, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flashruntime/__init__.py

@@ -0,0 +1,125 @@
+"""FlashRuntime — open fault-tolerant distributed ML runtime.
+
+A clean, pure-Python core (`pip install flashruntime` brings only pydantic):
+
+1. **Strategy planner** — decide *how* a job should run, with the math shown:
+
+       import flashruntime as flash
+
+       report = flash.plan(flash.PlanRequest(
+           workload=flash.TransformerFineTune(model="Qwen/Qwen2.5-7B", method="lora"),
+           resources=flash.Resources(gpus=4, gpu_type="RTX4090"),
+           objective=flash.Objective(mode="balanced", deadline_minutes=240),
+       ))
+       print(flash.render(report))
+
+2. **Lease manager** (`flashruntime.leases`) — the Mode A reliability core:
+   claim → heartbeat → expiry → requeue → idempotent commit, as a plain
+   state machine anyone can embed (the FlashML coordinator is one consumer).
+
+3. **Checkpoint catalog** (`flashruntime.checkpoint`) — manifests with
+   parts-first / manifest-last commit: a partial checkpoint can never look
+   valid, and recovery selects only verified, topology-compatible state.
+
+4. **Recovery policy** (`flashruntime.recovery`) — the typed failure
+   taxonomy and a versioned, deterministic action table. No agents, no
+   guesswork: same failure + same policy version ⇒ same action.
+
+Infrastructure integrations are opt-in extras, never core imports:
+`[service]` FastAPI coordinator + CLI job commands · `[k8s]` KubeRay
+backend · `[artifacts]`/`[oss]` MinIO / Alibaba OSS stores ·
+`[sklearn]` numpy + scikit-learn for the built-in task-module examples
+(`flashml_workloads/`).
+"""
+
+from typing import Any
+
+from flashruntime.planner import PLANNER_VERSION, plan, render
+from flashruntime.protocol.plan_v1alpha1 import (
+    ClassicalML,
+    IndependentTasks,
+    Objective,
+    PlanReport,
+    PlanRequest,
+    PyTorchTraining,
+    Resources,
+    StrategyPlan,
+    TransformerFineTune,
+)
+
+__all__ = [
+    # planner
+    "plan",
+    "render",
+    "run",
+    "PLANNER_VERSION",
+    "PlanRequest",
+    "PlanReport",
+    "StrategyPlan",
+    "TransformerFineTune",
+    "PyTorchTraining",
+    "ClassicalML",
+    "IndependentTasks",
+    "Resources",
+    "Objective",
+    # bring-your-own-code SDK (lazy — stdlib+pydantic only, but kept lazy
+    # so `import flashruntime` stays minimal)
+    "submit",
+    "CommandWorkload",
+    "OutputSpec",
+    "Source",
+    "integrations",
+]
+
+def run(plan: StrategyPlan, coordinator_url: str | None = None):
+    """Execute a planner-selected StrategyPlan — **designed, not yet built**.
+
+    This is the plan→execution bridge (HANDBOOK §6 "known conscious
+    debts"). The designed pipeline, so the implementer starts from the
+    intended shape rather than inventing one:
+
+    1. Freeze & record: the plan's `plan_id` is stamped on the job attempt
+       (every incident must answer "what did we think, and why").
+    2. Translate: for `workload_mode == "independent_tasks"`, build a
+       lease-backend JobSpec via the matching `recipes.WorkloadRecipe` and
+       POST it to the coordinator (`coordinator_url` or
+       FLASHML_RUNTIME_API). For `coordinated_training`,
+       `strategies.compiler_for(plan).compile(plan)` →
+       `launchers` by `plan.launcher` → launch and watch.
+    3. Return a run handle exposing job_id, state polling, and the ledger
+       event stream — mirroring `LaunchHandle` semantics.
+
+    Until then this raises NotImplementedError so callers fail loudly at
+    the boundary instead of half-running: today you plan with
+    `flash.plan()` and submit the JobSpec yourself (see
+    e2e/test_local_loop.py for the manual pattern).
+    """
+    raise NotImplementedError(
+        "flash.run() is designed but not implemented — build the plan→JobSpec "
+        "translation via recipes/ (Mode A) or strategies/+launchers/ (Mode B); "
+        "see the docstring for the intended pipeline and e2e/test_local_loop.py "
+        "for today's manual equivalent."
+    )
+
+
+# SDK exports resolve lazily: name -> (module, attribute) so the pydantic-only
+# core stays minimal until a bring-your-own-code helper is actually used.
+_SDK_EXPORTS = {
+    "submit": ("flashruntime.sdk", "submit"),
+    "CommandWorkload": ("flashruntime.workloads.command", "CommandWorkload"),
+    "OutputSpec": ("flashruntime.workloads.command", "OutputSpec"),
+    "Source": ("flashruntime.workloads.command", "Source"),
+    "integrations": ("flashruntime.integrations", None),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _SDK_EXPORTS:
+        import importlib
+
+        module_name, attr = _SDK_EXPORTS[name]
+        module = importlib.import_module(module_name)
+        value = module if attr is None else getattr(module, attr)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module 'flashruntime' has no attribute {name!r}")

flashruntime/artifacts/__init__.py

@@ -0,0 +1,25 @@
+"""Backend-neutral artifact storage.
+
+Public artifact identity is always an `artifact://` URI; the physical
+location (MinIO bucket locally, OSS bucket on Alibaba) is an ArtifactRecord
+detail. Implementations: S3CompatibleArtifactStore (MinIO and S3-compatible
+endpoints) and OSSArtifactStore (native Alibaba OSS via oss2).
+"""
+
+from flashruntime.artifacts.store import (
+    ArtifactStore,
+    OSSArtifactStore,
+    S3CompatibleArtifactStore,
+    artifact_uri_to_key,
+    key_to_artifact_uri,
+    store_from_env,
+)
+
+__all__ = [
+    "ArtifactStore",
+    "OSSArtifactStore",
+    "S3CompatibleArtifactStore",
+    "artifact_uri_to_key",
+    "key_to_artifact_uri",
+    "store_from_env",
+]