análise-de-dados

Skill de Análise de Dados

Visão Geral

Esta skill analisa arquivos Excel/CSV enviados pelo usuário usando DuckDB – um mecanismo SQL analítico em processo. Ela suporta inspeção de esquemas, consultas baseadas em SQL, resumos estatísticos e exportação de resultados, tudo por meio de um único script Python.

Capacidades Principais

• Inspecionar estrutura de arquivos Excel/CSV (planilhas, colunas, tipos, contagens de linhas)
• Executar consultas SQL arbitrárias contra os dados carregados
• Gerar resumos estatísticos (média, mediana, desvio padrão, percentis, nulos)
• Suportar pastas de trabalho do Excel com várias planilhas (cada planilha se torna uma tabela)
• Exportar resultados de consultas para CSV, JSON ou Markdown
• Lidar com arquivos grandes de forma eficiente com o mecanismo colunar do DuckDB

Fluxo de Trabalho

Etapa 1: Entender os Requisitos

Quando um usuário enviar arquivos de dados e solicitar análise, identifique:

• Localização do arquivo: Caminho(s) para os arquivos Excel/CSV em /mnt/user-data/uploads/
• Objetivo da análise: Quais insights o usuário deseja (resumo, filtragem, agregação, comparação, etc.)
• Formato de saída: Como os resultados devem ser apresentados (tabela, exportação CSV, JSON, etc.)
• Você não precisa verificar a pasta em /mnt/user-data

Etapa 2: Inspecionar a Estrutura do Arquivo

Primeiro, inspecione o arquivo enviado para entender seu esquema:

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action inspect

Isso retorna:

• Nomes das planilhas (para Excel) ou nome do arquivo (para CSV)
• Nomes das colunas, tipos de dados e contagens de não nulos
• Contagem de linhas por planilha/arquivo
• Dados de exemplo (primeiras 5 linhas)

Etapa 3: Realizar a Análise

Com base no esquema, construa consultas SQL para responder às perguntas do usuário.

Executar Consulta SQL

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action query \
  --sql "SELECT categoria, COUNT(*) as contagem, AVG(valor) as valor_medio FROM Planilha1 GROUP BY categoria ORDER BY contagem DESC"

Gerar Resumo Estatístico

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action summary \
  --table Planilha1

Isso retorna para cada coluna numérica: contagem, média, desvio padrão, mínimo, 25%, 50%, 75%, máximo, contagem_nulos. Para colunas de texto: contagem, únicos, valor principal, frequência, contagem_nulos.

Exportar Resultados

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/data.xlsx \
  --action query \
  --sql "SELECT * FROM Planilha1 WHERE valor > 1000" \
  --output-file /mnt/user-data/outputs/resultados-filtrados.csv

Formatos de saída suportados (detectados automaticamente pela extensão):

• .csv — Valores separados por vírgula
• .json — Array JSON de registros
• .md — Tabela Markdown

Parâmetros

Parâmetro	Obrigatório	Descrição
--files	Sim	Caminhos separados por espaço para arquivos Excel/CSV
--action	Sim	Um de: inspect, query, summary
--sql	Para query	Consulta SQL a ser executada
--table	Para summary	Nome da tabela/planilha a ser resumida
--output-file	Não	Caminho para exportar resultados (CSV/JSON/MD)

[!NOTE] NÃO leia o arquivo Python, apenas chame-o com os parâmetros.

Regras de Nomenclatura de Tabelas

• Arquivos Excel: Cada planilha se torna uma tabela com o nome da planilha (ex.: Planilha1, Vendas, Clientes)
• Arquivos CSV: O nome da tabela é o nome do arquivo sem extensão (ex.: dados.csv → dados)
• Múltiplos arquivos: Todas as tabelas de todos os arquivos estão disponíveis no mesmo contexto de consulta, permitindo junções entre arquivos
• Caracteres especiais: Nomes de planilhas/arquivos com espaços ou caracteres especiais são sanitizados automaticamente (espaços → underscores). Use aspas duplas para nomes que começam com números ou contêm caracteres especiais, ex.: "2024_Vendas"

Padrões de Análise

Exploração Básica

-- Contagem de linhas
SELECT COUNT(*) FROM Planilha1

-- Valores distintos em uma coluna
SELECT DISTINCT categoria FROM Planilha1

-- Distribuição de valores
SELECT categoria, COUNT(*) as contagem FROM Planilha1 GROUP BY categoria ORDER BY contagem DESC

-- Intervalo de datas
SELECT MIN(data_coluna), MAX(data_coluna) FROM Planilha1

Agregação e Agrupamento

-- Receita por categoria e mês
SELECT categoria, DATE_TRUNC('month', data_pedido) as mes,
       SUM(receita) as receita_total
FROM Vendas
GROUP BY categoria, mes
ORDER BY mes, receita_total DESC

