DataSense

Projeto de portfolio em Data Science e Gestao da Informacao.

O DataSense e uma aplicacao onde o usuario faz upload de uma planilha ou arquivo tabular e conversa com os dados em linguagem natural. A ferramenta gera respostas analiticas, graficos, insights, auditoria de qualidade dos dados e recomendacoes praticas.

Links

• Site publicado: https://data-sense-three.vercel.app/
• API publicada: https://data-sense-api.onrender.com
• Documentacao da API: https://data-sense-api.onrender.com/docs

Preview

Objetivo

Criar um produto demonstravel para entrevistas e processos seletivos, mostrando habilidades em:

• Python para tratamento e analise de dados.
• SQL para consultas estruturadas.
• Visualizacao de dados.
• Inteligencia artificial aplicada a analise exploratoria.
• Auditoria e qualidade de dados.
• UX voltada para usuarios de negocio.
• Documentacao tecnica e de produto.

Problema

Muitas pessoas e empresas possuem dados em planilhas, mas nao sabem transformar esses dados rapidamente em perguntas respondidas, graficos, diagnosticos e decisoes. O projeto resolve esse problema oferecendo uma experiencia simples: enviar CSV, Excel, TSV, TXT ou JSON tabular, perguntar em linguagem natural e receber uma analise confiavel.

Solucao

O sistema atuara como um assistente para analise de dados:

• Le CSV, TSV, TXT delimitado, Excel e JSON tabular enviados pelo usuario.
• Guia a leitura logo no primeiro contato, com onboarding curto, exemplos prontos e expectativa clara do que sera gerado apos o upload.
• Detecta melhor o cabecalho real em planilhas Excel que possuem linha de titulo antes da tabela.
• Identifica colunas, tipos de dados, valores ausentes e possiveis problemas.
• Sugere conversao para colunas de periodo, como mes e trimestre, quando elas aparecem como texto.
• Permite perguntas em linguagem natural sobre os dados.
• Gera consultas, tabelas resumidas, graficos e explicacoes para dados de vendas, compras, clientes, fornecedores, categorias e regioes.
• Prioriza metricas de negocio, como receita/faturamento/valor total, evitando somar NF, prazo, avaliacao ou desconto por engano.
• Monta um dashboard automatico apos o upload com KPIs, evolucao mensal, rankings, nulos e score de qualidade.
• Permite personalizar o dashboard com titulo, tema, logo, tipo de grafico, ordem dos graficos e graficos ocultos.
• Recalcula o dashboard com filtros de periodo e categorias, como produto, fornecedor, cliente, categoria, regiao ou canal.
• Mantem uma faixa de contexto persistente com arquivo, dominio detectado, indicador principal, periodo e score de qualidade para orientar a navegacao.
• Detecta anomalias e problemas de qualidade.
• Gera uma auditoria inteligente da confiabilidade da analise, apontando cabecalho suspeito, datas como texto, metricas inadequadas, totais negativos, nulos, duplicatas e outliers.
• Pode usar IA pelo OpenRouter para revisar a auditoria quando OPENROUTER_API_KEY estiver configurada; sem chave, usa regras locais.
• Pode usar IA para uma segunda leitura gerencial em /datasets/{id}/managerial-analysis/ai, recebendo somente evidencias calculadas, como variacoes, causa raiz, alertas, drivers e limitacoes.
• Permite escolher o modelo do OpenRouter na chamada da IA, por exemplo ?model=anthropic/claude-3.5-sonnet.
• Sugere proximas analises e recomendacoes de negocio.
• Exporta relatorio em PDF ou PNG com resumo, qualidade, insights, graficos e recomendacoes.
• Renderiza graficos reais no relatorio, com mensagem clara quando nao ha dados suficientes para desenhar uma visualizacao.
• Exporta o dashboard personalizado em PDF via impressao e PNG gerado no navegador.
• Mostra analise mensal mais gerencial, com selecao por ano, recorte de meses, comparativo com ano anterior e media movel.
• Exporta pacote Power BI com dados tratados, comparativo mensal, causa raiz, medidas DAX, layout sugerido, modelo de paginas e indicadores executivos.
• Mantem historico local das ultimas analises carregadas.

Documentacao

• Definicao do projeto
• Roadmap
• Registro de decisoes
• Definicao tecnica do MVP
• Pacote Power BI

Estrutura inicial

backend/
  app/
    main.py
    services/
frontend/
  src/
