josias 0.3.3

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

Josias 🤖✨

O Guia Definitivo de Automação RPA em Python: Do Iniciante ao Profissional

Bem-vindo ao Josias! Se você já tentou automatizar tarefas repetitivas no computador, provavelmente esbarrou nos maiores problemas da automação tradicional:

• O robô parou de funcionar porque a janela mudou levemente de tamanho.
• Você não pode tocar no mouse físico enquanto o robô está trabalhando.
• O robô tentou ler um texto, falhou, e você não sabe o porquê.
• Após uma falha, dezenas de navegadores e planilhas ficaram travados em segundo plano consumindo memória.

O Josias foi criado para resolver essas dores. Ele combina Tesseract OCR avançado, 19 filtros de processamento de imagem em tempo real, reconhecimento dinâmico de escala, gerenciamento de processos e cliques virtuais em segundo plano (Win32 API), permitindo criar automações estáveis e profissionais.

Este manual foi escrito como um livro didático para guiar você desde a instalação básica até a construção de robôs híbridos avançados.

---

📖 Sumário do Guia

1. Capítulo 1: Preparando o Terreno (Instalação e Configurações)
2. Capítulo 2: Conhecendo o CLI (Seu Ajudante no Terminal)
3. Capítulo 3: Criando a Estrutura do Seu Robô (Templates)
4. Capítulo 4: Automação Desktop (Teclado, Mouse e OCR)
5. Capítulo 5: Automação Web (Dominando a Navegação com JosiasWeb)
6. Capítulo 6: Sistema de Backtrack (Recuperação de Falhas)
7. Capítulo 7: Depuração Visual de OCR (Visual Debugger)
8. Capítulo 8: Limpeza de Ambiente e Processos (Cleaner)

---

Capítulo 1: Preparando o Terreno (Instalação e Configurações)

Antes de colocarmos nosso robô para funcionar, precisamos preparar a máquina dele. O Josias utiliza uma ferramenta externa muito famosa para ler textos da tela: o Tesseract OCR.

1. Instalando o Tesseract OCR

A biblioteca requer o executável do Tesseract instalado para realizar as leituras de texto.

• 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): Rode sudo apt-get update && sudo apt-get install tesseract-ocr tesseract-ocr-por no seu terminal.
• macOS: Instale via Homebrew rodando brew install tesseract.

[!NOTE] Por padrão, a biblioteca busca o executável do Tesseract em C:\Program Files\Tesseract-OCR\tesseract.exe. Se você instalou em outro local, basta configurar o caminho como mostrado a seguir.

2. Instalando a biblioteca Josias

Você pode instalar a biblioteca diretamente do PyPI em qualquer terminal ou ambiente virtual:

pip install -U josias

3. Configurando seu Robô

O Josias carrega suas configurações automaticamente respeitando a seguinte prioridade:

1. Parâmetros passados ao instanciar a classe: Josias({"wait_timeout": 15}).
2. Variáveis de ambiente com prefixo JOSIAS_ (ex: JOSIAS_DEBUG_OCR=True).
3. Arquivo .josias.json, .josias.yaml ou .josias.yml na raiz da pasta do seu robô.

Exemplo de arquivo .josias.json ideal para seu projeto:

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

---

Capítulo 2: Conhecendo o CLI (Seu Ajudante no Terminal)

Ao instalar a biblioteca Josias, um comando global de terminal chamado josias é disponibilizado no seu ambiente virtual. Ele serve para fazer diagnósticos rápidos antes de começarmos a programar.

# 1. Verifica a integridade e exibe o status de todos os requisitos do sistema
josias status

# 2. Faz um teste rápido simulando uma leitura de texto para validar o Tesseract
josias test-tesseract

# 3. Executa um teste forense em uma imagem aplicando os 19 filtros e mostrando os resultados
josias test-ocr c:\pasta\minha_imagem.png

# 4. Exibe a versão atual instalada
josias version

