Metadata-Version: 2.4
Name: josias
Version: 0.3.3
Summary: Biblioteca Python avançada para automação de interface gráfica com OCR e processamento de imagem avançado
Author: Josias Azevedo da Silva
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyAutoGUI>=0.9.54
Requires-Dist: pytesseract>=0.3.13
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: PyYAML>=6.0
Requires-Dist: selenium>=4.10.0
Requires-Dist: psutil>=5.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Dynamic: license-file

# 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)](#capítulo-1-preparando-o-terreno-instalação-e-configurações)
2. [Capítulo 2: Conhecendo o CLI (Seu Ajudante no Terminal)](#capítulo-2-conhecendo-o-cli-seu-ajudante-no-terminal)
3. [Capítulo 3: Criando a Estrutura do Seu Robô (Templates)](#capítulo-3-criando-a-estrutura-do-seu-robô-templates)
4. [Capítulo 4: Automação Desktop (Teclado, Mouse e OCR)](#capítulo-4-automação-desktop-teclado-mouse-e-ocr)
5. [Capítulo 5: Automação Web (Dominando a Navegação com JosiasWeb)](#capítulo-5-automação-web-dominando-a-navegação-com-josiasweb)
6. [Capítulo 6: Sistema de Backtrack (Recuperação de Falhas)](#capítulo-6-sistema-de-backtrack-recuperação-de-falhas)
7. [Capítulo 7: Depuração Visual de OCR (Visual Debugger)](#capítulo-7-depuração-visual-de-ocr-visual-debugger)
8. [Capítulo 8: Limpeza de Ambiente e Processos (Cleaner)](#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](https://github.com/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:
```bash
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:
```json
{
  "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.

```bash
# 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.
    ```bash
    josias init MeuRoboWeb web
    ```
*   **Exemplo 2 (Desktop)**: Popula a pasta atual (`.`) com os arquivos para automação desktop local, sem criar uma subpasta extra.
    ```bash
    josias init . desktop
    ```
*   **Exemplo 3 (Híbrido - Padrão)**: Cria a pasta `HelloBot` combinando automação web e desktop.
    ```bash
    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
```python
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.

```python
# 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.

```python
# 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.

```python
# 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
```python
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**.

```python
# 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.

```python
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.

```python
# 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.

```python
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"])
```
