josias 0.3.2

Biblioteca Python avançada para automação de interface gráfica com OCR e processamento de imagem avançado

Josias 🤖✨

Josias é uma nova e avançada ferramenta em Python para automação de interface gráfica (RPA / GUI Automation). Ela foi projetada para resolver os principais problemas de automação visual tradicional: rigidez de resolução, travamento de mouse físico, falta de rastreabilidade em falhas de OCR e instabilidade em sistemas que exigem recuperação de erros.

Combinando Tesseract OCR avançado, 19 filtros de pré-processamento de imagem em tempo real, detecção de escala dinâmica e cliques virtuais não-intrusivos (Win32 API), a Josias garante automações robustas e resilientes.

---

📖 Sumário

1. Prerrequisitos & Instalação
2. Arquitetura & Configuração
3. Localização e Cliques de Imagem (Escala Dinâmica)
4. Reconhecimento Óptico de Caracteres (OCR Inteligente)
5. Localização Relativa (Âncora + Alvo)
6. Gerenciador de Espera Inteligente (Smart Wait)
7. Controle de Teclado e Atalhos
8. Mouse Virtual Win32 (Segundo Plano)
9. Sistema de Overlays Visuais (Destaques na Tela)
10. Mecanismo de Backtracking (Recuperação de Falhas)
11. Depurador Visual de OCR (Visual Debug Dump)
12. Interface de Linha de Comando (CLI)
13. Automação Web
14. Automação Desktop
15. Utilitário de Limpeza (Cleaner)

---

📦 Prerrequisitos & Instalação

1. Instalando o Tesseract OCR (Obrigatório)

A biblioteca requer o executável do Tesseract instalado na máquina para realizar as operações de OCR.

• Windows: Baixe o instalador de 32 ou 64 bits em UB-Mannheim Tesseract Wiki. Instale no caminho padrão: C:\Program Files\Tesseract-OCR\.
• Linux (Ubuntu/Debian): sudo apt-get update && sudo apt-get install tesseract-ocr tesseract-ocr-por
• macOS: brew install tesseract

[!NOTE] Por padrão, a biblioteca Josias busca o executável automaticamente no caminho C:\Program Files\Tesseract-OCR\tesseract.exe. Caso tenha instalado em outro diretório, veja a seção de configurações abaixo.

2. Instalando a Biblioteca

Navegue até a pasta raiz da biblioteca no terminal e instale-a localmente em modo editável:

pip install -e .

---

⚙️ Arquitetura & Configuração

O comportamento da biblioteca pode ser configurado de três formas complementares, respeitando a seguinte ordem de prioridade (a mais alta sobrescreve as anteriores):

1. Parâmetros passados diretamente na inicialização da classe Josias(config_dict).
2. Variáveis de ambiente com o prefixo JOSIAS_.
3. Arquivo de configuração de projeto (.josias.json, .josias.yaml ou .josias.yml) no diretório atual de execução.
4. Valores padrões internos da biblioteca.

Exemplo de arquivo .josias.json (no diretório de trabalho do seu robô):

{
  "tesseract_path": "C:\\Program Files\\Tesseract-OCR\\tesseract.exe",
  "confidence_threshold": 75.0,
  "use_virtual_mouse": true,
  "debug_ocr": true,
  "debug_ocr_dir": "logs_ocr_debug",
  "show_overlay": true,
  "overlay_color": "blue"
}

Exemplo de uso via Variáveis de Ambiente (Terminal):

set JOSIAS_USE_VIRTUAL_MOUSE=True
set JOSIAS_DEBUG_OCR=True
python meu_robo.py

Inicialização em Python:

from josias import Josias

# Sem argumentos: carrega arquivo .json/.yaml automaticamente ou usa os padrões do sistema
bot = Josias()

# Com argumentos explícitos:
custom_bot = Josias({
    "confidence_threshold": 80.0,
    "overlay_color": "green",
    "wait_timeout": 15
})

---

🖼️ Localização e Cliques de Imagem (Escala Dinâmica)

A detecção de imagens da biblioteca Josias possui tolerância a variações de escala (quando um elemento muda levemente de tamanho devido à resolução do monitor).

Métodos Principais:

• find_image(image_path, region=None, confidence=0.9, max_attempts=3, specific=True, wait_until_found=False, wait_until_disappears=False, wait_timeout=None, scales=None)
• click_image(image_path, ...) (Aceita os mesmos parâmetros de busca + ações do mouse)

