Document Conversion API

Konvertiert zwischen PDF/Office-Dokumenten und strukturiertem JSON, in beide Richtungen. NEXUS-Kandidat #6 – manueller Build, nicht FORGE-generiert, folgt demselben Muster manueller Cloud-Run-Assets wie Kandidat #3 (agent-verification-api) und Kandidat #4 (url-metadata-api).

• POST /extract-pdf-to-json – Text, Tabellen (pro Seite), Seitenzahl, Metadaten. 0,02 $/Aufruf.

• POST /extract-docx-to-json – Absätze (mit Überschriftenebenen/-stilen), Tabellen, Metadaten. 0,01 $/Aufruf.

• POST /extract-xlsx-to-json – Zellraster pro Blatt, begrenzte Zeilen/Spalten. 0,01 $/Aufruf.

• POST /generate-pdf-from-json – strukturierte Blöcke (Überschrift/Absatz/Tabelle) -> PDF-Bytes. 0,02 $/Aufruf.

• POST /generate-docx-from-json – strukturierte Blöcke -> .docx-Bytes. 0,01 $/Aufruf.

• MCP-Tools unter /mcp, die alle 5 spiegeln – derzeit kostenlos, siehe „Bekannte Einschränkungen“.

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

Alle 5 Endpunkte akzeptieren base64-kodierte Dateibytes direkt im Anforderungstext – niemals eine URL zum Abrufen. Dies ist eine bewusste Abgrenzung des Umfangs: Es entfernt SSRF vollständig von der Risikofläche dieses Assets (im Gegensatz zu url-metadata-api/agent-verification-api, die beide vom Aufrufer bereitgestellte URLs abrufen und SSRF-Schutz benötigen).

Warum diese Bibliotheken, warum keine externe Datenquelle

Reine Open-Source-Software, ausgereift, keine LLM-Aufrufe, keine externen Netzwerkaufrufe zur Laufzeit (vollständig lokale Berechnung): pdfplumber (PDF-Extraktion, kapselt pdfminer.six), python-docx (Word), openpyxl (Excel), reportlab (PDF-Erzeugung). Es gibt bewusst keine benannten Drittanbieter-Datenquellen in diesem Asset – um das BuyWhere-artige Halluzinationsrisiko zu vermeiden (skills/asset-lifecycle): Es gibt nichts Externes, das falsch sein könnte; das gesamte Produkt besteht darin, „eine bekannte Bibliothek auf Bytes anzuwenden, die der Aufrufer gesendet hat“. Kein numpy/scipy (vermeidet den bekannten Cloud-Run-Buildpacks-Fehler – kein Fortran-Compiler für den Quellcode-Build von scipy – siehe skills/infra-deploy-ops; keine dieser Bibliotheken benötigt sie ohnehin).

Related MCP server: docxtpl MCP Server

Warum 0,01–0,02 $ (gegenüber 0,35 $ für agent-verification-api, 0,01 $ für url-metadata-api)

Hier gibt es keine kostenpflichtige Drittanbieter-API (anders als bei WHOIS in live-entity-verification/agent-verification-api) – reine CPU-/Speicherkosten, daher liegt dies in derselben niedrigen Preisklasse wie der einzelne Abruf von url-metadata-api für 0,01 $ und nicht annähernd bei den 0,35 $ von agent-verification-api. PDF-Operationen (extract-pdf-to-json, generate-pdf-from-json) sind mit 0,02 $ etwas teurer als docx/xlsx mit 0,01 $: pdfplumber/reportlab leisten pro Aufruf deutlich mehr Arbeit (seitenweise Layout-Analyse / PDF-Rendering) als python-docx/openpyxl (einfaches XML-Parsing eines Zip-Archivs). Es wird erwartet, dass dieses Asset das vorhersehbarste der 3 manuellen Kandidaten ist, nicht der Spitzenverdiener – Dokumentkonvertierung ist ein häufiges, wenig schwankendes Agentenbedürfnis und keine differenzierte/seltene Fähigkeit – daher liegt der Fokus auf konsistenter, reibungsloser Nutzung statt auf Marge pro Aufruf.

Zwei Risiken, die dieses Asset hat, die anderen 3 manuellen Assets aber nicht

1. CPU-gebunden, nicht I/O-gebunden. Jeder Parser-/Generator-Aufruf ist synchron (keine asynchrone API in einer der 4 Bibliotheken), anders als bei den anderen 3 Assets, die über httpx.AsyncClient I/O-gebunden sind. Jeder Handler lagert die eigentliche Arbeit über asyncio.to_thread() innerhalb eines asyncio.wait_for()-Timeouts (25 s) aus, sodass ein langsames Parsen eines Aufrufers niemals die gesamte Ereignisschleife / jede gleichzeitige Anfrage blockiert. Bekannte verbleibende Einschränkung: asyncio.wait_for() bricht die wartende Aufgabe ab, kann aber den zugrunde liegenden Betriebssystem-Thread nicht beenden – Python hat keine API, um einen laufenden Thread zwangsweise zu beenden. Eine pathologische Eingabe, die pdfminer/openpyxl intern aufhängt, hält diesen einen Worker-Thread auf unbestimmte Zeit besetzt, selbst nachdem der Aufrufer eine 504 erhält. Abgeschwächt, nicht gelöst: Ein begrenztes Semaphor (NEXUS_MAX_CONCURRENT_JOBS, Standard 4) begrenzt, wie viele solcher „verlorenen“ Threads sich gleichzeitig ansammeln können – neue Anfragen erhalten ein sauberes 503 statt eines unbegrenzten Thread-Wachstums, aber ein bereits verlorener Thread wird nie freigegeben. Eine vollständige Lösung müsste die CPU-gebundene Arbeit in einen separaten, beendbaren Prozess auslagern (ProcessPoolExecutor + harter Abbruch) statt in einen Thread; das wurde hier als unverhältnismäßig für einen 7-Tage-Bewertungskandidaten nicht umgesetzt.

