hcaptcha-challenger-tributojusto 0.20.0

Autonomous hCaptcha solver using Google Gemini multimodal models with Playwright + Camoufox.

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

pip install hcaptcha-challenger

Ou com uv:

uv add hcaptcha-challenger

Pré-requisitos

• Python >= 3.10
• Chave de API do Google Gemini: aistudio.google.com/apikey
• Arquivo .env na raiz do projeto:

GEMINI_API_KEY=sua_chave_aqui

Uso básico

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):

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

Configuração avançada

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:

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:

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

Para adicionar suas próprias skills:

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

Token de resposta

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