AI Ask

DataSpoc Lens puede traducir preguntas en lenguaje natural a SQL, ejecutar la consulta y devolver los resultados. No se requiere conocimiento de SQL.

Configuracion

Opcion 1: IA local con Ollama (gratuito, sin API key)

dataspoc-lens setup-ai

Esto instala y configura Ollama con un modelo local. Completamente gratuito, ningun dato sale de tu maquina.

Opcion 2: Proveedores en la nube

Instala el extra de IA:

pip install dataspoc-lens[ai]

Configura via variables de entorno:

# 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-...

O agrega a ~/.dataspoc-lens/config.yaml:

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

Proveedores

Proveedor	Costo	Privacidad	Modelo
ollama	Gratuito	Local (no se envian datos externamente)	Configurable (por defecto definido por setup-ai)
anthropic	Pago (por token)	Datos enviados a Anthropic API	Claude (ultimo)
openai	Pago (por token)	Datos enviados a OpenAI API	GPT (ultimo)

Prioridad de configuracion

1. Variables de entorno (DATASPOC_LLM_PROVIDER, DATASPOC_LLM_API_KEY, DATASPOC_LLM_MODEL)
2. ~/.dataspoc-lens/config.yaml
3. Por defecto: 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

Usa --debug para ver el prompt completo enviado al 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. Lens lee el esquema de todas las tablas montadas (nombres de columnas y tipos)
2. Se incluye una muestra de filas para contexto
3. El esquema, datos de muestra y tu pregunta se envian al LLM configurado
4. El LLM retorna una consulta SQL compatible con DuckDB
5. Lens ejecuta el SQL contra tu data lake
6. Los resultados se muestran (o se exportan con --export)

Exportar resultados

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

Salida 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
}

Ejemplos

# 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?"