Argus

Argus

Plataforma de recuperação para agentes de IA. O Argus roteia buscas por 14 provedores, recupera URLs mortas, captura conteúdo importante de sites, constrói pacotes locais de documentação e pesquisa, e persiste tudo com artefatos locais rastreáveis.

Recursos em resumo:

• Aquisição ciente de topologia — O Argus sabe se está em um IP residencial ou de datacenter, roteando busca e extração automaticamente para evitar bloqueios e minimizar saltos de rede.
• 14 provedores, uma API — roteamento com prioridade para camada gratuita, provedores com orçamento esgotado são ignorados automaticamente
• Início sem chaves — pip install argus-search oferece DuckDuckGo + Yahoo imediatamente, sem necessidade de contas
• SearXNG auto-hospedado = 70+ mecanismos — Google, Bing, Yahoo, Startpage, Ecosia, Qwant e mais via um único contêiner Docker
• Extração de conteúdo em 12 etapas — retorna o texto completo da página com portões de qualidade, não apenas links
• Fluxos de recuperação opinativos — recupere artigos mortos, capture páginas importantes de um site e construa pacotes locais de documentação e pesquisa
• Armazenamento de corpus de propriedade do Argus — dados de execução vão para um diretório de dados de usuário gravável, não para o seu checkout do repositório
• Sessões multi-turno — passe session_id para contexto conversacional entre buscas
• Atribuição de pontuação — opcionalmente mostre quais provedores contribuíram para cada pontuação RRF fundida
• Painel de uso — inspecione orçamentos de provedores, volume recente de consultas e uso por máquina em /dashboard
• 4 modos de busca — descoberta, pesquisa, recuperação, fundamentação
• Recuperação de URL morta — /recover-url com Wayback Machine e fallbacks de arquivo
• 4 caminhos de integração — API HTTP, CLI, servidor MCP, SDK Python

Construído para criadores de agentes de IA, pipelines de RAG e equipes de operações que precisam de busca confiável, captura e evidências locais sem costurar APIs manualmente.

Status: beta. Os fluxos de recuperação e o modelo de corpus são orientados à produção, mas ainda estão amadurecendo.

Status: veja a página de status pública. Mantenedores autorizados podem usar o README argus-ops privado para os relatórios datados mais recentes.

Conteúdo

• Início rápido
• Desenvolvimento
• Onde o Argus Grava Dados
• Fluxos Opinativos
• Provedores
• API HTTP
• Painel
• Integração
  • CLI
  • MCP
  • Python
• Extração de Conteúdo
• Arquitetura
• Configuração
• Quando Não Usar o Argus
• FAQ

Início Rápido

Modo 1: CLI Local (zero configuração)

pip install argus-search && argus search -q "python web frameworks"

É isso. O DuckDuckGo cuida da busca — sem contas, sem chaves, sem contêineres. Você tem busca gratuita ilimitada do seu laptop agora mesmo. Adicione chaves de API quando quiser mais provedores, ou não adicione.

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Funciona em qualquer máquina com Python 3.11+ — laptop, Mac Mini, Raspberry Pi, VM na nuvem. Nada para hospedar.

Para MCP (Claude Code, Codex, OpenCode, Cursor, VS Code):

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

Isso grava configuração nativa para Claude Code, Codex CLI, OpenCode e Cursor. Reinicie o cliente após a configuração. Para configuração manual de stdio:

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

Ou instale pelo Registro MCP:

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

Desenvolvimento autônomo não precisa de servidor ou chaves, mas deve ser explicitamente habilitado. MCP em produção sempre delega para uma autoridade HTTP autenticada.

Veja Configuração do Cliente MCP para arquivos de configuração exatos, comandos de verificação, configuração HTTP remota e solução de problemas.

Modo 2: Servidor Full Stack

Tem um Raspberry Pi rodando Pi-hole? Um Mac Mini na sua mesa? Um laptop antigo? Isso é suficiente para rodar o full stack — SearXNG (seu próprio mecanismo de busca privado, desabilitado por padrão) mais extração de conteúdo com renderização JS local.

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

O SearXNG usa 512MB de RAM e oferece um mecanismo de busca privado estilo Google (desabilitado por padrão — defina ARGUS_SEARXNG_ENABLED=true) que ninguém pode limitar por taxa, bloquear ou cobrar. Ele roda junto com o Pi-hole em hardware que milhões de pessoas já possuem.

