Argus

Argus

Plataforma de recuperación para agentes de IA. Argus enruta búsquedas a través de 14 proveedores, recupera URLs muertas, captura contenido importante de sitios web, construye paquetes locales de documentación e investigación, y persiste todo con artefactos locales trazables.

Características de un vistazo:

• Adquisición consciente de topología — Argus sabe si está en una IP residencial o de centro de datos, enrutando búsqueda y extracción automáticamente para evitar bloqueos y minimizar saltos de red.
• 14 proveedores, una API — enrutamiento de primer nivel gratuito, proveedores con presupuesto agotado se omiten automáticamente
• Inicio sin claves — pip install argus-search te da DuckDuckGo + Yahoo inmediatamente, sin necesidad de cuentas
• SearXNG autoalojado = 70+ motores — Google, Bing, Yahoo, Startpage, Ecosia, Qwant y más a través de un contenedor Docker
• Extracción de contenido en 12 pasos — devuelve el texto completo de la página con controles de calidad, no solo enlaces
• Flujos de trabajo de recuperación opinados — recupera artículos muertos, captura páginas importantes de un sitio y construye paquetes locales de documentación e investigación
• Almacenamiento de corpus propiedad de Argus — los datos de ejecución van a un directorio de datos de usuario escribible, no a tu checkout del repositorio
• Sesiones multi-turno — pasa session_id para contexto conversacional entre búsquedas
• Atribución de puntuación — muestra opcionalmente qué proveedores contribuyeron a cada puntuación RRF fusionada
• Panel de uso — inspecciona presupuestos de proveedores, volumen reciente de consultas y uso a nivel de máquina en /dashboard
• 4 modos de búsqueda — descubrimiento, investigación, recuperación, verificación
• Recuperación de URLs muertas — /recover-url con Wayback Machine y respaldos de archivo
• 4 rutas de integración — API HTTP, CLI, servidor MCP, SDK de Python

Construido para creadores de agentes de IA, pipelines RAG y equipos de operaciones que necesitan búsqueda, captura y evidencia local confiables sin tener que unir APIs manualmente.

Estado: beta. Los flujos de trabajo de recuperación y el modelo de corpus están orientados a producción, pero aún están madurando.

Estado: consulta la página de estado pública. Los mantenedores autorizados pueden usar el README de argus-ops privado para los informes fechados más recientes.

Contenido

• Inicio rápido
• Desarrollo
• Dónde escribe datos Argus
• Flujos de trabajo opinados
• Proveedores
• API HTTP
• Panel
• Integración
  • CLI
  • MCP
  • Python
• Extracción de contenido
• Arquitectura
• Configuración
• Cuándo no usar Argus
• Preguntas frecuentes

Inicio rápido

Modo 1: CLI local (sin configuración)

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

Eso es todo. DuckDuckGo maneja la búsqueda — sin cuentas, sin claves, sin contenedores. Obtienes búsqueda gratuita ilimitada desde tu portátil ahora mismo. Agrega claves API cuando quieras más proveedores, o no lo hagas.

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 en cualquier máquina con Python 3.11+ — portátil, Mac Mini, Raspberry Pi, VM en la nube. Nada que alojar.

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

Eso escribe configuración nativa para Claude Code, Codex CLI, OpenCode y Cursor. Reinicia el cliente después de la configuración. Para configuración manual de stdio:

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

O instala desde el Registro MCP:

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

El desarrollo independiente no necesita servidor ni claves, pero debe estar explícitamente habilitado. El MCP de producción siempre delega a una autoridad HTTP autenticada.

Consulta Configuración del cliente MCP para archivos de configuración exactos, comandos de verificación, configuración HTTP remota y solución de problemas.

Modo 2: Servidor de pila completa

¿Tienes una Raspberry Pi ejecutando Pi-hole? ¿Un Mac Mini en tu escritorio? ¿Un portátil viejo? Eso es suficiente para ejecutar la pila completa — SearXNG (tu propio motor de búsqueda privado, deshabilitado por defecto) más extracción de contenido con renderizado 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

