move top-level modules into a real package

2026-04-22 15:47:46 +02:00
parent e33160282c
commit 8ebab832d5
35 changed files with 6192 additions and 31 deletions
@@ -0,0 +1,30 @@
+# 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.