Document Parser SDK and Format Router Architecture

6. Core Data Structures

Every parser produces a ParsedDocument composed of DocumentElement and DocumentTree records so that 40 byte WRL Chunker matches trace back to exact source byte offsets, line ranges, pages, and sections:

Type or Struct	Key Fields	Purpose
DocumentMeta	document_sha256: str, mime_type: str | None, filename: str | None, suffix: str	Coordinator supplied document identity envelope passed to /parse.
EnvelopeElement	id: str, element_type: str, content: str, source_start_offset: int | None, source_end_offset: int | None, source_start_line: int | None, source_end_line: int | None	Structural block carrying exact 0 based, end exclusive UTF 8 byte and line spans.
TreeNode	id: str, node_type: str, title: str | None, content: str, level: int, source_start_offset: int | None, source_end_offset: int | None, children: list[TreeNode]	Hierarchical tree node used by ingest_core for WRL chunking and fallback gate evaluation.
ParsedDocument	id: Uuid, metadata: DocumentMetadata, elements: list[DocumentElement], structure: DocumentStructure, document_tree: DocumentTree | None	Complete parse output persisted to shared-storage and indexed into rbix.
EnrichmentResult	added_elements: list[DocumentElement], annotations: dict[Uuid, list[Annotation]], additional_metadata: dict[str, Any], stage_metrics: StageMetrics	Additive enrichment payload emitted by gliner2_runner or custom enrichers.

7. Python SDK Reference (pycaber.parser_sdk)

The Python SDK (packages/pycaber_parser and pycaber.parser_sdk) exposes callback registration hooks and the multi process WorkerSupervisor server:

• pycaber.parser_sdk.register_parser(callback): Registers callback(file_path: str, config: dict) -> dict | str invoked on POST /parse.
• pycaber.parser_sdk.register_enricher(callback): Registers callback(document_json_path: str, config: dict) -> dict | str invoked on POST /enrich.
• pycaber.parser_sdk.serve(config=None, port=None): Starts the Axum and Tokio HTTP container server (default port 8081), releasing the Python GIL during network I/O.
• pycaber.parser_sdk.serve_worker_supervisor(capabilities, config=None, port=None, python_path=None, scripts_dir=None, default_capability=None): Launches the fault tolerant multi process WorkerSupervisor (start_tolerant) supporting capabilities [("docling", "docling_runner"), ("markdown", "markdown_runner"), ("gliner2", "gliner2_runner"), ("metadata", "metadata_runner")].

8. Container HTTP REST Wire Protocol (schema_version: "4.2")

Method	Endpoint	Request Payload	Success Response	Status Codes	Description
POST	/parse	ParseRequest (handle, doc, config)	ParseResponse (document, metrics)	200, 400, 500, 503	Primary structural and byte span extraction endpoint.
POST	/enrich	EnrichRequest (document, handle, doc, config)	EnrichResponse (result, metrics)	200, 400, 500, 503	Additive NER (gliner2) and metadata enrichment endpoint.
GET	/health	None	HealthStatus (healthy, capabilities)	200, 503	Liveness and per capability readiness probe.
GET	/manifest	None	ParserManifest	200	Declares supported formats, capabilities, and GPU requirements.