Merge pull request #1102 from Open-Source-Legal/claude/explore-docxodus-G49qt

Add first-class DOCX support with Docxodus microservice and WASM renderer

Author: JSv4

.envs/.test/.django

@@ -58,3 +58,5 @@ VECTOR_EMBEDDER_API_KEY=abc123
 MULTIMODAL_EMBEDDER_URL=http://multimodal-embedder:8000
 MULTIMODAL_EMBEDDER_API_KEY=abc123
 DOCLING_PARSER_SERVICE_URL=http://docling-parser:8000/parse/
+DOCXODUS_PARSER_SERVICE_URL=http://docxodus-parser:8080/parse
+DOCXODUS_PARSER_TIMEOUT=120

CHANGELOG.md

@@ -64,6 +64,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **First-class DOCX document support via Docxodus pipeline**: Added a complete parallel ingestion pipeline and rendering tree for DOCX files, bringing Word document support alongside existing PDF and TXT pipelines. Changes include:
+  - **Backend: Docxodus microservice** (`docxodus-service/`): .NET 8 minimal API wrapping `OpenContractExporter.Export()` to produce OpenContractDocExport-compatible JSON with structural annotations and character offsets from DOCX files. Multi-stage Docker build exposed on port 8080.
+  - **Backend: DocxodusServiceParser** (`opencontractserver/pipeline/parsers/docxodus_parser.py`): REST parser that sends base64-encoded DOCX to the microservice, normalizes camelCase→snake_case response fields, and handles transient/permanent error classification.
+  - **Backend: DocxThumbnailGenerator** (`opencontractserver/pipeline/thumbnailers/docx_thumbnailer.py`): Two-tier thumbnail approach — extracts embedded thumbnails from DOCX ZIP archives (`docProps/thumbnail.jpeg`), falling back to text-based thumbnails via XML parsing of `word/document.xml`.
+  - **Frontend: DocxAnnotator** (`frontend/src/components/annotator/renderers/docx/DocxAnnotator.tsx`): WASM-powered DOCX renderer using `docxodus` npm package's `convertDocxToHtmlWithExternalAnnotations()` for annotation projection onto native DOCX HTML output. Supports text selection for new annotation creation via `findTextOccurrences()`.
+  - **Frontend: DocxAnnotatorWrapper** (`frontend/src/components/annotator/components/wrappers/DocxAnnotatorWrapper.tsx`): State management wrapper mirroring TxtAnnotatorWrapper pattern — manages annotation CRUD, chat sources, text search, and ref registration.
+  - **Frontend: DocumentKnowledgeBase integration**: DOCX loading flow (fetches raw bytes + extracted text) and renderer dispatch added to both query handlers.
+  - **Frontend utilities**: `isDocxFileType()` in `frontend/src/utils/files.ts`, `DOCX_MIME_TYPE` constant, `docxBytesAtom` / `useDocxBytes()` hook in DocumentAtom, `getDocxBytes()` in cachedRest.
+  - **Docker Compose**: `docxodus-parser` service added to `local.yml`, `production.yml`, and `test.yml` with dependency wiring.
+  - **Dependencies**: `docxodus@5.5.0` and `dompurify@3.3.3` added to frontend.
+  - **Backend tests**: `test_doc_parser_docxodus.py` with parser unit tests (success, timeout, connection error, normalization) and thumbnailer tests (text preview, embedded thumbnail, invalid DOCX handling).
+  - **Frontend tests**: `DocxAnnotator.ct.tsx` component test with `docScreenshot` captures.
+
 - **Richer social media link previews for corpus and document links**: Improved the Cloudflare OG worker to generate better social tags. Changes include:
   - Corpus descriptions are now included in OG/Twitter description tags, combined with document count (e.g. "Corpus description — 15 documents")
   - Document-in-corpus links now surface the parent corpus description when the document lacks its own description

config/graphql/annotation_types.py

@@ -50,12 +50,20 @@ class AnnotationInputType(AnnotatePermissionsForReadMixin, graphene.InputObjectT
 
 class AnnotationType(AnnotatePermissionsForReadMixin, DjangoObjectType):
     json = GenericScalar()  # noqa
+    annotation_type = graphene.String(
+        description="Annotation type (e.g. TOKEN_LABEL, SPAN_LABEL). "
+        "Returns raw DB value to avoid enum serialization errors on invalid data.",
+    )
     feedback_count = graphene.Int(description="Count of user feedback")
     content_modalities = graphene.List(
         graphene.String,
         description="Content modalities present in this annotation: TEXT, IMAGE, etc.",
     )
 
+    def resolve_annotation_type(self, info):
+        """Return annotation_type as a plain string to tolerate invalid DB values."""
+        return self.annotation_type or ""
+
     def resolve_content_modalities(self, info):
         """Return content modalities list from model."""
         return self.content_modalities or []

docs/assets/images/screenshots/auto/annotations--txt-document--with-spans.png

@@ -41,6 +41,8 @@
     "axios": "^1.13.5",
     "d3": "^7.9.0",
     "date-fns": "^4.1.0",
+    "docxodus": "5.5.3",
+    "dompurify": "^3.3.3",
     "framer-motion": "6.*",
     "fuse.js": "^6.5.3",
     "graphql": "^16.2.0",
@@ -137,6 +139,7 @@
     "@playwright/test": "^1.52.0",
     "@testing-library/react-hooks": "^8.0.1",
     "@types/d3": "^7.4.3",
+    "@types/dompurify": "^3.2.0",
     "@types/json-schema": "^7.0.15",
     "@types/lodash.uniqueid": "^4.0.9",
     "@types/react-helmet-async": "^1.0.3",

docs/assets/images/screenshots/auto/annotator--docx-annotator--read-only.png

@@ -15,6 +15,7 @@ import * as pdfjs from "pdfjs-dist";
 import { ApolloClient, InMemoryCache, ApolloProvider } from "@apollo/client";
 import { ThemeProvider } from "../src/theme/ThemeProvider";
 import { allStyles } from "@os-legal/ui";
+import { setWasmBasePath } from "docxodus";
 
 // Create a type for the Jotai Store
 type Store = ReturnType<typeof createStore>;
@@ -44,9 +45,14 @@ beforeMount(async ({ App }: BeforeMountParams) => {
   console.log(`[Playwright Hook] Before mounting component with providers`);
 
   // Configure PDF.js to use a worker - https://github.com/mozilla/pdf.js/issues/10478
-  //GlobalWorkerOptions.workerSrc = '';
   pdfjs.GlobalWorkerOptions.workerSrc = workerSrc;
 
+  // Configure Docxodus WASM path for Playwright CT environment.
+  // In normal dev/prod, import.meta.url auto-detects the path, but in
+  // Playwright CT the test bundle compilation breaks auto-detection.
+  // Tests use page.route() to intercept /docxodus-wasm/** and serve from disk.
+  setWasmBasePath("/docxodus-wasm/");
+
   // Create a fresh Jotai store for this test
   window.jotaiStore = createStore();