Parâmetros Importantes:

• specific: Se True (padrão), procura a imagem apenas na escala nativa 1.0. Se False, testa múltiplas escalas paralelamente.
• scales: Lista de escalas numéricas para redimensionar o template durante a varredura (ex: [1.0, 0.95, 1.05]).
• mouse_button: 'left' (esquerdo), 'right' (direito), 'double' (duplo clique) ou 'move_to' (apenas posiciona).

Exemplo Didático:

# Clica em um botão na tela procurando em escala de 100%, 95% ou 105% de tamanho
# Se o botão não for encontrado imediatamente, tenta por até 3 vezes ajustando a confiança
bot.click_image(
    image_path="assets/btn_salvar.png",
    confidence=0.9,
    specific=False,
    scales=[1.0, 0.95, 1.05],
    mouse_button="double"
)

---

📝 Reconhecimento Óptico de Caracteres (OCR Inteligente)

Quando o elemento visual a ser interagido contém textos variáveis, o OCR é a melhor abordagem. Josias oferece controle avançado de Whitelist (filtragem de caracteres) para evitar leituras ambíguas.

Métodos Principais:

• find_text(text, region, filter_type="both", confidence_threshold=75.0, ...)
• click_text(text, region, ...)
• extract_text_from_region(region, filter_type="both", ...)

Filtros de Caracteres (filter_type):

• 'numbers': Limpa e valida apenas algarismos numéricos (0-9). Excelente para ler valores e códigos de barra.
• 'letters': Limpa e valida apenas caracteres alfabéticos (a-z, A-Z).
• 'both': Permite qualquer caractere alfanumérico (padrão).

Exemplo Didático:

# Procura e clica exclusivamente nos dígitos "12345" em uma região específica
# O filtro 'numbers' impede que sujeiras ou ruídos na tela gerem falsos positivos
sucesso = bot.click_text(
    text="12345",
    region=(200, 150, 300, 100),
    filter_type="numbers",
    confidence_threshold=80.0
)

---

📍 Localização Relativa (Âncora + Alvo)

Em muitas interfaces (como formulários do SAP ou Oracle), existem campos de input vazios que não possuem imagem estável ou texto para clicar diretamente. No entanto, eles estão sempre posicionados ao lado de um rótulo estático (a âncora).

Josias resolve isso calculando a distância Euclidiana entre uma âncora única e um elemento genérico.

# Localiza o rótulo estável ("rótulo_campo.png") e clica no campo de texto genérico ("campo_input.png")
# mais próximo, contanto que esteja a no máximo 150 pixels de distância
bot.click_relative_image(
    anchor_image="assets/lbl_nome.png",
    target_image="assets/input_vazio.png",
    max_distance=150,
    mouse_button="left"
)

---

⏳ Gerenciador de Espera Inteligente (Smart Wait)

Evite o uso de time.sleep() fixo em seus scripts. A Josias fornece rotinas de loop ativo não-bloqueante para aguardar condições visuais da tela.

Parâmetros de Espera Dinâmica:

• wait_until_found: Aguarda até o elemento aparecer na tela (timeout configurável).
• wait_until_disappears: Aguarda até que o elemento suma da tela (ex: barra de carregamento).
• wait_timeout: Tempo limite em segundos (se não informado, usa o valor da configuração).

Exemplos Didáticos:

# 1. Espera uma tela de carregamento sumir antes de prosseguir
bot.find_image("assets/loading_spinner.png", wait_until_disappears=True, wait_timeout=60)

# 2. Clica no botão "Confirmar" assim que ele aparecer na tela
bot.click_text("Confirmar", wait_until_found=True, wait_timeout=30)

---

⌨️ Controle de Teclado e Atalhos

Além de digitação caractere por caractere, Josias permite injetar atalhos de sistema e sequências de comandos complexas usando strings de formatação especial.

Comandos de Texto Especiais (sendtext):

Você pode embutir comandos de controle no início ou no meio do texto a ser digitado:

• {ctrl}a : Selecionar tudo
• {del} : Deletar seleção
• {tab} : Mover foco com Tab
• {enter} : Confirmar com Enter
• {backspace} : Apagar caractere
• {escape} : Pressionar ESC

Comandos de Atalhos Diretos (keyboard_command):

A Josias suporta mais de 100 atalhos mapeados de forma intuitiva, como Ctrl+S, F7, Alt+Tab, Print Screen etc.

