fix(multi_format_api): avoid zero-column DataFrame on empty JSON arrays

[gabrielbressan-tfy]

Problem

The multi_format_api handler (display name URL Reader) crashes when an API returns a structurally valid but empty record array — e.g. {"results": [], "next_url": "..."}.

parse_json returned a bare pd.DataFrame(), which is shape (0, 0) — zero rows and zero columns (pandas can't infer column names from an empty list of dicts). When the API-handler planner then runs SELECT * FROM df, DuckDB rejects the zero-column frame:

Invalid Input Error: Need a DataFrame with at least one column

This is a DuckDB schema-inference limitation, not a data problem — the query is valid and the data is legitimately empty. But the error that bubbles up to the agent is a generic DuckDB traceback with no hint that "your filters matched zero rows," so the LLM misreads a data condition as a syntax problem and starts mutating the query (guessing record_path, column names, etc.) — a wasteful retry-storm.

Fix

The empty-record branch in parse_json now always returns a 0-row frame with at least one column:

• Preserve the envelope's top-level scalar siblings (next_url, count, status, …) as columns — mirroring what the non-empty path already does when it reattaches envelope metadata.
• Fall back to a single _empty sentinel column when there's no envelope metadata to borrow (e.g. a bare top-level []).

A valid-but-empty response now returns a clean empty result set, giving the agent an unambiguous "valid query, zero rows" signal instead of a DuckDB traceback.

XML and CSV paths always emit ≥1 column, so JSON was the only affected format.

Tests

• Tightened the existing empty-array test to assert df.shape[1] >= 1.
• Added a regression for the {"results": [], "next_url": "..."} envelope case (columns preserved, results key excluded).
• Added a regression for the bare [] sentinel fallback.

All 15 tests in the handler module pass (/venv/bin/python -m pytest in the dev-mindsdb container).

🤖 Generated with Claude Code