💬 Chat with SQL

Converse com Seus Dados em Linguagem Natural

Transforme perguntas em SQL automaticamente.

---

📋 Sobre o Projeto

O Chat with SQL permite fazer perguntas em português sobre bancos de dados e receber respostas precisas, sem escrever SQL manualmente.

O Problema

Usuário: "Quais foram as vendas do mês passado?"

Sem Chat with SQL:
- Precisa saber SQL
- Precisa conhecer o schema
- Precisa escrever a query correta

Com Chat with SQL:
- Pergunta em português → Resposta em português

A Solução

1. Schema Awareness - Entende estrutura do banco
2. Text-to-SQL - Converte pergunta em SQL
3. Query Execution - Executa com segurança
4. Answer Generation - Responde em linguagem natural

---

🚀 Quick Start

1. Clone o Projeto

git clone <repo>
cd 11-chat-sql

2. Crie o Ambiente Virtual

python -m venv .venv
source .venv/bin/activate  # Linux/Mac

3. Instale as Dependências

pip install -r requirements.txt

4. Configure as Variáveis

cp .env.example .env
# Edite o .env com suas chaves

5. Inicialize o Banco de Exemplo

python init_db.py

6. Execute a Interface

streamlit run app.py

---

📁 Estrutura do Projeto

11-chat-sql/
├── README.md              # Este arquivo
├── ROTEIRO.md             # Roteiro para gravação
├── APOIO.md               # Material explicativo
├── app.py                 # Interface Streamlit
├── init_db.py             # Inicializa banco de exemplo
├── requirements.txt
├── .env.example
├── .gitignore
├── Makefile
├── verify_setup.py
│
├── slides/
│   └── slides.md          # Slides Marp
│
├── notebooks/
│   ├── 01_fundamentos_sql.py
│   ├── 02_implementacao_sql.py
│   └── 03_producao_sql.py
│
├── src/
│   ├── __init__.py
│   ├── config.py              # Configurações
│   ├── models.py              # Schemas Pydantic
│   ├── database.py            # Conexão e execução
│   ├── schema_inspector.py    # Extrai schema do banco
│   ├── text_to_sql.py         # Converte texto para SQL
│   ├── sql_validator.py       # Valida queries (segurança)
│   ├── answer_generator.py    # Gera resposta natural
│   └── graph.py               # Orquestração LangGraph
│
├── tests/
│   └── test_chat_sql.py
│
└── data/
    └── sample.db          # SQLite de exemplo

---

🏗️ Arquitetura

┌─────────────────────────────────────────────────────────────────┐
│                        CHAT WITH SQL                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   "Quais as vendas do mês?"                                     │
│     │                                                           │
│     ▼                                                           │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              SCHEMA INSPECTOR                           │   │
│   │              Extrai tabelas, colunas, tipos             │   │
│   └───────────────────────────┬─────────────────────────────┘   │
│                               │                                 │
│                               ▼                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              TEXT-TO-SQL                                │   │
│   │              LLM gera query SQL                         │   │
│   └───────────────────────────┬─────────────────────────────┘   │
│                               │                                 │
│                               ▼                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              SQL VALIDATOR                              │   │
│   │              Valida segurança (sem DROP, DELETE...)     │   │
│   └───────────────────────────┬─────────────────────────────┘   │
│                               │                                 │
│                               ▼                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              QUERY EXECUTOR                             │   │
│   │              Executa no banco                           │   │
│   └───────────────────────────┬─────────────────────────────┘   │
│                               │                                 │
│                               ▼                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              ANSWER GENERATOR                           │   │
│   │              Responde em linguagem natural              │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│   "As vendas do mês foram R$ 125.430,00"                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

⚙️ Pré-requisitos

Requisito	Versão
Python	3.11+
OpenAI API Key	GPT-4o-mini ou superior
SQLite	Incluído no Python

Bancos Suportados

• SQLite (padrão, incluído)
• PostgreSQL (com psycopg2)
• MySQL (com mysql-connector)

---

🔧 Comandos Úteis

# Instalar dependências
make install

# Inicializar banco de exemplo
make init-db

# Verificar setup
make setup

# Executar Streamlit
make app

# Rodar testes
make test

---

📊 Banco de Exemplo

O projeto inclui um banco SQLite com dados fictícios:

Tabelas

Tabela	Descrição
clientes	Cadastro de clientes
produtos	Catálogo de produtos
vendas	Registro de vendas
vendas_itens	Itens de cada venda

Dados de Exemplo

• 50 clientes
• 20 produtos
• 200 vendas
• 500 itens de venda

---

🎯 Exemplos de Perguntas

✅ "Quantos clientes temos cadastrados?"
✅ "Qual o produto mais vendido?"
✅ "Quais foram as vendas de janeiro?"
✅ "Qual cliente comprou mais?"
✅ "Qual o ticket médio de vendas?"
✅ "Liste os produtos com estoque baixo"
✅ "Qual a receita total por mês?"

---

🔒 Segurança

O SQL Validator bloqueia queries perigosas:

Operação	Status
SELECT	✅ Permitido
INSERT	❌ Bloqueado
UPDATE	❌ Bloqueado
DELETE	❌ Bloqueado
DROP	❌ Bloqueado
TRUNCATE	❌ Bloqueado

---

📚 Recursos

• LangChain SQL
• Text-to-SQL
• SQLite Docs

---

👤 Autor

Alexsander Valente
alexsander.app.br

---

Parte do curso IA Generativa na Prática