runledger-cli 0.1.2__tar.gz → 0.1.4__tar.gz

runledger_cli-0.1.4/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: runledger-cli
+Version: 0.1.4
+Summary: Zero‑instrumentation experiment registry CLI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Requires-Dist: rich
+
+Here’s the updated README with the troubleshooting note added right after the installation instructions. The primary command remains `runledger`, but users who hit the Windows PATH issue now have a clear fallback.
+
+---
+
+# RunLedger
+
+**A zero-instrumentation experiment registry.** Point RunLedger at a folder of JSON experiment files and search, filter, aggregate, diff, and export the results; no SDK, no code changes, no cloud.
+
+Most experiment trackers make you instrument your training code before they can help you. RunLedger reads the JSON you're already writing, no `wandb.init()`, no `mlflow.log_metric()`, and indexes it in real Postgres, giving you full relational search: structured comparisons, full-text, fuzzy matching, and exact array-element lookups, from one CLI command.
+
+Backed by Postgres, served by a Spring Boot API, and fronted by a Python CLI.
+
+## Install
+
+```bash
+pip install runledger-cli
+```
+
+Requires Docker. If it's not installed, `runledger` detects that on first run and links you straight to the installer; everything else (Postgres, the backend) is managed for you.
+
+### Troubleshooting: `runledger` command not found (Windows)
+
+On some Windows systems, the Python Scripts folder is not automatically added to your PATH. If `runledger` is not recognized after installation, you have two options:
+
+1. **Add the Scripts folder to your PATH permanently** (recommended):
+    - Find where `runledger` was installed: `pip show runledger-cli | findstr Location`
+    - Navigate to that folder, then up one level to the `Scripts` directory.
+    - Add that `Scripts` path to your system PATH via **System Properties > Environment Variables**.
+    - Restart your terminal.
+
+2. **Use the Python module fallback** (works immediately, no PATH changes):
+   ```bash
+   python -m cli.ledger
+   ```
+   All subcommands and the guided wizard work exactly the same way; just prefix every command with `python -m cli.ledger`.
+
+Once the PATH is configured, `runledger` will work as shown in the examples below.
+
+<details>
+<summary>Installing from source</summary>
+
+```bash
+git clone https://github.com/yourusername/run-ledger.git
+cd run-ledger
+docker compose up -d
+pip install -e .
+```
+</details>
+
+## Quick start
+
+```bash
+runledger scan ~/experiments --batch my-sweep
+runledger search --metric accuracy --op gt --value 0.9 --batch my-sweep
+runledger aggregate --metric accuracy --agg AVG --group-by experiment --batch my-sweep
+```
+
+New here? Run `runledger` with no arguments — the guided wizard walks you through your first scan and search.
+
+## What you get
+
+- **Search any field, no schema required** — structured comparisons (`gt`, `lt`, `eq`...), full-text with stemming, and fuzzy matching for typos, all on arbitrary dot-paths, including fields nested inside arrays (`results[].sst2_cacc`).
+- **Compound AND/OR** across multiple conditions in one query.
+- **Exact match pointers** — array searches tell you exactly which element(s) matched (`results[3].sst2_cacc = 0.933`), not just that the run did.
+- **Aggregates & group-by** — `AVG` / `MAX` / `MIN` / `SUM` / `COUNT`, straight from the CLI.
+- **Safe re-scanning** — ingestion is idempotent; a changed file gets a new version, and `diff --history` shows you what changed and when.
+- **Run diff, saved searches, JSONL ingestion, block-depth control** — see [docs/examples.md](docs/examples.md) for each in action.
+- **Self-hosted, local-first** — your data never leaves your machine.
+
+## Metric paths
+
+Address any value with a dot-path — `accuracy`, `metrics.loss`, `results[].sst2_cacc`. Shorthand (`cacc`) resolves automatically when it's unambiguous. Run `runledger metrics --batch <batch>` to see everything discovered in a scan, or add `--verbose` for full paths.
+
+## Docs
+
+- [API reference](docs/api.md)
+- [Usage examples](docs/examples.md)
+
+## License
+
+MIT

