How shyamal002/snowflake_cortex_analyst_bot works
Project type and purpose
• This is a full-stack, single-page analytical chatbot built on Streamlit.
• Purpose: take plain-English user questions, convert them to SQL via Snowflake Cortex Analyst, execute on Snowflake, apply semantic metadata, enforce guardrails, and render tabular/chart results.
File structure
• Top level:
• pyproject.toml, requirements.txt – dependency definitions
• src/ – all application code and assets
• src/ subfolders:
• config/ – SQL DDL scripts and semantic-model YAML
• guardrails/ – NeMo/LlamaGuard configuration and prompts
• snowflake_cortex_bot.py – the Streamlit app entrypoint
• No separate “frontend” vs. “backend” folder; both UI and logic live in a single Python process.
Key architecture insights from README
• Technologies: Streamlit (UI), Pandas/Matplotlib or Streamlit charts (visualization), Snowflake Python connector, Cortex Analyst SDK (LLM→SQL), NVIDIA NeMo & LlamaGuard (moderation), SpaCy (NLP helpers), session state for context, custom logging/feedback.
• External systems: Snowflake DB (tables + semantic model YAML stage), Cortex Analyst service, optional Ollama LLM host.
a. Main components
1. User Browser / Streamlit UI
2. Application Logic
– Natural-Language Router (Streamlit input → prompt builder)
– Session Memory (Streamlit session_state)
– Guardrails Module (NeMo/LlamaGuard)
– SQL Translator (Snowflake Cortex Analyst API)
– Snowflake Connector (executes SQL + loads semantic model)
– Visualization Engine (Pandas/DataFrame → charts)
– Feedback & Logging (writes to local logs or Cortex Feedback API)
3. Semantic Model Store (Snowflake stage + demo_semantic_model.yaml)
4. Snowflake Database (tables created via SQL scripts)
5. External LLM Services (Cortex Analyst, optional Ollama for guardrails)
b. Relationships & data flow
1. User enters NL query in Streamlit UI
2. App logic consults Session Memory → builds prompt
3. Prompt passes through Guardrails → moderated prompt
4. Moderated prompt sent to Cortex Analyst → returns SQL
5. SQL submitted to Snowflake via Connector
6. Snowflake returns raw data
7. App logic applies Pandas/semantic model metadata → prepares visualization
8. Results rendered back in UI
9. User feedback captured → sent to Feedback API or log file
c. Architectural patterns & principles
• Modular separation: config, guardrails, core logic in distinct folders
• Single-process microservice: UI + business logic co-located
• Externalized semantic metadata (YAML) for decoupled schema awareness
• Stateful session for multiturn conversation
• Plug-in guardrails layer to enforce safety
d. Relevant technologies/frameworks
• Streamlit – UI and session state
• Snowflake Python connector / SnowSQL CLI
• Snowflake Cortex Analyst SDK – NL→SQL
• NVIDIA NeMo & LlamaGuard – content filters
• Pandas & Streamlit charts – data rendering
• SpaCy – optional NLP pre/post-processing
• uv (alternative installer), Python venv
Final advice
• Be exhaustive yet readable: break the system into logical layers (presentation, processing, data).
• Essential elements listed above.
• Don’t over-modularize; focus on 6–8 core components for clarity.