SearXNG toma 512MB de RAM y te da un motor de búsqueda privado estilo Google (deshabilitado por defecto — configura ARGUS_SEARXNG_ENABLED=true) que nadie puede limitar, bloquear o cobrar. Se ejecuta junto a Pi-hole en hardware que millones de personas ya poseen.

Dónde escribe datos Argus

El código de Argus y los datos de ejecución de Argus son cosas diferentes.

• Código vive donde instales o clones Argus.
• Datos de corpus de ejecución viven en un directorio de datos de usuario escribible resuelto por platformdirs, o en ARGUS_DATA_ROOT si lo sobrescribes.

Inspecciona las rutas exactas en tu máquina:

argus paths

Por defecto Argus escribe:

• caché de documentación oficial bajo el docs/cache/ resuelto
• paquetes de investigación bajo docs/research/
• estado de ejecución de flujos de trabajo bajo workflows/runs/
• instantáneas versionadas de flujos de trabajo bajo snapshots/

Esto significa que Argus no requiere un checkout hermano de ../docs-cache. Si tienes un árbol de docs-cache más antiguo, impórtalo una vez con:

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

Flujos de trabajo opinados

Estos flujos de trabajo construyen artefactos locales, no solo respuestas JSON transitorias.

Recuperar un artículo muerto

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

Argus busca candidatos de recuperación, extrae el mejor resultado, guarda las fuentes recuperadas localmente y escribe un informe respaldado por citas más un manifiesto.

Capturar las partes importantes de un sitio

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

Argus se mantiene en el dominio, usa descubrimiento asistido por sitemap más puntuación heurística de enlaces, guarda las páginas importantes que encuentra y escribe un resumen detallado con referencias.

Construir un paquete de documentación + investigación

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

Argus captura documentación oficial en su caché local de documentación, agrega fuentes de apoyo no oficiales de la búsqueda y escribe un paquete de investigación combinado con artefactos trazables.

Desarrollo

El desarrollo del repositorio está fijado a Python 3.12. El mínimo de ejecución del paquete sigue siendo Python 3.11, pero los contribuyentes deben usar el flujo de trabajo uv a continuación para que la verificación local coincida con CI y evitar usar accidentalmente un intérprete de sistema más antiguo.

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

El repositorio incluye .python-version con 3.12 para que uv, pyenv y herramientas similares elijan el intérprete correcto por defecto. Más orientación para contribuyentes está en CONTRIBUTING.md.

Proveedores

¹ SearXNG agrega Google, Bing, Yahoo, Startpage, Ecosia, Qwant, Wikipedia y más de 60 — todo detrás de un único endpoint autoalojado. Ejecuta docker compose up -d en cualquier máquina con 512MB de RAM libre.

² WolframAlpha devuelve respuestas calculadas (matemáticas, conversiones de unidades, consultas factuales), no resultados de búsqueda web. Solo se activa en modos grounding y research. Las consultas que no puede calcular (búsquedas web generales) devuelven vacío — sin error, sin penalización de salud.

Más de 7,000 consultas gratuitas/mes de proveedores recurrentes de nivel gratuito con claves API (WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k), o hasta 12,000+ cuando el crédito mensual de Parallel está disponible para una cuenta elegible con tarjeta registrada. DuckDuckGo, Yahoo y GitHub no tienen límite mensual. SearXNG está deshabilitado por defecto (habilítalo en .env). Prioridad de enrutamiento: Nivel 0 (gratis: SearXNG*, DuckDuckGo, Yahoo, GitHub, WolframAlpha) → Nivel 1 (recurrente mensual: Brave, Tavily, Exa, Linkup, Parallel) → Nivel 3 (único: Serper, You.com, Valyu, SearchAPI). Los proveedores con presupuesto agotado se omiten automáticamente.

API HTTP

Todos los endpoints tienen el prefijo /api. Documentación OpenAPI en http://localhost:8000/docs.

