Evolution API + MLX Summarization

Ferramenta CLI para capturar mensagens do WhatsApp via Evolution API, processar mídias (áudio/imagem) localmente com MLX (Apple Silicon) e gerar atas e resumos inteligentes.

Estrutura do Projeto

project/
├── .env                 # Configurações (Crie a partir do exemplo)
├── requirements.txt     # Dependências Python
├── app/
│   ├── main.py          # Ponto de entrada da CLI (Typer)
│   ├── evolution_client.py # Cliente da API Evolution
│   ├── media_pipeline.py   # Processamento MLX (Whisper, VLM, LLM)
│   └── ...
├── assets/              # Fallback local para mídias expiradas (opcional)
└── data/                # Arquivos gerados (messages.txt, ata.md, etc)

Pré-requisitos

• Python 3.10+
• macOS com Apple Silicon (M1/M2/M3)
• Ambiente Conda (recomendado)
• Evolution API rodando e configurada

Instalação

1. Crie e ative o ambiente:

   conda create -n mlx python=3.11
   conda activate mlx

2. Instale as dependências:

   pip install -r requirements.txt

   Nota: O ffmpeg é necessário para o Whisper. Instale com brew install ffmpeg se ainda não tiver.

3. Configure o ambiente: Edite o arquivo .env com suas credenciais da Evolution API e datas desejadas. Para OCR de PDFs (documentMessage), configure também MISTRAL_API_KEY.

Uso

A ferramenta possui comandos para configurar o chat alvo, capturar mensagens e gerar relatórios. Execute a partir da raiz do projeto:

0. Configurar Chat Alvo (JID)

Busca interativamente o JID de um contato ou grupo e salva no .env.

# Listar todos os chats (com paginação)
python -m app.main set-jid

# Buscar por nome ou número
python -m app.main set-jid "Nome do Grupo"

1. Configurar Intervalo de Datas

Define interativamente o início e fim da busca de mensagens.

python -m app.main set-time

2. Exportar Mensagens

Busca mensagens, transcreve áudios, descreve imagens e extrai texto de PDFs (Mistral OCR).

python -m app.main export
# Ou com opções
python -m app.main export --start 2025-01-01 --end 2025-01-07 --limit 1000

--limit define o tamanho do lote por requisição na API (paginação), não um teto global.

Se a mídia estiver expirada na Evolution API (link mmg expirado), o export tenta fallback local em assets/ pelo ID da mensagem:

assets/3EB075519BBFD00B86C135.pdf
assets/3EB0D9FEB1836A82B187E4.pdf
assets/ACCC398DA97ACC0B2C2E6A6D04ECA44C.mp3

Extensões comuns:

• imagem: .jpg, .jpeg, .png, .webp
• áudio: .ogg, .mp3, .wav, .m4a
• documento: .pdf, .docx, .doc, .txt

No fetch remoto, são feitas até 3 tentativas antes de usar fallback local.

2. Gerar Ata

Lê o arquivo exportado e gera uma ata em Markdown.

python -m app.main minutes

3. Gerar Resumo WhatsApp

Lê o arquivo exportado e gera um resumo em tópicos com emojis.

python -m app.main summary

Personalização

• Modelos: Altere os modelos MLX no arquivo .env (WHISPER_MODEL, LLM_MODEL_TEXT, etc).
• OCR de documentos: configure MISTRAL_API_KEY, MISTRAL_OCR_MODEL e MISTRAL_OCR_MAX_CHARS no .env.
• Descrição de imagem truncada: aumente LLM_MAX_TOKENS_IMAGE_DESCRIPTION no .env.
• Prompts: Edite app/prompts_ptbr.py para ajustar o estilo dos resumos.