data/
  sample/
    clientes_demo.json
    compras_demo.csv
    compras_demo.xlsx
    estoque_financeiro_demo.tsv
    vendas_demo.csv
    vendas_demo.xlsx
docs/

Como executar localmente

Backend

cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

A API ficara disponivel em:

• http://127.0.0.1:8000/health
• http://127.0.0.1:8000/docs

Para ativar a revisao de qualidade e a segunda leitura gerencial com IA no backend local, copie o exemplo de ambiente:

copy .env.example .env

Depois edite backend/.env e preencha:

OPENROUTER_API_KEY=sua_chave_openrouter
OPENROUTER_MODEL=openai/gpt-4o-mini
OPENROUTER_TIMEOUT_SECONDS=12
OPENROUTER_SITE_URL=https://data-sense-three.vercel.app
OPENROUTER_APP_TITLE=DataSense
DATASENSE_MANAGERIAL_AI_ENABLED=true

A chave deve ficar somente no backend. Nunca coloque OPENROUTER_API_KEY no frontend ou na Vercel do frontend. Se OPENROUTER_API_KEY nao existir, as rotas de auditoria e analise gerencial com IA usam somente regras locais e seguem funcionando normalmente.

Frontend

cd frontend
npm install
npm run dev

Se preferir usar pnpm:

cd frontend
pnpm install
pnpm run dev

O frontend ficara disponivel em:

• http://localhost:5173

Para apontar o frontend para uma API publicada, crie frontend/.env com:

VITE_API_BASE_URL=https://sua-api.onrender.com

Identidade visual

O projeto usa o nome DataSense e possui logo em SVG nos arquivos:

• frontend/public/brand-mark.svg
• frontend/public/logo-datasense.svg

Deploy

Backend no Render

O arquivo render.yaml define a API como um Web Service Python:

• Build: pip install -r requirements.txt
• Start: uvicorn app.main:app --host 0.0.0.0 --port $PORT
• Health check: /health

Para ativar IA em producao, configure no Render, dentro do Web Service da API:

• OPENROUTER_API_KEY: chave do OpenRouter.
• OPENROUTER_MODEL: modelo padrao, por exemplo openai/gpt-4o-mini.
• OPENROUTER_TIMEOUT_SECONDS: 12.
• OPENROUTER_SITE_URL: URL publica do frontend.
• OPENROUTER_APP_TITLE: DataSense.
• DATASENSE_MANAGERIAL_AI_ENABLED: true para ativar a segunda leitura gerencial por IA.

Frontend na Vercel

Configure a Vercel com root directory frontend e defina a variavel:

• VITE_API_BASE_URL: URL publica da API no Render

Deploy atual:

• https://data-sense-three.vercel.app/

Formatos aceitos

• CSV (.csv)
• TSV (.tsv)
• TXT delimitado (.txt)
• Excel (.xlsx e .xls)
• JSON tabular (.json)

O limite inicial de upload e de 15 MB.

Dataset demonstrativo

Use os arquivos:

• data/sample/vendas_demo.csv
• data/sample/vendas_demo.xlsx
• data/sample/compras_demo.csv
• data/sample/compras_demo.xlsx
• data/sample/clientes_demo.json
• data/sample/estoque_financeiro_demo.tsv

Eles possuem dados ficticios de vendas, compras, clientes e estoque/financeiro. O frontend tambem publica esses arquivos em frontend/public/samples, permitindo carregar exemplos diretamente pela interface.

Perguntas uteis para teste:

• Mostre vendas por mes.
• Top 5 produtos por faturamento.
• Top 5 fornecedores por compras.
• Mostre compras por mes.
• Mostre clientes por receita.
• Mostre valor_total por produto.

Status

Fase atual: MVP demonstravel em refinamento, com foco em clareza de produto, leitura orientada para decisao e experiencia pronta para portfolio, demo e primeiras apresentacoes.

Ja possui:

• upload por clique ou arrastar/soltar;
• leitura de CSV/Excel/TSV/TXT/JSON;
• onboarding inicial com exemplos prontos;
• perfil automatico do dataset;
• diagnostico gerencial e comparativos mensais;
• dashboard automatico personalizavel com filtros globais;
• historico local;
• auditoria de qualidade;
• chat analitico;
• exportacao de relatorio em PDF/PNG e pacote Power BI.

Contribuindo e licenca

• Convencao de commits e fluxo de trabalho: veja CONTRIBUTING.md.
• Distribuido sob a licenca MIT.