Onde o Argus Grava Dados

O código do Argus e os dados de execução do Argus são coisas diferentes.

• Código fica onde você instala ou clona o Argus.
• Dados de corpus de execução ficam em um diretório de dados de usuário gravável resolvido por platformdirs, ou em ARGUS_DATA_ROOT se você o substituir.

Inspecione os caminhos exatos na sua máquina:

argus paths

Por padrão, o Argus grava:

• cache de documentação oficial sob o docs/cache/ resolvido
• pacotes de pesquisa sob docs/research/
• estado de execução de fluxos sob workflows/runs/
• snapshots versionados de fluxos sob snapshots/

Isso significa que o Argus não requer um checkout irmão de ../docs-cache. Se você tiver uma árvore docs-cache mais antiga, importe-a uma vez com:

argus corpus import-docs-cache -s /path/to/docs-cache

Fluxos Opinativos

Esses fluxos constroem artefatos locais, não apenas respostas JSON transitórias.

Recuperar Um Artigo Morto

argus recover-article -u "https://example.com/old-post" -t "Example Post"

O Argus busca candidatos para recuperação, extrai o melhor resultado, salva as fontes recuperadas localmente e escreve um relatório com citações e manifesto.

Capturar As Partes Importantes De Um Site

argus capture-site -u "https://docs.example.com"

O Argus permanece no domínio, usa descoberta assistida por sitemap mais pontuação heurística de links, salva as páginas importantes que encontra e escreve um resumo detalhado com referências.

Construir Um Pacote De Documentação + Pesquisa

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

O Argus captura documentação oficial no cache local de documentação, adiciona fontes de apoio não oficiais da busca e escreve um pacote de pesquisa combinado com artefatos rastreáveis.

Desenvolvimento

O desenvolvimento do repositório é fixado em Python 3.12. O piso de execução do pacote permanece Python 3.11, mas contribuidores devem usar o fluxo uv abaixo para que a verificação local corresponda ao CI e evite usar acidentalmente um interpretador de sistema mais antigo.

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

O repositório inclui .python-version com 3.12 para que uv, pyenv e ferramentas similares escolham o interpretador correto por padrão. Mais orientações para contribuidores estão em CONTRIBUTING.md.

Provedores

¹ O SearXNG agrega Google, Bing, Yahoo, Startpage, Ecosia, Qwant, Wikipedia e mais de 60 outros — tudo atrás de um único endpoint auto-hospedado. Execute docker compose up -d em qualquer máquina com 512MB de RAM livre.

² O WolframAlpha retorna respostas computadas (matemática, conversões de unidades, consultas factuais), não resultados de busca web. Ele só ativa nos modos grounding e research. Consultas que ele não pode computar (buscas web gerais) retornam vazio — sem erro, sem penalidade de saúde.

Mais de 7.000 consultas gratuitas/mês de provedores recorrentes de camada gratuita com chaves de API (WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k), ou até 12.000+ quando o crédito mensal da Parallel está disponível para uma conta elegível com cartão cadastrado. DuckDuckGo, Yahoo e GitHub não têm limite mensal. O SearXNG está desabilitado por padrão (habilite em .env). Prioridade de roteamento: Camada 0 (gratuitos: SearXNG*, DuckDuckGo, Yahoo, GitHub, WolframAlpha) → Camada 1 (recorrentes mensais: Brave, Tavily, Exa, Linkup, Parallel) → Camada 3 (únicos: Serper, You.com, Valyu, SearchAPI). Provedores com orçamento esgotado são ignorados automaticamente.

API HTTP

Todos os endpoints prefixados com /api. Documentação OpenAPI em http://localhost:8000/docs.

