Metadata-Version: 2.4
Name: hcaptcha-challenger-tributojusto
Version: 0.20.0
Summary: Autonomous hCaptcha solver using Google Gemini multimodal models with Playwright + Camoufox.
Author: luisdutra31
License-Expression: GPL-3.0-or-later
Keywords: camoufox,captcha,gemini,hcaptcha,hcaptcha-challenger,hcaptcha-solver,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: browserforge>=1.2.4
Requires-Dist: camoufox[geoip]>=0.4.11
Requires-Dist: google-genai>=1.66.0
Requires-Dist: httpx[http2]>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: msgpack<2.0.0,>=1.1.1
Requires-Dist: opencv-python<5.0,>=4.11.0.88
Requires-Dist: pillow>=11.1.0
Requires-Dist: playwright
Requires-Dist: pydantic-settings>=2.12.0
Requires-Dist: pytz>=2025.2
Requires-Dist: typer>=0.21.1
Provides-Extra: dataset
Requires-Dist: typer; extra == 'dataset'
Description-Content-Type: text/markdown

# hcaptcha-challenger

Biblioteca Python para resolução autônoma de desafios hCaptcha via modelos multimodais (Gemini). Integra com Playwright + Camoufox para automação stealth de navegadores.

## Instalação

```bash
pip install hcaptcha-challenger
```

Ou com `uv`:

```bash
uv add hcaptcha-challenger
```

## Pré-requisitos

- Python >= 3.10
- Chave de API do Google Gemini: [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
- Arquivo `.env` na raiz do projeto:

```env
GEMINI_API_KEY=sua_chave_aqui
```

## Uso básico

```python
import asyncio
from camoufox import AsyncCamoufox
from hcaptcha_challenger import AgentV, AgentConfig
from hcaptcha_challenger.models import ChallengeSignal

async def main():
    async with AsyncCamoufox(headless=False, humanize=True) as browser:
        page = browser.pages[-1] if browser.pages else await browser.new_page()

        agent = AgentV(
            page=page,
            agent_config=AgentConfig(
                DISABLE_BEZIER_TRAJECTORY=True,  # Camoufox já humaniza os movimentos
            ),
        )

        await page.goto("https://exemplo.com/pagina-com-hcaptcha")

        # hCaptcha visível (com checkbox)
        await agent.robotic_arm.click_checkbox()
        signal = await agent.wait_for_challenge()

        if signal == ChallengeSignal.SUCCESS:
            print("hCaptcha resolvido com sucesso!")

asyncio.run(main())
```

## hCaptcha invisível

Para páginas onde o hCaptcha é disparado automaticamente (sem checkbox visível):

```python
# Não chame click_checkbox() — apenas aguarde o desafio
signal = await agent.wait_for_challenge()
```

## Configuração avançada

```python
agent_config = AgentConfig(
    # Modelo Gemini para classificação de imagens
    IMAGE_CLASSIFIER_MODEL="gemini-2.5-flash",

    # Timing de cliques (reduza para evitar timeouts em conexões lentas)
    CLICK_DELAY_MS=80,
    INTER_CLICK_DELAY_S=0.2,
    SUBMIT_DELAY_S=0.5,

    # Número máximo de tentativas antes de desistir
    MAX_CHALLENGE_ATTEMPTS=4,

    # Logs detalhados de debug
    enable_challenger_debug=True,

    # Desabilita trajetória Bezier (use quando o browser já humaniza movimentos)
    DISABLE_BEZIER_TRAJECTORY=True,

    # Rotação de múltiplas chaves Gemini (separe por vírgula no .env)
    # GEMINI_API_KEYS=chave1,chave2,chave3
)
```

Todas as opções podem ser definidas via variáveis de ambiente ou arquivo `.env`.

## Múltiplas chaves de API (rotação)

Para alta disponibilidade com fallback automático entre modelos:

```env
GEMINI_API_KEYS=chave1,chave2,chave3
```

O provider tenta automaticamente os modelos na seguinte ordem em caso de erro 503/429:
`gemini-2.5-pro` → `gemini-2.5-flash` → `gemini-3-flash-preview` → `gemini-2.5-flash-lite` → ...

## Estrutura do projeto

```
src/hcaptcha_challenger/
├── agent/
│   ├── agent.py          # AgentV — máquina de estados principal
│   ├── config.py         # AgentConfig, SolveState
│   ├── robotic_arm.py    # Coordenador dos pilots e reasoners
│   ├── logger.py         # Logging rico com Rich
│   └── pilot/
│       ├── actions.py    # Cliques, drag-drop, mouse
│       ├── navigation.py # Detecção de frames e desafios
│       ├── challenges.py # Handlers por tipo de desafio
│       └── core.py       # Interceptação de rede (payload/resposta)
├── tools/
│   ├── image_classifier/     # Desafios 9-grid (image_label_binary)
│   ├── challenge_router/     # Classificação do tipo de desafio
│   └── spatial/              # Reasoners para drag-drop e area-select
├── skills/
│   ├── rules.yaml            # Regras de correspondência prompt → template
│   └── library/              # Templates Markdown de instruções por desafio
└── models.py                 # Tipos e modelos de dados (Pydantic)
```

## Tipos de desafio suportados

| Tipo | Descrição |
|------|-----------|
| `image_label_binary` | Seleção em grid 3x3 (ex: "selecione todos os gatos") |
| `image_label_area_select` | Clique em pontos específicos da imagem |
| `image_drag_single` | Arrastar um elemento para a posição correta |
| `image_drag_multi` | Múltiplos drag-drops em sequência |
| `image_label_multi_select` | Seleção múltipla em polígonos |

## Skills (instruções por tipo de desafio)

O sistema de skills permite adicionar instruções específicas para padrões de desafio recorrentes. As regras ficam em `skills/rules.yaml` e os templates em `skills/library/`.

Exemplo de regra para desafios de referência visual:

```yaml
- triggers: ["semelhantes", "referência"]
  job_type: "image_label_binary"
  template: "binary_similar_reference.md"
```

Para adicionar suas próprias skills:

```python
AgentConfig(custom_skills_path="meus_skills/rules.yaml")
```

## Token de resposta

```python
from hcaptcha_challenger import CaptchaResponse

signal = await agent.wait_for_challenge()

if agent.cr_list:
    cr: CaptchaResponse = agent.cr_list[-1]
    print(cr.generated_pass_UUID)  # token para submissão
```

## Licença

GPL-3.0-or-later