2. Dekompressionsbomben-/Ressourcenerschöpfung. .docx/.xlsx sind Zip-Archive – eine manipulierte Datei mit kleiner komprimierter, aber großer unkomprimierter Größe (Zip-Bombe) ist eine echte DoS-Vektor, der sich von allem unterscheidet, womit die anderen 3 Assets konfrontiert sind. _check_zip_bomb_safe() prüft das zentrale Zip-Verzeichnis (zipfile.infolist(), günstig, dekomprimiert KEINE Eintragsdaten), bevor Bytes an python-docx/openpyxl übergeben werden: Es wird abgelehnt, wenn die gesamte unkomprimierte Größe 50 MB überschreitet oder wenn das Komprimierungsverhältnis eines einzelnen Eintrags das 100-fache übersteigt. Jeder Upload ist außerdem auf 8 MB rohe/dekodierte Bytes begrenzt, bevor überhaupt geparst wird (einschließlich PDFs, auch wenn diese nicht auf Zip basieren – begrenzt die Eingabegröße im schlimmsten Fall unabhängig vom Format).

Bekannte Einschränkungen (bewusst unkorrigiert – CLAUDE.md §3, kein Gate ohne Beleg, dass es nötig ist)

• MCP-Toolaufrufe werden nicht berechnet. Dasselbe Muster für In-Process-Aufrufe (und aus demselben Grund) wie bei den verwandten manuellen Assets: Das MCP-Tool ruft die gemeinsame Konvertierungsfunktion direkt auf, nicht über einen HTTP-Wiedereintritt in die ASGI-App.

• Keine Ratenbegrenzung pro Aufrufer. Für eine 7-Tage-Wegwerfmessung in Ordnung; hinzufügen, falls es überlebt.

• Generierte Dokumente werden nicht auf Round-Trip-Treue über das hinaus validiert, was lokal geraucht getestet wurde – reportlabs Tabellen-/Absatzdarstellung und python-docx-Zuordnung der Überschriftenebenen sind ausgereifte, weit verbreitete Codepfade, die hier nicht gegen jeden möglichen Office-/PDF-Reader erneut verifiziert werden.

• Siehe das Risiko „CPU-gebunden“ oben für die verbleibende Einschränkung des Thread-Lecks.

NEXUS_X402_FREE_MODE

Gleiches Gate-Muster wie similarity-search-api/live-entity-verification (skills/x402-payments) – Standard false (berechnet ab Tag 1, kein Freemium-Fenster; die Engine hat keine externe Validierungsabhängigkeit wie die WHOIS-basierte Engine von live-entity-verification, daher gibt es kein gleichwertiges „bereits in Produktion bewährtes“ Argument, um direkt auf kostenpflichtig umzusteigen – es wird trotzdem berechnet, gemäß dem „moderaten und stabilen“ Umsatzrahmen des Session-Briefings, nicht wegen eines bestimmten Präzedenzfalls). Für Tests ohne echten Facilitator-Roundtrip lokal auf true setzen.

Bereitstellungsziel: Cloud Run, nicht Railway

Gleiche Pipeline wie Kandidaten #3/#4 – siehe skills/infra-deploy-ops. Speicher auf 1 GiB erhöht (gegenüber dem hartcodierten 512-MiB-Standard des gemeinsamen scripts/deploy_cloud_run.sh) – dies ist das speicherintensivste der 3 manuellen Kandidaten (PDF-/Office-Parsing-Bibliotheken, pypdfium2/Pillow transitiv über pdfplumber). Direkt über gcloud run deploy bereitgestellt (nicht über das gemeinsame Skript, um die gemeinsame Infrastruktur nicht für eine Speichererhöhung eines einzelnen Kandidaten zu ändern):

# 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>

Messung (Kandidat #6, 7-Tage-Fenster)

7-Tage-Fenster ab der ersten echten Bereitstellung. Quelle der Wahrheit: traffic_events/revenue_events/mcp_call_events-Tabellen (asset_name = 'document-conversion-api'), nicht Cloud-Run-Logs. Tag 7: Bei null echtem Datenverkehr (Crawler herausgefiltert) den Cloud-Run-Dienst anhalten/löschen, gleiche Entscheidungsregel wie bei den Kandidaten #3/#4.