Text-to-SQL Agent Pipeline

Build LLM agents that convert natural language to SQL queries using RAG and safety validation.

Features

• 🤖 LLM-powered text-to-SQL generation
• 🔒 SQL safety validation
• 🔍 RAG-based context retrieval
• ✅ Type-safe with Pydantic
• 🧪 Comprehensive test suite

Setup

# 1. Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# 2. Configure and setup
cp .env.example .env
# Edit .env to set OLLAMA_MODEL=lfm2 (or your preferred model)

bash scripts/setup.sh  # Installs deps, pulls models, creates DB

# 3. Start Ollama (terminal 1)
uv run scripts/serve_ollama.py

# 4. Run tutorials (terminal 2)
python tutorials/01_data_collection.py

Tutorials

7 progressive tutorials teaching LLM agent development:

1. Data Collection - Create biomedical database
2. Schema Discovery - LLM-powered schema analysis
3. Pydantic Validation - Type-safe structured outputs
4. Safety Validation - SQL query security
5. RAG Indexing - Vector store for context retrieval
6. Text-to-SQL - Generate queries with RAG
7. Agentic Pipeline - LangGraph orchestration

python tutorials/01_data_collection.py
python tutorials/02_schema_discovery.py
# ... continue through 07

See tutorials/README.md for details.

Usage Example

from src.utils.llm import LLMClient
from src.utils.validation import SQLValidator
from src.models.schemas import SQLQuery

llm = LLMClient()
query = llm.generate_structured(
    prompt="Count patients with diabetes",
    response_model=SQLQuery
)

validator = SQLValidator()
if validator.validate(query.query).is_valid:
    print(f"Safe: {query.query}")

Testing

pytest                    # Run all tests
pytest --cov=src          # With coverage

Troubleshooting

Ollama connection error:

uv run scripts/check_ollama.py
uv run scripts/serve_ollama.py

Model not found:

cat .env | grep OLLAMA
uv run scripts/check_ollama.py

Database not found:

python tutorials/01_data_collection.py

Architecture

User Question → LangGraph Pipeline
                ↓
            RAG + LLM → Generate SQL
                ↓
            Validate → Safety checks
                ↓
            Execute → SQLite
                ↓
            Results

License

MIT