AI Ask

O DataSpoc Lens pode traduzir perguntas em linguagem natural para SQL, executar a query e retornar os resultados. Nenhum conhecimento de SQL necessário.

Configuração

Opção 1: IA local com Ollama (gratuita, sem API key)

dataspoc-lens setup-ai

Isso instala e configura o Ollama com um modelo local. Completamente gratuito, nenhum dado sai da sua máquina.

Opção 2: Provedores na nuvem

Instale o extra de IA:

pip install dataspoc-lens[ai]

Configure via variáveis de ambiente:

# Anthropic (Claude)
export DATASPOC_LLM_PROVIDER=anthropic
export DATASPOC_LLM_API_KEY=sk-ant-...

# OpenAI (GPT)
export DATASPOC_LLM_PROVIDER=openai
export DATASPOC_LLM_API_KEY=sk-...

Ou adicione ao ~/.dataspoc-lens/config.yaml:

llm:
  provider: anthropic     # ollama, anthropic, or openai
  api_key: sk-ant-...     # not needed for ollama
  model: ""               # optional, uses provider default

Provedores

Provedor	Custo	Privacidade	Modelo
ollama	Gratuito	Local (nenhum dado enviado externamente)	Configurável (padrão definido pelo setup-ai)
anthropic	Pago (por token)	Dados enviados para a API da Anthropic	Claude (mais recente)
openai	Pago (por token)	Dados enviados para a API da OpenAI	GPT (mais recente)

Prioridade de configuração

1. Variáveis de ambiente (DATASPOC_LLM_PROVIDER, DATASPOC_LLM_API_KEY, DATASPOC_LLM_MODEL)
2. ~/.dataspoc-lens/config.yaml
3. Padrão: ollama

Uso

dataspoc-lens ask "What are the top 5 customers by total spending?"

SQL: SELECT c.name, SUM(o.total) as total_spent
     FROM customers c JOIN orders o ON c.id = o.customer_id
     GROUP BY c.name ORDER BY total_spent DESC LIMIT 5

┌──────────────┬─────────────┐
│ name         │ total_spent │
├──────────────┼─────────────┤
│ Alice Smith  │ 15420.50    │
│ Bob Johnson  │ 12300.00    │
│ Carol White  │ 9870.25     │
│ Dave Brown   │ 8540.00     │
│ Eve Davis    │ 7210.75     │
└──────────────┴─────────────┘

(5 row(s), 1.230s)

Modo debug

Use --debug para ver o prompt completo enviado ao LLM:

dataspoc-lens ask "Monthly revenue trend" --debug

--- Prompt sent to LLM ---
You are a SQL assistant. Given the following table schemas, write a DuckDB SQL
query to answer the user's question.

Tables:
- customers (id INTEGER, name VARCHAR, email VARCHAR, ...)
- orders (order_id INTEGER, customer_id INTEGER, order_date DATE, total DOUBLE, ...)
- products (product_id INTEGER, name VARCHAR, price DOUBLE, ...)

Question: Monthly revenue trend

Return ONLY the SQL query, no explanation.
--- End of prompt ---

SQL: SELECT DATE_TRUNC('month', order_date) as month,
     SUM(total) as revenue
     FROM orders GROUP BY month ORDER BY month

┌────────────┬──────────┐
│ month      │ revenue  │
├────────────┼──────────┤
│ 2024-01-01 │ 125400   │
│ 2024-02-01 │ 138200   │
│ 2024-03-01 │ 152800   │
└────────────┴──────────┘

(3 row(s), 1.450s)

Como funciona

1. O Lens lê o schema de todas as tabelas montadas (nomes e tipos de colunas)
2. Uma amostra de linhas é incluída como contexto
3. O schema, dados de amostra e sua pergunta são enviados para o LLM configurado
4. O LLM retorna uma query SQL compatível com DuckDB
5. O Lens executa o SQL contra seu data lake
6. Os resultados são exibidos (ou exportados com --export)

Exportar resultados

dataspoc-lens ask "Revenue by product category" --export revenue.csv
dataspoc-lens ask "Customer segments" --export segments.parquet

Saída JSON

dataspoc-lens ask "Total orders" --output json

{
  "sql": "SELECT COUNT(*) as total_orders FROM orders",
  "columns": ["total_orders"],
  "rows": [[48680]],
  "duration": 0.95,
  "error": null
}

Exemplos

# Aggregations
dataspoc-lens ask "What is the average order value?"

# Joins
dataspoc-lens ask "Which products have never been ordered?"

# Time series
dataspoc-lens ask "Show weekly order counts for the last 3 months"

# Filtering
dataspoc-lens ask "How many orders were cancelled in January?"