Exemplos Didáticos:

# Clica no campo e limpa o valor existente antes de digitar
bot.click_text("Nome do Cliente", sendtext="{ctrl}a{del}Josias Silva{enter}")

# Executa um atalho de teclado direto
bot.keyboard_command("Ctrl+S") # Salva
bot.keyboard_command("F7")     # Executa comando de consulta

---

🖱️ Mouse Virtual Win32 (Segundo Plano)

Esta é uma das principais inovações da biblioteca. Ao configurar use_virtual_mouse: true, a biblioteca abandona as chamadas que deslocam o cursor físico do usuário.

Como funciona?

O Josias captura o manipulador da janela do Windows (Window Handle - HWND) posicionado sob as coordenadas do clique e posta mensagens Win32 diretamente na fila de eventos da aplicação alvo utilizando chamadas nativas em C (ctypes):

• WM_LBUTTONDOWN e WM_LBUTTONUP (Clique esquerdo)
• WM_RBUTTONDOWN e WM_RBUTTONUP (Clique direito)
• WM_MOUSEMOVE (Movimento de cursor)

Vantagens:

• Trabalho sem interrupções: Você pode continuar usando o mouse físico para navegar no navegador, responder chats ou redigir emails enquanto a automação clica silenciosamente no SAP, planilhas Excel ou sistemas ERP em segundo plano.
• Resolução de DPI automática: Ajusta automaticamente as coordenadas de clique conforme a escala de DPI configurada no monitor do Windows (96, 120, 144 DPI etc.).

# Inicializa o bot em modo não-intrusivo
bot = Josias({"use_virtual_mouse": True})

# O clique será enviado via Windows Message API.
# Seu cursor físico NÃO se moverá!
bot.click_text("Menu Principal")

---

🎨 Sistema de Overlays Visuais (Destaques na Tela)

Para facilitar a validação e auditoria em tempo real, a Josias exibe retângulos coloridos ao redor das áreas que estão sendo clicadas.

Como funciona o Fallback de Overlay?

1. Tkinter: Cria uma janela transparente sem bordas no topo da tela com crosshair (mira) centralizada no local exato do clique.
2. Windows GDI (Fallback): Caso o Tkinter falhe devido a restrições de ambiente, a biblioteca desenha o retângulo diretamente no Buffer de Tela da API gráfica do Windows (gdi32.dll) utilizando CreatePen, MoveToEx e LineTo, limpando a tela logo em seguida com InvalidateRect.
3. Console Log (Fallback final): Em ambientes sem interface (como servidores sem display), imprime as coordenadas no logger.

Customização e Teste:

# Altera a cor do retângulo para azul, com espessura de linha 6 pixels e duração de 1,5 segundos
bot.configure_overlay(enabled=True, color="blue", duration=1500, width=6)

# Abre uma demonstração visual desenhando na tela com todas as cores suportadas sequentially
bot.test_overlay_colors()

---

🔄 Mecanismo de Backtracking (Recuperação de Falhas)

Interfaces web e desktop podem oscilar de velocidade ou exibir popups inesperados. O sistema de backtrack garante que, caso a etapa N falhe, o robô retorne para a etapa N-1 para tentar reestabelecer o fluxo correto.

                  ┌──────────────────────┐
                  │   Etapa 1: Cadastro  │◄────────────────┐
                  └──────────┬───────────┘                 │
                             │ (Sucesso)                   │
                             ▼                             │ (Reexecuta anterior)
                  ┌──────────────────────┐                 │
                  │   Etapa 2: Clientes  │─────────────────┤
                  └──────────┬───────────┘ (Falha no click)│
                             │                             │
                             │ (Recuperado)                │
                             ▼                             │
                  ┌──────────────────────┐                 │
                  │ Etapa 3: Digitar Nome│─────────────────┘
                  └──────────────────────┘

Exemplo 1: Em lista de tarefas sequenciais (execute_tasks)

from josias import execute_tasks

# Se o robô não conseguir clicar na opção "Clientes" devido a lentidão do menu, 
# ele volta automaticamente e executa o clique em "Cadastros" novamente antes de tentar a etapa 2.
tarefas = [
    { 'text': 'Cadastros', 'region': (100, 100, 200, 50) },
    { 'text': 'Clientes', 'region': (100, 150, 200, 50), 'backtrack': True },
    { 'text': 'Adicionar', 'region': (100, 200, 200, 50), 'backtrack': True }
]

