EmailClassifier

Aplicação web para classificação inteligente de e-mails corporativos. O sistema analisa a intenção da mensagem, identifica ações pendentes e gera uma resposta curta, profissional e relacionada ao contexto principal.

Funcionalidades

• Classificação em Produtivo, Improdutivo ou Indeterminado.
• Priorização de problemas, solicitações, cobranças, acessos e entregas sobre elogios ou avisos sociais.
• Detecção de ironia em relatos de falhas técnicas.
• Extração de entidades como chamados, documentos, planilhas, drive, reuniões, prazos e sistemas.
• Respostas específicas para incidentes, integrações, documentos, acessos, follow-ups e dúvidas.
• Remoção de Markdown e emojis decorativos das respostas.
• Validação de textos sem contexto, metalinguísticos ou sem sentido.
• Interface React responsiva com design editorial.
• Testes automatizados do motor de classificação e da API Flask.

Tecnologias

Backend

• Python
• Flask
• Flask-CORS
• NLTK
• Requests
• Hugging Face
• Ollama local

Frontend

• React 19
• Vite
• JavaScript
• CSS

O provider padrão é local e determinístico. Nenhum serviço pago é necessário para executar o projeto.

Estrutura

emailclassifier/
├── app.py
├── backend/
│   ├── .env.example
│   ├── requirements.txt
│   ├── runtime.txt
│   ├── src/
│   │   ├── controllers/
│   │   ├── models/
│   │   ├── services/
│   │   └── utils/
│   └── tests/
├── emailfrontend/
│   ├── index.html
│   ├── package.json
│   └── src/
├── vercel.json
└── README.md

Pré-requisitos

• Python compatível com o ambiente configurado em backend/runtime.txt.
• Node.js e npm.
• Git, caso o projeto seja clonado de um repositório.

Configuração do backend

Na raiz do projeto, crie e ative um ambiente virtual:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instale as dependências:

pip install -r backend\requirements.txt

Copie o arquivo de exemplo:

Copy-Item backend\.env.example backend\.env

Por padrão, o backend usa o motor local:

AI_PROVIDER=local
ENABLE_HUGGINGFACE=False
FALLBACK_TO_LOCAL=True

Providers opcionais

Para usar Ollama instalado localmente:

AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2:3b

Para habilitar Hugging Face, é necessário configurar explicitamente uma chave própria e aceitar o uso de um serviço externo:

AI_PROVIDER=huggingface
ENABLE_HUGGINGFACE=True
HF_API_KEY=sua-chave

Executar o backend

Na raiz do projeto:

.\.venv\Scripts\Activate.ps1
python app.py

Por padrão, a API fica disponível em:

http://localhost:8080

Endpoints principais:

POST /api/classificar
GET  /api/health
GET  /api

Exemplo de requisição:

{
	"texto": "O sistema de pagamentos está fora do ar e preciso de ajuda."
}

Executar o frontend

Em outro terminal:

cd emailfrontend
npm install
npm run dev

Acesse:

http://localhost:5173

O frontend usa /api/classificar por padrão. Para executar frontend e backend em portas separadas durante o desenvolvimento, defina VITE_API_URL no ambiente do frontend:

VITE_API_URL=http://localhost:8080/api/classificar

Comandos disponíveis:

npm run dev
npm run build
npm run lint
npm run preview

Testes

Na raiz do projeto:

.\venv\Scripts\Activate.ps1
python -m unittest discover -s backend\tests -p "test_*.py" -v

Os testes cobrem classificação, mensagens mistas, ironia, entidades, respostas contextuais, providers, validação de entrada e contrato HTTP da API.

Fluxo de classificação

1. O controller valida o corpo da requisição e o tamanho do texto.
2. O AIService rejeita conteúdo sem contexto ou metalinguístico como Indeterminado.
3. O pipeline extrai tom, ironia, intenção, entidades e ações pendentes.
4. Problemas e ações operacionais têm prioridade sobre interações sociais.
5. O sistema tenta o provider configurado, quando habilitado.
6. Respostas genéricas ou inválidas são rejeitadas.
7. O fallback local gera uma resposta contextual sem custo externo.