Las llamadas de bucle local pueden usar la API sin autenticación. Los llamadores HTTP remotos deben enviar ARGUS_API_KEY como Authorization: Bearer ... o X-API-Key: .... Las rutas privilegiadas bajo /api/admin/* requieren ARGUS_ADMIN_API_KEY (o recurren a ARGUS_API_KEY si no hay una clave de administrador separada 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 sigue siendo una ruta de compatibilidad de liveness 200. Intencionalmente no verifica PostgreSQL, proveedores, Maya ni el navegador, para que una interrupción de dependencia no cause tormentas de reinicio de contenedores. Consulta operaciones de producción para la topología canónica y procedimientos de operador, y estado operativo para semántica de endpoints, clasificación de readiness, expiración de observaciones y telemetría segura.

Modos de búsqueda

El enrutamiento por niveles siempre se aplica primero. Dentro de cada nivel, el modo selecciona el orden de los proveedores.

Formato de respuesta

{
  "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 incluye url, title, snippet, domain, provider y score. El array traces muestra qué proveedores fueron llamados y sus resultados.

Cuando include_attribution es verdadero, cada resultado también incluye score_attribution: un mapa proveedor-a-puntuación que descompone la puntuación de Fusión de Rango Recíproco del resultado. RRF es aditivo, por lo que la atribución de cada proveedor es exactamente su propia contribución de rango, y los valores suman score. La atribución está desactivada por defecto y se almacena en caché por separado de las búsquedas sin atribución.

Presupuestos

{
  "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 proveedor rastrea el uso. El nivel 1 (mensual) usa una ventana móvil de 30 días; el nivel 3 (único) usa un contador de por vida que nunca se reinicia. Cuando un proveedor alcanza su presupuesto, Argus lo omite y pasa al siguiente. Los proveedores gratuitos (DuckDuckGo, GitHub) no tienen límite. SearXNG es gratuito pero está deshabilitado por defecto. Configura ARGUS_*_MONTHLY_BUDGET_USD para imponer límites personalizados por proveedor.

Panel

Ejecuta el servidor HTTP y abre /dashboard:

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

El panel muestra el consumo de presupuesto de proveedores, proveedores sobre ritmo y agotados, volumen de consultas de los últimos 30 días, uso por máquina y actividad reciente de proveedores. Las tarjetas de presupuesto se actualizan automáticamente.

Configura ARGUS_ADMIN_API_KEY para requerir inicio de sesión en el panel. Si no hay clave de administrador configurada, el panel está abierto a cualquiera que pueda alcanzar el servidor, lo cual es adecuado solo para uso local de confianza.

Para despliegue en subruta detrás de un proxy inverso, configura ARGUS_ROOT_PATH al prefijo de ruta externa:

ARGUS_ROOT_PATH=/argus argus serve

Eso hace que las redirecciones del panel, los enlaces y las URLs de fragmentos HTMX funcionen cuando el proxy sirve Argus en una ruta como https://khamel.com/argus/.

Para HTTPS público directo, el repositorio incluye un perfil de Caddy:

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

Para una implementación existente de Authentik/nginx, mantén la autenticación en la capa del proxy y establece ARGUS_ROOT_PATH al prefijo público.

Integración

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 los comandos admiten --json para salida estructurada.

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

MCP

MCP es un adaptador de ejecución sin estado sobre la API HTTP autenticada. No construye proveedores ni un broker y no posee estado de navegador, base de datos, presupuesto, sesión, salud o bandeja de salida. Configura el proceso del adaptador con:

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

El endpoint de producción implementado admite tanto el contrato de compatibilidad verificado de MCP 2025-11-25 como la revisión de transporte sin estado de MCP 2026-07-28. La ruta más nueva es de un solo uso y no requiere un protocolo de inicio ni Mcp-Session-Id; las políticas duraderas, presupuestos, sesiones y evidencia permanecen bajo la autoridad HTTP. Consulta docs/research/2026-08-11-mcp-stateless-production-authority.md para el límite respaldado por el código fuente y las sondas requeridas sin gasto.

Opción A — Adaptador local (stdio)

Instala el adaptador en la misma máquina que tu cliente MCP:

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

Usa la ruta completa si argus no está en PATH: "/home/you/.local/bin/argus". El adaptador hereda ARGUS_AUTHORITY_URL y ARGUS_AUTHORITY_TOKEN del proceso del cliente. Para ejecutar un broker local en su lugar, los entornos de desarrollo deben establecer explícitamente ARGUS_MCP_STANDALONE=true; producción lo rechaza.

Funciona con Claude Code, Codex CLI, OpenCode, Cursor y cualquier cliente MCP basado en stdio. Usa argus mcp init --global --client all para escribir configuraciones de cliente nativas para la máquina actual.

Las instrucciones detalladas de configuración y verificación del cliente están en docs/mcp-clients.md.

Opción B — Adaptador MCP remoto (clientes a través de Tailscale)

Ejecuta Argus en una máquina, conecta cada cliente a través de la red. Sin instalación local en los clientes.

En el host del 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

Las credenciales MCP remotas también deben ser credenciales con alcance válido en la autoridad HTTP porque el adaptador reenvía cada token de portador autenticado sin cambios. Para stdio, ARGUS_AUTHORITY_TOKEN es la credencial del llamador.

Para mantener la API HTTP y el servicio MCP remoto en ejecución después de un reinicio en un 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

El instalador valida el entorno mínimo del adaptador, lo instala como /etc/argus/mcp.env solo para root, y luego instala e inicia ambas unidades. La unidad MCP nunca carga el .env de la autoridad, las bóvedas de proveedores, la configuración de la base de datos, las rutas del navegador ni los volúmenes de datos escribibles.

En cada cliente:

Con Tailscale, <server> es la IP de Tailscale de tu máquina (por ejemplo, 100.x.x.x). Un servidor, cada máquina en tu malla obtiene búsqueda.

Aprovisionamiento con un solo 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

El script escribe configuraciones de Claude/Cursor, Codex y OpenCode en el objetivo. El stdio local no requiere una clave de escucha MCP, pero el adaptador aún requiere su ARGUS_AUTHORITY_TOKEN con alcance. El modo MCP remoto requiere ARGUS_REMOTE_URL y ARGUS_API_KEY. Requiere Python 3.

argus mcp init también genera configuraciones automáticamente:

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

Estado de lanzamiento

Empujar main no publica PyPI. La publicación del paquete y del Registro MCP ocurre a través del flujo de trabajo de publicación de GitHub al crear un lanzamiento o mediante despacho manual. Consulta docs/releasing.md para la sincronización de versiones, verificaciones previas y verificación de publicación.

Transportes: stdio (adaptador local predeterminado), sse (remoto heredado) y streamable-http (remoto moderno, "type":"http" en configuración). Los transportes MCP remotos requieren ARGUS_API_KEY; cada transporte delega la ejecución a ARGUS_AUTHORITY_URL.

Herramientas disponibles:

• MCP stdio y remoto respaldado por HTTP: search_web, extract_content, recover_url, expand_links, search_health, search_budgets, recover_dead_article, capture_site y build_research_pack
• El desarrollo independiente explícito además expone solo local test_provider, cookie_health, valyu_answer, herramientas de ruta/archivo y recursos. Estos están intencionalmente ausentes en los adaptadores de producción.

search_web acepta free_only=true para restringir resultados solo a proveedores gratuitos (nivel 0), y include_attribution=true para incluir atribución de puntuación por proveedor en la respuesta Markdown.

Uso de Argus desde MCP vs HTTP

Dos transportes, una regla: los agentes usan MCP, todo lo demás usa HTTP.

• MCP (argus mcp serve) — un adaptador autenticado sin estado para marcos de IA que hablan MCP de forma nativa. Las herramientas principales delegan en la autoridad HTTP: search_web, extract_content, recover_url, expand_links e inicios de flujo de trabajo. Los reinicios de MCP no pueden bifurcar contabilidad, sesiones, salud o estado de bandeja de salida.
• HTTP (POST /api/search, POST /api/extract, POST /api/workflows/...) — para scripts, trabajos cron e integraciones de servicios (incluida Maya). Envía una credencial de llamador con alcance en Authorization; los valores del cuerpo "caller" son etiquetas de diagnóstico y no pueden anular la identidad autenticada.

El contrato de transporte y rol entre servicios para la flota más amplia (Maya / Hermes / Argus) es canónico en la documentación de arquitectura de Maya.

Python

Las importaciones directas de broker y extracción son una conveniencia de desarrollo independiente. Los llamadores de Python en producción usan la API HTTP autenticada para que toda la ejecución y la contabilidad duradera permanezcan en una sola autoridad.

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)

Extracción de contenido

Argus intenta hasta doce métodos para extraer contenido de cualquier URL: extracción de autenticación para muros de pago, luego extractores locales (trafilatura, Crawl4AI, Obscura, Playwright, IP residencial), luego API externas (Jina, Valyu Contents, Firecrawl, You.com, Wayback, archive.is). Cada intento se verifica por calidad de completitud y salida basura. Consulta docs/providers.md para la comparación completa de extractores.

Evaluación de completitud se ejecuta automáticamente después de cada extracción exitosa. Argus puntúa cinco señales — elipsis final, marcadores de truncamiento de feed ("Leer más", pies de página RSS de WordPress), finales a mitad de oración, párrafos finales abruptos y recuentos de palabras redondos sospechosos — y devuelve is_complete, completeness_confidence y truncation_type junto con el texto. Cuando la confianza es ≥ 85%, Argus continúa probando el siguiente extractor en lugar de devolver un resultado parcial; esto significa que una búsqueda de trafilatura que termina con "..." caerá automáticamente a Playwright, Jina, Wayback, etc. Los llamadores que ya tienen texto (por ejemplo, elementos de feed RSS) pueden usar POST /api/assess-content para verificar la completitud sin desencadenar la extracción.

Obscura (opcional) es un navegador headless ligero en Rust (~70MB binario, 30MB RAM) con modo sigiloso integrado — establece navigator.webdriver=undefined, aleatoriza huellas de canvas/GPU/audio por sesión y bloquea 3,520 dominios de rastreadores. Esto aborda directamente la detección de bots en sitios con mucho JS y anti-scraping que bloquean Playwright/Chrome estándar. Sin clave API, sin límite de tasa — completamente local.

Dos formas de usarlo:

Instala el binario: github.com/h4ckf0r0day/obscura/releases

Extract obtiene el texto completo de una URL funcional y te dice si ese texto está completo. Recover-URL encuentra alternativas cuando una URL está muerta, detrás de un muro de pago o radicalmente cambiada.

Arquitectura

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

Agrega nuevos proveedores o extractores con un solo archivo de adaptador. Consulta CONTRIBUTING.md para la interfaz.

Cómo funciona una consulta

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

1. Verificación de caché. SearchCache hashea la consulta normalizada, el modo y si se solicitó atribución (SHA256). Un acierto devuelve inmediatamente con un TTL de 168 horas (7 días).

2. Cola de proveedores. resolve_routing() toma la lista de preferencias específica del modo y ordena establemente por nivel: nivel 0 (gratuito) primero, nivel 1 (mensual) después, nivel 3 (único) al final. Ejemplo para modo de descubrimiento:

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

3. Ejecución secuencial con controles. Cada proveedor se verifica en orden. Cuatro controles deben pasar antes de una llamada API:

   • Configuración — ¿está habilitado y configurado el proveedor (clave API presente)?
   • Salud — ¿ha fallado 5+ veces consecutivas (activa un enfriamiento de 60 minutos)?
   • Presupuesto — para nivel 1+: ¿está agotado el presupuesto? Para nivel 1 (mensual), el ritmo verifica si la tasa de uso de 7 días agotaría el presupuesto restante en menos de una semana — los días vacíos acumulan margen. Para nivel 3 (único), un contador de por vida controla el acceso — el agotamiento es la única verificación.
   • Ejecutar — la llamada HTTP real. Los éxitos reinician los contadores de fallos; los fallos los incrementan.

4. Fusión RRF. Los resultados de todos los proveedores consultados se fusionan usando Fusión de Rango Recíproco (k=60). La puntuación de cada resultado es la suma de 1/(k + rank) en cada proveedor que lo devolvió. Los resultados que aparecen en múltiples proveedores se clasifican más alto.

5. Deduplicación y truncamiento. Las URLs se normalizan (se eliminan www., parámetros de seguimiento como utm_*, barras finales) y se deduplican. La lista fusionada se trunca a max_results (predeterminado 10).

6. Almacenar en caché y persistir. La autoridad escribe la respuesta final en su caché en memoria y en el repositorio SQL configurado (PostgreSQL en producción, SQLite para desarrollo independiente). Los resultados de búsqueda y las extracciones incluyen metadatos de procedencia (egress, machine, source_type) para la auditoría posterior. Las bases de datos existentes se actualizan de forma aditiva al inicio.

Configuración

Toda la configuración se realiza mediante variables de entorno. Consulte .env.example para la lista completa. Los proveedores limitados de claves API son opcionales: configure tanto la clave API como ARGUS_<PROVIDER>_ENABLED=true. Las claves faltantes se degradan correctamente: los proveedores se omiten, no generan errores.

Al ejecutar desde el repositorio, Argus ahora carga automáticamente .env y .env.local (sin sobrescribir las variables de entorno ya exportadas). Desactive este comportamiento con ARGUS_AUTOLOAD_DOTENV=false.

/api/v2/* es aditivo y devuelve un sobre canónico de versión 2. Permanece con fallo cerrado con unready mientras la autoridad de evidencia está deshabilitada. Las combinaciones no seguras de Host, Origin, credenciales, tipo de medio y tamaño de cuerpo se rechazan antes del trabajo de proveedor, extractor, sesión o persistencia. Las rutas de versión 1 conservan sus formas de respuesta establecidas.

Cuándo no usar Argus

Argus es mejor cuando necesita búsqueda, captura, procedencia y artefactos locales juntos.

Evítelo cuando:

• solo necesite una API de búsqueda y no necesite controles de respaldo o presupuesto
• solo necesite un raspado de página único sin corpus persistente o salida de informe
• necesite una interfaz de búsqueda para usuarios finales en lugar de infraestructura de recuperación de backend
• necesite resumen completamente determinista sin pasos heurísticos o asistidos por LLM

Preguntas frecuentes

¿En qué se diferencia esto de llamar directamente a Tavily/Serper? Argus los llama por usted, además de otros 13 proveedores. Obtiene un conjunto de resultados clasificado y deduplicado en lugar de administrar múltiples claves API y unir resultados. Los proveedores gratuitos se prueban primero, por lo que solo gasta créditos cuando es necesario.

¿Puedo ejecutar solo un proveedor? Sí. Establezca solo la clave API del proveedor que desee. Todos los demás se omiten silenciosamente. Para configuración cero, simplemente instale y listo: DuckDuckGo + Yahoo manejan la búsqueda sin claves.

¿Necesito Docker? No. pip install argus-search funciona inmediatamente en cualquier máquina con Python 3.11+. Docker solo se necesita para SearXNG (establezca ARGUS_SEARXNG_ENABLED=true en .env) o Crawl4AI (renderizado JS local).

¿Qué versión de Python deben usar los contribuyentes? Use Python 3.12 para el desarrollo y verificación del repositorio: uv sync --python 3.12 --extra dev --extra mcp y luego uv run pytest tests/ -v --tb=short. El paquete publicado aún admite Python 3.11+.

¿Cuál es la forma más segura de implementar Argus en una red? Use Tailscale u otra red privada, vincúlese explícitamente a la interfaz de confianza, establezca ARGUS_API_KEY y reserve /api/admin/* para ARGUS_ADMIN_API_KEY. Trate la exposición directa a Internet como un modo avanzado detrás de un proxy inverso.

Licencia

MIT — consulte CHANGELOG.md para el historial de versiones.