How zaibys/us-census-chatbot works
Project Type & Purpose
• This is a full-stack, AI-powered web application built in Python with a Streamlit front end.
File Structure
Top-level folders/files:
• streamlit_app.py – Streamlit UI entry point
• src/ – core application logic
– main.py – orchestration of the request pipeline
– system_prompt.py & embeddings.py – LLM prompt and embedding logic
– big_query_manager.py – BigQuery client wrapper
– data_handler.py & response_handler.py – result formatting & fallback handling
– logger.py – centralized logging
– components.py – UI components for Streamlit
• chroma_langchain_db/chroma.sqlite3 – local vector store for schema embeddings
• .env-template – environment variables (GCP project ID, BigQuery credentials)
README Insights
• Confirms tech stack: Streamlit, LangChain, Gemini AI, Google BigQuery, Docker/GCP infra.
• High-level flow described (user → NL to SQL → BigQuery → visualization).
Main Components & Their Relationships
a. Frontend (Streamlit)
• streamlit_app.py + components.py
• Collects natural-language input, renders charts/tables.
b. Orchestration Layer
• main.py – central controller that sequences sub-components.
c. NLP & SQL Generation
• system_prompt.py – builds prompts for Gemini AI
• embeddings.py – creates/queries embeddings in local Chroma DB (chroma.sqlite3) to fetch relevant schema context
• LangChain + Gemini API (external service)
d. Query Execution
• big_query_manager.py – sends SQL to Google BigQuery, retrieves raw results
e. Data Processing & Response Handling
• data_handler.py – transforms BigQuery rows into pandas/dataframe
• response_handler.py – formats fallback or success responses
f. Persistence & Logging
• Local Chroma vector store (chroma.sqlite3) for cached schema embeddings
• logger.py – logs each step (prompt, SQL, errors)
g. External Services
• Google BigQuery (data warehouse)
• LangChain + Google’s Gemini (LLM + embeddings)
h. Infrastructure
• Docker containerization (Dockerfile not shown but implied by README)
• GCP environment variables (.env-template)
Architectural Patterns & Design Principles
• Pipeline / Chain-of-Responsibility: each step handles a specific concern (prompt → embed → LLM → SQL → execute → display).
• Separation of concerns: UI vs orchestration vs data access vs processing.
• Caching via vector store to reduce repeated schema lookups.
• Fallback mechanism if LLM fails to generate SQL (handled in response_handler.py).