Add a Python SDK: flows declared in your own repository

A data scientist keeps their code where it is and decorates it: `@node`
declares a function's ports beside the function, `Flow(name, nodes=[...])`
says which of them make a flow, and `use(fn, wire=..., **settings)` rebinds
one for a single flow. `fluksio sync` uploads the document plus a generated
import shim per node, so the store still holds a complete, runnable,
git-versioned definition while the code it imports stays theirs.

`fluksio login|run|runs` and `flow.submit().wait()` are the client half, over
the run endpoints that already existed. Runs record the user repository's
commit beside the store's, so "what code produced this number" is answerable
on the side that now holds the code.

- `fluksio/sdk/`: ports, decorators, the flow builder and its checks, the shim
  generator, an HTTP client and sync. Standard library only at import, so
  `from fluksio import node` in a training script pulls in no engine.
- `FlowDef.origin` marks a flow code-defined; `Run.origin_commit` carries the
  repository's commit; `POST /modules/refresh` retires the workers without an
  install, which every sync calls — a worker holds the imported package in
  memory, so an edit to it is invisible until the process goes.
- The canvas shows a generated body read-only and names the repository to edit
  instead; a body edited there stops the next sync rather than being discarded.
- The worker's reporter carries inert `Port`, `node`, `use` and `Flow`, since
  the shim imports a module whose first line declares them.
- `examples/myresearch` is the worked example, `make sync-example` uploads it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012ue1tkFWB1bcGy3aWhCKpU

examples/myresearch/__init__.py

@@ -0,0 +1,7 @@
+"""A research package that knows nothing about Fluksio, except where it says so.
+
+Everything here is ordinary Python: `prepare`, `fit` and `evaluate` are called
+directly by `python -m myresearch.pipeline`, and the decorators on them only
+say what a node of each would look like. `fluksio sync examples/myresearch` is
+what turns that into a flow.
+"""

examples/myresearch/data.py

@@ -0,0 +1,34 @@
+"""Where the data comes from."""
+
+from __future__ import annotations
+
+import json
+
+import fluksio
+from fluksio import Port, node
+
+
+@node(provides=[Port("dataset", "artifact"), Port("rows", "int")])
+def prepare(source: str = "builtin", limit: int = 512):
+    """Make the training set and store it, returning a reference to it.
+
+    `source` and `limit` have defaults and are not ports, so they become the
+    node's settings: the canvas can tune them without touching this file.
+    """
+    rows = [{"x": index / limit, "y": (index % 7) / 7} for index in range(limit)]
+    payload = json.dumps({"source": source, "rows": rows}).encode()
+    return {
+        "dataset": fluksio.save_artifact(payload, "dataset.json", "application/json"),
+        "rows": len(rows),
+    }
+
+
+@node(requires=["dataset"], provides=[Port("augmented", "artifact")])
+def augment(dataset, factor: int = 2):
+    """Grow the training set, so `finetune` has something of its own."""
+    payload = json.loads(open(fluksio.load_artifact(dataset)).read())
+    payload["rows"] = payload["rows"] * factor
+    blob = json.dumps(payload).encode()
+    return {
+        "augmented": fluksio.save_artifact(blob, "augmented.json", "application/json")
+    }

examples/myresearch/evaluate.py

@@ -0,0 +1,19 @@
+"""Scoring what was trained."""
+
+from __future__ import annotations
+
+import json
+
+import fluksio
+from fluksio import Port, node
+
+
+@node(requires=["weights"], provides=Port("score", "float"))
+def evaluate(weights):
+    """Score the model, returning the number rather than a dict.
+
+    `provides=Port(...)` — one port rather than a list of them — is the opt-in
+    to a bare return: the generated node wraps it in the message it belongs to.
+    """
+    trained = json.loads(open(fluksio.load_artifact(weights)).read())
+    return round(1 - trained["lr"] / (1 + trained["epochs"]), 4)

examples/myresearch/pipeline.py

@@ -0,0 +1,48 @@
+"""Which nodes make up which flow.
+
+Membership is this list, not the file a function sits in: `fit` is declared in
+`train.py` and used by both flows below, once as itself and once rewired and
+reconfigured. Wiring is not membership either — nodes connect because one
+provides a message another requires, never because one imported the other.
+
+    fluksio sync examples/myresearch
+    fluksio run train --lr 0.05 --wait
+"""
+
+from __future__ import annotations
+
+from fluksio import Flow, Port, use
+from myresearch.data import augment, prepare
+from myresearch.evaluate import evaluate
+from myresearch.train import fit
+
+train = Flow(
+    "train",
+    title="Train",
+    nodes=[prepare, fit, evaluate],
+    inputs=[Port("lr", "float", initial=0.01)],
+    outputs=["score", "final_loss"],
+)
+
+finetune = Flow(
+    "finetune",
+    title="Finetune",
+    nodes=[
+        prepare,
+        augment,
+        # The same function, reading `augmented` instead of `dataset` and with
+        # a shorter schedule. `train` is unaffected.
+        use(fit, wire={"dataset": "augmented"}, epochs=3),
+        evaluate,
+    ],
+    inputs=[Port("lr", "float", initial=0.0001)],
+    outputs=["score"],
+)
+
+
+if __name__ == "__main__":
+    # Run it here, with no engine involved: the decorators changed nothing
+    # about calling these functions.
+    dataset = prepare(limit=64)
+    losses = list(fit(dataset["dataset"], lr=0.05, epochs=5))
+    print("losses:", [round(step["loss"], 4) for step in losses])

examples/myresearch/train.py

@@ -0,0 +1,41 @@
+"""The part that would be on the GPU."""
+
+from __future__ import annotations
+
+import json
+import math
+
+import fluksio
+from fluksio import Port, node
+
+
+@node(
+    requires=["dataset", Port("lr", "float")],
+    provides=[
+        Port("loss", "float", stream=True),
+        Port("weights", "artifact"),
+        Port("final_loss", "float"),
+    ],
+    device="gpu",
+    device_policy="prefer",
+    timeout=600,
+)
+def fit(dataset, lr, epochs=25):
+    """Train, reporting the loss as it goes.
+
+    Yielding is the reporting: each one publishes on the `loss` port the
+    instant it happens, and the run keeps every value as a series — which is
+    why there is no `log_metric()` to call. `device="gpu"` with
+    `device_policy="prefer"` sends this to a worker carrying that label when
+    one is attached, and runs it here when none is.
+    """
+    rows = json.loads(open(fluksio.load_artifact(dataset)).read())["rows"]
+    loss = 1.0
+    for epoch in range(epochs):
+        loss = math.exp(-lr * epoch * 10) * (1 + 0.05 * (epoch % 3)) / (1 + lr)
+        yield {"loss": loss}
+    weights = json.dumps({"lr": lr, "epochs": epochs, "n": len(rows)}).encode()
+    return {
+        "weights": fluksio.save_artifact(weights, "weights.json", "application/json"),
+        "final_loss": loss,
+    }