feat(sources): soporte de API key de OpenAlex + cliente consciente de rate-limits (modelo de créditos 2026)

[complexluise]

Contexto — OpenAlex cambió su modelo (efectivo 13-feb-2026)

Verificado en uso real (2026-06-22): la ingesta online (seed --equation, resolve, chain, enrich) recibe 429 sostenido de OpenAlex. No es un bug nuestro — OpenAlex cambió su autenticación y rate-limiting:

• API keys ahora obligatorias (desde 13-feb-2026).
• Polite pool y parámetro mailto= ELIMINADOS ("No more polite pool! No more email parameter… it was never secure and couldn't scale"). bib2graph hoy manda mailto → no-op.
• Modelo de créditos: singleton = 1, list = 10, content/descarga = 100, vector search = 1000 créditos.
  • Gratis (sin key): 100 créditos/día (~10 llamadas list — inusable para seeding real).
  • Con API key: 100.000 créditos/día.
  • (OpenAlex dice que los números "aren't final, still calibrating".)

Causa del 429: pegamos sin key → tier gratis 100 créditos/día → se agota en una sesión y queda 429 hasta el reset diario.

Qué hacer

1. api_key en OpenAlexSource (param + config de workspace y/o env, p. ej. OPENALEX_API_KEY), enviado como api_key=<key>. Deprecar/quitar el mailto polite-pool (muerto).
2. Cliente consciente de límites: manejar 429 con backoff (+ Retry-After si viene), requests/s configurable, y un presupuesto/preview de créditos para no agotar el día por sorpresa (encaja con el preview del forrajeo, feat(cli): preview de crecimiento del chaining antes del fetch — historia B2 #89). Mensaje accionable cuando falta la key o se agotó el crédito.
3. Generalizar a política de auth + rate-limit por proveedor. TODO proveedor (OpenAlex hoy; Semantic Scholar, Crossref, etc. después — ver feat(sources): poblar external_ids al ingestar (cruce cross-motor) — al sumar el 2º motor #120) tiene su propia key y sus propios límites. Que el contrato Source (ADR 0018) declare su autenticación y sus límites; el cliente los respeta. Esto es parte de la visión source-agnóstica (ADR 0036/0035).
4. Documentar cómo el usuario obtiene y configura la API key de OpenAlex.

Prioridad

Alta: el flujo online (la mitad del producto) quedó degradado por el cambio externo. El flujo de archivo (--from-bib, offline) sigue sano; lo que pega a OpenAlex (search/resolve/chain/enrich) necesita la key.

Fuentes

• Anuncio oficial (13-feb-2026): https://groups.google.com/g/openalex-users/c/rI1GIAySpVQ
• Docs auth/rate-limits: https://github.com/ourresearch/openalex-docs/blob/main/how-to-use-the-api/rate-limits-and-authentication.md
• Pricing: https://help.openalex.org/hc/en-us/articles/24397762024087-Pricing

Relacionado: ADR 0018 (Source agnóstico), ADR 0035 (resolución pega a OpenAlex), #120 (multi-motor), #89 (preview de crecimiento).

[complexluise]

Reencuadre del PO (2026-06-22): OpenAlex funciona sin API key, pero limitado (tier gratis, ~100 créditos/día). Con API key, más límite — como muchos servicios (gratis con pocas llamadas; key para usar más). No mata el flujo online: solo hay que avisar del límite. Así que:

• La key es opcional (para uso intensivo), no obligatoria. Baja a prioridad media.
• Alcance de este issue: (1) avisar del límite/free-tier en la doc y en un error accionable al recibir 429; (2) soportar api_key opcional en OpenAlexSource para subir el límite; (3) deprecar el mailto muerto. Generalizable a otros proveedores (feat(sources): poblar external_ids al ingestar (cruce cross-motor) — al sumar el 2º motor #120).
• El tier gratis cubre el quickstart y uso liviano; por eso no es bloqueante.

[complexluise]

⚠️ Cruce con #210 (ya en el release 0.10.2) — revisar antes de cerrar este issue

Detectado en la sesión de verificación e2e (2026-06-30). #210 —mergeado y dentro del release 0.10.2 (PR #228)— introdujo un mensaje de 429 accionable (_MSG_RATE_LIMIT_429 en sources/openalex.py) cuyo remedio primario es el email/polite-pool y trata la api_key como opcional:

"…declarar tu email mueve la petición al polite pool, que tiene un límite más generoso… Opcional: una api_key mejora el límite aún más (OPENALEX_API_KEY)."

Si la premisa de este issue (#124) es correcta —OpenAlex eliminó el polite-pool y el mailto el 13-feb-2026, y la api_key es el remedio real— entonces ese mensaje quedó al revés (apunta a un polite-pool muerto como remedio primario y degrada la api_key a opcional). Conviene invertir el framing cuando se implemente #124: api_key como remedio primario, mailto deprecado.

Dato empírico del capstone (matiz)

En la corrida e2e, b2g seed --equation "…" --max-results 5 funcionó sin email ni api_key (5 papers sembrados, sin 429). O sea: el tier anónimo todavía sirve consultas chicas; el 429 aparece con volumen/seeding real. La situación de créditos parece estar en transición (el propio anuncio dice "aren't final, still calibrating").

Recomendación

1. Decidir (con verificación contra los docs vigentes de OpenAlex) si el polite-pool/mailto está realmente muerto.
2. Si sí: al implementar feat(sources): soporte de API key de OpenAlex + cliente consciente de rate-limits (modelo de créditos 2026) #124, actualizar también _MSG_RATE_LIMIT_429 y la enmienda de ADR 0012 para que api_key sea el remedio primario. Esto cierra el cruce con feat(sources): error accionable cuando OpenAlex limita la tasa (429) por falta de email/api_key #210.
3. No bloquea publicar 0.10.2: el mensaje actual menciona OPENALEX_API_KEY, así que es subóptimo pero no roto.

Origen: verificación e2e autónoma del CLI (capstone 0.11.0).