Chamadas de loopback local podem usar a API sem autenticação. Chamadas HTTP remotas devem enviar ARGUS_API_KEY como Authorization: Bearer ... ou X-API-Key: .... Rotas privilegiadas sob /api/admin/* exigem ARGUS_ADMIN_API_KEY (ou caem para ARGUS_API_KEY se nenhuma chave de administrador separada estiver configurada).

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

/api/health permanece uma rota de compatibilidade de liveness com 200. Ela intencionalmente não verifica PostgreSQL, provedores, Maya ou o navegador, para que uma indisponibilidade de dependência não cause tempestades de reinicialização de contêineres. Veja operações de produção para a topologia canônica e procedimentos de operador, e status operacional para semântica de endpoints, classificação de prontidão, expiração de observação e telemetria segura.

Modos de busca

O roteamento por camadas sempre se aplica primeiro. Dentro de cada camada, o modo seleciona a ordem dos provedores.

Formato de resposta

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

Cada resultado inclui url, title, snippet, domain, provider e score. O array traces mostra quais provedores foram chamados e seus resultados.

Quando include_attribution é verdadeiro, cada resultado também inclui score_attribution: um mapa provedor-para-pontuação que decompõe a pontuação de Fusão de Rank Recíproco do resultado. RRF é aditivo, então a atribuição de cada provedor é exatamente sua própria contribuição de rank, e os valores somam score. A atribuição está desligada por padrão e é armazenada em cache separadamente das buscas sem atribuição.

Orçamentos

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

Cada provedor rastreia uso. A camada 1 (mensal) usa uma janela móvel de 30 dias; a camada 3 (única) usa um contador vitalício que nunca reinicia. Quando um provedor atinge seu orçamento, o Argus o ignora e passa para o próximo. Provedores gratuitos (DuckDuckGo, GitHub) não têm limite. O SearXNG é gratuito, mas desabilitado por padrão. Defina ARGUS_*_MONTHLY_BUDGET_USD para impor limites personalizados por provedor.

Painel

Execute o servidor HTTP e abra /dashboard:

argus serve
# http://127.0.0.1:8000/dashboard

O painel mostra o consumo de orçamento dos provedores, provedores acima do ritmo e esgotados, volume de consultas dos últimos 30 dias, uso por máquina e atividade recente de provedores. Os cartões de orçamento atualizam automaticamente.

Defina ARGUS_ADMIN_API_KEY para exigir login no painel. Se nenhuma chave de administrador estiver definida, o painel está aberto para qualquer pessoa que possa alcançar o servidor, o que é adequado apenas para uso local confiável.

Para implantação em subcaminho atrás de um proxy reverso, defina ARGUS_ROOT_PATH para o prefixo de caminho externo:

ARGUS_ROOT_PATH=/argus argus serve

Isso faz com que redirecionamentos do dashboard, links e URLs de fragmentos HTMX funcionem quando o proxy serve o Argus em um caminho como https://khamel.com/argus/.

Para HTTPS público direto, o repositório inclui um perfil Caddy:

ARGUS_DOMAIN=argus.example.com ACME_EMAIL=you@example.com \
  docker compose --profile proxy up -d

Para uma implantação existente com Authentik/nginx, mantenha a autenticação na camada de proxy e defina ARGUS_ROOT_PATH para o prefixo público.

Integração

CLI

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

Todos os comandos suportam --json para saída estruturada.

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

MCP

MCP é um adaptador de execução sem estado sobre a API HTTP autenticada. Ele não constrói provedores ou um broker e não possui estado de navegador, banco de dados, orçamento, sessão, saúde ou outbox. Configure o processo do adaptador com:

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

O endpoint de produção implantado suporta tanto o contrato de compatibilidade MCP 2025-11-25 verificado quanto a revisão de transporte sem estado MCP 2026-07-28. O caminho mais novo é único e não requer handshake de inicialização ou Mcp-Session-Id; políticas duráveis, orçamentos, sessões e evidências permanecem de propriedade da autoridade HTTP. Consulte docs/research/2026-08-11-mcp-stateless-production-authority.md para o limite respaldado pela fonte e as sondas obrigatórias sem gasto.

Opção A — Adaptador local (stdio)

Instale o adaptador na mesma máquina que seu cliente MCP:

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

Use o caminho completo se argus não estiver no PATH: "/home/you/.local/bin/argus". O adaptador herda ARGUS_AUTHORITY_URL e ARGUS_AUTHORITY_TOKEN do processo do cliente. Para executar um broker local, ambientes de desenvolvimento devem definir explicitamente ARGUS_MCP_STANDALONE=true; produção o rejeita.

Funciona com Claude Code, Codex CLI, OpenCode, Cursor e qualquer cliente MCP baseado em stdio. Use argus mcp init --global --client all para escrever configurações nativas de cliente para a máquina atual.

Instruções detalhadas de configuração e verificação de clientes estão em docs/mcp-clients.md.

Opção B — Adaptador MCP remoto (clientes via Tailscale)

Execute o Argus em uma máquina, conecte cada cliente pela rede. Sem instalação local nos clientes.

No host do adaptador:

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

Credenciais MCP remotas também devem ser credenciais com escopo válido na autoridade HTTP, pois o adaptador encaminha cada token de portador autenticado sem alterações. Para stdio, ARGUS_AUTHORITY_TOKEN é a credencial do chamador.

Para manter a API HTTP e o serviço MCP remoto em execução após a reinicialização em um host systemd:

cat >mcp.env <<'EOF'
ARGUS_AUTHORITY_URL=http://argus-api:8000
ARGUS_AUTHORITY_TOKEN=replace-with-scoped-caller-token
ARGUS_API_KEY=replace-with-the-same-scoped-caller-token
EOF
chmod 600 mcp.env
ARGUS_MCP_ENV_FILE="$PWD/mcp.env" scripts/install-systemd.sh
systemctl status argus argus-mcp --no-pager

O instalador valida o ambiente mínimo do adaptador, instala-o como /etc/argus/mcp.env somente para root, e então instala e inicia ambas as unidades. A unidade MCP nunca carrega o .env da autoridade, cofres de provedores, configurações de banco de dados, caminhos de navegador ou volumes de dados graváveis.

Em cada cliente:

Com Tailscale, <server> é o IP Tailscale da sua máquina (ex.: 100.x.x.x). Um servidor, todas as máquinas na sua malha obtêm busca.

Provisionamento com um comando:

# Load secrets, then push config to any machine:
eval $(secrets decrypt argus | grep -E 'ARGUS_REMOTE_URL|ARGUS_API_KEY' | sed 's/^/export /')

curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s local              # this machine; uses local stdio if argus is installed
curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s user@100.x.x.x    # remote machine

O script grava configurações do Claude/Cursor, Codex e OpenCode no destino. Stdio local não requer uma chave de listener MCP, mas o adaptador ainda exige sua ARGUS_AUTHORITY_TOKEN com escopo. O modo MCP remoto requer ARGUS_REMOTE_URL e ARGUS_API_KEY. Requer Python 3.

argus mcp init também gera configurações automaticamente:

argus mcp init --global              # local stdio adapter for Claude Code + OpenCode + Cursor
argus mcp init --client codex        # local stdio for Codex (writes ~/.codex/config.toml)
argus mcp init --client opencode     # local stdio for OpenCode
ARGUS_REMOTE_URL=http://argus.local:8271 ARGUS_API_KEY=... argus mcp init --global --client all
argus mcp init --client gemini       # prints gemini mcp add command
argus mcp init --global --client all # everything above

Status de Lançamento

Enviar main não publica no PyPI. A publicação de pacote e Registro MCP acontece por meio do fluxo de trabalho de publicação do GitHub na criação de release ou despacho manual. Consulte docs/releasing.md para sincronização de versão, verificações de pré-lançamento e verificação de publicação.

Transportes: stdio (adaptador local padrão), sse (remoto legado) e streamable-http (remoto moderno, "type":"http" na configuração). Transportes MCP remotos exigem ARGUS_API_KEY; todo transporte delega execução para ARGUS_AUTHORITY_URL.

Ferramentas disponíveis:

• MCP stdio e remoto com suporte HTTP: search_web, extract_content, recover_url, expand_links, search_health, search_budgets, recover_dead_article, capture_site e build_research_pack
• Desenvolvimento autônomo explícito adicionalmente expõe apenas local test_provider, cookie_health, valyu_answer, ferramentas de caminho/arquivo e recursos. Eles estão intencionalmente ausentes nos adaptadores de produção.

search_web aceita free_only=true para restringir resultados apenas a provedores gratuitos (nível 0), e include_attribution=true para incluir atribuição de pontuação por provedor na resposta Markdown.

Usando Argus via MCP vs HTTP

Dois transportes, uma regra: agentes usam MCP, todo o resto usa HTTP.

• MCP (argus mcp serve) — um adaptador autenticado sem estado para estruturas de IA que falam MCP nativamente. Ferramentas principais delegam à autoridade HTTP: search_web, extract_content, recover_url, expand_links e inícios de fluxo de trabalho. Reinicializações MCP não podem bifurcar contabilidade, sessões, saúde ou estado de outbox.
• HTTP (POST /api/search, POST /api/extract, POST /api/workflows/...) — para scripts, trabalhos cron e integrações de serviço (incluindo Maya). Envie uma credencial de chamador com escopo em Authorization; valores de corpo "caller" são rótulos de diagnóstico e não podem substituir a identidade autenticada.

O contrato de transporte entre serviços e função para a frota mais ampla (Maya / Hermes / Argus) é canônico na documentação de arquitetura do Maya.

Python

Importações diretas de broker e extração são uma conveniência de desenvolvimento autônomo. Chamadores Python em produção usam a API HTTP autenticada para que toda execução e contabilidade durável permaneçam em uma única autoridade.

from argus.broker.router import create_broker
from argus.models import SearchQuery, SearchMode
from argus.extraction import extract_url

broker = create_broker()

response = await broker.search(
    SearchQuery(query="python web frameworks", mode=SearchMode.DISCOVERY, max_results=10),
    compute_attribution=True,
)
for r in response.results:
    print(f"{r.title}: {r.url} (score: {r.score:.3f})")
    print(r.score_attribution)

content = await extract_url(response.results[0].url)
print(content.title)
print(content.text)

Extração de Conteúdo

O Argus tenta até doze métodos para extrair conteúdo de qualquer URL: extração de autenticação para paywalls, depois extratores locais (trafilatura, Crawl4AI, Obscura, Playwright, IP residencial), depois APIs externas (Jina, Valyu Contents, Firecrawl, You.com, Wayback, archive.is). Cada tentativa é verificada quanto à qualidade de completude e saída de lixo. Consulte docs/providers.md para a comparação completa de extratores.

Avaliação de completude é executada automaticamente após cada extração bem-sucedida. O Argus pontua cinco sinais — reticências finais, marcadores de truncamento de feed ("Leia mais", rodapés WordPress RSS), finais no meio da frase, parágrafos finais abruptos e contagens de palavras redondas suspeitas — e retorna is_complete, completeness_confidence e truncation_type junto com o texto. Quando a confiança é ≥ 85%, o Argus continua tentando o próximo extrator em vez de retornar um resultado parcial; isso significa que uma busca trafilatura que termina com "..." cairá automaticamente para Playwright, Jina, Wayback, etc. Chamadores que já têm texto (ex.: itens de feed RSS) podem usar POST /api/assess-content para verificar completude sem acionar extração.

Obscura (opcional) é um navegador headless Rust leve (~70MB binário, 30MB RAM) com modo stealth integrado — ele define navigator.webdriver=undefined, randomiza impressões digitais de canvas/GPU/áudio por sessão e bloqueia 3.520 domínios de rastreadores. Isso aborda diretamente a detecção de bots em sites com muito JS e anti-raspagem que bloqueiam Playwright/Chrome padrão. Sem chave de API, sem limite de taxa — totalmente local.

Duas maneiras de usá-lo:

Instale o binário: github.com/h4ckf0r0day/obscura/releases

Extract obtém o texto completo de uma URL funcional e informa se esse texto está completo. Recover-URL encontra alternativas quando uma URL está morta, atrás de paywall ou radicalmente alterada.

Arquitetura

Caller (CLI/HTTP/MCP/Python) → SearchBroker → tier-sorted providers → RRF ranking → response
                                     ↕ SessionStore (optional)
                            Extractor (on demand) → 12-step fallback chain with quality gates

Adicione novos provedores ou extratores com um único arquivo de adaptador. Consulte CONTRIBUTING.md para a interface.

Como uma Consulta Funciona

query arrives → cache? → build provider queue → execute sequentially → RRF fuse → dedup → respond

1. Verificação de cache. SearchCache aplica hash na consulta normalizada, modo e se atribuição foi solicitada (SHA256). Acerto retorna imediatamente com um TTL de 168 horas (7 dias).

2. Fila de provedores. resolve_routing() pega a lista de preferências específica do modo e ordena de forma estável por nível: nível 0 (gratuito) primeiro, nível 1 (mensal) depois, nível 3 (pagamento único) por último. Exemplo para modo de descoberta:

   searxng → duckduckgo → yahoo → github → brave → exa → tavily → linkup → parallel → serper → you → valyu
   

3. Execução sequencial com portões. Cada provedor é verificado em ordem. Quatro portões devem passar antes de uma chamada de API:

   • Configuração — o provedor está habilitado e configurado (chave de API presente)?
   • Saúde — falhou 5+ vezes consecutivas (aciona resfriamento de 60 minutos)?
   • Orçamento — para nível 1+: o orçamento está esgotado? Para nível 1 (mensal), o ritmo verifica se a taxa de uso de 7 dias drenaria o orçamento restante em menos de uma semana — dias vazios acumulam folga. Para nível 3 (pagamento único), um contador vitalício controla o acesso — esgotamento é a única verificação.
   • Executar — a chamada HTTP real. Sucessos redefinem contadores de falha; falhas os incrementam.

4. Fusão RRF. Resultados de todos os provedores consultados são mesclados usando Fusão de Classificação Recíproca (k=60). A pontuação de cada resultado é a soma de 1/(k + rank) em cada provedor que o retornou. Resultados que aparecem em múltiplos provedores classificam mais alto.

5. Deduplicação e truncamento. URLs são normalizadas (removendo www., parâmetros de rastreamento como utm_*, barras finais) e deduplicadas. A lista mesclada é truncada para max_results (padrão 10).

6. Cachear e persistir. A autoridade grava a resposta final em seu cache em memória e no repositório SQL configurado (PostgreSQL em produção, SQLite para desenvolvimento autônomo). Resultados de busca e extrações incluem metadados de proveniência (egress, machine, source_type) para auditoria downstream. Bancos de dados existentes são atualizados de forma aditiva na inicialização.

Configuração

Toda a configuração via variáveis de ambiente. Consulte .env.example para a lista completa. Provedores limitados de chave de API são opcionais: defina tanto a chave de API quanto ARGUS_<PROVIDER>_ENABLED=true. Chaves ausentes degradam graciosamente — provedores são ignorados, não erros.

Ao executar a partir do repositório, o Argus agora carrega automaticamente .env e .env.local (sem sobrescrever variáveis de ambiente já exportadas). Desative esse comportamento com ARGUS_AUTOLOAD_DOTENV=false.

/api/v2/* é aditivo e retorna um envelope canônico versão 2. Ele permanece com falha fechada com unready enquanto a autoridade de evidências está desabilitada. Combinações inseguras de Host, Origin, credencial, tipo de mídia e tamanho de corpo são rejeitadas antes do trabalho de provedor, extrator, sessão ou persistência. Rotas versão 1 mantêm suas formas de resposta estabelecidas.

Quando Não Usar Argus

Argus é melhor quando você precisa de busca, captura, proveniência e artefatos locais juntos.

Evite-o quando:

• você só precisa de uma API de busca e não precisa de fallback ou controles de orçamento
• você só precisa de uma raspagem de página única sem corpus persistente ou saída de relatório
• você precisa de uma UI de busca para usuário final em vez de infraestrutura de recuperação de backend
• você precisa de sumarização totalmente determinística sem etapas heurísticas ou assistidas por LLM

FAQ

Como isso é diferente de chamar Tavily/Serper diretamente? Argus os chama para você — além de outros 13 provedores. Você obtém um conjunto de resultados classificado e deduplicado em vez de gerenciar várias chaves de API e unir resultados. Provedores gratuitos são tentados primeiro, então você só gasta créditos quando necessário.

Posso executar apenas um provedor? Sim. Defina apenas a chave de API do provedor desejado. Todos os outros são silenciosamente ignorados. Para configuração zero, basta instalar e usar — DuckDuckGo + Yahoo lidam com a busca sem chaves.

Preciso de Docker? Não. pip install argus-search funciona imediatamente em qualquer máquina com Python 3.11+. Docker é necessário apenas para SearXNG (defina ARGUS_SEARXNG_ENABLED=true em .env) ou Crawl4AI (renderização JS local).

Qual versão do Python os contribuidores devem usar? Use Python 3.12 para desenvolvimento e verificação do repositório: uv sync --python 3.12 --extra dev --extra mcp e depois uv run pytest tests/ -v --tb=short. O pacote publicado ainda suporta Python 3.11+.

Qual é a maneira mais segura de implantar Argus em uma rede? Use Tailscale ou outra rede privada, vincule explicitamente à interface confiável, defina ARGUS_API_KEY e reserve /api/admin/* para ARGUS_ADMIN_API_KEY. Trate a exposição direta à internet como um modo avançado atrás de um proxy reverso.

Licença

MIT — consulte CHANGELOG.md para o histórico de versões.