ohadlivay/db-whisperer

1. What this repo is

- DB Whisperer is a Python + Streamlit application for interactive database exploration.

- Its core idea is an LLM-assisted workflow: the user asks questions in the UI, and the app routes them through query-generation, ambiguity-resolution, and data-loading services.

2. Top-level entry point

- app.py is the deployable entry point used by Streamlit.

- The main runtime boundary is: browser UI → Streamlit app → package code under src/db_whisperer.

3. Presentation layer

- src/db_whisperer/gui/app.py contains the Streamlit UI logic.

- style.css and changelog.json are UI assets, not core business logic.

- This layer is responsible for session interaction, API key collection, and displaying results/errors.

4. Application orchestration layer

- src/db_whisperer/application/service.py is the coordination layer.

- It likely acts as the controller that decides which subsystem to invoke based on user intent: query a dataset, resolve ambiguity, or perform ETL-related preparation.

- This is the main internal boundary between the UI and the domain-specific services.

5. Querying subsystem

- src/db_whisperer/querier/ is the path for “ask a question, get SQL/data back.”

- It includes:

- prompt_builder.py for constructing model prompts,

- openrouter_client.py for LLM calls,

- sql_validator.py for checking generated SQL,

- service.py for orchestration.

- Architecturally, this is the path that turns natural language into validated database queries.

6. Ambiguity-resolution subsystem

- src/db_whisperer/ambiguity/ handles cases where the user’s request is unclear or underspecified.

- It has its own prompt_builder.py, openrouter_client.py, and service.py, which suggests a separate LLM interaction flow focused on clarification rather than query generation.

- This is a distinct guardrail layer before the app commits to an SQL answer.

7. ETL / dataset preparation subsystem

- src/db_whisperer/etler/service.py handles data loading or transformation concerns.

- The repo ships with multiple datasets in data/, including:

- relational CSV tables,

- single CSV files,

- a MIMIC-III clinical database demo.

- This indicates the app supports prepared datasets and likely uses an ETL step to make them queryable.

8. External service boundary

- The only clear external runtime dependency in the architecture is OpenRouter.

- Both the ambiguity and querying flows have dedicated OpenRouter clients, so LLM calls are isolated behind subsystem-specific adapters.

- The README says the API key is sent for the current session and not persisted, which matters for the trust boundary in the UI/session layer.

9. Shared contracts and cross-cutting concerns

- src/db_whisperer/contracts.py likely defines shared data structures/interfaces between services.

- src/db_whisperer/prompt_logging.py is a cross-cutting utility for recording prompts or model interactions, useful for traceability/debugging.

- These pieces sit below the orchestration layer and above the UI/transport layer.

10. Benchmarking and evaluation

- benchmark/run.py and benchmark/cases.json form a separate evaluation path from the interactive app.

- This suggests the repo can run repeatable test cases against the same core logic, independent of the Streamlit UI.

- For an architecture diagram, this is a sibling consumer of the service layer, not part of the main user flow.

11. Testing structure

- tests/ mirrors the package structure: ambiguity, application, etler, gui, and querier.

- There are focused unit tests for prompt builders, OpenRouter clients, services, and UI behavior, plus at least one relational integration test.

- That mirrors the repo’s modular architecture and confirms the subsystem boundaries.

12. How to draw the main flow

- The primary diagram should show:

- User/browser

- Streamlit GUI

- Application service

- branching into Querier, Ambiguity, and ETL

- with OpenRouter as the external LLM service

- and local dataset files as the data source backing the querying/ETL path.

- The benchmark runner should be shown separately as an offline evaluation consumer of the same core services.