🏢 Groq Business Finder & Phone Scraper

Uma solução automatizada e com arquitetura escalável para prospecção de negócios (Leads) utilizando a inteligência artificial da Groq aliada a técnicas avançadas de Web Scraping.

🎯 Visão Geral

Este projeto recebe o nome de um mercado, setor comercial ou nicho (ex: "Clínicas Odontológicas em São Paulo") e realiza duas operações de forma assíncrona:

1. LLM Search: Consulta a API da Groq (Llama-3) orientando a inteligência a retornar um conjunto de empresas reais com seus respectivos websites devidamente estruturados.
2. Deep Scraping: Realiza acessos automatizados (com HTTP timeout safety) a esses domínios em busca de meios de contato telefônico ativo, focando nativamente na captação de links de redirecionamento (WhatsApp APIs) e expressões regulares rigorosas na árvore do HTML (Telefones comerciais).

Tudo isso encapsulado sobre uma interface gráfica rica e responsiva, operando sem o clássico problema de travamento de janela graças à manipulação "Thread-safe" da UI. O executável também conta com Atualização Automática transparente via GitHub Releases.

🏗️ Arquitetura do Projeto

O código foi inteiramente refatorado respeitando o SoC (Separation of Concerns) — permitindo sustentabilidade a longo prazo:

📦 Phone-Receiver
┣ 📂 src/
┃ ┣ 📂 services/
┃ ┃ ┣ 📜 ai_service.py       # Camada LLM: Conexão Groq, Prompts Inteligentes e Parsing de JSON
┃ ┃ ┣ 📜 scraper_service.py  # Camada Web: Requisições (requests), Análise DOM (bs4) e Regex
┃ ┃ ┗ 📜 updater_service.py  # Camada de Auto-Update: Consome API do GitHub para baixar novas releases
┃ ┗ 📂 ui/
┃   ┗ 📜 app_window.py       # Camada de Apresentação: Layout Tkinter seguro, Threads e Callbacks
┣ 📂 tests/                  # Suíte de testes automatizados unitários (Pytest)
┣ 📜 main.py                 # Application Entrypoint (Iniciador limpo)
┣ 📜 requirements.txt        # Gerenciamento de dependências com travas de versão estável
┗ 📜 README.md               # Documentação corporativa do sistema

🚀 Tecnologias Integradas

• Python 3.13+
• Tkinter/TTK (Interface Nativa Padrão OS)
• Groq API (groq SDK oficial para inferência ultrarrápida do modelo llama-3.1-8b-instant)
• Keyring (Armazenamento seguro de chaves usando o cofre de credenciais nativo do OS)
• BeautifulSoup4 & Requests (Análise sintática do DOM e HTTP Client)
• PyInstaller & GitHub Actions (Pipeline CI/CD completo para builds multiplataforma Windows/macOS/Linux)
• Pytest (Testes unitários e mocks rigorosos)

⚙️ Instalação e Execução Local

1. Clonando o repositório

git clone https://github.com/schulzdimitri/LeadFinder.git
cd LeadFinder

2. Configurando o Ambiente Virtual Recomendado

Visando separar as dependências do Host OS, utilize o módulo venv ou uv:

python3 -m venv .venv
source .venv/bin/activate   # Para uso no Linux e macOS
# .venv\Scripts\activate    # Para uso no Microsoft Windows

3. Instalando as Dependências

pip install -r requirements.txt

4. Executando a Aplicação

python3 main.py

5. Executando os Testes (Opcional)

PYTHONPATH=. pytest tests/ -v

🔐 Uso e Configuração Segura

Você precisará de uma Chave API da Groq para validar as consultas de infraestrutura do provedor LLM.

1. Crie uma conta de desenvolvedor no Groq Console
2. Acesse a aba API Keys e clique em Create API Key.
3. Copie o valor numérico longo (obrigatoriamente começando com a sintaxe gsk_...).
4. Rode a aplicação e cole a chave no campo designado. A chave será salva criptografada usando o Cofre Seguro do seu Sistema Operacional (Keyring). Das próximas vezes que o app abrir, ele lembrará a chave de forma segura!

🔄 Sistema de Auto-Updater Integrado

A partir da versão v1.0.0+, o software é distribuído com sistema de atualização contínua. Ao abrir o app, a interface roda uma thread que se comunica com o GitHub para verificar a existência de novas Tags. Se aprovado pelo usuário, ele baixa e substitui os binários sem dor de cabeça — seja num .exe executável no Windows ou pacote .app no macOS!

⚠️ Erros Comuns e Tratamento

• Error code: 401 - Invalid API Key: Certifique-se de que não faltam caracteres na sua chave recém copiada. Chaves que recém foram criadas podem levar alguns segundos extras para serem processadas globalmente pelos servidores Groq.
• Erro de Threads - macOS: A aplicação já foi corrigida a nível do Tkinter (self.after()) mitigando bugs clássicos onde a Thread secundária tentava manipular visualmente o layout primário.

⚖️ Aviso Legal (Disclaimer)

Este repositório tem escopo educacional e corporativo. Técnicas de Web Scraping operam navegando sites aleatoriamente de forma não interativa. Todas as extrações devem obedecer à lei de proteção de dados regional em vigor (LGPD/GDPR), resguardar direitos privados dos desenvolvedores dos e-commerce investigados e respeitar as sinalizações e políticas descritas no robots.txt de domínio de terceiros.