Chromy/plans/13-robust-query-result-formatting.md

13. Make Query Result Formatting More Robust

Summary

Convert raw Chroma query results into typed internal matches before formatting them for terminal output.

Implementation Steps

• Add a QueryMatch dataclass with fields for id, document, distance, and metadata.
• Add a parser that converts Chroma QueryResult data into list[QueryMatch].
• Handle empty results, missing documents, missing metadata, missing distances, and unexpected metadata shapes defensively.
• Change terminal formatting to accept list[QueryMatch].
• Keep current text output as stable as practical.

Public Interface Changes

• CLI output should remain effectively the same for normal query results.
• Internal formatter APIs change from raw Chroma result dictionaries to typed match objects.

Test Plan

• Test empty query results.
• Test populated results with ids, documents, distances, and metadata.
• Test missing documents, missing metadata, multiple query result groups, and non-mapping metadata values.
• Smoke test query against a real collection.

Assumptions

• The first implementation can format the first query group only, matching current behavior.
• Support for alternate output formats is not added in this plan.