How samithila/nl-db-agent works
nl-db-agent answers business questions by routing them to SQL, industry-document retrieval, or both, then returning a grounded natural-language response with citations and route details. The documented flow starts with clarification and routing; SQL work uses schema inspection, generation, validation, guardrails, and execution, while RAG retrieves document context. The API exposes the agent and feedback capabilities; evaluation and tracing support quality analysis. Several implementation details are unsampled, so the graph omits unverified connections rather than inferring a pipeline from module names.
Main entry points: graph.py Agent Graph · main.py REST API · db_connector.py DB Connector · schema_inspector.py Schema Inspector
Components 24
Agent Workflow
- Run State
agent/state.py - Clarifier
tools/clarifier.py - Route Classifier
agent/router.py - Agent Graph
agent/graph.py - Answer Formatter
tools/formatter.py
Data Access
- Schema Inspector
tools/schema_inspector.py - SQL Generator
tools/sql_generator.py - SQL Validator
tools/validator.py - Query Executor
tools/executor.py - DB Connector
db_connector.py - User Database
- Document Retriever
rag/retriever.py - Document Ingestion
rag/ingestion.py - Pinecone Index
Safety Controls
- Access Permissions
guardrails/permissions.py - Rate and Query Limits
guardrails/limits.py - Injection Safety
guardrails/safety.py
Quality and Observability
- Run Tracer
observability/tracer.py - Benchmark Metrics
evaluation/metrics.py - LLM Judge
evaluation/llm_judge.py
Other components
- Analyst
- OpenAI Models
Connections 33
- Analyst → Query UI: asks question
README.md - Query UI → REST API: submits query
README.md - REST API → Agent Graph: runs query
api/main.py - Agent Graph → Run State: updates state
agent/graph.py - Agent Graph → Clarifier: checks ambiguity
agent/graph.py - Agent Graph → Route Classifier: routes query
agent/graph.py - Agent Graph → Schema Inspector: retrieves schema
agent/graph.py - Agent Graph → SQL Generator: generates SQL
agent/graph.py - Agent Graph → SQL Validator: validates SQL
agent/graph.py - Agent Graph → Query Executor: executes query
agent/graph.py - Agent Graph → Access Permissions: checks access
agent/graph.py - Agent Graph → Rate and Query Limits: checks limits
agent/graph.py - Agent Graph → Injection Safety: checks safety
agent/graph.py - Agent Graph → Document Retriever: retrieves context
agent/graph.py - Agent Graph → Answer Formatter: formats answer
agent/graph.py - Schema Inspector → DB Connector: inspects database
tools/schema_inspector.py - SQL Generator → Schema Inspector: uses schema
tools/sql_generator.py - SQL Validator → DB Connector: checks database
tools/validator.py - Query Executor → DB Connector: runs read-only SQL
tools/executor.py - DB Connector → User Database: connects to
db_connector.py - Access Permissions → DB Connector: reads schema
guardrails/permissions.py - Route Classifier → Schema Inspector: checks connected schema
agent/router.py - Document Retriever → Pinecone Index: searches vectors
rag/retriever.py - Document Ingestion → Pinecone Index: indexes chunks
- Document Retriever → OpenAI Models: embeds query
rag/retriever.py - Route Classifier → OpenAI Models: classifies question
agent/router.py - Answer Formatter → OpenAI Models: synthesizes answer
tools/formatter.py - REST API → Run Tracer: records runs
api/main.py - Benchmark Metrics → Agent Graph: benchmarks runs
evaluation/metrics.py - Benchmark Metrics → LLM Judge: scores answers
evaluation/metrics.py - LLM Judge → OpenAI Models: evaluates answers
- REST API → Analyst: returns answer
api/main.py - Analyst → REST API: rates answer
README.md