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
This commit is contained in:
2026-08-23 20:16:08 +02:00
co-authored by Claude Fable 5
parent 775d151307
commit a38e2745eb
35 changed files with 2693 additions and 142 deletions
+13 -2
View File
@@ -1,4 +1,4 @@
"""`fluksio serve`, `fluksio enroll`, `fluksio worker`.
"""`fluksio serve`, `fluksio enroll`, `fluksio worker`, `sync`, `run`, `runs`.
The point of this module is a machine nobody can route to: a node on a cluster
where ports cannot be opened, or a laptop with no Docker. `fluksio serve`
@@ -268,6 +268,11 @@ def _parser() -> argparse.ArgumentParser:
help="run nodes for an engine elsewhere (fluksio-worker)",
add_help=False,
)
# The client half: talking to an engine rather than being one.
from fluksio.sdk.cli import add_parsers
add_parsers(subparsers)
return parser
@@ -276,7 +281,13 @@ def main(argv: list[str] | None = None) -> int:
# Everything after `worker` belongs to the agent's own parser.
if argv and argv[0] == "worker":
return cmd_worker(argv[1:])
args = _parser().parse_args(argv)
parser = _parser()
if argv and argv[0] == "run":
# A flow's inputs are its own, so `--lr 0.05` cannot be declared here:
# whatever this parser does not know is typed against the flow.
args, rest = parser.parse_known_args(argv)
return int(args.func(args, rest))
args = parser.parse_args(argv)
result: int = args.func(args)
return result