roar-cli 0.3.3__tar.gz → 0.3.5__tar.gz

{roar_cli-0.3.3 → roar_cli-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roar-cli
-Version: 0.3.3
+Version: 0.3.5
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -51,6 +51,14 @@ Project-URL: Repository, https://github.com/treqs/roar
 
 **Run Observation & Artifact Registration**
 
+## Quickstart
+
+```bash
+uv tool install roar-cli      # installs the `roar` command (Python 3.10+)
+roar init                     # set up roar in your project
+roar run <command>            # track a run — then `roar dag` to see it
+```
+
 `roar` tracks data artifacts and execution steps in ML pipelines, enabling reproducibility and lineage queries. `roar` tracking happens automagically by observing your commands as they run, capturing essential context without requiring you to define a pipeline explicitly.
 
 By identifying files based on their actual content rather than their names, it ensures you can always trace a result back to the exact inputs and code that produced it. This gives you reliable reproducibility and a clear history of your artifacts, all derived naturally from your workflow.
@@ -60,12 +68,16 @@ While `roar` captures your work locally, connecting it to a GLaaS (Global Lineag
 ## Installation
 
 ```bash
-pip install roar-cli
-# or with uv
+# Recommended: install the `roar` command in an isolated tool environment
+uv tool install roar-cli
+# or: pipx install roar-cli
+
+# Into an existing environment (e.g. to use roar alongside Ray in the same venv)
 uv pip install roar-cli
+# or: pip install roar-cli
 ```
 
-Requires Python 3.10+.
+Requires Python 3.10+. (A single stable-ABI wheel covers every Python 3.10+.)
 
 > For the full prereqs, platform support matrix, tracer-backend setup,
 > macOS SIP notes, and sdist build steps, see the canonical
@@ -83,44 +95,17 @@ Requires Python 3.10+.
 
 PyPI wheels are published for Linux (`x86_64`, `aarch64`) and macOS (`x86_64`, `arm64`).
 
-If a matching wheel isn't available, `pip install` falls through to the
-source distribution. The sdist ships the Rust tracer source but no
-pre-built binaries, so it requires a C toolchain (`gcc` / `clang`), Rust
-(`rustup`), and a few minutes to compile the tracers on first install.
+On platforms without a published wheel (e.g. musl/Alpine, Windows, or glibc
+older than the manylinux baseline), `pip install` falls through to the
+source distribution, which ships the Rust tracer source but no pre-built
+binaries — so it needs a C toolchain (`gcc` / `clang`), Rust (`rustup`),
+and a few minutes to compile the tracers on first install.
 
 ### Development Installation
 
-```bash
-# Clone the repository
-git clone https://github.com/treqs/roar.git
-cd roar
-
-# One-shot dev install: Python package + Rust tracer binaries
-bash scripts/install-dev.sh
-```
-
-`scripts/install-dev.sh` runs `pip install -e ".[dev]"` (preferring `uv`
-when available) and then builds the Rust tracer binaries
-(`roar-tracer`, `roar-tracer-preload`, `roar-tracer-ebpf`, `roard`,
-`roar-proxy`) and stages them into `roar/bin/`. A bare
-`pip install -e .` does _not_ build the tracer binaries because they
-live in separate cargo crates outside the maturin manifest, so
-`roar run` would fail with "No tracer binary found" until the script
-runs. See [Building from source](#building-from-source) below for
-details and the manual flow.
-
-## Quick Start
-
-```bash
-# Initialize roar in your project
-cd my-ml-project
-roar init
-
-# Run commands with provenance tracking
-roar run python preprocess.py --input data.csv --output features.parquet
-roar run python train.py --data features.parquet --output model.pt
-roar run python evaluate.py --model model.pt --output metrics.json
-```
+Installing from source (editable Python package + Rust tracer binaries) is
+covered under [Development → Building from source](#building-from-source).
+The fast path is `bash scripts/install-dev.sh`.
 
 ## Product Telemetry
 
@@ -162,8 +147,8 @@ roar config set telemetry.enabled false
 Environment opt-outs always win over saved config:
 
 ```bash
-DO_NOT_TRACK=1 roar run python train.py
-ROAR_NO_TELEMETRY=1 roar run python train.py
+DO_NOT_TRACK=1 roar run python3 train.py
+ROAR_NO_TELEMETRY=1 roar run python3 train.py
 ```
 
 Telemetry is also suppressed automatically in CI, pytest, and Roar-managed
@@ -258,7 +243,7 @@ Run a command with provenance tracking. Roar captures:
 - Command arguments
 
 ```bash
-roar run python train.py --epochs 10 --lr 0.001
+roar run python3 train.py --epochs 10 --lr 0.001
 roar run ./scripts/preprocess.sh
 roar run torchrun --nproc_per_node=4 train.py
 
@@ -611,9 +596,9 @@ Named groups of artifacts, used for downloaded datasets or upload bundles.
 
 ```bash
 # Record your pipeline
-roar run python preprocess.py
-roar run python train.py --epochs 10
-roar run python evaluate.py
+roar run python3 preprocess.py
+roar run python3 train.py --epochs 10
+roar run python3 evaluate.py
 
 # Later, reproduce an artifact
 roar reproduce <model-hash> --run
@@ -639,40 +624,21 @@ Add `.roar/` to your `.gitignore` (roar offers to do this during `roar init`).
 
 ## GLaaS Server
 
-Roar can register sessions, jobs, steps, and artifacts with a GLaaS (Global Lineage-as-a-Service) server using the `roar register` command.
-
-### Server Setup
-
-```bash
-# Install with server dependencies
-uv pip install -e ".[server]"
-# or without uv
-pip install -e ".[server]"
-
-# Run the server
-glaas-server
-
-# Or with custom host/port
-GLAAS_HOST=0.0.0.0 GLAAS_PORT=8080 glaas-server
-```
-
-The server provides:
-
-- REST API for artifact and job registration
-- Web UI at `/` with artifact and job browsers
-- Search and filtering by command, GPU, file type, etc.
-
-### Client Configuration
+GLaaS (Global Lineage-as-a-Service) is the shared registry roar publishes to
+with `roar register` and `roar put`. It's hosted at
+[glaas.ai](https://glaas.ai) (default API endpoint `https://api.glaas.ai`),
+so there's nothing to run yourself — sign in and publish.
 
 ```bash
-# Set the GLaaS server URL
-roar config set glaas.url http://localhost:8000
+# Sign in (browser/device flow) for attributed, private, or project publishing
+roar login
 
-# Show your SSH key (copy to GLaaS web UI)
-roar auth register
+# Or register an SSH key for programmatic auth
+roar auth register      # show your public key to paste at glaas.ai
+roar auth test          # verify the connection
 
-# Test authentication
-roar auth test
+# Point roar at a different GLaaS deployment if needed
+roar config set glaas.url https://api.glaas.ai
 ```
 
 > [!TIP]
@@ -751,13 +717,13 @@ Verify the install with `roar tracer`; every backend listed should be
 ruff check .
 
 # Format check
-ruff format --check
+ruff format --check .
 
 # Type checking
 mypy roar
 
 # Run all checks at once
-ruff check . && ruff format --check && mypy roar
+ruff check . && ruff format --check . && mypy roar
 ```
 
 ### Running Tests

{roar_cli-0.3.3 → roar_cli-0.3.5}/README.md

@@ -2,6 +2,14 @@
 
 **Run Observation & Artifact Registration**
 
+## Quickstart
+
+```bash
+uv tool install roar-cli      # installs the `roar` command (Python 3.10+)
+roar init                     # set up roar in your project
+roar run <command>            # track a run — then `roar dag` to see it
+```
+
 `roar` tracks data artifacts and execution steps in ML pipelines, enabling reproducibility and lineage queries. `roar` tracking happens automagically by observing your commands as they run, capturing essential context without requiring you to define a pipeline explicitly.
 
 By identifying files based on their actual content rather than their names, it ensures you can always trace a result back to the exact inputs and code that produced it. This gives you reliable reproducibility and a clear history of your artifacts, all derived naturally from your workflow.
@@ -11,12 +19,16 @@ While `roar` captures your work locally, connecting it to a GLaaS (Global Lineag
 ## Installation
 
 ```bash
-pip install roar-cli
-# or with uv
+# Recommended: install the `roar` command in an isolated tool environment
+uv tool install roar-cli
+# or: pipx install roar-cli
+
+# Into an existing environment (e.g. to use roar alongside Ray in the same venv)
 uv pip install roar-cli
+# or: pip install roar-cli
 ```
 
-Requires Python 3.10+.
+Requires Python 3.10+. (A single stable-ABI wheel covers every Python 3.10+.)
 
 > For the full prereqs, platform support matrix, tracer-backend setup,
 > macOS SIP notes, and sdist build steps, see the canonical
@@ -34,44 +46,17 @@ Requires Python 3.10+.
 
 PyPI wheels are published for Linux (`x86_64`, `aarch64`) and macOS (`x86_64`, `arm64`).
 
-If a matching wheel isn't available, `pip install` falls through to the
-source distribution. The sdist ships the Rust tracer source but no
-pre-built binaries, so it requires a C toolchain (`gcc` / `clang`), Rust
-(`rustup`), and a few minutes to compile the tracers on first install.
+On platforms without a published wheel (e.g. musl/Alpine, Windows, or glibc
+older than the manylinux baseline), `pip install` falls through to the
+source distribution, which ships the Rust tracer source but no pre-built
+binaries — so it needs a C toolchain (`gcc` / `clang`), Rust (`rustup`),
+and a few minutes to compile the tracers on first install.
 
 ### Development Installation
 
-```bash
-# Clone the repository
-git clone https://github.com/treqs/roar.git
-cd roar
-
-# One-shot dev install: Python package + Rust tracer binaries
-bash scripts/install-dev.sh
-```
-
-`scripts/install-dev.sh` runs `pip install -e ".[dev]"` (preferring `uv`
-when available) and then builds the Rust tracer binaries
-(`roar-tracer`, `roar-tracer-preload`, `roar-tracer-ebpf`, `roard`,
-`roar-proxy`) and stages them into `roar/bin/`. A bare
-`pip install -e .` does _not_ build the tracer binaries because they
-live in separate cargo crates outside the maturin manifest, so
-`roar run` would fail with "No tracer binary found" until the script
-runs. See [Building from source](#building-from-source) below for
-details and the manual flow.
-
-## Quick Start
-
-```bash
-# Initialize roar in your project
-cd my-ml-project
-roar init
-
-# Run commands with provenance tracking
-roar run python preprocess.py --input data.csv --output features.parquet
-roar run python train.py --data features.parquet --output model.pt
-roar run python evaluate.py --model model.pt --output metrics.json
-```
+Installing from source (editable Python package + Rust tracer binaries) is
+covered under [Development → Building from source](#building-from-source).
+The fast path is `bash scripts/install-dev.sh`.
 
 ## Product Telemetry
 
@@ -113,8 +98,8 @@ roar config set telemetry.enabled false
 Environment opt-outs always win over saved config:
 
 ```bash
-DO_NOT_TRACK=1 roar run python train.py
-ROAR_NO_TELEMETRY=1 roar run python train.py
+DO_NOT_TRACK=1 roar run python3 train.py
+ROAR_NO_TELEMETRY=1 roar run python3 train.py
 ```
 
 Telemetry is also suppressed automatically in CI, pytest, and Roar-managed
@@ -209,7 +194,7 @@ Run a command with provenance tracking. Roar captures:
 - Command arguments
 
 ```bash
-roar run python train.py --epochs 10 --lr 0.001
+roar run python3 train.py --epochs 10 --lr 0.001
 roar run ./scripts/preprocess.sh
 roar run torchrun --nproc_per_node=4 train.py
 
@@ -562,9 +547,9 @@ Named groups of artifacts, used for downloaded datasets or upload bundles.
 
 ```bash
 # Record your pipeline
-roar run python preprocess.py
-roar run python train.py --epochs 10
-roar run python evaluate.py
+roar run python3 preprocess.py
+roar run python3 train.py --epochs 10
+roar run python3 evaluate.py
 
 # Later, reproduce an artifact
 roar reproduce <model-hash> --run
@@ -590,40 +575,21 @@ Add `.roar/` to your `.gitignore` (roar offers to do this during `roar init`).
 
 ## GLaaS Server
 
-Roar can register sessions, jobs, steps, and artifacts with a GLaaS (Global Lineage-as-a-Service) server using the `roar register` command.
-
-### Server Setup
-
-```bash
-# Install with server dependencies
-uv pip install -e ".[server]"
-# or without uv
-pip install -e ".[server]"
-
-# Run the server
-glaas-server
-
-# Or with custom host/port
-GLAAS_HOST=0.0.0.0 GLAAS_PORT=8080 glaas-server
-```
-
-The server provides:
-
-- REST API for artifact and job registration
-- Web UI at `/` with artifact and job browsers
-- Search and filtering by command, GPU, file type, etc.
-
-### Client Configuration
+GLaaS (Global Lineage-as-a-Service) is the shared registry roar publishes to
+with `roar register` and `roar put`. It's hosted at
+[glaas.ai](https://glaas.ai) (default API endpoint `https://api.glaas.ai`),
+so there's nothing to run yourself — sign in and publish.
 
 ```bash
-# Set the GLaaS server URL
-roar config set glaas.url http://localhost:8000
+# Sign in (browser/device flow) for attributed, private, or project publishing
+roar login
 
-# Show your SSH key (copy to GLaaS web UI)
-roar auth register
+# Or register an SSH key for programmatic auth
+roar auth register      # show your public key to paste at glaas.ai
+roar auth test          # verify the connection
 
-# Test authentication
-roar auth test
+# Point roar at a different GLaaS deployment if needed
+roar config set glaas.url https://api.glaas.ai
 ```
 
 > [!TIP]
@@ -702,13 +668,13 @@ Verify the install with `roar tracer`; every backend listed should be
 ruff check .
 
 # Format check
-ruff format --check
+ruff format --check .
 
 # Type checking
 mypy roar
 
 # Run all checks at once
-ruff check . && ruff format --check && mypy roar
+ruff check . && ruff format --check . && mypy roar
 ```
 
 ### Running Tests

{roar_cli-0.3.3 → roar_cli-0.3.5}/pyproject.toml

@@ -1,10 +1,11 @@
+
 [build-system]
 requires = ["maturin>=1.11.5,<2.0"]
 build-backend = "maturin"
 
 [project]
 name = "roar-cli"
-version = "0.3.3"
+version = "0.3.5"
 description = "Reproducibility and provenance tracker for ML training pipelines"
 authors = [
     { name="TReqs Team", email="info@treqs.ai" }

roar_cli-0.3.5/roar/application/composite/__init__.py

@@ -0,0 +1,37 @@
+"""Composite artifacts v2 — qualifying hash + structural detection.
+
+The host-agnostic ``sha256-tree`` qualifying hash (the dataset GLaaS key) and the
+declared/structural detectors that decide what a composite is and which files carry
+its identity. Composites form at the boundaries (``get``/``put``/``register``), not
+inside ``roar run``.
+
+This package is additive; it does not yet replace the legacy heuristic composite
+path in ``roar.application.publish``.
+"""
+
+from .canonical import normalize_relpath, preimage
+from .detect import Detection, detect, detect_nested
+from .qualifying import (
+    Composite,
+    Leaf,
+    blake3_tree,
+    build,
+    build_nested,
+    sha256_tree,
+    tree,
+)
+
+__all__ = [
+    "Composite",
+    "Detection",
+    "Leaf",
+    "blake3_tree",
+    "build",
+    "build_nested",
+    "detect",
+    "detect_nested",
+    "normalize_relpath",
+    "preimage",
+    "sha256_tree",
+    "tree",
+]

roar_cli-0.3.5/roar/application/composite/canonical.py

@@ -0,0 +1,71 @@
+"""Canonical preimage for the qualifying composite hash (``sha256-tree``).
+
+The qualifying hash is roar's host-agnostic, content-addressable dataset key: a
+``sha256`` over a canonical, injective serialization of a composite's leaves. It is
+path-sensitive (moving a file changes the key), content-only (no host metadata
+enters), and locally computable, so the key registered by ``roar put`` equals the
+key produced by ``roar get`` for the same bytes and layout.
+
+This is distinct from roar's internal ``blake3`` file hashing: blake3 stays the
+fast hash for primitive file lineage; ``sha256-tree`` is the *dataset* key.
+
+Frozen decisions (any change is a version bump of the domain tag):
+  - leaf = (normalized_posix_relpath, "<component-algo>:<hexdigest>")
+  - component-algo is always ``sha256`` for a qualifying leaf; nested composites
+    use ``sha256-tree``
+  - leaves are sorted by the UTF-8 bytes of their normalized relpath
+  - size and mode do not enter the preimage
+  - NUL separates path from digest; newline terminates each leaf line
+  - a domain-separation prefix prevents cross-protocol collisions
+"""
+
+from __future__ import annotations
+
+DOMAIN_V1 = b"roar:sha256-tree:v1\n"
+QUALIFYING_ALGO = "sha256"
+NESTED_ALGO = "sha256-tree"
+
+
+def normalize_relpath(path: str) -> str:
+    """Normalize a relative path to canonical POSIX form.
+
+    Backslashes become forward slashes, a leading ``./`` and leading slashes are
+    stripped. ``..`` components are rejected (a leaf must stay within its composite
+    root) and an empty result is an error.
+    """
+    p = path.replace("\\", "/")
+    while p.startswith("./"):
+        p = p[2:]
+    p = p.lstrip("/")
+    if not p:
+        raise ValueError("empty relative path is not a valid leaf key")
+    if any(segment == ".." for segment in p.split("/")):
+        raise ValueError(f"path escapes composite root: {path!r}")
+    return p
+
+
+def leaf_line(relpath: str, algo: str, hexdigest: str) -> bytes:
+    """Serialize one leaf to its canonical line (relpath already normalized)."""
+    if not hexdigest:
+        raise ValueError(f"leaf {relpath!r} has empty digest")
+    return relpath.encode("utf-8") + b"\x00" + f"{algo}:{hexdigest.lower()}".encode() + b"\n"
+
+
+def preimage(leaves: list[tuple[str, str, str]], *, domain: bytes = DOMAIN_V1) -> bytes:
+    """Build the canonical preimage from ``(relpath, algo, hexdigest)`` triples.
+
+    Relpaths are normalized and the set is sorted by normalized relpath bytes.
+    Duplicate normalized relpaths are rejected.
+    """
+    normalized: dict[str, tuple[str, str]] = {}
+    for relpath, algo, hexdigest in leaves:
+        key = normalize_relpath(relpath)
+        if key in normalized:
+            raise ValueError(f"duplicate leaf path in composite: {key!r}")
+        normalized[key] = (algo, hexdigest)
+
+    out = bytearray(domain)
+    for key in sorted(normalized, key=lambda k: k.encode("utf-8")):
+        algo, hexdigest = normalized[key]
+        out += leaf_line(key, algo, hexdigest)
+    return bytes(out)

roar_cli-0.3.5/roar/application/composite/detect.py

@@ -0,0 +1,120 @@
+"""Structural dataset detection — declared/structural, never scored.
+
+Each detector is a pure function of a file listing (relpaths) and returns a
+:class:`Detection` naming the structural ``kind``, which files are identity-bearing
+(``data``/``meta``) versus excluded ``boilerplate``, and any nested sub-datasets.
+
+This replaces the role of the confidence scorer: a format's on-disk structure
+either declares it or it does not. There are no thresholds or weights. When nothing
+matches, ``kind`` is ``"unstructured"`` and the caller decides (an explicit
+``roar put --dataset`` may still declare it; an unstructured pile falls to the
+download size-gate when imported from a host).
+"""
+
+from __future__ import annotations
+
+import posixpath
+from dataclasses import dataclass
+
+# Repo/git boilerplate present everywhere — never data, never identity-bearing.
+#
+# IDENTITY CONTRACT: this set is excluded from every composite digest (both the get
+# sha256-tree and the put/register blake3-tree paths derive their exclusions from
+# `detect().boilerplate`). It is therefore part of the `roar:{combiner}-tree:v1` digest
+# domain: changing a member silently re-digests existing datasets and breaks the
+# put-export <-> get-import identity guarantee. Any edit here MUST bump the tree domain
+# version (v1 -> v2) in `canonical.py` and `composite_builder.py`.
+BOILERPLATE = frozenset({".gitattributes", ".gitignore", "README.md", "LICENSE", ".DS_Store"})
+
+
+@dataclass(frozen=True)
+class Detection:
+    kind: str
+    data: list[str]  # identity-bearing data files
+    meta: list[str]  # identity-bearing, format-declared metadata
+    boilerplate: list[str]  # excluded
+    nested: list[str]  # subdir prefixes that are themselves structural datasets
+
+
+def _split_boilerplate(paths: list[str]) -> tuple[list[str], list[str]]:
+    boiler = [p for p in paths if posixpath.basename(p) in BOILERPLATE]
+    rest = [p for p in paths if posixpath.basename(p) not in BOILERPLATE]
+    return rest, boiler
+
+
+def _has(paths: set[str], name: str) -> bool:
+    return any(p == name or p.endswith("/" + name) for p in paths)
+
+
+def detect(paths: list[str]) -> Detection:
+    """Detect the structural kind of a flat list of relpaths (one composite root)."""
+    rest, boiler = _split_boilerplate(paths)
+    pset = set(rest)
+
+    # --- LeRobot v2.x/v3.x: meta/info.json + data/chunk-*/*.parquet ---
+    if _has(pset, "meta/info.json") and any(p.startswith("data/chunk-") for p in rest):
+        meta = sorted(p for p in rest if p.startswith("meta/"))
+        data = sorted(p for p in rest if p.startswith("data/") or p.startswith("videos/"))
+        other = sorted(set(rest) - set(meta) - set(data))
+        return Detection("lerobot", data, meta, boiler + other, [])
+
+    # --- Zarr store: v2 (.zarray/.zgroup) or v3 (zarr.json) ---
+    if any(posixpath.basename(p) in (".zarray", ".zgroup", "zarr.json") for p in rest):
+        return Detection("zarr", sorted(rest), [], boiler, [])
+
+    # --- Lance dataset: <name>.lance/ with _versions/ + data/ ---
+    if any(p.endswith(".lance") or ".lance/" in ("/" + p) for p in rest) or _has(pset, "_versions"):
+        return Detection("lance", sorted(rest), [], boiler, [])
+
+    # --- TFDS / RLDS: dataset_info.json + features.json (+ *.tfrecord-*) ---
+    if _has(pset, "dataset_info.json") and _has(pset, "features.json"):
+        meta = sorted(
+            p for p in rest if posixpath.basename(p) in ("dataset_info.json", "features.json")
+        )
+        data = sorted(set(rest) - set(meta))
+        return Detection("rlds", data, meta, boiler, [])
+
+    # --- WebDataset: a set of .tar shards ---
+    tars = [p for p in rest if p.endswith(".tar")]
+    if len(tars) >= 2 and len(tars) == len(rest):
+        return Detection("webdataset", sorted(tars), [], boiler, [])
+
+    # --- Flat parquet shards (climbmix / esm2 style) ---
+    parquets = [p for p in rest if p.endswith(".parquet")]
+    if len(parquets) >= 2:
+        excluded = boiler + sorted(set(rest) - set(parquets))
+        return Detection("parquet-shards", sorted(parquets), [], excluded, [])
+
+    return Detection("unstructured", sorted(rest), [], boiler, [])
+
+
+# Formats that declare themselves with a manifest/layout file are nestable as
+# sub-datasets. Loose-shard formats (parquet-shards, webdataset) are deliberately
+# excluded: a directory of partition dirs full of parquet shards (Hive-style
+# ``date=.../part-*.parquet``) is ONE partitioned dataset, not nested sub-datasets,
+# and is indistinguishable from a true container without a per-child manifest.
+_NESTABLE_KINDS = frozenset({"lerobot", "zarr", "lance", "rlds"})
+
+
+def detect_nested(paths: list[str]) -> Detection:
+    """Detect a *container* of sub-datasets (the nesting case).
+
+    Groups paths by top-level directory; if at least two top dirs each independently
+    detect as a *manifest-bearing* structural dataset, returns kind ``"nested"`` with
+    those dirs as nested composites. Otherwise falls back to flat :func:`detect` —
+    so partitioned single datasets and loose-shard splits stay one flat composite.
+    """
+    rest, boiler = _split_boilerplate(paths)
+    by_top: dict[str, list[str]] = {}
+    for p in rest:
+        if "/" in p:
+            top, sub = p.split("/", 1)
+            by_top.setdefault(top, []).append(sub)
+
+    structural_children = [
+        top for top, subs in by_top.items() if detect(subs).kind in _NESTABLE_KINDS
+    ]
+
+    if len(structural_children) >= 2:
+        return Detection("nested", [], [], boiler, sorted(structural_children))
+    return detect(paths)