runledger_cli-0.1.4/README.md

@@ -0,0 +1,81 @@
+Here’s the updated README with the troubleshooting note added right after the installation instructions. The primary command remains `runledger`, but users who hit the Windows PATH issue now have a clear fallback.
+
+---
+
+# RunLedger
+
+**A zero-instrumentation experiment registry.** Point RunLedger at a folder of JSON experiment files and search, filter, aggregate, diff, and export the results; no SDK, no code changes, no cloud.
+
+Most experiment trackers make you instrument your training code before they can help you. RunLedger reads the JSON you're already writing, no `wandb.init()`, no `mlflow.log_metric()`, and indexes it in real Postgres, giving you full relational search: structured comparisons, full-text, fuzzy matching, and exact array-element lookups, from one CLI command.
+
+Backed by Postgres, served by a Spring Boot API, and fronted by a Python CLI.
+
+## Install
+
+```bash
+pip install runledger-cli
+```
+
+Requires Docker. If it's not installed, `runledger` detects that on first run and links you straight to the installer; everything else (Postgres, the backend) is managed for you.
+
+### Troubleshooting: `runledger` command not found (Windows)
+
+On some Windows systems, the Python Scripts folder is not automatically added to your PATH. If `runledger` is not recognized after installation, you have two options:
+
+1. **Add the Scripts folder to your PATH permanently** (recommended):
+    - Find where `runledger` was installed: `pip show runledger-cli | findstr Location`
+    - Navigate to that folder, then up one level to the `Scripts` directory.
+    - Add that `Scripts` path to your system PATH via **System Properties > Environment Variables**.
+    - Restart your terminal.
+
+2. **Use the Python module fallback** (works immediately, no PATH changes):
+   ```bash
+   python -m cli.ledger
+   ```
+   All subcommands and the guided wizard work exactly the same way; just prefix every command with `python -m cli.ledger`.
+
+Once the PATH is configured, `runledger` will work as shown in the examples below.
+
+<details>
+<summary>Installing from source</summary>
+
+```bash
+git clone https://github.com/yourusername/run-ledger.git
+cd run-ledger
+docker compose up -d
+pip install -e .
+```
+</details>
+
+## Quick start
+
+```bash
+runledger scan ~/experiments --batch my-sweep
+runledger search --metric accuracy --op gt --value 0.9 --batch my-sweep
+runledger aggregate --metric accuracy --agg AVG --group-by experiment --batch my-sweep
+```
+
+New here? Run `runledger` with no arguments — the guided wizard walks you through your first scan and search.
+
+## What you get
+
+- **Search any field, no schema required** — structured comparisons (`gt`, `lt`, `eq`...), full-text with stemming, and fuzzy matching for typos, all on arbitrary dot-paths, including fields nested inside arrays (`results[].sst2_cacc`).
+- **Compound AND/OR** across multiple conditions in one query.
+- **Exact match pointers** — array searches tell you exactly which element(s) matched (`results[3].sst2_cacc = 0.933`), not just that the run did.
+- **Aggregates & group-by** — `AVG` / `MAX` / `MIN` / `SUM` / `COUNT`, straight from the CLI.
+- **Safe re-scanning** — ingestion is idempotent; a changed file gets a new version, and `diff --history` shows you what changed and when.
+- **Run diff, saved searches, JSONL ingestion, block-depth control** — see [docs/examples.md](docs/examples.md) for each in action.
+- **Self-hosted, local-first** — your data never leaves your machine.
+
+## Metric paths
+
+Address any value with a dot-path — `accuracy`, `metrics.loss`, `results[].sst2_cacc`. Shorthand (`cacc`) resolves automatically when it's unambiguous. Run `runledger metrics --batch <batch>` to see everything discovered in a scan, or add `--verbose` for full paths.
+
+## Docs
+
+- [API reference](docs/api.md)
+- [Usage examples](docs/examples.md)
+
+## License
+
+MIT

{runledger_cli-0.1.2 → runledger_cli-0.1.4}/cli/guided.py

