How radi07/sql_agent works
Project Type and Purpose
• This is a full-stack AI agent: a Streamlit frontend (app.py, dashboard.py, assets/style.css) backed by a Python package (“querymancer/”) that turns natural-language into SQL queries, routes them through multi-model inference, applies optimization strategies, and talks to a local SQLite database and remote LLM APIs.
File Structure
• Top-level entrypoints:
• app.py (Streamlit chat UI)
• dashboard.py (performance dashboard)
• Static assets: assets/style.css
• Executables/scripts: bin/create-database
• Data layer: data/ecommerce.sqlite (schema illustrated in README)
• Logs & metrics: logs/{calibration_history.json, model_performance.json}
• Core library: querymancer/
• agent.py – orchestrator
• config.py – loads .env and selects models
• logging.py – centralized logger setup
• models.py – wrappers for Groq & SambaNova API calls
• optimizations.py – complexity router, token optimizer, threshold calibrator
• tools.py – schema introspection & SQL builder
• Tests: test_*.py plus JSON snapshots for complexity & token optimization
Extract Architecture from README
• Presentation: Streamlit UI for conversation + dashboard
• Application logic: “Querymancer agent” that interprets user input, introspects schema, builds and optimizes SQL, then calls appropriate LLM
• Multi-model inference: Groq (“llama-3.3-70b-versatile”) vs. SambaNova (“DeepSeek-R1”)
• Optimization pipelines: routing by complexity, token reduction, parameter auto-tuning
• Monitoring & calibration: logs feed performance dashboard and automatically adjust thresholds
Main Components
a. Frontend Layer
• Streamlit App (app.py)
• Static CSS (assets/style.css)
• Dashboard (dashboard.py)
b. Backend Core (querymancer package)
• Agent Orchestrator
• Schema Introspection (tools.py)
• SQL Generator (tools.py)
• Optimization Pipelines (optimizations.py):
• Complexity Router (with LRU cache)
• Token Optimization Pipeline
• Threshold Calibration
• Model Wrappers (models.py)
• Configuration Loader (config.py)
• Logging & Monitoring (logging.py)
c. Data Layer
• SQLite Database (data/ecommerce.sqlite)
d. External Services Layer
• Groq API
• SambaNova API
e. Cross-Cutting Concerns
• Environment Variables (.env for API keys)
• Logs & Metrics Store (logs/*.json)
Relationships and Data Flows
1. User enters query in Streamlit UI →
2. Agent receives NL input →
3. Agent calls Schema Introspector to fetch table/column metadata →
4. Agent generates raw SQL →
5. Raw SQL → Complexity Router → routes to appropriate model path →
6. Selected path triggers Token Optimization Pipeline →
7. Optimized SQL and context sent to Model Wrapper →
8. Wrapper invokes Groq or SambaNova REST API (with keys from config) →
9. LLM response → Agent post-processes and returns result to UI →
10. Throughout: Logging module records decisions, complexity scores, performance metrics → logs JSON → Dashboard reads logs
• Threshold Calibrator periodically reads historical logs → adjusts complexity thresholds stored in config or a local store → influences future routing decisions.
Architectural Patterns & Design Principles
• Layered Architecture (Presentation, Application, Domain, Infrastructure)
• Strategy Pattern for choosing optimization algorithms & model selection
• Pipeline Pattern for token optimization stages
• Caching (LRU) in Complexity Router to avoid repeated analyses
• Observer/Publisher-Subscriber for performance monitoring and calibration
• Single Responsibility: each module focuses on one concern (e.g., config, logging, optimization)
Relevant Technologies & Frameworks
• Python 3.12 (managed via uv)
• Streamlit (UI)
• SQLite (built-in DB)
• REST APIs (Groq, SambaNova)
• JSON for logs and calibration history
• Pre-commit, pyproject.toml for dependency & dev tooling
Putting It All Together
• Central block: Querymancer Core (sub-divide into orchestration, tools, optimizations, models, config, logging)
• Above: Streamlit UI → below: SQLite DB → to the right: External LLM APIs
• Side loop: logs → dashboard and calibrator → back into optimizations
• Final tip: break out each optimization strategy as its own sub-component to show granularity and extensibility.