---

Capítulo 3: Criando a Estrutura do Seu Robô (Templates)

Para você não perder tempo criando pastas e escrevendo códigos repetitivos, a CLI possui o comando josias init que gera projetos profissionais estruturados de forma instantânea.

Como gerar projetos:

A sintaxe do comando é: josias init [NomeDoRobo] [web | desktop | hybrid]

• Exemplo 1 (Web): Cria a pasta MeuRoboWeb com um template focado em navegação web rápida.

  josias init MeuRoboWeb web
  

• Exemplo 2 (Desktop): Popula a pasta atual (.) com os arquivos para automação desktop local, sem criar uma subpasta extra.

  josias init . desktop
  

• Exemplo 3 (Híbrido - Padrão): Cria a pasta HelloBot combinando automação web e desktop.

  josias init HelloBot hybrid
  

A estrutura gerada pelo comando:

HelloBot/
├── HelloBot.botproj  <- Metadados de configuracao do projeto
├── bot.py            <- Onde você desenvolve o codigo do seu robo
├── resources/        <- Pasta para armazenar capturas de tela e imagens
├── build.bat         <- Script Windows para instalar as dependencias na .venv
├── build.ps1         <- Script PowerShell para ativacao e instalacao
├── build.sh          <- Script Linux/macOS para instalacao rapida
└── requirements.txt  <- Arquivo contendo as dependencias do robo

[!TIP] Ativação Inteligente: Os scripts de build (build.bat etc.) são inteligentes. Se você tiver uma pasta .venv na pasta pai do projeto, eles a detectarão e ativarão automaticamente, evitando a duplicação de ambientes virtuais!

---

Capítulo 4: Automação Desktop (Teclado, Mouse e OCR)

O robô clássico interage com as janelas e programas instalados no sistema operacional. Para isso, a classe principal Josias fornece os controles de clique inteligente, leitura OCR e atalhos.

Inicialização

from josias import Josias

bot = Josias({
    "use_virtual_mouse": False, # Se True, envia cliques Win32 sem mover o cursor fisico
    "show_overlay": True,        # Desenha uma caixa vermelha na tela antes de clicar
    "overlay_color": "red"       # Cor da caixa de destaque
})

🖱️ 1. Localização e Clique de Imagem (Escala Dinâmica)

Diferente das ferramentas comuns que falham se o elemento mudar de tamanho devido à escala do monitor (ex: monitores de notebooks que usam zoom de 125%), o Josias busca imagens em diferentes escalas de forma inteligente.

# Clica em uma imagem salva na pasta resources
bot.click_image("resources/botao_salvar.png", wait_until_found=True, confidence=0.8)

📝 2. Cliques e Reconhecimento via OCR

Você não precisa recortar imagens de todos os botões. Você pode clicar neles usando o texto escrito neles! O motor de processamento do Josias aplica 19 filtros de imagem diferentes para garantir que a leitura funcione mesmo em fundos complexos.

# Procura pelo texto "Confirmar" e clica nele
bot.click_text("Confirmar", wait_until_found=True)

# Clica no campo de texto "Pesquisar" e digita "relatorio"
bot.click_text("Pesquisar", sendtext="relatorio")

⌨️ 3. Teclado, Atalhos e Escrita Fluida

Escreva textos longos ou execute combinações de teclas do sistema operacional com facilidade.

# Digita texto com um pequeno intervalo de tempo entre as letras (simula digitação humana)
bot.type_text("Digitando dados no sistema...", interval=0.05)

# Executa atalhos do Windows ou programas
bot.keyboard_command("Ctrl+S") # Atalho para salvar
bot.keyboard_command("Tab")    # Pressiona a tecla Tab para navegar

---

Capítulo 5: Automação Web (Dominando a Navegação com JosiasWeb)