@@ -112,6 +112,14 @@ def fetch_verbose_metrics(batch):
         return resp.json()
     return []
 
+def build_shorthand_map(batch):
+    """Return dict {shorthand_key: [full_path, ...]} from verbose metrics."""
+    entries = fetch_verbose_metrics(batch)
+    mapping = {}
+    for e in entries:
+        mapping.setdefault(e['key'], []).append(e['path'])
+    return mapping
+
 def perform_search(metric=None, op=None, value=None, q=None, fuzzy=False, batch=None, pointers=True, block=None):
     params = {"page": 0, "size": 50, "sort": "created_at,desc"}
     if batch:
@@ -179,12 +187,18 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
         console.print()
 
     if dot_path is None:
-        try:
-            pretty = json.dumps(payload, indent=2)
-        except Exception:
-            pretty = str(payload)
-        console.print(Panel(pretty, title=f"Run {run['id']} · {source_file}"))
-        return
+        # If we have matched pointers, derive a path from the first concrete pointer
+        if matched:
+            concrete = matched[0]['pointer']
+            parts = concrete.replace('[', '.').replace(']', '').split('.')
+            dot_path = '.'.join(parts)
+        else:
+            try:
+                pretty = json.dumps(payload, indent=2)
+            except Exception:
+                pretty = str(payload)
+            console.print(Panel(pretty, title=f"Run {run['id']} · {source_file}"))
+            return
 
     parts = [seg.replace("[]", "") for seg in dot_path.split(".")]
     max_block = len(parts) - 1
@@ -207,9 +221,17 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
                 title = f"Run {run['id']} · {source_file}  |  metric: {dot_path}  |  depth: 0 (match {i+1}/{len(matched)})"
                 console.print(Panel(pretty, title=title))
         else:
-            ancestor_parts = parts[:len(parts) - (block + 1)]
-            pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
-            node = navigate_json_pointer(payload, pointer) if pointer else payload
+            if block > 0 and matched:
+                concrete = matched[0]['pointer']
+                segments = concrete.replace('[', '.').replace(']', '').split('.')
+                ancestor_segments = segments[:len(segments) - (block + 1)]
+                pointer = "/" + "/".join(ancestor_segments) if ancestor_segments else ""
+                node = navigate_json_pointer(payload, pointer) if pointer else payload
+            else:
+                ancestor_parts = parts[:len(parts) - (block + 1)]
+                pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
+                node = navigate_json_pointer(payload, pointer) if pointer else payload
+
             depth_label = ""
             if block == max_block:
                 depth_label = " (full run)"
@@ -243,15 +265,14 @@ def run_guided_search():
                          "Answer a few questions and we'll find your best experiments.",
                          title="Welcome"))
 
-    # ── Step 1: Folder & Batch ──
-    console.print("\n[bold][Step 1/5] Select your experiment folder[/bold]")
-    folder = Prompt.ask("Folder path (drag‑and‑drop or type)",
-                        default="")
-    batch  = Prompt.ask("Batch name (optional, default: folder name)", default="")
+    # 1. Folder
+    folder = Prompt.ask("[bold]Folder containing your JSON/JSONL files[/bold]\n"
+                        "(drag‑and‑drop or type a path)")
+    batch  = Prompt.ask("[bold]Batch name (optional, default: folder name)[/bold]", default="")
     if not batch:
         batch = Path(folder).name
 
-    # ── Step 2: Scan if needed ──
+    # 2. Scan if needed
     console.print(f"\n[bold][Step 2/5] Ingest data from '{batch}'[/bold]")
     metrics = fetch_verbose_metrics(batch)
     if metrics:
@@ -267,6 +288,9 @@ def run_guided_search():
             console.print("[red]Metric discovery failed. Exiting.[/red]")
             return
 
+    # Build shorthand -> full paths map
+    shorthand_map = build_shorthand_map(batch)
+
     # Show schema summary table
     table = Table(title="Available Metrics")
     table.add_column("#", justify="right")
@@ -276,14 +300,14 @@ def run_guided_search():
         table.add_row(str(i), m["key"], m["path"])
     console.print(table)
 
