🌐 English readers: this document is in PT-BR, but your browser can translate it automatically (right-click → "Translate").

Motor de triagem inteligente de bugs desenvolvido para Engenharia de Garantia de Qualidade (QA). Ele combina processamento de linguagem natural (NLP) com lógica de regras para priorizar automaticamente relatos de erros e gerar documentação técnica em formato Gherkin — pronto para copiar para Jira ou GitHub Issues.

⭐ Se esta triagem te ajudou, dá uma estrelinha no projeto — quanto mais estrelas, mais QAs encontram o app na busca do GitHub. É de graça!

---

• 🔵 Triagem em duas camadas
  1. Camada técnica: termos críticos (crash, pagamento, login, segurança, 500...) escalam a severidade.
  2. Camada NLP: análise de sentimento por léxico em português + detecção de negação ("não funciona", "não consigo", "parou de responder"...) + padrões por raiz (regex) — lentidão dispensa enumerar toda flexão (lento, lenta, lentíssimo, lentamente...) e o lookahead (?!es?\b) exclui o falso positivo lente/lentes.
• 🟣 Análise por IA (Fase 3): se houver chave GEMINI_API_KEY e o checkbox 🔮 estiver marcado, o app chama o Google Gemini e complementa a triagem com severidade sugerida, categoria, causa raiz provável, passos para reproduzir e resumo técnico — tudo em JSON estruturado, com fallback automático para o motor local se a API falhar (ou se o usuário desligar a IA para aquela triagem).
• 🟢 Prioridade final reconciliada: os dois motores são combinados pela regra do maior vence (nenhum alerta grave é ignorado) e o app sinaliza divergência quando discordam, recomendando revisão humana.
• ⚠️ 100% offline e determinístico: o motor triagem.py usa apenas a biblioteca padrão do Python — sem API de tradução, sem internet, sem custo e com resultado sempre reproduzível.
• 🔷 Transparência de QA: o relatório informa o motor de análise usado e os fatores identificados em cada triagem.
• 💚 Relatório Gherkin (Dado/Quando/Então) baseado na prioridade detectada.
• 🟠 Exportação: baixar relatório (.md), abrir Issue no GitHub pré-preenchida ou criar issue real no Jira via API (com prioridade mapeada automaticamente).
• ⚪ Histórico da sessão em tabela (pandas) com opção de limpar.
• 📁 Histórico persistido (JSONL local + ☁️ Supabase) — cada triagem vira um snapshot fiel em data/historico.jsonl (local, gitignored); quando o Supabase está configurado (URL + anon key nos secrets), o histórico passa a viver na nuvem e sobrevive a redeploys (com failover automático pra JSONL se a nuvem cair). Seletor de data + download do relatório em Markdown + vínculo com a issue criada no Jira. Backend visível no expander do histórico.
• 🛡️ Guardrails de entrada/saída (PII) — detecta e mascara token Atlassian, chaves Gemini/Google/OpenAI, tokens GitHub, e-mails, senhas numéricas, telefones e CPFs digitados no relato: nada sensível vai para o Gemini, o Jira, o GitHub ou o histórico.
• 🧪 88 testes + CI — suíte pytest (motor, Jira, persistência, guardrails, dashboard, RAG e nuvem) rodando a cada push via GitHub Actions (badge de qualidade em cima).
• 📈 Dashboard de QA — visão geral 100% local do histórico persistido: KPIs (total, CRÍTICAs, MÉDIAS, normais, score médio), distribuição de severidade, volume por dia, funcionalidades mais afetadas e comparativo IA vs. motor local (divergências).
• 📚 RAG no histórico — o Gemini consulta as triagens passadas (retrieval local por similaridade Jaccard) e responde se o problema já aconteceu e como foi resolvido antes, apontando os registros similares. Depois de resolver o bug, registre a solução no app — vira aprendizado para as próximas triagens similares.
• 🟫 Sem falsos positivos técnicos: palavras como erro, bug e falha são vocabulário normal de teste e não disparam severidade sozinhas.
• 🟥 Interface com identidade visual própria (tema Streamlit em config.toml).

---

• 🐍 Python 3.13 — lógica e motor NLP (biblioteca re / stdlib)
• 🚀 Streamlit 1.62 — interface web e deploy na nuvem
• 🔮 Google Gemini (google-genai) — análise de causa raiz via LLM (Fase 3)
• 🐼 pandas — tabela de histórico de triagens
• 🐧 Desenvolvido em Linux Mint Debian (Laboratório Hack28)

