Document Conversion API

Convierte entre documentos PDF/Office y JSON estructurado, en ambas direcciones. Candidato NEXUS #6 -- compilación manual, no generado por FORGE, siguiendo el mismo patrón de activo manual de Cloud Run que el candidato #3 (agent-verification-api) y el candidato #4 (url-metadata-api).

• POST /extract-pdf-to-json -- texto, tablas (por página), recuento de páginas, metadatos. $0.02/llamada.

• POST /extract-docx-to-json -- párrafos (con niveles de encabezado/estilos), tablas, metadatos. $0.01/llamada.

• POST /extract-xlsx-to-json -- cuadrículas de celdas por hoja, filas/columnas limitadas. $0.01/llamada.

• POST /generate-pdf-from-json -- bloques estructurados (encabezado/párrafo/tabla) -> bytes PDF. $0.02/llamada.

• POST /generate-docx-from-json -- bloques estructurados -> bytes .docx. $0.01/llamada.

• Herramientas MCP en /mcp que replican los 5 -- actualmente gratuitas, ver "Limitaciones conocidas".

• GET /health, GET /.well-known/agent-card.json, GET /openapi.json (tiene x-payment-info).

Los 5 endpoints reciben bytes de archivo codificados en base64 directamente en el cuerpo de la solicitud -- nunca una URL a la que hacer fetch. Esto es un límite de alcance deliberado: elimina el SSRF de la superficie de riesgo de este activo por completo (a diferencia de url-metadata-api/agent-verification-api, que ambos hacen fetch de URLs proporcionadas por el llamante y necesitan protecciones SSRF).

Por qué estas librerías, por qué ninguna fuente de datos externa

OSS puro, maduro, sin llamadas LLM, cero llamadas de red externas en tiempo de ejecución (cómputo totalmente local): pdfplumber (extracción PDF, envuelve pdfminer.six), python-docx (Word), openpyxl (Excel), reportlab (generación PDF). Sin fuente de datos externa de terceros nombrada en ningún lugar de este activo -- deliberadamente, para evitar el riesgo de alucinación estilo BuyWhere (skills/asset-lifecycle): no hay nada externo que pueda fallar, todo el producto es "ejecutar una librería conocida sobre bytes que el llamante nos envió". Sin numpy/scipy (evita el fallo conocido de Cloud Run Buildpacks -- sin compilador Fortran para la compilación desde fuente de scipy -- ver skills/infra-deploy-ops; ninguna de estas librerías los necesita de todos modos).

Related MCP server: docxtpl MCP Server

Por qué $0.01-$0.02 (frente a $0.35 de agent-verification-api, $0.01 de url-metadata-api)

Sin coste de API de terceros de pago aquí (a diferencia de WHOIS en live-entity-verification/ agent-verification-api) -- coste puro de CPU/memoria, así que se sitúa en el mismo nivel bajo que el $0.01 de una sola fetch de url-metadata-api en lugar de acercarse al $0.35 de agent-verification-api. Las operaciones PDF (extract-pdf-to-json, generate-pdf-from-json) tienen un precio un escalón más alto ($0.02) que docx/xlsx ($0.01): pdfplumber/reportlab hacen significativamente más trabajo por llamada (análisis de diseño a nivel de página / renderizado PDF) que python-docx/openpyxl (análisis XML directo de un archivo zip). Se espera que este activo sea el más predecible de los 3 candidatos manuales en lugar del que más ingrese -- la conversión de documentos es una necesidad de agente común y de baja varianza, no una capacidad diferenciada/rara -- así que el precio favorece un uso consistente y de baja fricción sobre el margen por llamada.

Dos riesgos que este activo tiene que los otros 3 activos manuales no

1. Limitado por CPU, no por E/S. Cada llamada de analizador/generador es síncrona (sin API asíncrona en ninguna de las 4 librerías), a diferencia de los otros 3 activos que están limitados por E/S vía httpx.AsyncClient. Cada handler descarga el trabajo real vía asyncio.to_thread() dentro de un timeout de asyncio.wait_for() (25s) para que un análisis lento de un llamante nunca bloquee todo el bucle de eventos / cada solicitud concurrente. Limitación residual conocida: asyncio.wait_for() cancela la tarea en espera, no puede matar el hilo del sistema operativo subyacente -- Python no tiene API para terminar forzosamente un hilo en ejecución. Una entrada patológica que cuelgue pdfminer/openpyxl internamente mantiene ese hilo de trabajo ocupado indefinidamente incluso después de que el llamante reciba un 504. Mitigado, no resuelto: un semáforo limitado (NEXUS_MAX_CONCURRENT_JOBS, por defecto 4) limita cuántos hilos "filtrados" de este tipo pueden acumularse concurrentemente -- las nuevas solicitudes reciben un 503 limpio en lugar de un crecimiento ilimitado de hilos, pero un hilo ya filtrado nunca se recupera. Una solución completa necesitaría el trabajo limitado por CPU en un proceso separado y terminable (ProcessPoolExecutor + terminación forzosa) en lugar de un hilo; no hecho aquí por ser desproporcionado para un candidato de probation de 7 días.