-- Top 10 clientes por gasto
SELECT nome_cliente, SUM(valor) as gasto_total
FROM Pedidos GROUP BY nome_cliente
ORDER BY gasto_total DESC LIMIT 10

Junções Entre Arquivos

-- Juntar vendas com informações de clientes de arquivos diferentes
SELECT s.id_pedido, s.valor, c.nome_cliente, c.regiao
FROM vendas s
JOIN clientes c ON s.id_cliente = c.id
WHERE s.valor > 500

Funções de Janela

-- Total acumulado e classificação
SELECT data_pedido, valor,
       SUM(valor) OVER (ORDER BY data_pedido) as total_acumulado,
       RANK() OVER (ORDER BY valor DESC) as classificacao_valor
FROM Vendas

Análise Estilo Tabela Dinâmica

-- Tabela dinâmica: receita mensal por categoria
SELECT categoria,
       SUM(CASE WHEN MES(data) = 1 THEN receita END) as Jan,
       SUM(CASE WHEN MES(data) = 2 THEN receita END) as Fev,
       SUM(CASE WHEN MES(data) = 3 THEN receita END) as Mar
FROM Vendas
GROUP BY categoria

Exemplo Completo

Usuário envia vendas_2024.xlsx (com planilhas: Pedidos, Produtos, Clientes) e pergunta: "Analise meus dados de vendas — mostre os principais produtos por receita e tendências mensais."

Etapa 1: Inspecionar o arquivo

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/vendas_2024.xlsx \
  --action inspect

Etapa 2: Principais produtos por receita

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/vendas_2024.xlsx \
  --action query \
  --sql "SELECT p.nome_produto, SUM(o.quantidade * o.preco_unitario) as receita_total, SUM(o.quantidade) as total_unidades FROM Pedidos o JOIN Produtos p ON o.id_produto = p.id GROUP BY p.nome_produto ORDER BY receita_total DESC LIMIT 10"

Etapa 3: Tendências mensais de receita

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/vendas_2024.xlsx \
  --action query \
  --sql "SELECT DATE_TRUNC('month', data_pedido) as mes, SUM(quantidade * preco_unitario) as receita FROM Pedidos GROUP BY mes ORDER BY mes" \
  --output-file /mnt/user-data/outputs/tendencias-mensais.csv

Etapa 4: Resumo estatístico

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/vendas_2024.xlsx \
  --action summary \
  --table Pedidos

Apresente os resultados ao usuário com explicações claras sobre descobertas, tendências e insights acionáveis.

Exemplo com Múltiplos Arquivos

Usuário envia pedidos.csv e clientes.xlsx e pergunta: "Qual região tem o maior valor médio de pedido?"

python /mnt/skills/public/data-analysis/scripts/analyze.py \
  --files /mnt/user-data/uploads/pedidos.csv /mnt/user-data/uploads/clientes.xlsx \
  --action query \
  --sql "SELECT c.regiao, AVG(p.valor) as valor_medio_pedido, COUNT(*) as quantidade_pedidos FROM pedidos p JOIN Clientes c ON p.id_cliente = c.id GROUP BY c.regiao ORDER BY valor_medio_pedido DESC"

Manipulação da Saída

Após a análise:

• Apresente os resultados das consultas diretamente na conversa como tabelas formatadas
• Para resultados grandes, exporte para um arquivo e compartilhe usando a ferramenta present_files
• Sempre explique as descobertas em linguagem simples com os principais pontos
• Sugira análises de acompanhamento quando os padrões forem interessantes
• Ofereça-se para exportar os resultados se o usuário quiser mantê-los

Cache

O script armazena em cache automaticamente os dados carregados para evitar reanalisar arquivos a cada chamada:

• No primeiro carregamento, os arquivos são analisados e armazenados em um banco de dados DuckDB persistente em /mnt/user-data/workspace/.data-analysis-cache/
• A chave do cache é um hash SHA256 de todo o conteúdo dos arquivos de entrada — se os arquivos mudarem, um novo cache é criado
• Chamadas subsequentes com os mesmos arquivos usarão o banco de dados em cache diretamente (inicialização quase instantânea)
• O cache é transparente — nenhum parâmetro extra é necessário

Isso é especialmente útil ao executar várias consultas contra os mesmos arquivos de dados (inspecionar → consultar → resumir).

Notas

• DuckDB suporta SQL completo, incluindo funções de janela, CTEs, subconsultas e agregações avançadas
• Colunas de data do Excel são analisadas automaticamente; use funções de data do DuckDB (DATE_TRUNC, EXTRACT, etc.)
• Para arquivos muito grandes (100MB+), o DuckDB lida com eles eficientemente sem carregar tudo na memória
• Nomes de colunas com espaços são acessíveis usando aspas duplas: "Nome da Coluna"