-    # ── Step 3: Build conditions ──
+    # 3. Build one or more conditions
     console.print(f"\n[bold][Step 3/5] Define your search conditions[/bold]")
     filters = []
     combine = "and"
     first_condition = True
 
     while True:
-        # Metric selection (filter‑as‑you‑type)
+        # Metric selection (filter‑as‑you‑type with explicit path and sub‑list support)
         metric_names = [m["key"] for m in metrics]
         selected_metric = None
         filtered = metric_names[:]
@@ -304,6 +328,32 @@ def run_guided_search():
             console.print(ftable)
 
             query = Prompt.ask("Type to filter metrics (or 'all' to reset, number to select)", default="")
+
+            # Explicit dot‑path / array‑path – accept directly
+            if '.' in query or '[]' in query:
+                selected_metric = query
+                break
+
+            # Shorthand with multiple possible full paths – show sub‑list
+            if query in shorthand_map:
+                paths = shorthand_map[query]
+                if len(paths) == 1:
+                    selected_metric = paths[0]
+                    break
+                else:
+                    sub_table = Table(title=f"Select full path for '{query}'")
+                    sub_table.add_column("#", justify="right")
+                    sub_table.add_column("Full Path", style="cyan")
+                    for i, p in enumerate(paths, 1):
+                        sub_table.add_row(str(i), p)
+                    console.print(sub_table)
+                    sub_choice = Prompt.ask("Choose a path", default="1")
+                    if sub_choice.isdigit():
+                        idx = int(sub_choice) - 1
+                        if 0 <= idx < len(paths):
+                            selected_metric = paths[idx]
+                            break
+
             if query.lower() == "all":
                 filtered = metric_names[:]
                 continue
@@ -335,24 +385,24 @@ def run_guided_search():
         conds = " [bold yellow]" + f" {combine.upper()} ".join(f"{f['metric']} {f['op']} {f['value']}" for f in filters) + "[/bold yellow]"
         console.print(f"\n[bold]Current filter(s):[/bold]{conds}")
 
-        if first_condition and len(metric_names) > 1:
-            another = Confirm.ask("Add another condition?", default=False)
-            if not another:
-                break
-            if len(filters) >= 2:
-                combine = Prompt.ask("Combine with", choices=["and", "or"], default="and")
-        else:
+        # Ask for another condition
+        another = Confirm.ask("Add another condition?", default=False)
+        if not another:
             break
+
+        # If this is about to be the second condition, ask for combine operator BEFORE adding it
+        if len(filters) == 1:
+            combine = Prompt.ask("Combine with", choices=["and", "or"], default="and")
         first_condition = False
 
-    # ── Step 4: Block depth ──
+    # Block depth
     console.print(f"\n[bold][Step 4/5] Choose output detail[/bold]")
     block = None
     if Confirm.ask("Limit output to a specific block depth? (block‑0 = tightest match)", default=False):
         block = Prompt.ask("Block depth", default="0")
         block = int(block)
 
-    # ── Step 5: Search & Results ──
+    # 5. Run search
     console.print(f"\n[bold][Step 5/5] Searching...[/bold]")
     if len(filters) == 1:
         f = filters[0]
@@ -366,7 +416,7 @@ def run_guided_search():
         for run in data["content"]:
             show_blocks(run, filters[0]["metric"] if len(filters) == 1 else None, [block] if block is not None else None)
 
-    # ── Post‑search menu ──
+    # Post‑search menu
     while True:
         console.print("\n[bold]What would you like to do next?[/bold]")
         console.print("  [1] Save this search")
@@ -385,23 +435,20 @@ def run_guided_search():
             if save_search(name, batch, params):
                 console.print(f"[green]Saved search '{name}'.[/green]")
         elif choice == "2":
-            # Simple text export to a file
             out_file = Prompt.ask("Output file path", default="runledger_export.txt")
             if data and data.get("content"):