Quando a sua automação envolve abrir páginas de internet, preencher formulários web ou extrair dados de portais, nós utilizamos o motor JosiasWeb. Ele gerencia o Selenium de forma simplificada, baixando os drivers em segundo plano automaticamente.

Inicializando o Navegador

from josias import JosiasWeb

# Inicializa o Chrome. Você pode trocar para "firefox" ou "edge".
# Use headless=True para o navegador rodar escondido em segundo plano.
web = JosiasWeb(browser_type="chrome", headless=False)

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

🎯 Seletores Inteligentes e Automáticos

Esqueça a sintaxe verbosa de precisar dizer se está buscando por ID ou XPath. O JosiasWeb analisa a string enviada e escolhe a melhor estratégia de localização:

• Se começar com / ou (, busca como XPath.
• Se começar com # (sem espaços), busca como ID.
• Para qualquer outro caso, busca como CSS Selector.

# 1. Digita na caixa de pesquisa (CSS Selector detectado de forma transparente)
web.type_text("input[name='q']", "josias")

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

# 3. Extrai o texto do resultado (CSS Selector)
texto = web.get_text(".package-snippet__name")
print(f"Texto extraido: {texto}")

# 4. Fecha o navegador ao finalizar
web.close()

---

Capítulo 6: Sistema de Backtrack (Recuperação de Falhas)

Muitas automações falham porque a internet oscila ou um sistema lento não responde a tempo. O Josias resolve isso com o sistema de Backtrack Inteligente. Se um passo falhar, o robô automaticamente tenta reexecutar as ações anteriores para se recuperar.

from josias import Josias

bot = Josias()

# Criamos uma lista sequencial de tarefas a serem executadas
tarefas = [
    {"action": "click_text", "target": "Menu"},
    {"action": "click_text", "target": "Relatorios"},
    {"action": "click_text", "target": "Gerar PDF"}
]

# O robô executa a lista. Se falhar em "Gerar PDF", ele volta 
# e clica em "Relatorios" e "Menu" novamente para refazer o caminho.
sucesso = bot.execute_tasks(tarefas, enable_backtrack=True, max_retries=2)

---

Capítulo 7: Depuração Visual de OCR (Visual Debugger)

Quando um robô não consegue localizar ou clicar em um texto na tela por OCR, é muito difícil saber o motivo. O Josias possui um depurador visual integrado. Ao ativar a propriedade debug_ocr, a biblioteca salva automaticamente capturas de tela forenses em caso de falha na busca.

# Ative na configuracao
bot = Josias({"debug_ocr": True, "debug_ocr_dir": "logs_ocr_debug"})

O que é gerado na pasta de Debug:

• original_crop.png: O recorte exato da tela onde o robô tentou ler o texto.
• method_01_grayscale.png a method_19_hsv.png: As 19 variações de imagem geradas em tempo real. Isso mostra qual filtro de cor deixou as letras mais nítidas para o Tesseract.
• ocr_report.txt: Um relatório detalhando o que foi lido em cada método e o nível de confiança (0% a 100%).

---

Capítulo 8: Limpeza de Ambiente e Processos (Cleaner)

Uma das maiores causas de falhas em servidores RPA é o acúmulo de processos "órfãos". Se o robô trava, navegadores e drivers continuam abertos consumindo toda a memória RAM da máquina. A classe Cleaner ajuda a manter o ambiente de execução limpo.

from josias import Cleaner

# 1. Encerra TODOS os processos comuns travados em segundo plano
# (Encerra Chrome, Firefox, Edge, Chromedriver, Excel, Notepad)
# Dica: Execute esta linha no início e no final do código do seu robô!
Cleaner.kill_by_names()

# 2. Encerra apenas programas específicos se desejar
Cleaner.kill_by_names(["excel.exe", "notepad.exe"])

# 3. Deleta capturas de tela e arquivos temporários antigos gerados pelo robô
Cleaner.clean_temp_files("logs_ocr_debug", extensions=[".png", ".txt"])