BI Dashboard Agent
Agente de Business Intelligence que transforma planilhas em dashboards profissionais com
KPIs, gráficos e insights gerados por IA.
Demo: https://bi-agent-rosy.vercel.app
Anti-alucinação por design. Todos os números vêm do Pandas (determinístico).
O LLM recebe o perfil estatístico já calculado e apenas interpreta — nunca calcula.
Stack
- Backend: FastAPI + Pandas + NumPy + SciPy
- LLM: Groq (primário) → Google Gemini (fallback), com retry e troca automática de modelo
- Frontend: Next.js 16 (App Router, TypeScript, Tailwind 4, Recharts)
Arquitetura
bi-dashboard-agent/
├── backend/
│ ├── main.py # Endpoints FastAPI, CORS, rate limit, cache
│ ├── analyzer.py # Perfil estatístico com Pandas
│ ├── dashboard_planner.py # Regras de seleção de KPIs e gráficos
│ ├── llm.py # Cadeia multi-provider Groq → Gemini
│ ├── prompts.py # System prompts do agente BI (pt-BR)
│ ├── filters.py # Aplicação de filtros no DataFrame
│ ├── cache.py # Persistência em disco (JSON por file_id)
│ ├── pdf_export.py # Playwright → PDF (endpoint legado)
│ └── tests/ # 26 testes pytest
└── frontend/
└── src/
├── app/ # / · /history · /report/[fileId]
├── components/ # Upload, KPICard, ChartBlock, Chat, FilterBar, ...
└── lib/api.ts # Cliente REST tipado
Documentação completa em docs/ — comece por
docs/00_CONTEXT.md.
Setup
1. Backend
cd backend
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
pip install -r requirements.txt
copy .env.example .env # preencha GROQ_API_KEY e/ou GOOGLE_API_KEY
python main.py
Backend sobe em http://127.0.0.1:8000. Valide em /health.
Chaves (ao menos uma é necessária):
2. Frontend
cd frontend
npm install
# crie .env.local com:
# NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
npm run dev
Frontend em http://localhost:3000.
Guia detalhado, com validação e erros comuns, em docs/03_SETUP.md.
Fluxo
- Upload de
.csv, .xlsx, .xls, .xlsm ou .tsv (máx. 50 MB)
/analyze → perfil estatístico (tipos, nulos, quartis, correlação, outliers) +
plano de dashboard por regras- A interface renderiza KPIs e gráficos (bar, line, pie, scatter, boxplot) + heatmap de
correlação
- Gerar insights → análise em 5 seções via streaming SSE
- Chat para perguntas ad-hoc, ciente dos filtros ativos
- Filtros (
in, range, eq) recomputam perfil, KPIs e gráficos
- Drill-down: clique em uma barra para ver as linhas por trás, com export CSV
- Baixar PDF: abre o relatório em A4 paisagem e o diálogo de impressão
Endpoints
| Método | Rota | Uso |
|---|
| GET | /health | Status, versão, uptime, arquivos em cache |
| POST | /upload | Envia planilha, retorna file_id |
| POST | /analyze/{file_id} | Perfil + plano de dashboard |
| GET | /analyze/{file_id} | Recupera análise em cache |
| POST | /analyze/{file_id}/filtered | Reanálise sobre subconjunto filtrado |
| GET | /files · DELETE /files/{id} | Lista e remove análises |
| GET | /report_data/{file_id} | Dados da página de relatório |
| POST | /drill/{file_id} | Linhas por trás de um ponto do gráfico |
| POST | /insights_stream/{file_id} | Insights via SSE |
| POST | /chat_stream/{file_id} | Chat via SSE |
| GET/POST | /suggestions/{file_id} | 4 perguntas sugeridas |
| POST | /export/{file_id} | PDF via Playwright (legado — sem uso no frontend) |
Contratos completos em docs/08_API.md.
Testes
cd backend
pytest
26 testes cobrindo a cadeia de LLM (retry, fallback, detecção de erro transitório,
normalização entre providers), filtros com recomputação de perfil, detecção de data e
agregação por grupo. Rodam no CI a cada push (GitHub Actions).
Smoke test manual em docs/10_TESTING.md.
Deploy
| Componente | Plataforma | Configuração |
|---|
| Frontend | Vercel | Root frontend/, deploy automático a cada push em main |
| Backend | Railway (Dockerfile pronto) ou local + túnel Cloudflare | Root backend/ |
Guia passo a passo em DEPLOY.md.
NEXT_PUBLIC_API_URL é lida em tempo de build. Alterá-la no Vercel exige um
redeploy para ter efeito.
Documentação
Licença
MIT