execute_tasks(tarefas)

Exemplo 2: Modo Sessão em código estruturado

Você pode ativar a pilha de backtrack dinamicamente em blocos de comandos normais:

bot.start_task_session()

# Etapa 1
bot.click_text("Configurações")
# Etapa 2: Se falhar em "Segurança", o bot reexecuta a Etapa 1 automaticamente
bot.click_text("Segurança", backtrack=True)

bot.end_task_session()

---

🔬 Depurador Visual de OCR (Visual Debug Dump)

Quando o OCR falha (não encontra o texto com a confiança mínima exigida) ou quando debug_ocr: true está ativo nas configurações, a Josias realiza uma análise forense do processo.

Estrutura da Pasta de Debug Gerada:

Uma pasta com a data, hora e o termo pesquisado será gerada em debug_ocr/ (ou na pasta que você configurou):

debug_ocr/
└── ocr_20260703_194512_Confirmar/
    ├── 00_original_crop.png       # Recorte da tela original enviada ao Tesseract
    ├── method_01_HSV_Enhancement.png  # Crop tratado com realce de saturação
    ├── method_03_Inversao_Fundo.png   # Crop tratado com inversão de texto claro
    ├── ... (até 19 variações de filtros)
    └── ocr_report.txt             # Relatório contendo informações analíticas

Exemplo de Conteúdo do ocr_report.txt:

====================================================
              JOSIAS OCR DIAGNOSTIC REPORT          
====================================================

Data/Hora: 2026-07-03 19:45:12
Texto Alvo: 'Confirmar'
Tipo de Filtro: 'both'
Limiar de Confiança Exigido: 75.0%

>>> ELEMENTO ESCOLHIDO <<<
Método de Imagem: HSV Enhancement (saturação aumentada) - PRIORITÁRIO (Index 1)
Configuração Tesseract: page_layout_psm6 (Config 3)
Texto Encontrado: 'Confirmar'
Confiança Final: 86.42%
Posição Relativa: (45, 12, 110, 25)

--- Histórico de correspondência encontrada ---
1. Metodo: 'HSV Enhancement...' | Config: 'page_layout_psm6' | Texto: 'Confirmar' | Confianca: 86.42%
2. Metodo: 'Inversão...' | Config: 'single_line_psm7' | Texto: 'Confrmar' | Confianca: 61.20%

Desta forma, se o robô falhar na leitura de um campo, você saberá exatamente qual filtro de imagem gerou a melhor legibilidade e poderá ajustar os parâmetros para a próxima execução.

---

💻 Interface de Linha de Comando (CLI)

Após instalar a biblioteca, a ferramenta josias estará disponível diretamente no terminal do seu ambiente virtual.

# 1. Verifica o status do sistema, executável do Tesseract e dependências do Windows
josias status

# 2. Testa e valida a integração direta do OCR, indicando se a leitura está ativa e quais idiomas estão na pasta tessdata
josias test-tesseract

# 3. Executa um teste forense em uma imagem local aplicando os 19 filtros e exibindo o que o Tesseract leu em cada método
josias test-ocr c:\capturas\tela_erro.png

# 4. Gera um projeto de automação estruturado completo
# Sintaxe: josias init [NomeDoRobo] [web | desktop | hybrid]
# Exemplo 1 (Web): Cria a pasta 'MeuRoboWeb' com template focado em navegador
josias init MeuRoboWeb web

# Exemplo 2 (Desktop): Popula a pasta atual com template para automação desktop nativa
josias init . desktop

# Exemplo 3 (Híbrido): Cria a pasta 'HelloBot' combinando as duas tecnologias (Padrão)
josias init HelloBot hybrid

# 5. Exibe a versão instalada da biblioteca
josias version

---

🌐 Automação Web

A biblioteca Josias possui um motor integrado de automação web chamado JosiasWeb, construído sobre o Selenium. Ele gerencia automaticamente o download de drivers (através do Selenium Manager) e fornece esperas inteligentes, além de simplificar a interação com elementos DOM usando seletores do tipo ID, CSS Selector ou XPath de forma automática.

Inicialização e Navegação:

• JosiasWeb(browser_type="chrome", headless=False): Instancia o motor para Chrome, Firefox ou Edge.
• open(url=None): Inicializa a sessão do navegador e maximiza a janela.
• navigate_to(url): Navega até a URL desejada e aguarda o carregamento.
• maximize(): Maximiza a janela do navegador.