---

git clone https://github.com/Iago3-stack/ai-bug-triage-system.git   # 📥 clona o repo
cd ai-bug-triage-system                                             # 📂 entra na pasta
python3 -m venv .venv                                                # 🐍 cria o ambiente virtual
source .venv/bin/activate                                            # ⚡ ativa o venv
pip install -r requirements.txt                                      # 📦 instala as dependências
streamlit run home.py                                                # 🚀 roda a aplicação

A análise por IA usa a chave GEMINI_API_KEY (gratuita em aistudio.google.com/apikey). Sem a chave, o app funciona normalmente só com o motor local:

• 🔑 Local: crie um arquivo .env na raiz com GEMINI_API_KEY=... (ele é ignorado pelo .gitignore).
• ☁️ Streamlit Cloud: Settings → Secrets → GEMINI_API_KEY (nunca coloque a chave em código ou no repositório).

🔗 Exportação para o Jira (API REST)

O botão 📋 Exportar para Jira cria a issue do tipo Tarefa direto no seu projeto Jira Cloud. Você configura de dois jeitos:

• 🖱️ Pela interface: no app, abra 🔑 Jira — configurar exportação no sidebar e preencha e-mail Atlassian, API Token e chave do projeto. Basta login+token (Basic Auth) — não é preciso OAuth nem senha.
• ⚙️ Por variáveis de ambiente (.env ou Streamlit Secrets): JIRA_EMAIL, JIRA_API_TOKEN, JIRA_PROJECT_KEY e, opcionalmente, JIRA_URL (padrão https://iagoqa.atlassian.net).

🔑 Para gerar o API Token: acesse https://id.atlassian.com/manage-profile/security/api-tokens → Create API token → copie o token (ele só aparece uma vez). A chave do projeto (ex.: KAN para "Rastreamento de bugs") aparece na URL do seu projeto: https://iagoqa.atlassian.net/browse/KAN-4 → KAN.

Tipo de item (importante): o app assume Tarefa por padrão (compatível com projetos Kanban, onde Bug não existe). Os tipos válidos do template Kanban são: Tarefa, História, Epic, Subtask. Para outro projeto, troque via JIRA_ISSUE_TYPE.

Prioridades mapeadas automaticamente: NORMAL ✅ → Low · MÉDIA ⚠️ → Medium · ALTA 🚨 → High · CRÍTICA 🚨 → Highest.

🧪 Teste rápido do cliente sem interface (python jira_client.py) — exige as credenciais no ambiente:

python jira_client.py   # 🧪 cria uma issue de teste via API

🧪 Teste rápido dos motores sem interface:

python triagem.py   # 🟢 motor determinístico local
python ia.py        # 🔮 análise por IA (Gemini) — exige a chave

---

🧩 Conheça a engenharia por trás do AI Bug Triage System — o processo completo de requisitos, casos de teste e estratégia de QA está em 📚 docs/.

Arquivo	Papel
🖥️ home.py	Interface web (Streamlit): cabeçalho, ferramenta, export e histórico
🧠 triagem.py	Motor NLP: léxico PT, padrões de negação e classificação de severidade (offline)
🔗 jira_client.py	Cliente da API REST v3 do Jira: cria issues (Tarefa) com prioridade mapeada
🔮 ia.py	Análise por IA via Google Gemini: causa raiz, categoria e passos (com fallback)
📚 rag.py	RAG leve no histórico: retrieval por similaridade Jaccard (offline) + geração que responde "já aconteceu? como resolvemos?"
🧪 test_triagem.py	18 testes unitários do motor (rodam no CI)
🧪 test_jira_client.py	15 testes unitários do cliente Jira (rodam no CI)
📁 persistencia.py	Histórico em data/historico.jsonl (JSONL local, gitignored) — facade: com nuvem configurada, grava no Supabase; senão, JSONL puro
☁️ nuvem_supabase.py	Backend de persistência na nuvem (Supabase REST): insert/select/update e vínculo Jira — credenciais só em secrets/.env
🛡️ guardrails.py	Bloqueia vazamento de credenciais/PII: mascara tokens, chaves, e-mails, senhas numéricas, telefones e CPFs antes de IA/Jira/GitHub/histórico
🧪 test_persistencia.py	8 testes unitários da persistência (rodam no CI)
🧪 test_guardrails.py	14 testes de detecção/máscara de credenciais e PII (rodam no CI)
🧪 test_dashboard.py	6 testes das agregações do Dashboard de QA (rodam no CI)
🧪 test_rag.py	13 testes do RAG: tokenização, similaridade, recuperação top-k, contexto (com resolução) e orquestração (rodam no CI)
🧪 test_nuvem_supabase.py	14 testes da persistência em nuvem: config, conversão, HTTP (mockado), resolução, failover e dispatch do facade (rodam no CI)
📈 dashboard.py	Dashboard de QA: KPIs + severidade + volume/dia + funcionalidades + IA vs. léxico (leitura do JSONL)
📦 requirements.txt	Dependências pinadas
🎨 .streamlit/config.toml	Tema e configurações da app
📚 docs/	Documentação de engenharia e qualidade

---

• ✅ Fase 1 — Motor NLP offline (léxico PT + negação, sem TextBlob/Google Translate)
• ✅ Fase 2 — Exportação do relatório, histórico de sessão e identidade visual
• ✅ Fase 3 — Integração com LLMs (Gemini) para análise de causa raiz, categoria e passos — com fallback automático
• ✅ Seletor de IA por triagem (checkbox 🔮) — você decide quando o Gemini entra: desligue para triagem 100% local ou ligue para ganhar causa raiz e passos
• ✅ Testes unitários do motor (pytest) — 88 testes (motor + Jira + persistência + guardrails + dashboard + RAG + nuvem), rodam automaticamente via CI (GitHub Actions)
• ✅ Exportação via API do Jira — cria issue do tipo Tarefa no iagoqa.atlassian.net (prioridade mapeada automaticamente)
• ✅ Persistência do histórico (JSONL) — cada triagem vira um snapshot fiel em data/historico.jsonl (local, gitignored): com IA salva o relatório completo; sem IA, só o léxico. Seletor de data + download do relatório
• ✅ Guardrails de entrada/saída (PII/credenciais) — detecta e mascara tokens Atlassian, chaves Gemini/Google/OpenAI, tokens GitHub, e-mails, senhas numéricas, telefones e CPFs digitados no relato: nada sensível vai para o Gemini, o Jira, o GitHub ou o histórico
• ✅ Dashboard de QA — visão geral do histórico persistido: KPIs, distribuição de severidade, volume por dia, funcionalidades mais afetadas e comparativo IA vs. motor local (100% local, sem enviar nada)
• ✅ RAG no histórico — o Gemini consulta as triagens passadas (top-k similares, retrieval local por Jaccard) e responde "isso já aconteceu? como resolvemos?" com a resolução anterior; se não acha, sinaliza caso novo
• • ✅ Roadmap 10/10 🎉 — MVP concluído; próximos passos rumo ao SaaS abaixo

🚀 Rumo a um SaaS de QA (roadmap futuro):

Depois de esgotar o MVP, a visão é evoluir para um produto tipo SaaS/CRM de triagem:

• ☁️ Persistência em nuvem (Supabase/Postgres) — histórico real entre sessões (hoje o disco da nuvem é efêmero)
• 🔐 Autenticação (login) — cada usuário vê só o seu histórico (multi-tenant)
• 🧠 Causa raiz com histórico (evolução do RAG ✅) → sugerir a correção que resolveu da última vez → triage agent
• 🔁 Modelos alternativos (Groq/Llama-Ollama) no mesmo ia.py, sem depender só do Gemini
• 🔔 Notificações (Slack/Discord/e-mail) em CRÍTICA · 🌐 webhook/API · 📧 relatório agendado · 📊 LLMOps/evals Roadmap completo acompanhado no brainstorming do projeto (~/Documentos/roadmap-ia.md).

---

🧑‍💻 Autor: Iago Nunes (Iago3-stack) — QA Automation Engineer | Estudante de IA & Machine Learning na UNIASSELVI.

📜 Este projeto é distribuído sob a licença MIT (ver arquivo LICENSE). Qualquer uso, cópia ou modificação deve manter a atribuição de crédito ao autor original — remover ou ocultar a autoria viola a licença. Veja AUTORIA.md para a origem e as provas públicas de autoria.

🕓 O histórico completo de construção (commits, datas e motivações) está público em github.com/Iago3-stack/ai-bug-triage-system.