-                from ledgger import build_export_blocks, format_blocks_as_text
+                from ledger import build_export_blocks, format_blocks_as_text
                 blocks = build_export_blocks(data["content"], filters[0]["metric"] if len(filters) == 1 else None, [block] if block is not None else None, include_pointers=True)
                 Path(out_file).write_text(format_blocks_as_text(blocks), encoding="utf-8")
                 console.print(f"[green]Exported {len(blocks)} block(s) to {out_file}[/green]")
             else:
                 console.print("[yellow]No data to export.[/yellow]")
         elif choice == "3":
-            # Restart the guided flow
             run_guided_search()
             return
         elif choice == "4":
             id1 = Prompt.ask("First Run ID")
             id2 = Prompt.ask("Second Run ID")
-            # Quick diff using the API
             resp1 = requests.get(f"{API_BASE}/{id1}")
             resp2 = requests.get(f"{API_BASE}/{id2}")
             if resp1.status_code == 200 and resp2.status_code == 200:

{runledger_cli-0.1.2 → runledger_cli-0.1.4}/cli/ledger.py

@@ -47,9 +47,10 @@ except Exception:
 # ------------------------------------------------------------
 # Configuration
 # ------------------------------------------------------------
-API_BASE = "http://localhost:8080/api/runs"
+_BASE = os.environ.get("RUNLEDGER_BASE_URL", "http://localhost:8080")
+API_BASE = f"{_BASE}/api/runs"
+HEALTH_URL = f"{_BASE}/actuator/health"
 COMPOSE_FILE = os.path.join(os.path.dirname(__file__), "docker-compose.yml")
-HEALTH_URL = "http://localhost:8080/actuator/health"
 PAGE_SIZE = 10
 
 console = Console()
@@ -333,11 +334,13 @@ def navigate_json_pointer(doc, pointer: str):
 
 def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
     payload = run.get("payload", {})
+    # Use experiment name, then source file, then run id
     if isinstance(payload, dict):
         source_file = payload.get("_source", {}).get("file") or payload.get("experiment") or f"run-{run['id']}"
     else:
         source_file = f"run-{run['id']}"
 
+    # Show matched pointers if available
     matched = run.get("matched")
     if matched:
         console.print("  Matches:")
@@ -351,14 +354,21 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
         console.print()
 
     if dot_path is None:
-        label = "-- full run (full‑text/fuzzy match)"
-        try:
-            pretty = json.dumps(payload, indent=2)
-        except Exception:
-            pretty = str(payload)
-        console.print(Panel(pretty, title=f"Run {run['id']} · {source_file}"))
-        return
+        # If we have matched pointers, derive a path from the first concrete pointer
+        if matched:
+            concrete = matched[0]['pointer']
+            parts = concrete.replace('[', '.').replace(']', '').split('.')
+            dot_path = '.'.join(parts)
+        else:
+            label = "-- full run (full‑text/fuzzy match)"
+            try:
+                pretty = json.dumps(payload, indent=2)
+            except Exception:
+                pretty = str(payload)
+            console.print(Panel(pretty, title=f"Run {run['id']} · {source_file}"))
+            return
 
+    # Strip "[]" so JSON Pointer navigation works
     parts = [seg.replace("[]", "") for seg in dot_path.split(".")]
     max_block = len(parts) - 1
 
@@ -372,6 +382,7 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
 
     for block in sorted(levels, reverse=True):
         if block == 0 and matched:
+            # For block=0, show each matched snippet individually
             for i, m in enumerate(matched):
                 snippet = m.get("snippet")
                 try:
@@ -381,9 +392,19 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
                 title = f"Run {run['id']} · {source_file}  |  metric: {dot_path}  |  depth: 0 (match {i+1}/{len(matched)})"
                 console.print(Panel(pretty, title=title))
         else:
-            ancestor_parts = parts[:len(parts) - (block + 1)]
-            pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
-            node = navigate_json_pointer(payload, pointer) if pointer else payload
+            if block > 0 and matched:
+                # Use the first match's concrete pointer for precise navigation
+                # Example: "clients[1].sweep[0].fin_asr" → "/clients/1/sweep"
+                concrete = matched[0]['pointer']
+                segments = concrete.replace('[', '.').replace(']', '').split('.')
+                ancestor_segments = segments[:len(segments) - (block + 1)]
+                pointer = "/" + "/".join(ancestor_segments) if ancestor_segments else ""
+                node = navigate_json_pointer(payload, pointer) if pointer else payload
+            else:
+                ancestor_parts = parts[:len(parts) - (block + 1)]
+                pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
+                node = navigate_json_pointer(payload, pointer) if pointer else payload
+
             depth_label = ""
             if block == max_block:
                 depth_label = " (full run)"
@@ -394,7 +415,6 @@ def show_blocks(run: dict, dot_path: str = None, block_levels: list = None):
             except Exception:
                 pretty = str(node)
             console.print(Panel(pretty, title=f"Run {run['id']} · {source_file}  |  metric: {dot_path}  |  depth: {block}{depth_label}"))
-
 # ------------------------------------------------------------
 # Export helpers
 # ------------------------------------------------------------
@@ -444,9 +464,16 @@ def build_export_blocks(content, dot_path, block_levels, include_pointers=True):
                         "value": m.get("value")
                     })
             else:
