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 @@
+# 16. Add Logging for Debuggability
+
+## Summary
+
+Add optional diagnostic logging for ingestion, query, and Chroma operations while keeping normal CLI output clean.
+
+## Implementation Steps
+
+- Configure Python's `logging` module in the CLI entrypoint.
+- Add a global `--verbose` flag to enable debug-level logs.
+- Log file loading, chunk counts, embedding calls, Chroma writes, collection operations, and query timing.
+- Send logs to stderr so stdout remains reserved for command output.
+- Avoid logging document contents or full embeddings.
+
+## Public Interface Changes
+
+- Add global CLI flag `--verbose`.
+- Normal output remains unchanged when verbose mode is not enabled.
+
+## Test Plan
+
+- Test parser behavior for `--verbose`.
+- Test that debug logs are suppressed by default.
+- Test that verbose mode emits representative diagnostic logs to stderr.
+- Smoke test `add-data` and `query` with verbose mode enabled.
+
+## Assumptions
+
+- A single global verbosity level is enough for now.
+- Structured logging means consistent logger names and message fields, not a JSON logging format.