Make inspect/head robust to multi-config datasets + dict-shaped split info

- inspect: tolerate SplitInfo objects OR plain dicts (some Hub datasets return
  {'name':..., 'dataset_name':...} with no counts) and a None dataset_size.
- head: auto-resolve config (multi-config datasets with no default) and fall back to the
  first available split when the requested/default split (e.g. 'train') is absent, with hints.
- Add deterministic unit tests (tests/test_cli.py). Found via real-world testing on
  openbmb/UltraData-SFT-2605.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: davanstrien

src/hf_ds/cli.py

@@ -55,6 +55,18 @@ def _features_to_str(features) -> dict:
     return {name: str(feat) for name, feat in features.items()}
 
 
+def _split_summary(s) -> dict:
+    """Normalize a split value to row/byte counts.
+
+    `DatasetInfo.splits` values are usually `SplitInfo` dataclasses (attribute access), but for
+    some Hub datasets they come back as plain dicts — sometimes without counts at all
+    (e.g. `{'name': 'think', 'dataset_name': ...}`). Handle every shape, defaulting to None.
+    """
+    if isinstance(s, dict):
+        return {"num_examples": s.get("num_examples"), "num_bytes": s.get("num_bytes")}
+    return {"num_examples": getattr(s, "num_examples", None), "num_bytes": getattr(s, "num_bytes", None)}
+
+
 def _fail(message: str) -> None:
     out.error(message)
     raise typer.Exit(1)
@@ -169,10 +181,7 @@ def inspect(
         "configs": configs,
         "config": target,
         "features": _features_to_str(info.features),
-        "splits": {
-            name: {"num_examples": s.num_examples, "num_bytes": s.num_bytes}
-            for name, s in (info.splits or {}).items()
-        },
+        "splits": {name: _split_summary(s) for name, s in (info.splits or {}).items()},
         "dataset_size_bytes": info.dataset_size,
     }
     out.dict(result)
@@ -194,15 +203,40 @@ def head(
     Note you cannot do `ds[0]` on a stream — in current `datasets` that returns a lazy
     column accessor, not the first row.
     """
-    from datasets import load_dataset
+    from datasets import get_dataset_config_names, get_dataset_split_names, load_dataset
 
     if json_out:
         out.set_mode(OutputFormat.json)
+
+    # Many Hub datasets have multiple configs and no default — resolve to the first so a bare
+    # `hf ds head <repo>` just works instead of erroring with "Config name is missing".
+    if config is None:
+        try:
+            cfgs = get_dataset_config_names(repo_id, token=token)
+        except Exception as exc:  # noqa: BLE001
+            _fail(f"could not resolve configs for '{repo_id}': {type(exc).__name__}: {exc}")
+            return
+        if cfgs:
+            config = cfgs[0]
+            if len(cfgs) > 1:
+                out.hint(f"multiple configs — showing '{config}'. others: {', '.join(cfgs[1:])}")
+
+    # The requested/default split may not exist (plenty of datasets have no 'train', e.g.
+    # think/no_think or test-only). Fall back to the first available split.
+    chosen = split
+    try:
+        avail = get_dataset_split_names(repo_id, config_name=config, token=token)
+    except Exception:  # noqa: BLE001 - best-effort; if this fails, just try the requested split
+        avail = []
+    if avail and split not in avail:
+        chosen = avail[0]
+        out.hint(f"split '{split}' not found — showing '{chosen}'. available: {', '.join(avail)}")
+
     try:
-        ds = load_dataset(repo_id, name=config, split=split, streaming=True, token=token)
+        ds = load_dataset(repo_id, name=config, split=chosen, streaming=True, token=token)
         rows = list(ds.take(n))
     except Exception as exc:  # noqa: BLE001
-        _fail(f"could not stream '{repo_id}' (split='{split}'): {type(exc).__name__}: {exc}")
+        _fail(f"could not stream '{repo_id}' (config='{config}', split='{chosen}'): {type(exc).__name__}: {exc}")
         return
     # out.table renders a padded table (human), TSV (agent), or JSON (json), and truncates
     # wide cells for humans automatically.

tests/test_cli.py

@@ -0,0 +1,35 @@
+"""Deterministic unit tests for hf-ds helpers (no network)."""
+
+from hf_ds.cli import _detect_builder, _render_recipe, _split_summary
+
+
+class _SplitInfoLike:
+    num_examples = 10
+    num_bytes = 100
+
+
+def test_split_summary_object():
+    assert _split_summary(_SplitInfoLike()) == {"num_examples": 10, "num_bytes": 100}
+
+
+def test_split_summary_dict_with_counts():
+    assert _split_summary({"num_examples": 5, "num_bytes": 50}) == {"num_examples": 5, "num_bytes": 50}
+
+
+def test_split_summary_dict_without_counts():
+    # Regression: openbmb/UltraData-SFT-2605 returns {'name': ..., 'dataset_name': ...} dicts.
+    assert _split_summary({"name": "think", "dataset_name": "x"}) == {"num_examples": None, "num_bytes": None}
+
+
+def test_render_recipe_substitutes_repo():
+    out = _render_recipe("generator", "me/foo")
+    assert "me/foo" in out
+    assert "{repo}" not in out
+
+
+def test_detect_builder_by_extension(tmp_path):
+    (tmp_path / "a.csv").write_text("x\n1\n")
+    assert _detect_builder(tmp_path / "a.csv") == "csv"
+    (tmp_path / "b.png").write_bytes(b"\x89PNG")
+    # directory tally: 1 csv + 1 png -> a tie or csv/imagefolder; just assert it returns a known builder
+    assert _detect_builder(tmp_path) in {"csv", "imagefolder"}