External Providers

Estado

Implemented. Todos los adaptadores están operativos. El token pool está en uso en producción para la integración con Perplexity. El request journal está habilitado para todos los adaptadores de pago.

Propósito

El research framework delega toda la comunicación externa en adaptadores. El objetivo es:

• Mantener el núcleo del framework (orquestador, fases, esquemas) agnóstico al proveedor.
• Hacer explícitos el coste, los límites de tasa y los modos de fallo.
• Proporcionar un audit trail completo de cada llamada externa.

Esta página es la referencia canónica para la capa de adaptadores y las políticas cross-cutting (token pool, request journal, retry, failover). El framework en su conjunto está en Framework. El modelo de auditoría y seguridad están en Modelo de auditoría y Principios de seguridad.

Contrato de adaptador

Cada adaptador implementa (o envuelve) una interfaz pequeña y estable. El contrato mínimo:

def search(query: str, *, limit: int = 10, **opts) -> list[Source]:
    """Devuelve una lista de objetos Source que coinciden con la query."""

Para adaptadores especializados (YouTube, Perplexity), el contrato se extiende pero siempre devuelve objetos de scout/schemas/sources.py (o un equivalente tipado).

El esquema Source:

Devolver objetos Source tipados es el contrato que hace que el resto del framework sea agnóstico al proveedor.

Inventario de adaptadores

El adaptador Perplexity se documenta en detalle más abajo. Los adaptadores de búsqueda comparten las mismas políticas de retry y rate limit; lo único que difiere es la auth y el modelo de coste.

Token Pool

La integración con Perplexity es la única que usa un token pool. El pool existe porque el lab tiene múltiples cuentas de Perplexity (por capacidad y redundancia) y porque la integración se construyó originalmente alrededor de un plan de tokens sk-cp-... que tiene límites de tasa por cuenta.

Configuración del pool

El pool se configura con token_pool_config.json (o token_pool_config.example.json para la plantilla):

{
  "providers": {
    "perplexity": {
      "tokens": [
        {"name": "primary",   "value": "pplx-XXXX", "weight": 3},
        {"name": "secondary", "value": "pplx-YYYY", "weight": 2},
        {"name": "fallback",  "value": "pplx-ZZZZ", "weight": 1}
      ],
      "strategy": "weighted-round-robin"
    }
  }
}

La estrategia puede ser round-robin, weighted-round-robin, least-used o failover. El default es weighted-round-robin.

Runtime del pool

El token pool se mantiene en memoria. En cada request:

1. El pool selecciona un token según la estrategia.
2. El adaptador hace la request con el token seleccionado.
3. El pool registra la request y la respuesta.
4. Si la request falla con 401 o 403, el pool marca el token como quota_exhausted y selecciona el siguiente. La request se reintenta con el nuevo token.
5. Si todos los tokens están quota_exhausted, el pool devuelve un error y la fase se marca como failed_retryable.

El pool también registra:

• Las requests totales por token.
• Los errores totales por token.
• El último error por token.
• La última request exitosa por token.

El estado del pool se expone como un fichero JSON bajo {framework-root}/runtime/token_pool_state.json. Se le puede pedir al Coordinator que muestre el estado actual.

Seguridad del pool

El fichero del pool es el fichero más sensible del framework. Es:

• Almacenado con permisos 0600 (solo lectura/escritura del owner).
• Excluido de cualquier backup que se suba fuera de la máquina.
• Recargado en cada restart del proceso (el fichero es la fuente de verdad, el estado en memoria es un caché).
• Auditado vía el request journal (cada request registra qué token se usó, por nombre, nunca por valor).

El valor de un token nunca se escribe en ningún log, journal o artefacto. El name del token es lo que registra el journal.

Request Journal

Cada llamada de adaptador se registra en un único journal append-only. El journal es {framework-root}/runtime/request_journal.jsonl. Cada línea es un objeto JSON:

{
  "ts": "2026-06-10T20:15:34.123Z",
  "mission_id": "hotel-barcelona-2026-09",
  "phase": "F1",
  "adapter": "tavily",
  "action": "search",
  "token_name": null,
  "request": {
    "query": "boutique hotel Barcelona Eixample",
    "limit": 10
  },
  "response_summary": {
    "status": 200,
    "items": 10,
    "duration_ms": 412
  },
  "result": "succeeded",
  "error": null
}

El journal es append-only. Las entradas nunca se actualizan ni se borran. La rotación es por fichero: cuando el journal excede un tamaño configurado (SCOUTE_JOURNAL_MAX_BYTES, default 50 MB), se renombra a request_journal.<timestamp>.jsonl y se empieza un fichero nuevo.

El journal es la base del modelo de auditoría. Se le puede pedir al Coordinator que:

• Muestre las últimas N requests para una misión dada.
• Muestre las requests para un token dado.
• Muestre las requests que fallaron.
• Replay una request (ayuda de debug).

El journal no almacena cuerpos de request que puedan contener datos personales. Si un adaptador acepta un input libre, el journal almacena una versión redactada (p. ej., keywords de la query pero no el texto completo).

Política de retry

Todos los adaptadores comparten una política de retry por defecto. La política la aplica un helper de retry compartido que envuelve la llamada del adaptador.

El helper de retry usa backoff exponencial con jitter completo. No reintenta en errores 4xx distintos de 429.

Failover

Failover es el acto de cambiar de un proveedor a otro cuando el primario no está disponible. El framework implementa failover a dos niveles.

Failover a nivel de adaptador

Cada fase declara una lista ordenada de adaptadores. La fase llama al primer adaptador; si devuelve failed_retryable tras agotar sus reintentos, la fase llama al siguiente adaptador.

Ejemplo para F1:

Adaptadores: tavily → duckduckgo → google

Si Tavily devuelve un 5xx, F1 reintenta Tavily dos veces, luego recurre a DuckDuckGo, luego a Google. Si los tres fallan, la fase es failed_retryable.

Failover a nivel de proveedor (solo Perplexity)

El token pool implementa failover a nivel de proveedor. Cuando una request a Perplexity falla por un problema de token (401, 403, 429 desde la perspectiva de cuota), el pool cambia al siguiente token. La request se reintenta de forma transparente.

Esto es adicional al retry HTTP normal. El flujo completo para una request a Perplexity es:

1. Escoger un token del pool.
2. Hacer la request.
3. Si la respuesta es 200, devolver.
4. Si la respuesta es 429 o 5xx, reintentar con el mismo token (backoff exponencial).
5. Si se agotan los reintentos, marcar el token como quota_exhausted (para 429) o error (para 5xx) y escoger el siguiente token.
6. Si todos los tokens están quota_exhausted, fallar la fase.

Límites de tasa

Cada adaptador tiene un cap de requests por minuto. El cap lo aplica un token bucket por adaptador:

El cap es configurable por despliegue. El cap se aplica antes de la request, no después, así que el framework no desperdicia requests en proveedores rate-limited.

Tracking de coste

Para adaptadores de pago (Tavily, Perplexity), el framework registra el coste de cada request en el journal. El coste es el producto del usage reportado en la respuesta y la tarifa publicada del proveedor.

El campo cost del journal se rellena cuando el adaptador devuelve información de usage. El framework expone un endpoint /api/cost-summary que agrega costes por misión, por adaptador y por token.

Ver también

• Framework
• Mission DAG
• Mission Lifecycle
• Modelo de auditoría
• Principios de seguridad
• Catálogo de fallos
• Variables de entorno