Interação com Elementos:

O JosiasWeb analisa a string de busca para selecionar automaticamente a melhor estratégia de localização:

• Se começar com / ou (, busca por XPath.
• Se começar com # (sem espaços), busca por ID.
• Caso contrário, busca por CSS Selector.

• click(selector, timeout=10): Espera o elemento ficar clicável e clica.
• type_text(selector, text, clear=True, timeout=10): Espera o elemento ficar visível, limpa e digita.
• get_text(selector, timeout=10): Obtém o conteúdo de texto do elemento.
• get_attribute(selector, attribute, timeout=10): Obtém o valor de um atributo (como href, src, etc.).
• execute_script(script, *args): Executa JavaScript na página.
• close(): Encerra o navegador.

Exemplo Prático de Automação Web:

from josias import JosiasWeb

# Inicializa o navegador Chrome
web = JosiasWeb(browser_type="chrome", headless=False)

# Abre e navega para o PyPI
web.open("https://pypi.org/")

# Digita na barra de pesquisa (CSS Selector identificado automaticamente)
web.type_text("input[name='q']", "josias")

# Clica no botão de pesquisa (XPath identificado automaticamente por iniciar com /)
web.click("//button[@type='submit']")

# Obtém e exibe o texto do primeiro resultado da busca
primeiro_resultado = web.get_text(".package-snippet__name")
print(f"Primeiro resultado encontrado: {primeiro_resultado}")

# Fecha o navegador
web.close()

---

🖥️ Automação Desktop

Para automação de sistemas nativos ou aplicativos legados instalados no Windows, a Josias oferece suporte a controle completo do mouse, digitação fluida e comandos de teclado avançados.

Fluxo de Trabalho Desktop:

1. Inicialização do Aplicativo: Use a biblioteca subprocess para iniciar programas do Windows (ex: Bloco de Notas, Calculadora, ERPs locais).
2. Ativação e Foco: Interaja com a janela do programa para trazê-la ao primeiro plano ou utilize o Mouse Virtual Win32 para enviar cliques em segundo plano.
3. Teclado e Atalhos: Envie comandos rápidos como Ctrl+S, Ctrl+Alt+Del ou navegue por formulários pressionando Tab.

Exemplo Prático Desktop:

import subprocess
import time
from josias import Josias

bot = Josias()

# Inicia o Bloco de Notas nativo do Windows
print("Abrindo Bloco de Notas...")
subprocess.Popen("notepad.exe")
time.sleep(1.5)

# Escreve texto de forma fluida
bot.type_text("Linha 1 do Bloco de Notas.\nLinha 2 via automacao Josias.", interval=0.03)

# Pressiona atalho para salvar o documento
bot.keyboard_command("Ctrl+S")
time.sleep(1.0)

# Digita o nome do arquivo salvando-o
bot.type_text("relatorio_financeiro.txt{enter}")

---

🧹 Utilitário de Limpeza (Cleaner)

Em robôs de RPA, é muito comum que falhas deixem navegadores, drivers e planilhas rodando em segundo plano (órfãos), consumindo memória RAM e travando execuções futuras. A Josias possui a classe utilitária Cleaner para gerenciar e encerrar esses processos de forma segura e rápida.

Métodos Disponíveis:

• Cleaner.kill_by_names(process_names=None): Encerra processos ativos com os nomes informados (ex: chrome.exe, excel.exe, chromedriver). Se nenhum nome for passado, encerra por padrão os processos órfãos mais comuns de RPA (drivers, navegadores e Office).
• Cleaner.clean_temp_files(directory, extensions=None): Limpa arquivos temporários ou relatórios antigos em uma pasta específica com base nas extensões passadas (padrão: .png, .jpg, .tmp, .log, .txt).

Exemplo de Uso de Limpeza:

from josias import Cleaner

# 1. Encerra processos órfãos comuns antes de iniciar a execução (boa prática)
print("Limpando ambiente...")
Cleaner.kill_by_names()

# 2. Se desejar fechar processos específicos (ex: Excel e Bloco de Notas)
Cleaner.kill_by_names(["excel.exe", "notepad.exe"])

# 3. Limpa capturas de tela e dumps temporários de OCR de execuções antigas
Cleaner.clean_temp_files("logs_ocr_debug", extensions=[".png", ".txt"])