2. Bomba de descompresión / agotamiento de recursos. .docx/.xlsx son archivos zip -- un archivo manipulado con un tamaño comprimido pequeño pero un tamaño descomprimido enorme (bomba zip) es un vector DoS real distinto de cualquier cosa que enfrenten los otros 3 activos. _check_zip_bomb_safe() inspecciona el directorio central del zip (zipfile.infolist(), barato, NO descomprime los datos de las entradas) antes de pasar los bytes a python-docx/openpyxl: rechaza si el tamaño total descomprimido excediera 50MB, o si el ratio de compresión de cualquier entrada individual excede 100x. Cada subida también está limitada a 8MB de bytes crudos/decodificados antes de cualquier análisis (PDFs incluidos, aunque no estén basados en zip -- acota el tamaño de entrada en el peor caso independientemente del formato).

Limitaciones conocidas (dejadas sin arreglar a propósito -- CLAUDE.md §3, sin puerta sin evidencia de que se necesite)

• Las llamadas a herramientas MCP no se cobran. Mismo patrón de llamada en proceso (y misma razón) que los activos manuales hermanos: la herramienta MCP llama a la función de conversión compartida directamente, no vía reentrada HTTP en la app ASGI.

• Sin limitación de tasa por llamante. Aceptable para una medición desechable de 7 días; añadir si sobrevive.

• Los documentos generados no se validan para fidelidad de ida y vuelta más allá de lo probado con smoke tests localmente -- el renderizado de tablas/párrafos de reportlab y el mapeo de niveles de encabezado de python-docx son rutas de código maduras y ampliamente usadas, no re-verificadas aquí contra cada posible lector de Office/PDF.

• Ver el riesgo "limitado por CPU" arriba para la limitación residual de fuga de hilos.

NEXUS_X402_FREE_MODE

Mismo patrón de puerta que similarity-search-api/live-entity-verification (skills/x402-payments) -- por defecto false (cobra desde el día 1, sin ventana freemium; el motor no tiene dependencia de validación externa como la tenía el motor basado en WHOIS de live-entity-verification, así que no hay un argumento equivalente de "ya probado en producción" para saltar directamente a pago -- se cobra de todos modos, según el marco de ingresos "moderados y estables" del brief de la sesión, no por un precedente específico). Poner a true localmente para probar sin un round-trip real de facilitador.

Destino de despliegue: Cloud Run, no Railway

Mismo pipeline que los candidatos #3/#4 -- ver skills/infra-deploy-ops. Memoria aumentada a 1Gi (frente al valor por defecto hardcodeado de 512Mi del scripts/deploy_cloud_run.sh compartido) -- este es el de mayor uso de memoria de los 3 candidatos manuales (librerías de análisis PDF/Office, pypdfium2/Pillow transitivamente vía pdfplumber). Desplegado directamente vía gcloud run deploy (no a través del script compartido, para evitar editar herramientas de infraestructura compartidas por un aumento de memoria de un solo candidato):

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
gcloud run deploy document-conversion-api \
  --source manual_assets/document-conversion-api \
  --project nexus-505016 --region us-central1 \
  --allow-unauthenticated --min-instances=0 --max-instances=3 --memory=1Gi --quiet \
  --env-vars-file manual_assets/document-conversion-api/env-vars.deploy.yaml

# 2. Grab the printed *.run.app URL, then:
gcloud run services update document-conversion-api --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

Medición (candidato #6, ventana de 7 días)

Ventana de 7 días desde el primer despliegue real. Fuente de verdad: tablas traffic_events/revenue_events/ mcp_call_events (asset_name = 'document-conversion-api'), no los logs de Cloud Run. Día 7: si cero tráfico real (filtrando crawlers), pausar/eliminar el servicio de Cloud Run, misma regla de decisión que los candidatos #3/#4.