Follow a record into its fields, name the metrics, name the version

Three things the first export pass got wrong for a real study.

**Dotted paths.** A node returns a record, not a scalar — the numbers arrive
inside `final_metrics` — so `--metrics final_metrics.train_loss` yielded an
empty column and `--metrics final_metrics` yielded the whole record in one
cell. Both sides of the wide table now take dotted paths, and the defaults
reach the same depth: every number a result carries is a column named by its
path, and inputs are compared leaf by leaf, so two configurations differing in
one field give that field as the axis rather than two blobs that are merely
not equal. Lists stay whole — a curve belongs in the long table.

**`--list`.** Metric names are flow-qualified, so `--name train_loss` matched
nothing and said only that. `fluksio export metrics --list` prints the names
the selection carries, and an empty export made with `--name` points at it.

**A version to compare.** The CLI ships ahead of the engine and a stale one
answered a flat 404 with nothing anywhere in the API to tell how old it was.
The engine reports `version` on `/observability/summary`, `fluksio status`
prints it, and a 404 from export now names both versions — or says "older"
when the field itself predates the engine. Bumped to 0.1.5, which is what
makes the number worth reading.

Also formats `flow/metrics.py`, which had been committed unformatted and was
the last `ruff format --check` failure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A9Hdrmf2cwNABCnE5x9UJa

backend/tests/api/routes/test_runs.py

@@ -654,7 +654,11 @@ def test_a_tree_that_did_not_move_is_not_written_again():
 
 @pytest.fixture
 def exported():
-    """Two runs of one flow, each with two curves and one input that varies."""
+    """Two runs of one flow: two curves each, and records on both sides.
+
+    The numbers a node returns are usually inside a record rather than at the
+    top of the result, so the fixture is shaped the way a real one is.
+    """
     made = datetime.now(UTC)
     with Session(db_engine) as session:
         for index, (lr, acc) in enumerate([(0.1, 0.5), (0.01, 0.25)]):
@@ -664,8 +668,17 @@ def exported():
                     id=run_id,
                     flow="export-study",
                     status="ok",
-                    params={"lr": lr, "epochs": 10},
-                    result={"acc": acc, "note": "n/a"},
+                    params={
+                        "lr": lr,
+                        "epochs": 10,
+                        "config": {"model": "mlp", "depth": index + 1},
+                    },
+                    result={
+                        "acc": acc,
+                        "note": "n/a",
+                        "final_metrics": {"train_loss": acc * 2},
+                        "test_metrics": {"known": {"perfect": 1.0}},
+                    },
                     created_at=made + timedelta(seconds=index),
                 )
             )
@@ -727,17 +740,32 @@ def test_an_exported_run_row_carries_the_inputs_that_vary(
     rows = _lines(export(format="jsonl"))
     assert [row["id"] for row in rows] == ["exp-1", "exp-0"]
     assert {row["param.lr"] for row in rows} == {0.1, 0.01}
-    # `epochs` is the same on both runs, so it is not what they differ by; a
-    # string in the result is not one of the run's numbers.
+    # `epochs` is the same on both runs, so it is not what they differ by, and
+    # neither is the model inside the config — but the depth beside it is.
     assert "param.epochs" not in rows[0]
-    assert rows[0]["metric.acc"] == 0.25
-    assert "metric.note" not in rows[0]
+    assert "param.config.model" not in rows[0]
+    assert {row["param.config.depth"] for row in rows} == {1, 2}
     assert "param.epochs" in _lines(export(format="jsonl", params="epochs"))[0]
 
+    # A number inside a record is a column of its own, however deep; a string
+    # is not one of the run's numbers wherever it sits.
+    assert rows[0]["metric.acc"] == 0.25
+    assert rows[0]["metric.final_metrics.train_loss"] == 0.5
+    assert rows[0]["metric.test_metrics.known.perfect"] == 1.0
+    assert "metric.note" not in rows[0]
+
+    named = _lines(export(format="jsonl", metrics="test_metrics.known.perfect"))
+    assert list(named[0])[-1] == "metric.test_metrics.known.perfect"
+    assert "metric.acc" not in named[0]
+
     # csv is the default, and the columns are in the order the header names.
     header = export().text.splitlines()[0]
     assert header.startswith("id,flow,status,")
-    assert header.endswith("param.lr,metric.acc")
+    assert header.endswith(
+        "param.config.depth,param.lr,"
+        "metric.acc,metric.final_metrics.train_loss,"
+        "metric.test_metrics.known.perfect"
+    )
 
 
 @pytest.fixture

backend/tests/test_cli.py

@@ -345,3 +345,46 @@ def test_an_export_is_parsed_with_its_selection() -> None:
     assert runs.func is cmd_export_runs
     assert runs.params == "lr"
     assert runs.format == "jsonl"
+
+
+def test_the_metric_names_are_asked_for_rather_than_guessed() -> None:
+    """A name is flow-qualified, so `--list` is what says what would match."""
+    from fluksio.cli import _parser
+    from fluksio.sdk.cli import _list_names
+
+    parser = _parser()
+    assert parser.parse_args(["export", "metrics"]).list_names is False
+    assert parser.parse_args(["export", "metrics", "--list"]).list_names is True
+
+    class Engine:
+        def runs(self, flow="", limit=0, **filters):
+            assert filters == {"status": "ok"}
+            return [{"id": "r-empty"}, {"id": "r-1"}]
+
+        def metrics(self, run_id, name="", stride=1):
+            # The newest run failed before it measured anything; the next one
+            # carries the vocabulary.
+            return [] if run_id == "r-empty" else [{"name": "train.train_loss"}]
+
+    args = parser.parse_args(
+        ["export", "metrics", "--flow", "train", "--status", "ok", "--list"]
+    )
+    assert _list_names(Engine(), args) == 0
+
+
+def test_an_engine_without_the_route_is_named_rather_than_404() -> None:
+    """A client ships ahead of the engine; a flat 404 does not say so."""
+    from fluksio.sdk.cli import _too_old
+
+    class Old:
+        def summary(self):
+            return {"status": "ok", "version": "0.1.4"}
+
+    class Ancient:
+        def summary(self):
+            # Older than the field itself.
+            return {"status": "ok"}
+
+    assert "engine is 0.1.4" in _too_old(Old())
+    assert "engine is older" in _too_old(Ancient())
+    assert "pip install -U fluksio" in _too_old(Ancient())