How ivoryrabbit/sql-helper works
Project type and purpose
• From the README (“sql-helper: Text-to-SQL using LLM and RAG”) and the presence of both a Streamlit app (app.py, .streamlit/) and a standalone API + worker (api/), this is a full-stack, service-oriented application.
• Purpose: Allow users to enter natural language questions via a UI, invoke a retrieval-augmented generation (RAG) pipeline and LLMs to produce SQL queries, execute them against a Postgres database (and optionally vector stores), and return results.
File structure
• Top-level:
• app.py + .streamlit/ → Streamlit frontend
• api/ → Python API + Temporal workflows + worker
• src/ → core libraries: LLM adapters, vector store abstractions, SQL agent logic, client-side controller/page code
• docker-related files & docker-compose.yaml → local dev environment for Postgres and Temporal
• resource/sql & resource/config → sample schemas and dev/prod configuration
• bin/ → start-up scripts for local and production
• Architectural clues:
• Separation of UI (app.py + src/client) from backend logic (api/src, core modules)
• Use of Temporal (api/src/component/{workflow,activities}.py + api/worker.py) implies an orchestration service pattern
• Multiple vector store implementations (chromadb, pgvector, qdrant) under src/core/vector_store suggest a plugin architecture
Key insights from README
• Runtime stack: Python 3.9, Streamlit for UI
• LLM platforms: OpenAI, Cohere, Claude, Meta Llama
• RAG backends: ChromaDB, Postgres PGVector
• Workflow: ingest question → fetch context (vector store) → call LLM → synthesize SQL → run against Postgres → return results