-                ancestor_parts = parts[:len(parts) - (block + 1)]
-                pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
-                node = navigate_json_pointer(payload, pointer) if pointer else payload
+                if block > 0 and matched:
+                    concrete = matched[0]['pointer']
+                    segments = concrete.replace('[', '.').replace(']', '').split('.')
+                    ancestor_segments = segments[:len(segments) - (block + 1)]
+                    pointer = "/" + "/".join(ancestor_segments) if ancestor_segments else ""
+                    node = navigate_json_pointer(payload, pointer) if pointer else payload
+                else:
+                    ancestor_parts = parts[:len(parts) - (block + 1)]
+                    pointer = "/" + "/".join(ancestor_parts) if ancestor_parts else ""
+                    node = navigate_json_pointer(payload, pointer) if pointer else payload
                 blocks.append({
                     "id": run["id"],
                     "sourceFile": source_file,
@@ -556,6 +583,14 @@ def compute_delta(val1, val2):
 # ------------------------------------------------------------
 # Non‑interactive CLI outputs
 # ------------------------------------------------------------
+def build_shorthand_map(batch):
+    """Return dict {shorthand_key: [full_path, ...]} from verbose metrics."""
+    entries = fetch_verbose_metrics(batch)
+    mapping = {}
+    for e in entries:
+        mapping.setdefault(e['key'], []).append(e['path'])
+    return mapping
+
 def cli_metrics(args):
     if args.verbose:
         entries = fetch_verbose_metrics(args.batch)
@@ -792,6 +827,9 @@ def interactive_search(batch: str = None):
             console.print("[yellow]No metrics available yet. Ingest some runs first.[/yellow]")
             break
 
+        # Build shorthand -> full paths map
+        shorthand_map = build_shorthand_map(batch)
+
         selected_metric = None
         filtered = metrics[:]
         while True:
@@ -811,6 +849,32 @@ def interactive_search(batch: str = None):
             console.print(table)
 
             query = Prompt.ask("Type to filter metrics (or 'all' to reset, number to select)", default="")
+
+            # Explicit dot‑path / array‑path – accept directly
+            if '.' in query or '[]' in query:
+                selected_metric = query
+                break
+
+            # Shorthand with multiple possible full paths – show sub‑list
+            if query in shorthand_map:
+                paths = shorthand_map[query]
+                if len(paths) == 1:
+                    selected_metric = paths[0]
+                    break
+                else:
+                    sub_table = Table(title=f"Select full path for '{query}'")
+                    sub_table.add_column("#", justify="right")
+                    sub_table.add_column("Full Path", style="cyan")
+                    for i, p in enumerate(paths, 1):
+                        sub_table.add_row(str(i), p)
+                    console.print(sub_table)
+                    sub_choice = Prompt.ask("Choose a path", default="1")
+                    if sub_choice.isdigit():
+                        idx = int(sub_choice) - 1
+                        if 0 <= idx < len(paths):
+                            selected_metric = paths[idx]
+                            break
+
             if query.lower() == "all":
                 filtered = metrics[:]
                 continue

{runledger_cli-0.1.2 → runledger_cli-0.1.4}/cli/tests/test_data_features.py

@@ -57,7 +57,7 @@ def setup_data():
     # Ingest sample runs into the fresh batch
     result = run_cli("scan", str(SAMPLE_FOLDER), "--batch", BATCH_NAME)
     assert result.returncode == 0, result.stderr
-    assert "Successfully ingested 9 run(s)" in result.stdout
+    assert "Successfully ingested 10 run(s)" in result.stdout
 
 # ------------------------------------------------------------
 # v1 – Basic metric block search
@@ -251,4 +251,73 @@ def test_jsonl_ingestion(setup_data):
                 assert payload.get(k) == v, f"Mismatch at line {idx}: {k} {v} != {payload.get(k)}"
 
         # Clean up the temporary batch
-        requests.delete(f"{API_BASE}/batch/{batch}")  # if this endpoint exists, otherwise manual cleanup
+        requests.delete(f"{API_BASE}/batch/{batch}")  # if this endpoint exists, otherwise manual cleanup
+
+def test_nested_array_block_depth():
+    """Verify block‑depth on nested arrays using direct API calls."""
+    import uuid
+    import requests
+
+    batch = f"nest-{uuid.uuid4().hex[:6]}"
+
+    # 1. Ingest the nested file directly via the API
+    payload = {
+        "experiment": "nested_arrays_block_test",
+        "clients": [
+            {
+                "client_name": "clean_client",
+                "sweep": [
+                    {"w_base": 0.5, "fin_asr": 0.12, "sst2_asr": 0.07},
+                    {"w_base": 0.75, "fin_asr": 0.09, "sst2_asr": 0.06}
+                ]
+            },
+            {
+                "client_name": "poisoned_client",
+                "sweep": [
+                    {"w_base": 0.5, "fin_asr": 0.45, "sst2_asr": 0.88},
+                    {"w_base": 1.0, "fin_asr": 0.28, "sst2_asr": 0.72}
+                ]
+            }
+        ]
+    }
+    resp = requests.post(API_BASE, json={"payload": payload, "batch": batch})
+    assert resp.status_code == 201, f"ingest failed: {resp.text}"
+
+    # 2. Search for fin_asr < 0.3 with block=0
+    params = {"metric": "clients[].sweep[].fin_asr", "op": "lt", "value": "0.3",
+              "batch": batch, "block": "0", "size": "1", "pointers": "true"}
+    resp = requests.get(API_BASE, params=params)
+    assert resp.status_code == 200, resp.text
+    data = resp.json()
+    assert data["totalElements"] == 1
+    run = data["content"][0]
+
+    # 3. Verify matched pointers exist
+    matched = run.get("matched")
+    assert matched is not None, "matched pointers missing"
+    assert len(matched) == 3, f"expected 3 matches, got {len(matched)}"
+
+    # 4. block=1 should return the sweep array (a list)
+    params["block"] = "1"
+    resp = requests.get(API_BASE, params=params)
+    assert resp.status_code == 200, resp.text
+    data1 = resp.json()
+    block1_payload = data1["content"][0]["payload"]
+    assert isinstance(block1_payload, list), f"block=1 payload should be a list, got {type(block1_payload)}"
+    assert any("fin_asr" in json.dumps(elem) for elem in block1_payload)
+
+    # 5. block=2 should return the client object
+    params["block"] = "2"
+    resp = requests.get(API_BASE, params=params)
+    assert resp.status_code == 200, resp.text
+    data2 = resp.json()
+    block2_payload = data2["content"][0]["payload"]
+    assert isinstance(block2_payload, dict) and block2_payload.get("client_name") == "clean_client"
+
+    # 6. block=3 should return the clients array
+    params["block"] = "3"
+    resp = requests.get(API_BASE, params=params)
+    assert resp.status_code == 200, resp.text
+    data3 = resp.json()
+    block3_payload = data3["content"][0]["payload"]
+    assert isinstance(block3_payload, list) and len(block3_payload) > 0